Repository Public
1// SP Wallet Core2// File: Sources/SPWalletCore/Domains/Execution/DeveloperModels.swift3// Description: The owner-only developer routes (/api/v1/developer, services/api/src/trading-api/developer-routes.ts, keys.ts4// `keyView`, webhooks.ts): API keys with their scopes, limits and restrictions, usage, status, webhooks. A key's5// SECRET and a webhook's signing secret are in the answer of ONE call and nowhere else, ever: the types that carry6// them are not Codable, print redacted, and reflect nothing.7//8// Author: Simon-Pierre Boucher9// Contact: contact@spboucher.ai10import Foundation1112/**13 A secret the server shows ONCE (an API key token `spw_live_<key id>_<secret>`, or a webhook signing secret).14 DELIBERATELY NOT `Encodable`/`Decodable`: it cannot be written to a snapshot, a cache or a request body by accident.15 It prints as `<redacted>` in `description`, `debugDescription`, string interpolation, `dump` and `Mirror`.16 Hand `reveal()` to the screen that shows it once (or to the Keychain) and drop the value.17 */18public struct OneTimeSecret: Sendable, CustomStringConvertible, CustomDebugStringConvertible, CustomReflectable {19 private let value: String20 init(_ value: String) { self.value = value }21 /** The secret itself. Never log the result. */22 public func reveal() -> String { value }23 public var description: String { "<redacted>" }24 public var debugDescription: String { "<redacted>" }25 public var customMirror: Mirror { Mirror(self, children: [:]) }26}2728/** A key as the owner sees it: never the secret, never its hash. */29public struct APIKey: Decodable, Sendable, Equatable, Identifiable {30 /** public id `spk_<12 hex>` */31 public let id: String32 public let name: String33 /** `active`, `expired`, `revoked` — the server's statement */34 public let status: String35 /** permissions (SCOPES of trading-api/spec.ts) */36 public let scopes: [String]37 public let limits: APIKeyLimits38 public let restrictions: APIKeyRestrictions39 public let rateLimitPerMin: Int40 public let mandateId: String?41 /** execution scopes that cannot act: no trading mandate is bound to the key */42 public let inertScopes: [String]43 public let rotatedFrom: String?44 /** unix ms */45 public let createdAt: Int46 public let expiresAt: Int47 public let revokedAt: Int?48 public let revokedReason: String?49 public let lastUsedAt: Int?50 public let lastUsedIp: String?51 public var isActive: Bool { status == "active" }52}5354public struct APIKeyList: Decodable, Sendable, Equatable {55 public struct ScopeInfo: Decodable, Sendable, Equatable { public let scope: String; /** true: the scope can move funds or exposure (inert without a mandate) */ public let execution: Bool }56 public struct Bounds: Decodable, Sendable, Equatable { public let maxDays: Int; public let defaultRatePerMin: Int; public let maxRatePerMin: Int; public let maxKeys: Int; public let maxNotionalUsd: Double? }57 public struct Execution: Decodable, Sendable, Equatable { public let wired: Bool; /** false: SPW_TRADING_API_EXECUTION is not "on" — no new live risk through the trading API */ public let liveEnabled: Bool?; public let code: String?; public let note: String? }58 public let keys: [APIKey]59 /** the scopes this server offers: a scope it does not announce is not offered */60 public let scopes: [ScopeInfo]61 public let bounds: Bounds62 public let execution: Execution?63}6465/** POST /developer/keys/prepare. No default: the scopes, the expiry, the limits, the restrictions, the rate and the mandate binding are each stated. */66public struct APIKeyCreateRequest: Encodable, Sendable, Equatable {67 public let name: String68 public let scopes: [String]69 public let expiresInDays: Int70 public let limits: APIKeyLimits71 public let restrictions: APIKeyRestrictions72 public let rateLimitPerMin: Int73 public let mandateId: ExecutionNullable<String>74 public init(name: String, scopes: [String], expiresInDays: Int, limits: APIKeyLimits, restrictions: APIKeyRestrictions, rateLimitPerMin: Int, mandateId: String?) {75 self.name = name; self.scopes = scopes; self.expiresInDays = expiresInDays; self.limits = limits; self.restrictions = restrictions; self.rateLimitPerMin = rateLimitPerMin; self.mandateId = .init(mandateId)76 }77}7879/** The answer of the ONE call that creates or rotates a key. Not Codable (it carries the secret). */80public struct IssuedAPIKey: Sendable, CustomStringConvertible, CustomReflectable {81 public let key: APIKey82 /** the whole token, shown once */83 public let secret: OneTimeSecret84 /** rotation: the id of the key that stopped working */85 public let revoked: String?86 /** rotation: whether the mandate of the old key was carried to the new id (as served) */87 public let mandate: JSONValue?88 /** What the created key differs in from the intent the passkey approved. Empty in every honest case; shown when not (the key EXISTS: revoke it). */89 public let discrepancies: [String]90 public var description: String { "IssuedAPIKey(\(key.id), secret: <redacted>)" }91 public var customMirror: Mirror { Mirror(self, children: ["key": key.id]) }92}9394public struct APIKeyUsage: Decodable, Sendable, Equatable {95 public struct Item: Decodable, Sendable, Equatable, Identifiable { public let id: Int; public let keyId: String; public let ts: Int; public let method: String; public let route: String; public let status: Int; public let latencyMs: Int?; public let requestId: String? }96 public struct PerKey: Decodable, Sendable, Equatable { public let keyId: String; public let calls24h, errors24h, rateLimited24h, callsLastMinute, calls: Int; public let lastAt: Int?; public let p95Ms: Int? }97 public let items: [Item]98 public let perKey: [PerKey]99 public let retentionDays: Int100}101102public struct DeveloperStatus: Decodable, Sendable, Equatable {103 public struct API: Decodable, Sendable, Equatable { public let version: String; public let prefix: String; public let operations: Int; public let implemented: Int; public let notImplemented: [String] }104 public struct Service: Decodable, Sendable, Equatable, Identifiable { public let id: String; public let ok: Bool; public let detail: String; public let lastOkAt: Int? }105 public struct Keys: Decodable, Sendable, Equatable { public let total: Int; public let active: Int }106 public struct RateLimits: Decodable, Sendable, Equatable { public let defaultPerMin: Int; public let maxPerMin: Int; public let failedAuthPerMinPerAddress: Int; public let headers: [String] }107 public let api: API108 public let services: [Service]109 public let keys: Keys?110 public let rateLimits: RateLimits111 /** every server lock, each with `on` and the server's sentence */112 public let capabilities: [ExecutionLock]?113 public let ts: Int114}115116public struct Webhook: Decodable, Sendable, Equatable, Identifiable {117 public let id: String; public let url: String; public let events: [String]; public let enabled: Bool; public let label: String?118 public let createdAt: Int?; public let lastOkAt: Int?; public let lastError: String?; public let failures: Int?; public let hasSecret: Bool?119}120public struct WebhookDelivery: Decodable, Sendable, Equatable, Identifiable {121 public let id: Int; public let webhookId: String; public let eventId: String?; public let event: String122 /** `pending`, `delivered`, `failed` */123 public let state: String124 public let attempts: Int?; public let nextAttemptAt: Int?; public let lastStatus: Int?; public let lastError: String?; public let createdAt: Int?; public let deliveredAt: Int?125}126public struct WebhookList: Decodable, Sendable, Equatable {127 public struct Event: Decodable, Sendable, Equatable { public let event: String; public let emitted: Bool; public let description: String; public let payload: String }128 public struct Retry: Decodable, Sendable, Equatable { public let attempts: Int; public let backoffSec: [Double] }129 public let webhooks: [Webhook]130 public let events: [Event]131 public let deliveries: [WebhookDelivery]132 public let retry: Retry?133 /** how a delivery is signed, verbatim */134 public let signature: String?135}136/** The answer of the ONE call that creates a webhook or rotates its signing secret. Not Codable. */137public struct IssuedWebhookSecret: Sendable, CustomStringConvertible, CustomReflectable {138 public let webhook: Webhook139 public let secret: OneTimeSecret140 public var description: String { "IssuedWebhookSecret(\(webhook.id), secret: <redacted>)" }141 public var customMirror: Mirror { Mirror(self, children: ["webhook": webhook.id]) }142}143