@onramper/onramper-react-native 1.2.2-1 → 1.3.0

package/ios/HybridOnramperCheckoutButton.swift

@@ -39,7 +39,7 @@ final class HybridOnramperCheckoutButton: HybridOnramperCheckoutButtonSpec {
       let entry = await PreparedIntentRegistry.shared.consume(handle)
       // A newer handle arrived while this one was being consumed; it owns the view.
       guard self.mountedHandle == handle else { return }
-      guard let entry else {
+      guard let entry, entry.isValid else {
         // Handle was invalidated or already consumed. Remove whatever an earlier
         // handle hosted, so a stale Buy button can't stay on screen.
         self.container.clear()

package/ios/HybridOnramperNitro.swift

@@ -9,51 +9,73 @@ import SwiftUI
 /// callbacks, and feeds the SDK's `sessionExpirationHandler` from a stored
 /// async JS callback. The public typed JS API lives in `OnramperClient.ts`.
 final class HybridOnramperNitro: HybridOnramperNitroSpec {
-  private var client: OnramperClient?
-  private var stateObservation: AnyCancellable?
-  private var transactionIdObservation: AnyCancellable?
-  private var eventTask: Task<Void, Never>?
-
-  private var onState: ((String) -> Void)?
-  private var onEvent: ((String) -> Void)?
-  private var onTransactionId: ((String?) -> Void)?
-  // Nitro wraps a callback's return value in a Promise; our callback already
-  // returns Promise<NitroSessionCredentials>, hence the doubly-nested Promise.
-  private var sessionHandler: (() -> Promise<Promise<NitroSessionCredentials>>)?
-
-  // Handle of the most recent prepared intent owned by *this* client, used to
-  // enforce single-flight per client without touching other clients' intents.
-  private var lastPreparedHandle: String?
+  private let logRelay = SDKLogRelay()
+  @MainActor private var client: OnramperClient?
+  @MainActor private var stateObservation: AnyCancellable?
+  @MainActor private var transactionIdObservation: AnyCancellable?
+  @MainActor private var eventTask: Task<Void, Never>?
+
+  private let lifetime = PreparedIntentLifetime()
+  private let callbackLock = NSLock()
+  private struct Callbacks {
+    var onState: ((String) -> Void)?
+    var onEvent: ((String) -> Void)?
+    var onTransactionId: ((String?) -> Void)?
+    // Nitro wraps the async JS callback's own returned Promise.
+    var sessionHandler: (() -> Promise<Promise<NitroSessionCredentials>>)?
+  }
+  private var callbacks = Callbacks()
+
+  private func withCallbacks<Value>(_ body: (inout Callbacks) -> Value) -> Value {
+    callbackLock.lock()
+    defer { callbackLock.unlock() }
+    return body(&callbacks)
+  }
 
   // MARK: - Listener registration (synchronous)
 
+  func setLogListener(onLog: @escaping (String) -> Void) {
+    logRelay.setListener(onLog)
+  }
+
   func setStateListener(onState: @escaping (String) -> Void) {
-    self.onState = onState
+    withCallbacks { $0.onState = onState }
   }
 
   func setEventListener(onEvent: @escaping (String) -> Void) {
-    self.onEvent = onEvent
+    withCallbacks { $0.onEvent = onEvent }
   }
 
   func setTransactionIdListener(onTransactionId: @escaping (String?) -> Void) {
-    self.onTransactionId = onTransactionId
+    withCallbacks { $0.onTransactionId = onTransactionId }
   }
 
   func setSessionExpirationHandler(handler: @escaping () -> Promise<Promise<NitroSessionCredentials>>) {
-    self.sessionHandler = handler
+    withCallbacks { $0.sessionHandler = handler }
+  }
+
+  /// Also used by reset/signOut: invalidate synchronously before scheduling
+  /// asynchronous SDK work, so old results cannot become usable buttons.
+  private func beginPreparation() throws -> PreparedIntentLifetime.Ticket {
+    do { return try lifetime.begin() } catch { throw bridgeSDKError(error) }
   }
 
   // MARK: - Lifecycle
 
   func configure(config: OnramperNitroConfig) throws -> Promise<Void> {
     return Promise.async { [weak self] in
-      guard let self else { return }
-      try await self.performConfigure(config)
+      do {
+        guard let self else { throw BridgeLifecycleError.clientDestroyed }
+        try await self.performConfigure(config)
+      } catch {
+        throw bridgeSDKError(error)
+      }
     }
   }
 
   @MainActor
   private func performConfigure(_ config: OnramperNitroConfig) async throws {
+    try lifetime.checkActive()
     // Idempotent: a second configure() with the SDK already built is a no-op.
     if client != nil { return }
 
@@ -75,24 +97,34 @@ final class HybridOnramperNitro: HybridOnramperNitroSpec {
       }
     }()
 
+    let relay = logRelay
     let swiftConfig = OnramperConfiguration(
       apiKey: config.apiKey,
       clientId: config.clientId,
       environment: environment,
       theme: theme,
       logLevel: logLevel,
+      logHandler: { record in
+        OnramperLog.systemHandler(record)
+        relay.emit(record)
+      },
+      isEventLoggingEnabled: config.isEventLoggingEnabled,
+      isEventConsoleLoggingEnabled: config.isEventConsoleLoggingEnabled,
       sessionExpirationHandler: { [weak self] in
-        guard let self, let handler = self.sessionHandler else {
+        guard let self, let handler = self.withCallbacks({ $0.sessionHandler }) else {
           throw OnramperError.userTokenRefreshFailed("no session expiration handler registered")
         }
         // Await twice: outer Promise = the callback invocation, inner Promise =
         // the JS async function's own returned Promise. Then map to the SDK type.
+        try self.lifetime.checkActive()
         let creds = try await handler().await().await()
+        try self.lifetime.checkActive()
         return SessionCredentials(sessionId: creds.sessionId, sessionToken: creds.sessionToken)
       }
     )
 
     let newClient = OnramperClient(configuration: swiftConfig)
+    try lifetime.checkActive()
     client = newClient
     attachObservers(to: newClient)
   }
@@ -100,10 +132,12 @@ final class HybridOnramperNitro: HybridOnramperNitroSpec {
   @MainActor
   private func attachObservers(to client: OnramperClient) {
     stateObservation = client.$state.sink { [weak self] state in
-      self?.onState?(jsonString(state.toJSDict()))
+      guard let self, (try? self.lifetime.checkActive()) != nil else { return }
+      self.withCallbacks { $0.onState }?(jsonString(state.toJSDict()))
     }
     transactionIdObservation = client.$currentTransactionId.sink { [weak self] transactionId in
-      self?.onTransactionId?(transactionId)
+      guard let self, (try? self.lifetime.checkActive()) != nil else { return }
+      self.withCallbacks { $0.onTransactionId }?(transactionId)
     }
     // `events` is a computed AsyncStream that captures a single continuation, so
     // access it exactly once here. CheckoutEvent is Sendable → safe to iterate
@@ -111,38 +145,59 @@ final class HybridOnramperNitro: HybridOnramperNitroSpec {
     let stream = client.events
     eventTask = Task { [weak self] in
       for await event in stream {
-        self?.onEvent?(jsonString(event.toJSDict()))
+        guard let self, !Task.isCancelled, (try? self.lifetime.checkActive()) != nil else { break }
+        self.withCallbacks { $0.onEvent }?(jsonString(event.toJSDict()))
       }
     }
   }
 
   @MainActor
   private func requireClient() throws -> OnramperClient {
+    try lifetime.checkActive()
     guard let client else { throw OnramperError.notInitialized }
     return client
   }
 
   func initialize(sessionId: String, sessionToken: String) throws -> Promise<Void> {
     return Promise.async { [weak self] in
-      guard let self else { return }
-      let client = try await self.requireClient()
-      try await client.initialize(sessionId: sessionId, sessionToken: sessionToken)
+      do {
+        guard let self else { throw BridgeLifecycleError.clientDestroyed }
+        let client = try await self.requireClient()
+        try await client.initialize(sessionId: sessionId, sessionToken: sessionToken)
+        try self.lifetime.checkActive()
+      } catch {
+        throw bridgeSDKError(error)
+      }
     }
   }
 
   func reset() throws -> Promise<Void> {
+    _ = try beginPreparation()
     return Promise.async { [weak self] in
-      guard let self else { return }
-      let client = try await self.requireClient()
-      await client.reset()
+      do {
+        guard let self else { throw BridgeLifecycleError.clientDestroyed }
+        let client = try await self.requireClient()
+        await PreparedIntentRegistry.shared.dropInvalidated(for: self.lifetime)
+        await client.reset()
+        try self.lifetime.checkActive()
+      } catch {
+        throw bridgeSDKError(error)
+      }
     }
   }
 
   func signOut() throws -> Promise<Void> {
+    _ = try beginPreparation()
     return Promise.async { [weak self] in
-      guard let self else { return }
-      let client = try await self.requireClient()
-      await client.signOut()
+      do {
+        guard let self else { throw BridgeLifecycleError.clientDestroyed }
+        let client = try await self.requireClient()
+        await PreparedIntentRegistry.shared.dropInvalidated(for: self.lifetime)
+        await client.signOut()
+        try self.lifetime.checkActive()
+      } catch {
+        throw bridgeSDKError(error)
+      }
     }
   }
 
@@ -153,13 +208,19 @@ final class HybridOnramperNitro: HybridOnramperNitroSpec {
     prefillJson: String,
     styleJson: String
   ) throws -> Promise<PreparedIntentResult> {
+    let ticket = try beginPreparation()
     return Promise.async { [weak self] in
-      guard let self else { throw OnramperError.notInitialized }
-      return try await self.performGetCheckoutRequirements(
-        requestJson: requestJson,
-        prefillJson: prefillJson,
-        styleJson: styleJson
-      )
+      do {
+        guard let self else { throw BridgeLifecycleError.clientDestroyed }
+        return try await self.performGetCheckoutRequirements(
+          requestJson: requestJson,
+          prefillJson: prefillJson,
+          styleJson: styleJson,
+          ticket: ticket
+        )
+      } catch {
+        throw bridgeSDKError(error)
+      }
     }
   }
 
@@ -167,37 +228,35 @@ final class HybridOnramperNitro: HybridOnramperNitroSpec {
   private func performGetCheckoutRequirements(
     requestJson: String,
     prefillJson: String,
-    styleJson: String
+    styleJson: String,
+    ticket: PreparedIntentLifetime.Ticket
   ) async throws -> PreparedIntentResult {
-    let client = try requireClient()
-    let request = try decodeCheckoutRequest(requestJson)
-    // Best-effort: an unusable prefill payload decodes to nil and the checkout
-    // proceeds without it. Never logged — the values are user PII, and the SDK
-    // makes the same guarantee at every log level.
-    let prefill = decodeUserPrefill(prefillJson)
-    let style = decodeCheckoutButtonStyle(styleJson)
-
-    // Single-flight, scoped to this client: a new prepared intent supersedes
-    // this instance's prior unconsumed one, but leaves other clients' intents
-    // in the shared registry untouched.
-    if let prev = lastPreparedHandle {
-      await PreparedIntentRegistry.shared.drop(prev)
+    let prepared = try await PreparedIntentRegistry.shared.prepare(ticket: ticket) { [self] in
+      try ticket.check()
+      let client = try requireClient()
+      let request = try decodeCheckoutRequest(requestJson)
+      // Best-effort; prefill values are never logged.
+      let prefill = decodeUserPrefill(prefillJson)
+      let style = decodeCheckoutButtonStyle(styleJson)
+      let result = try await client.getCheckoutRequirements(request, prefill: prefill, buttonStyle: style)
+      let entry = PreparedIntentRegistry.PreparedIntent(button: AnyView(result.button), createdAt: Date())
+      let quoteDict = (codableToJSValue(result.quote) as? [String: Any]) ?? [:]
+      return (entry, jsonString(quoteDict))
     }
-
-    let result = try await client.getCheckoutRequirements(request, prefill: prefill, buttonStyle: style)
-    let entry = PreparedIntentRegistry.PreparedIntent(button: AnyView(result.button), createdAt: Date())
-    let handle = await PreparedIntentRegistry.shared.store(entry)
-    lastPreparedHandle = handle
-    let quoteDict = (codableToJSValue(result.quote) as? [String: Any]) ?? [:]
-    return PreparedIntentResult(intentHandle: handle, quoteJson: jsonString(quoteDict))
+    try await PreparedIntentRegistry.shared.validateDelivery(of: prepared.handle, ticket: ticket)
+    return PreparedIntentResult(intentHandle: prepared.handle, quoteJson: prepared.value)
   }
 
   func cancelPreparedIntent(intentHandle: String) throws -> Promise<Void> {
-    if intentHandle == lastPreparedHandle {
-      lastPreparedHandle = nil
-    }
-    return Promise.async {
-      await PreparedIntentRegistry.shared.drop(intentHandle)
+    return Promise.async { [weak self] in
+      do {
+        guard let self else { throw BridgeLifecycleError.clientDestroyed }
+        try self.lifetime.checkActive()
+        await PreparedIntentRegistry.shared.drop(intentHandle, owner: self.lifetime)
+        try self.lifetime.checkActive()
+      } catch {
+        throw bridgeSDKError(error)
+      }
     }
   }
 
@@ -206,17 +265,20 @@ final class HybridOnramperNitro: HybridOnramperNitroSpec {
   /// Releases the stored JS callbacks (Nitro holds strong refs to them) and the
   /// SDK client. Called from `OnramperClient.destroy()` in JS.
   func dispose() {
-    stateObservation?.cancel()
-    stateObservation = nil
-    transactionIdObservation?.cancel()
-    transactionIdObservation = nil
-    eventTask?.cancel()
-    eventTask = nil
-    onState = nil
-    onEvent = nil
-    onTransactionId = nil
-    sessionHandler = nil
-    lastPreparedHandle = nil
-    client = nil
+    guard lifetime.destroy() else { return }
+    logRelay.setListener(nil)
+    withCallbacks { $0 = Callbacks() }
+    // SDK ownership and Combine subscriptions belong to the main actor.
+    // Tickets are already invalid even if this cleanup has not run yet.
+    Task { @MainActor [self] in
+      stateObservation?.cancel()
+      stateObservation = nil
+      transactionIdObservation?.cancel()
+      transactionIdObservation = nil
+      eventTask?.cancel()
+      eventTask = nil
+      client = nil
+      await PreparedIntentRegistry.shared.dropInvalidated(for: lifetime)
+    }
   }
 }

package/ios/OnramperSDKBridge.swift

@@ -19,6 +19,9 @@ extension OnramperError {
     case .networkError: return "networkError"
     case .decodingError: return "decodingError"
     case .timeout: return "timeout"
+    case .paymentFailed: return "paymentFailed"
+    case .providerFailed: return "providerFailed"
+    case .applePayNotConfigured: return "applePayNotConfigured"
     case .requirementNotSatisfied: return "requirementNotSatisfied"
     case .amountOutOfRange: return "amountOutOfRange"
     case .oidcFlowCancelled: return "oidcFlowCancelled"
@@ -73,9 +76,14 @@ extension OnramperError {
     }
   }
 
-  /// A JS-friendly error dict: `{ code, message, info? }`.
+  /// A JS-friendly error dict, including customer-facing copy and support code.
   func toJSDict() -> [String: Any] {
-    var dict: [String: Any] = ["code": jsCode, "message": errorDescription ?? "Unknown error"]
+    var dict: [String: Any] = [
+      "code": jsCode,
+      "message": errorDescription ?? "Unknown error",
+      "userMessage": userMessage,
+      "supportCode": supportCode,
+    ]
     if let info = jsInfo { dict["info"] = info }
     return dict
   }
@@ -149,6 +157,7 @@ extension OnramperState {
         "renderType": ctx.renderType.jsValue,
         "paymentType": ctx.paymentType.jsValue,
       ]
+    case .paymentPending: return ["kind": "paymentPending"]
     case .completed: return ["kind": "completed"]
     case .failed(let error):
       return ["kind": "failed", "error": error.toJSDict()]
@@ -188,6 +197,14 @@ extension CheckoutEvent {
       return ["type": "paymentAuthorized"]
     case .paymentProcessing:
       return ["type": "paymentProcessing"]
+    case .paymentPending:
+      return ["type": "paymentPending"]
+    case .challengeStarted:
+      return ["type": "challengeStarted"]
+    case .challengeCompleted:
+      return ["type": "challengeCompleted"]
+    case .customerOnboardingRequired:
+      return ["type": "customerOnboardingRequired"]
     case .paymentCancelled:
       return ["type": "paymentCancelled"]
     case .providerError(let reason):

package/ios/PreparedIntentRegistry.swift

@@ -2,6 +2,65 @@ import Foundation
 import Security
 import SwiftUI
 
+/// Issued synchronously at the Nitro boundary, so request order does not depend
+/// on when Promise.async happens to reach the main actor. Disposal can also
+/// invalidate tickets immediately from the JS thread.
+final class PreparedIntentLifetime: @unchecked Sendable {
+    private let lock = NSLock()
+    private var generation = UUID()
+    private var destroyed = false
+
+    struct Ticket {
+        fileprivate let owner: PreparedIntentLifetime
+        fileprivate let generation: UUID
+
+        func check() throws { try owner.check(generation: generation) }
+    }
+
+    func begin() throws -> Ticket {
+        lock.lock()
+        defer { lock.unlock() }
+        guard !destroyed else { throw BridgeLifecycleError.clientDestroyed }
+        generation = UUID()
+        return Ticket(owner: self, generation: generation)
+    }
+
+    func checkActive() throws { try check(generation: nil) }
+
+    private func check(generation expected: UUID?) throws {
+        lock.lock()
+        defer { lock.unlock() }
+        guard !destroyed else { throw BridgeLifecycleError.clientDestroyed }
+        if let expected, expected != generation { throw BridgeLifecycleError.intentInvalidated }
+    }
+
+    func destroy() -> Bool {
+        lock.lock()
+        defer { lock.unlock() }
+        guard !destroyed else { return false }
+        destroyed = true
+        return true
+    }
+}
+
+enum BridgeLifecycleError: String, Error {
+    case clientDestroyed
+    case intentInvalidated
+
+    var payload: [String: Any] {
+        switch self {
+        case .clientDestroyed:
+            return ["code": rawValue, "supportCode": rawValue,
+                    "message": "This OnramperClient has been destroyed. Create a new client before making SDK calls.",
+                    "userMessage": "This checkout session has ended. Please reopen checkout."]
+        case .intentInvalidated:
+            return ["code": rawValue, "supportCode": rawValue,
+                    "message": "This checkout preparation was superseded or cleared. Use the most recent request.",
+                    "userMessage": "Your checkout details have changed. Please use the latest quote."]
+        }
+    }
+}
+
 actor PreparedIntentRegistry {
     /// Process-wide registry. `getCheckoutRequirements` (on HybridOnramperNitro)
     /// stores the SwiftUI button under a ULID handle; the separate
@@ -12,10 +71,23 @@ actor PreparedIntentRegistry {
     struct PreparedIntent {
         let button: AnyView
         let createdAt: Date
-        var consumed: Bool = false
+        fileprivate var ticket: PreparedIntentLifetime.Ticket?
+
+        init(button: AnyView, createdAt: Date) {
+            self.button = button
+            self.createdAt = createdAt
+        }
+
+        // The main-actor view rechecks after the hop from the registry actor.
+        var isValid: Bool {
+            guard let ticket else { return true }
+            do { try ticket.check(); return true } catch { return false }
+        }
     }
 
     private var entries: [String: PreparedIntent] = [:]
+    // Internal diagnostics used by the standalone native regression suite.
+    var count: Int { entries.count }
     private let ttl: TimeInterval
 
     init(ttl: TimeInterval = 300) {
@@ -29,17 +101,63 @@ actor PreparedIntentRegistry {
         return handle
     }
 
+    /// The bridge uses this path so stale successes AND stale errors are
+    /// rejected consistently, including SDK cancellation errors. The operation
+    /// may still finish on the server; this only controls local button ownership.
+    func prepare<Value>(
+        ticket: PreparedIntentLifetime.Ticket,
+        operation: @MainActor () async throws -> (PreparedIntent, Value)
+    ) async throws -> (handle: String, value: Value) {
+        dropInvalidated(for: ticket.owner)
+        try ticket.check()
+        do {
+            let (entry, value) = try await operation()
+            try ticket.check()
+            sweepExpired()
+            let handle = Self.makeULID()
+            var ownedEntry = entry
+            ownedEntry.ticket = ticket
+            entries[handle] = ownedEntry
+            return (handle, value)
+        } catch {
+            try ticket.check()
+            throw error
+        }
+    }
+
     func consume(_ handle: String) -> PreparedIntent? {
-        guard var entry = entries[handle], !entry.consumed else { return nil }
-        entry.consumed = true
-        entries[handle] = entry
-        return entry
+        // Transfer ownership to the mounted view instead of retaining consumed
+        // SwiftUI views until some future quote request triggers a sweep.
+        guard let entry = entries.removeValue(forKey: handle),
+              Date().timeIntervalSince(entry.createdAt) < ttl else { return nil }
+        return entry.isValid ? entry : nil
+    }
+
+    /// Validate after the registry-to-main-actor hop, immediately before the
+    /// bridge returns the handle. A rejected result never reaches JavaScript,
+    /// so it must release its stored view without waiting for another sweep.
+    @MainActor
+    func validateDelivery(of handle: String, ticket: PreparedIntentLifetime.Ticket) async throws {
+        do {
+            try ticket.check()
+        } catch {
+            await drop(handle, owner: ticket.owner)
+            throw error
+        }
     }
 
-    func drop(_ handle: String) {
+    func drop(_ handle: String, owner: PreparedIntentLifetime? = nil) {
+        if let owner, entries[handle]?.ticket?.owner !== owner { return }
         entries.removeValue(forKey: handle)
     }
 
+    func dropInvalidated(for owner: PreparedIntentLifetime) {
+        entries = entries.filter { _, entry in
+            guard let ticket = entry.ticket, ticket.owner === owner else { return true }
+            do { try ticket.check(); return true } catch { return false }
+        }
+    }
+
     func invalidateAll() {
         entries.removeAll()
     }

package/ios/SDKLogRelay.swift

@@ -0,0 +1,41 @@
+import Foundation
+import NitroModules
+import OnramperSDK
+
+/// The SDK can emit records from any thread. Keep callback registration and
+/// teardown synchronized; invoke outside the lock (Nitro schedules delivery).
+final class SDKLogRelay: @unchecked Sendable {
+  private let lock = NSLock()
+  private var listener: ((String) -> Void)?
+
+  func setListener(_ listener: ((String) -> Void)?) {
+    lock.lock()
+    self.listener = listener
+    lock.unlock()
+  }
+
+  func emit(_ record: OnramperLogRecord) {
+    lock.lock()
+    let callback = listener
+    lock.unlock()
+    guard let callback else { return }
+    callback(jsonString([
+      "timestamp": record.timestamp.timeIntervalSince1970 * 1000,
+      "level": String(describing: record.level),
+      "category": record.category,
+      "event": record.event,
+      "context": record.context,
+      "message": record.message,
+    ]))
+  }
+}
+
+/// Nitro otherwise converts a Swift error to a message-only JavaScript Error.
+/// Both failed events and rejected operations must carry the SDK's safe copy.
+func bridgeSDKError(_ error: Error) -> Error {
+  if let lifecycleError = error as? BridgeLifecycleError {
+    return RuntimeError.error(withMessage: "ONRAMPER_ERROR:" + jsonString(lifecycleError.payload))
+  }
+  guard let sdkError = error as? OnramperError else { return error }
+  return RuntimeError.error(withMessage: "ONRAMPER_ERROR:" + jsonString(sdkError.toJSDict()))
+}