@tinkerlandai/indiana-react-native 0.9.2 → 0.10.1

package/native-sdk/ios/IndianaClient.swift

@@ -0,0 +1,601 @@
+import Foundation
+
+public enum IndianaSubscriptionProvider: String, Sendable { case stripe, apple, google, merchant }
+public struct IndianaSubscriptionPlan: Sendable {
+    public let productVersionId: UUID
+    public let seatQuantities: [String: Int]
+    public let featureQuantities: [UUID: Int]
+    public init(productVersionId: UUID, seatQuantities: [String: Int] = [:], featureQuantities: [UUID: Int] = [:]) {
+        self.productVersionId = productVersionId; self.seatQuantities = seatQuantities; self.featureQuantities = featureQuantities
+    }
+}
+
+extension IndianaClient {
+    /// Enables Push on this client. OS permission requests remain under the host App's control.
+    public func enablePush() throws {
+        try enablePush(storage: IndianaPushKeychain(scope: configuration.scope))
+    }
+    func enablePush(storage: any IndianaPushJournalStorage) throws {
+        guard pushIdentity == nil else { return }
+        let installation = try IndianaPushIdentity(storage: storage)
+        if customerToken != nil { pushBindingSequence = try installation.reserve() }
+        pushIdentity = installation; schedulePush()
+    }
+    private func schedulePush() {
+        guard pushIdentity != nil else { return }
+        if case .protectedStorageUnavailable = pushSynchronizationError { return }
+        let original = epoch
+        Task {
+            do { _ = try await syncPush() }
+            catch {
+                if epoch == original { pushSynchronizationError = (error as? IndianaClientError) ?? .temporaryUnavailable }
+            }
+        }
+    }
+    @discardableResult public func syncPush() async throws -> IndianaPushInstallationState? {
+        guard let installation = pushIdentity else { throw IndianaClientError.invalidConfiguration }
+        if case .protectedStorageUnavailable = pushSynchronizationError { throw IndianaClientError.protectedStorageUnavailable }
+        let original = epoch, token = customerToken, binding = pushBindingSequence
+        let state = try installation.state()
+        var missingDetach = false
+        if let sequence = state.detachSeq {
+            let command = try installation.command("detach", scope: configuration.scope, sequence: sequence)
+            do {
+                let bytes = try await http.send(path: "push/installations/detach", method: "POST", authorization: "", body: command)
+                let acknowledged = try decodePush(bytes, installation: state.installationId)
+                guard !acknowledged.bound, acknowledged.identitySeq == sequence else { throw IndianaClientError.invalidResponse }
+            } catch IndianaClientError.requestFailed(404) { missingDetach = true }
+              catch IndianaClientError.requestFailed(412) { /* fenced old logout */ }
+            if !missingDetach { try installation.clearDetach(sequence) }
+        }
+        guard original == epoch else { throw IndianaClientError.identityChanged }
+        guard let token else { if missingDetach { throw IndianaClientError.requestFailed(404) }; pushSynchronizationError = nil; return nil }
+        let proofCredential = try await preparedCustomerToken()
+        let command = try installation.command("bind", scope: configuration.scope, sequence: binding, credential: proofCredential)
+        let response = try await authenticated(path: "push/installations/bind", body: command, credential: proofCredential)
+        guard original == epoch else { throw IndianaClientError.identityChanged }
+        let result = try decodePush(response, installation: state.installationId)
+        guard result.bound, result.identitySeq == binding else { throw IndianaClientError.invalidResponse }
+        if missingDetach, let sequence = state.detachSeq, binding > sequence { try installation.clearDetach(sequence) }
+        pushSynchronizationError = nil; return result
+    }
+    public func readPushInstallation() async throws -> IndianaPushInstallationState {
+        guard let installation = pushIdentity, let token = customerToken else { throw IndianaClientError.unauthenticated }
+        let proofCredential = try await preparedCustomerToken()
+        let command = try installation.command("read", scope: configuration.scope, credential: proofCredential)
+        let bytes = try await authenticated(path: "push/installations/read", body: command, credential: proofCredential)
+        return try decodePush(bytes, installation: installation.state().installationId)
+    }
+    public func capturePushObservation() throws -> IndianaPushObservationTicket {
+        guard pushIdentity != nil else { throw IndianaClientError.invalidConfiguration }
+        pushObservationID = UUID()
+        return IndianaPushObservationTicket(client: pushClientID, identity: epoch, observation: pushObservationID)
+    }
+    @discardableResult public func recoverPushCounters() async throws -> IndianaPushInstallationState? {
+        guard let installation = pushIdentity else { throw IndianaClientError.invalidConfiguration }
+        let original = epoch, expected = pushBindingSequence
+        pushObservationID = UUID()
+        let remote = try await readPushInstallation()
+        guard original == epoch else { throw IndianaClientError.identityChanged }
+        pushBindingSequence = try installation.recover(remote: remote, expected: expected)
+        return try await syncPush()
+    }
+    @discardableResult public func observePush(_ observation: IndianaPushObservation, ticket: IndianaPushObservationTicket) async throws -> IndianaPushInstallationState? {
+        guard ticket.client == pushClientID, ticket.identity == epoch, ticket.observation == pushObservationID else { return nil }
+        guard let installation = pushIdentity, let token = customerToken else { throw IndianaClientError.unauthenticated }
+        _ = try await syncPush()
+        guard ticket.identity == epoch, ticket.observation == pushObservationID else { return nil }
+        let sequence = try installation.reserveAddress()
+        let proofCredential = try await preparedCustomerToken()
+        let command = try installation.command("address", scope: configuration.scope, sequence: sequence, credential: proofCredential, observation: observation)
+        let bytes = try await authenticated(path: "push/installations/address", body: command, credential: proofCredential)
+        guard ticket.identity == epoch else { throw IndianaClientError.identityChanged }
+        return try decodePush(bytes, installation: installation.state().installationId)
+    }
+    public func readPushPreference() async throws -> Data { try await authenticated(path: "messaging/preferences/read", body: Data(#"{"channel":"push"}"#.utf8)) }
+    /// Explicitly requests one security notification to prove control of a conflicting provider token.
+    /// The response contains only an expiry; the challenge is delivered by the native notification callback.
+    public func requestPushAddressRecovery(_ observation: IndianaPushObservation, ticket: IndianaPushObservationTicket) async throws -> IndianaPushRecoveryRequest {
+        let (installation, token) = try recoveryPushIdentity(observation, ticket: ticket)
+        _ = try await syncPush()
+        _ = try recoveryPushIdentity(observation, ticket: ticket)
+        let sequence = try installation.reserveAddress()
+        let proofCredential = try await preparedCustomerToken()
+        let body = try installation.command("recovery_request", scope: configuration.scope, sequence: sequence, credential: proofCredential, observation: observation)
+        let bytes = try await authenticated(path: "push/installations/recovery/request", body: body, credential: proofCredential)
+        _ = try recoveryPushIdentity(observation, ticket: ticket)
+        struct Reply: Decodable { let scope: IndianaScope; let recovery: IndianaPushRecoveryRequest }
+        guard bytes.count <= 32768, let reply = try? JSONDecoder().decode(Reply.self, from: bytes), reply.scope == configuration.scope,
+              reply.recovery.requested else { throw IndianaClientError.invalidResponse }
+        let formatter = ISO8601DateFormatter(); formatter.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
+        guard formatter.date(from: reply.recovery.expiresAt) != nil || ISO8601DateFormatter().date(from: reply.recovery.expiresAt) != nil else { throw IndianaClientError.invalidResponse }
+        return reply.recovery
+    }
+    /// Supply the opaque indiana_push_recovery value received by the native notification callback.
+    /// Reacquire the current provider token under a fresh observation ticket before confirming.
+    @discardableResult public func confirmPushAddressRecovery(_ challenge: String, observation: IndianaPushObservation, ticket: IndianaPushObservationTicket) async throws -> IndianaPushInstallationState {
+        let (installation, token) = try recoveryPushIdentity(observation, ticket: ticket)
+        let state = try installation.state()
+        guard state.addressSeq > 0 else { throw IndianaClientError.invalidConfiguration }
+        let proofCredential = try await preparedCustomerToken()
+        let body = try installation.command("recovery_confirm", scope: configuration.scope, sequence: state.addressSeq, credential: proofCredential, observation: observation, challenge: challenge)
+        let bytes = try await authenticated(path: "push/installations/recovery/confirm", body: body, credential: proofCredential)
+        _ = try recoveryPushIdentity(observation, ticket: ticket)
+        let result = try decodePush(bytes, installation: state.installationId)
+        guard try installation.state().addressSeq == state.addressSeq else { throw IndianaClientError.identityChanged }
+        guard result.bound, result.identitySeq == pushBindingSequence, result.addressSeq == state.addressSeq, result.connectionId == observation.connectionId, result.addressStatus == "active" else { throw IndianaClientError.invalidResponse }
+        return result
+    }
+    private func recoveryPushIdentity(_ observation: IndianaPushObservation, ticket: IndianaPushObservationTicket) throws -> (IndianaPushIdentity, String) {
+        guard ticket.client == pushClientID, ticket.identity == epoch, ticket.observation == pushObservationID else { throw IndianaClientError.identityChanged }
+        guard let installation = pushIdentity, let token = customerToken else { throw IndianaClientError.unauthenticated }
+        guard observation.connectionId != nil, observation.kind != nil, observation.token != nil,
+              observation.permission == .granted || observation.permission == .provisional else { throw IndianaClientError.invalidConfiguration }
+        return (installation, token)
+    }
+    /// Retain requestId when retrying after an uncertain response.
+    public func setPushPreference(allowed: Bool, revision: Int64, requestId: UUID = UUID()) async throws -> Data {
+        guard (0..<IndianaPushIdentity.maxSequence).contains(revision) else { throw IndianaClientError.invalidConfiguration }
+        let body = try JSONSerialization.data(withJSONObject: ["requestId": requestId.uuidString.lowercased(), "channel": "push", "state":allowed ? "allowed" : "denied", "expectedRevision":revision])
+        return try await authenticated(path: "messaging/preferences/set", body: body)
+    }
+    private func decodePush(_ bytes: Data, installation: UUID) throws -> IndianaPushInstallationState {
+        struct Reply: Decodable { let scope: IndianaScope; let installation: IndianaPushInstallationState }
+        guard bytes.count <= 32768, let reply = try? JSONDecoder().decode(Reply.self, from: bytes), reply.scope == configuration.scope else { throw IndianaClientError.invalidResponse }
+        try reply.installation.validate(installation: installation); return reply.installation
+    }
+}
+/// Current customer session; credentials are memory-only.
+public actor IndianaClient {
+    private let configuration: IndianaConfiguration
+    private let http: IndianaSessionTransport
+    private var publicPaywallContent: (@Sendable (IndianaJSON) async throws -> IndianaJSON)?
+    private var customerToken: String?
+    private var analyticsEvents: [[String: IndianaJSON]] = []
+    private var analyticsFlushing = false
+    private var analyticsTimer: Task<Void, Never>?
+    private var epoch = UUID()
+    private var credentialRevision: UInt64 = 0
+    private var pushIdentity: IndianaPushIdentity?
+    private var pushBindingSequence: Int64 = 0
+    private let pushClientID = UUID()
+    private var pushObservationID = UUID()
+    public private(set) var pushSynchronizationError: IndianaClientError?
+    private let nativeStore: any IndianaAppleStore
+    private let nativeStorage: any IndianaNativePendingStorage
+    private let durableFunnels: Bool
+    private var storeRestorePending: [String: (UUID, Data)] = [:]
+    private var recoveringNative = false
+    private var nativeReceiptPending: [UUID: (UUID, Data)] = [:]
+    private struct WeakFunnel { weak var value: IndianaFunnelSession? }
+    private var funnels: [WeakFunnel] = []
+    private struct WeakPaywall { weak var value: IndianaPaywallSession? }
+    private var paywalls: [WeakPaywall] = []
+    private struct WeakContent { weak var value: IndianaContentSession? }
+    private var contents: [WeakContent] = []
+    #if canImport(UIKit)
+    private struct WeakFeature { weak var value: IndianaFeatureClient? }
+    private var featuresClients: [WeakFeature] = []
+    #endif
+    public init(configuration: IndianaConfiguration, sessionConfiguration: URLSessionConfiguration = .ephemeral) { self.configuration = configuration; self.http = IndianaSessionTransport(IndianaURLTransport(configuration: configuration, sessionConfiguration: sessionConfiguration), scope: configuration.scope); self.nativeStore = AppleStorefront(); self.nativeStorage = IndianaNativePendingKeychain(scope: configuration.scope); self.durableFunnels = true }
+    init(configuration: IndianaConfiguration, http: any IndianaHTTP, store: (any IndianaAppleStore)? = nil, nativeStorage: (any IndianaNativePendingStorage)? = nil, publicPaywallContent: (@Sendable (IndianaJSON) async throws -> IndianaJSON)? = nil, sessionNow: @escaping @Sendable () -> Date = { Date() }) { self.publicPaywallContent = publicPaywallContent; self.configuration = configuration; self.http = IndianaSessionTransport(http, scope: configuration.scope, now: sessionNow); self.nativeStore = store ?? AppleStorefront(); self.nativeStorage = nativeStorage ?? IndianaNativePendingKeychain(scope: configuration.scope); self.durableFunnels = false }
+    public func identify(customerToken token: String) async throws {
+        guard token.range(of: "^gg_ct_[A-Za-z0-9_-]{32,128}$", options: .regularExpression) != nil else { throw IndianaClientError.unauthenticated }
+        try await installIdentity(token)
+    }
+    private func installIdentity(_ token: String, session: IndianaCustomerSession? = nil) async throws {
+        analyticsTimer?.cancel(); analyticsTimer = nil; analyticsEvents = []
+        if let pushIdentity { pushBindingSequence = try pushIdentity.reserve(); pushSynchronizationError = nil }
+        epoch = UUID(); pushObservationID = UUID(); customerToken = token; nativeReceiptPending = [:]; storeRestorePending = [:]
+        let previous = takeViews()
+        credentialRevision += 1; let revision = credentialRevision, original = epoch
+        let invalidated: @Sendable () async -> Void = { [weak self] in await self?.invalidateSession(revision: revision) }
+        if let session { try await http.identify(session, revision: revision, onInvalidated: invalidated) } else { await http.identify(token, revision: revision, onInvalidated: invalidated) }
+        if original == epoch { schedulePush() }
+        await closeViews(previous)
+        guard original == epoch else { throw IndianaClientError.identityChanged }
+    }
+
+    public func identify(session: IndianaCustomerSession) async throws {
+        try session.validate()
+        try await installIdentity(session.accessToken, session: session)
+    }
+    @discardableResult public func refreshSession() async throws -> IndianaCustomerSession { try await http.refresh() }
+    /// A host with its own credential owner can supply current Access Tokens without sharing Refresh Tokens.
+    public func setAccessTokenProvider(_ provider: (@Sendable () async throws -> String)?) async { await http.setAccessTokenProvider(provider) }
+    public func funnel(runToken: String, commandStorage: (any IndianaFunnelCommandStorage)? = nil) async throws -> IndianaFunnelSession {
+        let original = epoch
+        let storage = try commandStorage ?? (durableFunnels ? IndianaFunnelCommandKeychain(configuration: configuration, runToken: runToken) : nil)
+        let session = try IndianaFunnelSession(configuration: configuration, http: http, runToken: runToken, commandStorage: storage)
+        if let customerToken { try await session.identify(customerToken: customerToken) }
+        guard original == epoch else { await session.reset(); throw IndianaClientError.identityChanged }
+        funnels.removeAll { $0.value == nil }; funnels.append(WeakFunnel(value: session)); return session
+    }
+    public func paywall(paywallId: UUID? = nil, paywallVersionId: UUID? = nil, provider: IndianaSubscriptionProvider, currency: String, locale: String = "en") throws -> IndianaPaywallSession {
+        guard let token = customerToken else { throw IndianaClientError.unauthenticated }
+        let session = try IndianaPaywallSession(configuration: configuration, http: http, customerToken: token, paywallId: paywallId, versionId: paywallVersionId, provider: provider, currency: currency, locale: locale, content: publicPaywallContent)
+        paywalls.removeAll { $0.value == nil }; paywalls.append(WeakPaywall(value: session)); return session
+    }
+    #if canImport(UIKit)
+    public func features(attributes: [String: IndianaJSON] = [:]) async throws -> IndianaFeatureClient {
+        let original = epoch, configuration = configuration
+        guard customerToken != nil else { throw IndianaClientError.unauthenticated }
+        let client = await MainActor.run { IndianaFeatureClient(configuration: configuration, attributes: attributes) { [self] operation, input in try await customerOperation(operation, input: input) } }
+        guard original == epoch else { await client.close(); throw IndianaClientError.identityChanged }
+        featuresClients.removeAll { $0.value == nil }; featuresClients.append(WeakFeature(value: client)); return client
+    }
+    #endif
+    /// Persist requestId and the exact input before retrying an uncertain start.
+    public func startFunnel(_ input: [String: IndianaJSON], commandStorage: (any IndianaFunnelCommandStorage)? = nil) async throws -> IndianaFunnelSession {
+        guard input["customer"] == nil, input["customerData"] == nil, input["customerId"] == nil,
+              input["operation"] == nil || input["operation"]?.string == "start", let token = customerToken else { throw IndianaClientError.invalidConfiguration }
+        var command = input; command["operation"] = .string("start")
+        let encoder = JSONEncoder(); encoder.outputFormatting = [.sortedKeys]
+        let body = try encoder.encode(IndianaJSON.object(command)); try IndianaSchema.validate("command", data: body)
+        let original = epoch
+        let data = try await http.send(path: "funnels", method: "POST", authorization: token, body: body)
+        guard original == epoch else { throw IndianaClientError.identityChanged }; try IndianaSchema.validate("response", data: data)
+        let result = try JSONDecoder().decode(IndianaJSON.self, from: data)
+        guard let value = result.object, let runToken = value["runToken"]?.string, value["customerId"] == nil,
+              value["scope"]?.object?["projectId"]?.string == configuration.scope.projectId.uuidString.lowercased(), value["scope"]?.object?["environment"]?.string == configuration.scope.environment.rawValue,
+              value["run"]?.object?["source"]?.object?["id"] == command["funnelId"], value["run"]?.object?["locale"] == command["locale"], value["run"]?.object?["parameters"] == command["parameters"] else { throw IndianaClientError.invalidResponse }
+        return try await funnel(runToken: runToken, commandStorage: commandStorage)
+    }
+    public func track(_ name: String, properties: [String: IndianaJSON] = [:], eventID: UUID = UUID(), timestamp: Date = Date()) async throws {
+        guard customerToken != nil, analyticsEvents.count < 1000 else { throw IndianaClientError.unauthenticated }
+        let formatter = ISO8601DateFormatter(); formatter.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
+        let event: [String: IndianaJSON] = ["eventUuid": .string(eventID.uuidString.lowercased()), "timestamp": .string(formatter.string(from: timestamp)), "name": .string(name), "properties": .object(properties)]
+        let body = try JSONEncoder().encode(IndianaJSON.object(["events": .array([.object(event)])]))
+        guard body.count <= 60_000 else { throw IndianaClientError.invalidConfiguration }
+        try IndianaSchema.validate("customertrackEventsRequest", data: body); analyticsEvents.append(event)
+        if analyticsTimer == nil { analyticsTimer = Task { [weak self] in try? await Task.sleep(nanoseconds: 2_000_000_000); guard !Task.isCancelled else { return }; await self?.flushScheduledEvents() } }
+        if analyticsEvents.count >= 100 { _ = try await flush() }
+    }
+    private func flushScheduledEvents() async { analyticsTimer = nil; _ = try? await flush() }
+    @discardableResult public func flush() async throws -> IndianaAnalyticsReceipt {
+        guard customerToken != nil else { throw IndianaClientError.unauthenticated }
+        guard !analyticsFlushing else { throw IndianaClientError.temporaryUnavailable }
+        analyticsTimer?.cancel(); analyticsTimer = nil; analyticsFlushing = true; defer { analyticsFlushing = false }
+        let original = epoch; var remaining = analyticsEvents.count; var total = IndianaAnalyticsReceipt()
+        while remaining > 0 {
+            guard original == epoch else { throw IndianaClientError.identityChanged }
+            var batch: [[String: IndianaJSON]] = []
+            for event in analyticsEvents.prefix(min(remaining, 100)) {
+                let candidate = try JSONEncoder().encode(IndianaJSON.object(["events": .array((batch + [event]).map(IndianaJSON.object))]))
+                if !batch.isEmpty && candidate.count > 64_000 { break }; batch.append(event)
+            }
+            let result = try await customerOperation(.trackEvents, input: ["events": .array(batch.map(IndianaJSON.object))])
+            let receipt = try JSONDecoder().decode(IndianaAnalyticsReceipt.self, from: JSONEncoder().encode(result))
+            guard receipt.inserted + receipt.duplicates + receipt.rejected + receipt.skipped == batch.count else { throw IndianaClientError.invalidResponse }
+            analyticsEvents.removeFirst(batch.count); remaining -= batch.count; total.add(receipt)
+        }
+        return total
+    }
+    public func content(_ input: [String: IndianaJSON], locale: String = "en", inputs: [String: IndianaJSON] = [:]) async throws -> IndianaContentSession {
+        let original = epoch
+        let session = try IndianaContentSession(configuration: configuration, input: input, locale: locale, inputs: inputs) { [self] request in
+            try await customerOperation(.resolveContent, input: request)
+        }
+        _ = try await session.refresh()
+        guard original == epoch else { await session.close(); throw IndianaClientError.identityChanged }
+        contents.removeAll { $0.value == nil }; contents.append(WeakContent(value: session)); return session
+    }
+    private struct CustomerViews {
+        var funnels: [WeakFunnel] = []
+        var paywalls: [WeakPaywall] = []
+        var contents: [WeakContent] = []
+        #if canImport(UIKit)
+        var features: [WeakFeature] = []
+        #endif
+    }
+    private func takeViews() -> CustomerViews {
+        var previous = CustomerViews()
+        previous.funnels = funnels; funnels = []
+        previous.paywalls = paywalls; paywalls = []
+        previous.contents = contents; contents = []
+        #if canImport(UIKit)
+        previous.features = featuresClients; featuresClients = []
+        #endif
+        return previous
+    }
+    private func clearIdentity() -> CustomerViews {
+        analyticsTimer?.cancel(); analyticsTimer = nil; analyticsEvents = []
+        do { if let pushIdentity { _ = try pushIdentity.reserve(detach: true) }; pushSynchronizationError = nil }
+        catch { pushSynchronizationError = .protectedStorageUnavailable }
+        epoch = UUID(); pushObservationID = UUID(); customerToken = nil; pushBindingSequence = 0; nativeReceiptPending = [:]; storeRestorePending = [:]
+        return takeViews()
+    }
+    private func closeViews(_ previous: CustomerViews) async {
+        for entry in previous.funnels { if let flow = entry.value { await flow.reset() } }
+        for entry in previous.paywalls { if let wall = entry.value { await wall.close() } }
+        for entry in previous.contents { if let content = entry.value { await content.close() } }
+        #if canImport(UIKit)
+        for entry in previous.features { if let feature = entry.value { await feature.close() } }
+        #endif
+    }
+    private func invalidateSession(revision: UInt64) async {
+        guard revision == credentialRevision, customerToken != nil else { return }
+        let previous = clearIdentity()
+        schedulePush()
+        await closeViews(previous)
+    }
+    public func reset() async {
+        credentialRevision += 1; let revision = credentialRevision
+        let previous = clearIdentity()
+        await http.identify(nil, revision: revision)
+        schedulePush()
+        await closeViews(previous)
+    }
+    /// The relay runs on your backend and adds its API key. A Funnel run token is never used for order recovery.
+    public func recoverNativeOrders(using relay: @Sendable (Data) async throws -> Data, synchronizeStore: Bool = false) async throws -> [Data] {
+        guard let token = customerToken, configuration.scope.environment == .sandbox, !recoveringNative else { throw IndianaClientError.unauthenticated }
+        recoveringNative = true; defer { recoveringNative = false }; let original = epoch
+        let storage = nativeStorage
+        let records = try await storage.orders()
+        let scanned = synchronizeStore ? try await nativeStore.restore() : await nativeStore.scanUnfinished()
+        var responses: [Data] = []
+        for record in records {
+            let matching = scanned.filter { $0.productID == record.productId && $0.accountToken == record.accountToken }
+            let items: [ApplePurchaseEvidence?] = matching.isEmpty ? [nil] : matching.map { Optional($0) }
+            for item in items {
+                guard original == epoch else { throw IndianaClientError.identityChanged }
+                let command: (UUID, Data)
+                if let pending = nativeReceiptPending[record.orderId] { command = pending }
+                else {
+                    let requestId = UUID()
+                    var proof: IndianaJSON = .null
+                    if let item {
+                        guard item.signedTransaction.utf8.count <= 131072 else { throw IndianaClientError.invalidResponse }
+                        proof = .object(["provider":.string("apple"), "orderId":.string(record.orderId.uuidString.lowercased()), "receiptId":.string(record.receiptId.uuidString.lowercased()), "signedTransaction":.string(item.signedTransaction)])
+                    }
+                    let body: IndianaJSON = .object(["operation":.string("native_receipt"), "requestId":.string(requestId.uuidString.lowercased()), "customerToken":.string(token), "orderId":.string(record.orderId.uuidString.lowercased()), "receiptId":.string(record.receiptId.uuidString.lowercased()), "nativeEvidence":proof])
+                    command = (requestId, try JSONEncoder().encode(body)); nativeReceiptPending[record.orderId] = command
+                }
+                let credential = try await preparedCustomerToken()
+                guard original == epoch else { throw IndianaClientError.identityChanged }
+                var outgoing = try JSONSerialization.jsonObject(with: command.1) as! [String: Any]
+                outgoing["customerToken"] = credential
+                let payload = try JSONSerialization.data(withJSONObject: outgoing)
+                let bytes: Data
+                do { bytes = try await relay(payload) }
+                catch let error as IndianaClientError {
+                    guard original == epoch else { throw IndianaClientError.identityChanged }
+                    if case .requestFailed(let status) = error, status < 500, status != 425 {
+                        nativeReceiptPending.removeValue(forKey: record.orderId)
+                        if status == 403 || status == 404 { continue }
+                    }
+                    throw error
+                }
+                guard original == epoch else { throw IndianaClientError.identityChanged }
+                struct Reply: Decodable { let scope: IndianaScope; let requestId: UUID; let orderId: UUID; let receiptId: UUID; let orderStatus: String; let refunded: Bool; let nativeCompletion: IndianaNativeCompletion? }
+                guard bytes.count <= 262144, let reply = try? JSONDecoder().decode(Reply.self, from: bytes), reply.scope == configuration.scope, reply.requestId == command.0, reply.orderId == record.orderId, reply.receiptId == record.receiptId, ["created", "pending", "trialing", "paid", "cancelled", "failed"].contains(reply.orderStatus) else { throw IndianaClientError.invalidResponse }
+                if let completion = reply.nativeCompletion {
+                    guard completion.orderId == record.orderId, completion.receiptId == record.receiptId, (1...50).contains(completion.transactionIds.count), Set(completion.transactionIds).count == completion.transactionIds.count, completion.transactionIds.allSatisfy({ !$0.isEmpty && $0.count <= 255 }) else { throw IndianaClientError.invalidResponse }
+                    for transaction in scanned where transaction.productID == record.productId && transaction.accountToken == record.accountToken && completion.transactionIds.contains(transaction.transactionID) {
+                        try await nativeStore.finish(transactionID: transaction.transactionID, confirmedTransactionIDs: Set(completion.transactionIds))
+                    }
+                    if !completion.membership { try await storage.remove(record.orderId) }
+                }
+                nativeReceiptPending.removeValue(forKey: record.orderId); responses.append(bytes)
+            }
+        }
+        return responses
+    }
+    /// Restores store transactions after reinstall or a device change. No local order journal is required.
+    public func restorePurchases(synchronizeStore: Bool = false) async throws -> [Data] {
+        guard !recoveringNative else { throw IndianaClientError.temporaryUnavailable }
+        recoveringNative = true; defer { recoveringNative = false }
+        let original = epoch
+        guard customerToken != nil else { throw IndianaClientError.unauthenticated }
+        let scanned = synchronizeStore ? try await nativeStore.restore() : await nativeStore.scanCurrent()
+        guard original == epoch else { throw IndianaClientError.identityChanged }
+        guard scanned.count <= 100 else { throw IndianaClientError.invalidResponse }
+        var replies: [Data] = []
+        for purchase in scanned {
+            guard original == epoch else { throw IndianaClientError.identityChanged }
+            // Unbound historical or family-shared transactions are not automatically transferred to an app account.
+            guard let intent = purchase.accountToken else { continue }
+            replies.append(try await submitStorePurchase(purchase, intent: intent, original: original))
+        }
+        return replies
+    }
+    private func submitStorePurchase(_ purchase: ApplePurchaseEvidence, intent: UUID, original: UUID) async throws -> Data {
+        guard purchase.signedTransaction.utf8.count <= 131072 else { throw IndianaClientError.invalidResponse }
+        let command: (UUID, Data)
+        if let old = storeRestorePending[purchase.transactionID] { command = old }
+        else {
+            let id = UUID()
+            let input: IndianaJSON = .object(["requestId":.string(id.uuidString.lowercased()), "provider":.string("apple"), "purchaseIntentId":.string(intent.uuidString.lowercased()), "productId":.string(purchase.productID), "signedTransaction":.string(purchase.signedTransaction)])
+            command = (id, try JSONEncoder().encode(input)); storeRestorePending[purchase.transactionID] = command
+        }
+        let bytes = try await authenticated(path: "subscriptions/native/restore", body: command.1)
+        guard original == epoch else { throw IndianaClientError.identityChanged }
+        struct Completion: Decodable { let transactionIds: [String]; let membership: Bool }
+        struct Operation: Decodable { let requestId: UUID; let orderId: UUID; let purchaseIntentId: UUID; let status: String; let refunded: Bool; let completion: Completion? }
+        struct Reply: Decodable { let operation: Operation }
+        guard bytes.count <= 262144, let reply = try? JSONDecoder().decode(Reply.self, from: bytes), reply.operation.requestId == command.0, reply.operation.purchaseIntentId == intent, ["created","pending","trialing","paid","cancelled","failed"].contains(reply.operation.status) else { throw IndianaClientError.invalidResponse }
+        if let completion = reply.operation.completion {
+            guard (1...50).contains(completion.transactionIds.count), Set(completion.transactionIds).count == completion.transactionIds.count, completion.transactionIds.allSatisfy({ !$0.isEmpty && $0.count <= 255 }), completion.transactionIds.contains(purchase.transactionID) else { throw IndianaClientError.invalidResponse }
+            try await nativeStore.finish(transactionID: purchase.transactionID, confirmedTransactionIDs: Set(completion.transactionIds))
+            guard original == epoch else { throw IndianaClientError.identityChanged }
+        }
+        storeRestorePending.removeValue(forKey: purchase.transactionID)
+        return bytes
+    }
+    /// Reviews the actual StoreKit quote before opening the payment sheet, then verifies on the server before finish.
+    public func purchaseSubscription(operationId: UUID, confirm: @Sendable (AppleStoreQuote) async -> Bool) async throws -> Data {
+        try await purchaseSubscriptionOperation(operationId: operationId, replacing:false,confirm:confirm)
+    }
+    /// Apple determines upgrade/downgrade timing within the same subscription group.
+    public func switchSubscription(operationId: UUID, confirm: @Sendable (AppleStoreQuote) async -> Bool) async throws -> Data {
+        try await purchaseSubscriptionOperation(operationId: operationId, replacing:true,confirm:confirm)
+    }
+    private func purchaseSubscriptionOperation(operationId: UUID, replacing: Bool, confirm: @Sendable (AppleStoreQuote) async -> Bool) async throws -> Data {
+        guard !recoveringNative else { throw IndianaClientError.temporaryUnavailable }
+        recoveringNative = true; defer { recoveringNative = false }
+        let original = epoch, response = replacing ? try await update(operationId:operationId) : try await attach(operationId: operationId)
+        guard let root = try JSONDecoder().decode(IndianaJSON.self, from: response).object, let operation = root["operation"]?.object,
+              operation["operationId"]?.string.flatMap(UUID.init(uuidString:)) == operationId else { throw IndianaClientError.invalidResponse }
+        if ["complete", "effective", "cancelled", "failed"].contains(operation["status"]?.string ?? "") { return response }
+        guard let instruction = operation["nativePurchase"]?.object, instruction["provider"] == .string("apple"),
+              instruction["receiptId"]?.string.flatMap(UUID.init(uuidString:)) == operationId,
+              let order = instruction["orderId"]?.string.flatMap(UUID.init(uuidString:)), instruction["appAccountToken"]?.string.flatMap(UUID.init(uuidString:)) == order,
+              let product = instruction["productId"]?.string else { throw IndianaClientError.invalidResponse }
+        let replacement = instruction["replacement"]?.object
+        guard replacing == (replacement != nil), !replacing || replacement?["policy"] == .string("apple_store") else { throw IndianaClientError.invalidResponse }
+        let tokens: [UUID]
+        if let replacement {
+            guard case .array(let raw)? = replacement["sourceAccountTokens"], raw.count <= 50 else { throw IndianaClientError.invalidResponse }
+            tokens = try raw.map { guard let value=$0.string.flatMap(UUID.init(uuidString:)) else { throw IndianaClientError.invalidResponse };return value }
+        } else { tokens = [] }
+        let allowedIntents = Set(tokens + [order])
+        let scanned = await nativeStore.scanCurrent()
+        guard original == epoch else { throw IndianaClientError.identityChanged }
+        if let purchased = scanned.first(where: { $0.accountToken.map(allowedIntents.contains) == true && $0.productID == product }) { return try await submitStorePurchase(purchased, intent: purchased.accountToken!, original: original) }
+        let terms = try AppleStoreTerms(instruction), quote = try await nativeStore.quote(productID: product, terms: terms)
+        guard original == epoch else { throw IndianaClientError.identityChanged }
+        let accepted = await confirm(quote)
+        guard original == epoch else { throw IndianaClientError.identityChanged }
+        guard accepted else { return replacing ? try await update(operationId:operationId,intent:"cancel") : try await attach(operationId:operationId,intent:"cancel") }
+        let result = try await nativeStore.purchase(productID: product, accountToken: order, terms: terms)
+        guard original == epoch else { throw IndianaClientError.identityChanged }
+        if case .purchased(let purchase) = result {
+            // Deferred downgrades retain the current transaction until the next renewal.
+            if replacing && purchase.productID == replacement?["sourceProductId"]?.string { return response }
+            guard let intent = purchase.accountToken, allowedIntents.contains(intent), purchase.productID == product else { throw IndianaClientError.invalidResponse }
+            return try await submitStorePurchase(purchase, intent: intent, original: original)
+        }
+        if case .canceled = result { return replacing ? try await update(operationId:operationId,intent:"cancel") : try await attach(operationId:operationId,intent:"cancel") }
+        return response
+    }
+    public func readHoldings() async throws -> Data { try await authenticated(path: "customer-holdings", body: Data("{}".utf8)) }
+    public func checkEntitlement(internalFeatureId: UUID, quantity: String = "1", properties: [String: IndianaJSON] = [:]) async throws -> Data {
+        let requirement: IndianaJSON = .object(["internal_feature_id": .string(internalFeatureId.uuidString.lowercased()), "quantity": .string(quantity), "properties": .object(properties)])
+        let body = try JSONEncoder().encode(["requirement": requirement])
+        try IndianaSchema.validate("checkRequest", data: body)
+        let result = try await authenticated(path: "entitlements/check", body: body)
+        try IndianaSchema.validate("checkResponse", data: result)
+        return result
+    }
+    /// The merchant backend authenticates its user, selects the Customer and adds the Server Key.
+    /// Retain the command's idempotencyKey after an unknown result. No credential is sent to the relay.
+    public func trackUsage(command: [String: IndianaJSON], using relay: @Sendable (Data) async throws -> Data) async throws -> Data {
+        guard customerToken != nil else { throw IndianaClientError.unauthenticated }
+        let original = epoch
+        let body = try JSONEncoder().encode(command)
+        try IndianaSchema.validate("usageCommand", data: body)
+        let result: Data
+        do { result = try await relay(body) }
+        catch { guard original == epoch else { throw IndianaClientError.identityChanged }; throw error }
+        guard original == epoch else { throw IndianaClientError.identityChanged }
+        try IndianaSchema.validate("usageResponse", data: result)
+        struct Scoped: Decodable { let scope: IndianaScope }
+        guard let returned = try? JSONDecoder().decode(Scoped.self, from: result), returned.scope == configuration.scope else { throw IndianaClientError.invalidResponse }
+        return result
+    }
+    /// Preview persists no payment attempt. Keep requestId when retrying; native execution requires server channel support.
+    public func previewAttach(requestId: UUID, plans: [IndianaSubscriptionPlan], provider: IndianaSubscriptionProvider, currency: String, billingSubscriptionId: UUID? = nil, offerId: UUID? = nil, nativeOffer: IndianaNativeStoreOffer? = nil) async throws -> Data {
+        guard (1...20).contains(plans.count), Set(plans.map(\.productVersionId)).count == plans.count,
+              currency.range(of: "^[A-Z]{3}$", options: .regularExpression) != nil,
+              plans.allSatisfy({ $0.featureQuantities.count <= 100 && $0.featureQuantities.values.allSatisfy { (0...10000).contains($0) } && $0.seatQuantities.count <= 20 && $0.seatQuantities.allSatisfy { $0.key.range(of: "^[a-z][a-z0-9_]{0,63}$", options: .regularExpression) != nil && (0...10000).contains($0.value) } }) else { throw IndianaClientError.invalidResponse }
+        let entries = plans.map { plan in IndianaJSON.object(["productVersionId":.string(plan.productVersionId.uuidString.lowercased()), "seatQuantities":.object(plan.seatQuantities.mapValues { .number(Double($0)) }), "featureQuantities":.object(Dictionary(uniqueKeysWithValues: plan.featureQuantities.map { ($0.key.uuidString.lowercased(), IndianaJSON.number(Double($0.value))) }))]) }
+        var fields: [String: IndianaJSON] = ["requestId":.string(requestId.uuidString.lowercased()), "plans":.array(entries), "provider":.string(provider.rawValue), "currency":.string(currency)]
+        if let billingSubscriptionId { fields["billingSubscriptionId"] = .string(billingSubscriptionId.uuidString.lowercased()) }
+        guard nativeOffer == nil || (nativeOffer!.matches(provider) && plans.count == 1),
+              offerId == nil || (billingSubscriptionId == nil && (provider == .stripe || provider == .merchant || nativeOffer != nil)) else { throw IndianaClientError.invalidResponse }
+        if let offerId { fields["offerId"] = .string(offerId.uuidString.lowercased()) }
+        if let nativeOffer { fields["nativeOffer"] = nativeOffer.wire }
+        let body: IndianaJSON = .object(fields)
+        return try await authenticated(path: "subscriptions/preview-attach", body: JSONEncoder().encode(body))
+    }
+    /// Execute only after reviewing and accepting the frozen quote. Retries recover the original order.
+    public func attach(operationId: UUID, intent:String="confirm") async throws -> Data {
+        guard ["confirm","cancel"].contains(intent) else { throw IndianaClientError.invalidResponse }
+        return try await authenticated(path: "subscriptions/attach", body: JSONEncoder().encode(["operationId": operationId.uuidString.lowercased(),"intent":intent]))
+    }
+    public func previewUpdate(requestId: UUID, membershipId: UUID, productVersionId: UUID, timing: String) async throws -> Data {
+        guard ["immediate", "renewal", "store"].contains(timing) else { throw IndianaClientError.invalidResponse }
+        let body: IndianaJSON = .object(["requestId":.string(requestId.uuidString.lowercased()),"membershipId":.string(membershipId.uuidString.lowercased()),"timing":.string(timing),"change":.object(["type":.string("plan"),"productVersionId":.string(productVersionId.uuidString.lowercased())])])
+        return try await authenticated(path: "subscriptions/preview-update", body: JSONEncoder().encode(body))
+    }
+    public func previewSeatUpdate(requestId: UUID, membershipId: UUID, licenseKey: String, quantity: Int, timing: String) async throws -> Data {
+        guard ["immediate", "renewal"].contains(timing), (0...10000).contains(quantity), licenseKey.range(of: "^[a-z][a-z0-9_]{0,63}$", options: .regularExpression) != nil else { throw IndianaClientError.invalidResponse }
+        let body: IndianaJSON = .object(["requestId":.string(requestId.uuidString.lowercased()),"membershipId":.string(membershipId.uuidString.lowercased()),"timing":.string(timing),"change":.object(["type":.string("seats"),"licenseKey":.string(licenseKey),"quantity":.number(Double(quantity))])])
+        return try await authenticated(path: "subscriptions/preview-update", body: JSONEncoder().encode(body))
+    }
+    public func previewQuantityUpdate(requestId: UUID, membershipId: UUID, internal_feature_id: UUID, quantity: Int, timing: String) async throws -> Data {
+        guard ["immediate", "renewal"].contains(timing), (0...10000).contains(quantity) else { throw IndianaClientError.invalidResponse }
+        let body: IndianaJSON = .object(["requestId":.string(requestId.uuidString.lowercased()),"membershipId":.string(membershipId.uuidString.lowercased()),"timing":.string(timing),"change":.object(["type":.string("quantity"),"internal_feature_id":.string(internal_feature_id.uuidString.lowercased()),"quantity":.number(Double(quantity))])])
+        return try await authenticated(path: "subscriptions/preview-update", body: JSONEncoder().encode(body))
+    }
+    /// Cancellation follows the billing channel of the held plan; App Store plans require store support.
+    public func previewCancellation(requestId: UUID, membershipId: UUID, timing: String) async throws -> Data {
+        guard ["immediate", "renewal"].contains(timing) else { throw IndianaClientError.invalidResponse }
+        let body: IndianaJSON = .object(["requestId":.string(requestId.uuidString.lowercased()),"membershipId":.string(membershipId.uuidString.lowercased()),"timing":.string(timing),"change":.object(["type":.string("cancel")])])
+        return try await authenticated(path: "subscriptions/preview-update", body: JSONEncoder().encode(body))
+    }
+    public func previewUncancel(requestId: UUID, membershipId: UUID) async throws -> Data {
+        let body: IndianaJSON = .object(["requestId":.string(requestId.uuidString.lowercased()),"membershipId":.string(membershipId.uuidString.lowercased()),"timing":.string("immediate"),"change":.object(["type":.string("uncancel")])])
+        return try await authenticated(path: "subscriptions/preview-update", body: JSONEncoder().encode(body))
+    }
+    public func update(operationId: UUID, intent:String="confirm") async throws -> Data { guard ["confirm","cancel"].contains(intent) else { throw IndianaClientError.invalidResponse };return try await authenticated(path: "subscriptions/update", body: JSONEncoder().encode(["operationId":operationId.uuidString.lowercased(),"intent":intent])) }
+    public func readSubscriptionUpdate(operationId: UUID) async throws -> Data { try await authenticated(path: "subscriptions/updates/read", body: JSONEncoder().encode(["operationId":operationId.uuidString.lowercased()])) }
+    public func readSubscriptionOperation(operationId: UUID) async throws -> Data {
+        try await authenticated(path: "subscriptions/operations/read", body: JSONEncoder().encode(["operationId": operationId.uuidString.lowercased()]))
+    }
+    public func readLedger(query: [String: IndianaJSON]) async throws -> Data {
+        let encoder = JSONEncoder(); encoder.outputFormatting = [.sortedKeys]
+        return try encoder.encode(try await customerOperation(.readLedger, input: ["query": .object(query)]))
+    }
+    public func quoteBalance(internal_feature_id: UUID, quantity: String, properties: [String: IndianaJSON] = [:]) async throws -> Data {
+        let command: IndianaJSON = .object(["operation":.string("quote"),"internal_feature_id":.string(internal_feature_id.uuidString.lowercased()),"quantity":.string(quantity),"properties":.object(properties)])
+        let encoder = JSONEncoder(); encoder.outputFormatting = [.sortedKeys]
+        return try await authenticated(path: "balances/quote", body: encoder.encode(["command":command]))
+    }
+    /// Execute a generated Customer operation under this client's current identity.
+    /// Server-only operations are absent from IndianaCustomerOperation.
+    public func customerOperation(_ operation: IndianaCustomerOperation, input: [String: IndianaJSON]) async throws -> IndianaJSON {
+        guard input["customerId"] == nil, input["customerToken"] == nil else { throw IndianaClientError.invalidConfiguration }
+        guard let token = customerToken else { throw IndianaClientError.unauthenticated }
+        let encoder = JSONEncoder(); encoder.outputFormatting = [.sortedKeys]
+        let defaults = IndianaCustomerSemantics.defaults(operation.rawValue, input)
+        try IndianaCustomerSemantics.preflight(operation.rawValue, defaults)
+        do { try IndianaSchema.validate("customer" + operation.rawValue + "Request", data: encoder.encode(IndianaJSON.object(defaults))) }
+        catch { throw IndianaClientError.invalidConfiguration }
+        let body = try encoder.encode(IndianaJSON.object(IndianaCustomerSemantics.request(operation.rawValue, defaults)))
+        let original = epoch
+        let data: Data
+        do { data = try await http.send(path: operation.path, method: operation.method, authorization: token, body: operation.method == "GET" ? nil : body) }
+        catch { guard original == epoch else { throw IndianaClientError.identityChanged }; throw error }
+        guard original == epoch else { throw IndianaClientError.identityChanged }
+        do { try IndianaSchema.validate("customer" + operation.rawValue + "Response", data: data) }
+        catch { throw IndianaClientError.invalidResponse }
+        let normalized: Data
+        do { normalized = try IndianaSchema.customerResponse("customer" + operation.rawValue + "Response", data: data) }
+        catch { throw IndianaClientError.invalidResponse }
+        let value = try JSONDecoder().decode(IndianaJSON.self, from: normalized)
+        try IndianaCustomerSemantics.response(operation.rawValue, value)
+        guard let scope = value.object?["scope"]?.object,
+              scope["projectId"]?.string.flatMap(UUID.init(uuidString:)) == configuration.scope.projectId,
+              scope["environment"]?.string == configuration.scope.environment.rawValue else { throw IndianaClientError.invalidResponse }
+        return value
+    }
+    private func preparedCustomerToken() async throws -> String {
+        let original = epoch; let value = try await http.access()
+        guard original == epoch else { throw IndianaClientError.identityChanged }; return value
+    }
+    private func authenticated(path: String, body: Data, credential: String? = nil) async throws -> Data {
+        if credential == nil, let operation = IndianaCustomerOperation.allCases.first(where: { $0.path == path }),
+           let input = try JSONDecoder().decode(IndianaJSON.self, from: body).object {
+            return try JSONEncoder().encode(try await customerOperation(operation, input: input))
+        }
+        guard customerToken != nil, let token = credential ?? customerToken else { throw IndianaClientError.unauthenticated }; let original = epoch
+        let bytes: Data
+        do { bytes = try await http.send(path: path, method: "POST", authorization: token, body: body) }
+        catch { guard original == epoch else { throw IndianaClientError.identityChanged }; throw error }
+        guard original == epoch else { throw IndianaClientError.identityChanged }
+        struct Scoped: Decodable { let scope: IndianaScope }
+        guard let returned = try? JSONDecoder().decode(Scoped.self, from: bytes), returned.scope == configuration.scope else { throw IndianaClientError.invalidResponse }
+        return bytes
+    }
+}