framepayments-react-native 1.0.0 → 2.0.0

package/android/src/main/java/com/framepayments/reactnativeframe/FrameSDKModule.kt

@@ -22,6 +22,7 @@ class FrameSDKModule(reactContext: ReactApplicationContext) :
 
   private var checkoutPromise: Promise? = null
   private var cartPromise: Promise? = null
+  private var onboardingPromise: Promise? = null
 
   override fun getName(): String = "FrameSDK"
 
@@ -38,16 +39,18 @@ class FrameSDKModule(reactContext: ReactApplicationContext) :
 
   @ReactMethod
   fun presentCheckout(customerId: String?, amount: Double, promise: Promise) {
-    val activity = currentActivity ?: run {
+    val activity = reactApplicationContext.currentActivity ?: run {
       promise.reject("NO_ACTIVITY", "No current activity", null)
       return
     }
     checkoutPromise = promise
-    val intent = Intent(activity, FrameCheckoutActivity::class.java).apply {
-      putExtra(FrameCheckoutActivity.EXTRA_CUSTOMER_ID, customerId)
-      putExtra(FrameCheckoutActivity.EXTRA_AMOUNT, amount.toInt())
+    activity.runOnUiThread {
+      val intent = Intent(activity, FrameCheckoutActivity::class.java).apply {
+        putExtra(FrameCheckoutActivity.EXTRA_CUSTOMER_ID, customerId)
+        putExtra(FrameCheckoutActivity.EXTRA_AMOUNT, amount.toInt())
+      }
+      activity.startActivityForResult(intent, FrameCheckoutActivity.REQUEST_CODE)
     }
-    activity.startActivityForResult(intent, FrameCheckoutActivity.REQUEST_CODE)
   }
 
   @ReactMethod
@@ -57,7 +60,7 @@ class FrameSDKModule(reactContext: ReactApplicationContext) :
     shippingAmountInCents: Double,
     promise: Promise
   ) {
-    val activity = currentActivity ?: run {
+    val activity = reactApplicationContext.currentActivity ?: run {
       promise.reject("NO_ACTIVITY", "No current activity", null)
       return
     }
@@ -66,12 +69,35 @@ class FrameSDKModule(reactContext: ReactApplicationContext) :
       return
     }
     cartPromise = promise
-    val intent = Intent(activity, FrameFlowActivity::class.java).apply {
-      putExtra(FrameFlowActivity.EXTRA_CUSTOMER_ID, customerId)
-      putExtra(FrameFlowActivity.EXTRA_ITEMS_JSON, itemsJson)
-      putExtra(FrameFlowActivity.EXTRA_SHIPPING_CENTS, shippingAmountInCents.toInt())
+    activity.runOnUiThread {
+      val intent = Intent(activity, FrameFlowActivity::class.java).apply {
+        putExtra(FrameFlowActivity.EXTRA_CUSTOMER_ID, customerId)
+        putExtra(FrameFlowActivity.EXTRA_ITEMS_JSON, itemsJson)
+        putExtra(FrameFlowActivity.EXTRA_SHIPPING_CENTS, shippingAmountInCents.toInt())
+      }
+      activity.startActivityForResult(intent, FrameFlowActivity.REQUEST_CODE)
+    }
+  }
+
+  @ReactMethod
+  fun presentOnboarding(
+    accountId: String?,
+    capabilities: com.facebook.react.bridge.ReadableArray,
+    promise: Promise
+  ) {
+    val activity = reactApplicationContext.currentActivity ?: run {
+      promise.reject("NO_ACTIVITY", "No current activity", null)
+      return
+    }
+    val capabilitiesJson = readableArrayToJsonArray(capabilities)
+    onboardingPromise = promise
+    activity.runOnUiThread {
+      val intent = Intent(activity, FrameOnboardingActivity::class.java).apply {
+        putExtra(FrameOnboardingActivity.EXTRA_ACCOUNT_ID, accountId)
+        putExtra(FrameOnboardingActivity.EXTRA_CAPABILITIES_JSON, capabilitiesJson)
+      }
+      activity.startActivityForResult(intent, FrameOnboardingActivity.REQUEST_CODE)
     }
-    activity.startActivityForResult(intent, FrameFlowActivity.REQUEST_CODE)
   }
 
   private fun readableArrayToJson(items: com.facebook.react.bridge.ReadableArray): String? {
@@ -82,16 +108,25 @@ class FrameSDKModule(reactContext: ReactApplicationContext) :
       obj.put("id", item.getString("id"))
       obj.put("title", item.getString("title"))
       obj.put("amountInCents", item.getDouble("amountInCents").toInt())
-      obj.put("imageUrl", item.getString("imageUrl"))
+      obj.put("imageUrl", item.getString("imageUrl") ?: "")
       arr.put(obj)
     }
     return arr.toString()
   }
 
-  override fun onActivityResult(activity: Activity?, requestCode: Int, resultCode: Int, data: Intent?) {
+  private fun readableArrayToJsonArray(arr: com.facebook.react.bridge.ReadableArray): String {
+    val jsonArr = org.json.JSONArray()
+    for (i in 0 until arr.size()) {
+      arr.getString(i)?.let { jsonArr.put(it) }
+    }
+    return jsonArr.toString()
+  }
+
+  override fun onActivityResult(activity: Activity, requestCode: Int, resultCode: Int, data: Intent?) {
     when (requestCode) {
       FrameCheckoutActivity.REQUEST_CODE -> handleCheckoutResult(resultCode, data)
       FrameFlowActivity.REQUEST_CODE -> handleCartResult(resultCode, data)
+      FrameOnboardingActivity.REQUEST_CODE -> handleOnboardingResult(resultCode, data)
       else -> return
     }
   }
@@ -138,6 +173,23 @@ class FrameSDKModule(reactContext: ReactApplicationContext) :
     }
   }
 
+  private fun handleOnboardingResult(resultCode: Int, data: Intent?) {
+    val promise = onboardingPromise ?: return
+    onboardingPromise = null
+    val map = WritableNativeMap()
+    if (resultCode == Activity.RESULT_OK) {
+      map.putString("status", "completed")
+      val paymentMethodId = data?.getStringExtra(FrameOnboardingActivity.EXTRA_PAYMENT_METHOD_ID)
+      if (paymentMethodId != null) {
+        map.putString("paymentMethodId", paymentMethodId)
+      }
+      promise.resolve(map)
+    } else {
+      map.putString("status", "cancelled")
+      promise.resolve(map)
+    }
+  }
+
   private fun jsonObjectToWritableMap(obj: JSONObject): WritableNativeMap {
     val map = WritableNativeMap()
     for (key in obj.keys()) {
@@ -171,5 +223,5 @@ class FrameSDKModule(reactContext: ReactApplicationContext) :
     return list
   }
 
-  override fun onNewIntent(intent: Intent?) {}
+  override fun onNewIntent(intent: Intent) {}
 }

package/ios/FramePreloader.swift

@@ -0,0 +1,28 @@
+//
+//  FramePreloader.swift
+//  FrameReactNative
+//
+//  Preloads the Frame module on the main thread BEFORE the React Native bridge
+//  initializes. This avoids "Helpers are not supported by the default hub" crash
+//  that occurs when Frame/Evervault/Sift load on a background thread during
+//  bridge module discovery.
+//
+
+import Foundation
+import Frame
+
+@objc(FramePreloader)
+public final class FramePreloader: NSObject {
+
+    /// Call from AppDelegate before [super application:didFinishLaunchingWithOptions].
+    /// Forces Frame (and its deps: Evervault, Sift) to load on main thread.
+    @objc public static func preloadOnMainThread() {
+        guard Thread.isMainThread else {
+            DispatchQueue.main.sync { preloadOnMainThread() }
+            return
+        }
+        // Touch FrameNetworking to trigger Frame module load on main thread.
+        // Evervault/Sift config is deferred to initializeWithAPIKey.
+        _ = FrameNetworking.shared
+    }
+}

package/ios/FrameReactNative.podspec

@@ -16,10 +16,16 @@ Pod::Spec.new do |s|
 
   s.dependency 'React-Core'
 
-  # Frame-iOS SDK – must be available to the app. Add via Swift Package Manager in Xcode:
-  # File → Add Package Dependencies → https://github.com/Frame-Payments/frame-ios
-  # Our native code imports Frame; ensure the app target links Frame-iOS (SPM).
-  # If Frame-iOS is provided as a pod in the future, uncomment:
+  # Frame-iOS SDK (Frame + FrameOnboarding) must be available to the app.
+  #
+  # SPM users (RN >= 0.73): add framepayments-react-native via Swift Package Manager.
+  # Frame and FrameOnboarding are declared as dependencies in Package.swift and resolve
+  # automatically — no manual step required.
+  #
+  # CocoaPods users: add frame-ios manually via Xcode:
+  #   File → Add Package Dependencies → https://github.com/Frame-Payments/frame-ios
+  #   Add both the "Frame-iOS" and "Frame-Onboarding" products to your app target.
+  # If Frame-iOS is published as a pod in the future, replace the above with:
   # s.dependency 'Frame-iOS'
 
   install_modules_dependencies(s) if respond_to?(:install_modules_dependencies)

package/ios/FrameSDKBridge.m

@@ -2,10 +2,28 @@
 //  FrameSDKBridge.m
 //  FrameReactNative
 //
+//  ObjC adapter that forwards to Swift FrameSDKBridge.
+//
 
 #import <React/RCTBridgeModule.h>
+#import "FrameVCHelper.h"
+
+// Import app's Swift header (ObjCFrameSDKBridge, FramePreloader). The example uses FrameExampleTemp.
+// If your app has a different module name, add Preprocessor Macro: FRAME_SWIFT_HEADER="YourApp-Swift.h"
+#if defined(FRAME_SWIFT_HEADER)
+#import FRAME_SWIFT_HEADER
+#elif __has_include("FrameExampleTemp-Swift.h")
+#import "FrameExampleTemp-Swift.h"
+#elif __has_include(<FrameExampleTemp/FrameExampleTemp-Swift.h>)
+#import <FrameExampleTemp/FrameExampleTemp-Swift.h>
+#else
+#error "Swift header not found. Add FRAME_SWIFT_HEADER=\"YourApp-Swift.h\" to your app target's Preprocessor Macros, or ensure Swift files compile before this file."
+#endif
 
-@interface RCT_EXTERN_MODULE(FrameSDK, FrameSDKBridge)
+@interface FrameSDKModule : NSObject <RCTBridgeModule>
+@end
+
+@interface RCT_EXTERN_MODULE(FrameSDK, FrameSDKModule)
 
 RCT_EXTERN_METHOD(initialize:(NSString *)apiKey
                   debugMode:(BOOL)debugMode
@@ -23,4 +41,58 @@ RCT_EXTERN_METHOD(presentCart:(id)customerId
                   resolver:(RCTPromiseResolveBlock)resolve
                   rejecter:(RCTPromiseRejectBlock)reject)
 
+RCT_EXTERN_METHOD(presentOnboarding:(id)accountId
+                  capabilities:(NSArray *)capabilities
+                  resolver:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
+@end
+
+@implementation FrameSDK
+@end
+
+@implementation FrameSDKModule
+
++ (BOOL)requiresMainQueueSetup {
+  return YES;
+}
+
+- (void)initialize:(NSString *)apiKey debugMode:(BOOL)debugMode resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject {
+  [[[ObjCFrameSDKBridge alloc] init] initialize:apiKey debugMode:debugMode resolver:resolve rejecter:reject];
+}
+
+- (void)presentCheckout:(id)customerId amount:(NSNumber *)amount resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject {
+  dispatch_async(dispatch_get_main_queue(), ^{
+    UIViewController *topVC = FrameGetTopViewController();
+    if (!topVC) {
+      reject(@"NO_ROOT_VC", @"Could not find root view controller to present checkout", nil);
+      return;
+    }
+    NSString *cId = [customerId isKindOfClass:[NSString class]] ? (NSString *)customerId : nil;
+    [[[ObjCFrameSDKBridge alloc] init] presentCheckoutFrom:topVC customerId:cId amount:amount.intValue resolver:resolve rejecter:reject];
+  });
+}
+
+- (void)presentCart:(id)customerId items:(NSArray *)items shippingAmountInCents:(NSNumber *)shippingAmountInCents resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject {
+  dispatch_async(dispatch_get_main_queue(), ^{
+    UIViewController *topVC = FrameGetTopViewController();
+    if (!topVC) {
+      reject(@"NO_ROOT_VC", @"Could not find root view controller to present cart", nil);
+      return;
+    }
+    [[[ObjCFrameSDKBridge alloc] init] presentCartFrom:topVC customerId:customerId items:items shippingAmountInCents:shippingAmountInCents.integerValue resolver:resolve rejecter:reject];
+  });
+}
+
+- (void)presentOnboarding:(id)accountId capabilities:(NSArray *)capabilities resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject {
+  dispatch_async(dispatch_get_main_queue(), ^{
+    UIViewController *topVC = FrameGetTopViewController();
+    if (!topVC) {
+      reject(@"NO_ROOT_VC", @"Could not find root view controller to present onboarding", nil);
+      return;
+    }
+    [[[ObjCFrameSDKBridge alloc] init] presentOnboardingFrom:topVC accountId:accountId capabilities:capabilities resolver:resolve rejecter:reject];
+  });
+}
+
 @end

package/ios/FrameSDKBridge.swift

@@ -10,15 +10,16 @@ import React
 import UIKit
 import SwiftUI
 import Frame
+import FrameOnboarding
 
-@objc(FrameSDK)
-class FrameSDKBridge: NSObject {
+@objc(ObjCFrameSDKBridge)
+public class FrameSDKBridge: NSObject {
 
-  @objc static func requiresMainQueueSetup() -> Bool {
+  @objc public static func requiresMainQueueSetup() -> Bool {
     return true
   }
 
-  @objc
+  @objc public
   func initialize(_ apiKey: String, debugMode: Bool, resolver resolve: @escaping RCTPromiseResolveBlock, rejecter reject: @escaping RCTPromiseRejectBlock) {
     DispatchQueue.main.async {
       FrameNetworking.shared.initializeWithAPIKey(apiKey, debugMode: debugMode)
@@ -26,47 +27,58 @@ class FrameSDKBridge: NSObject {
     }
   }
 
-  @objc
-  func presentCheckout(_ customerId: NSObject, amount: NSNumber, resolver resolve: @escaping RCTPromiseResolveBlock, rejecter reject: @escaping RCTPromiseRejectBlock) {
-    let cId = customerId as? String
-    let amountInt = amount.intValue
-    DispatchQueue.main.async { [weak self] in
-      self?.presentCheckoutOnMain(customerId: cId, amount: amountInt, resolve: resolve, reject: reject)
-    }
+  @objc public
+  func presentCheckout(from viewController: UIViewController, customerId: String?, amount: Int, resolver resolve: @escaping RCTPromiseResolveBlock, rejecter reject: @escaping RCTPromiseRejectBlock) {
+    presentCheckoutOnMain(from: viewController, customerId: customerId, amount: amount, resolve: resolve, reject: reject)
   }
 
-  private func presentCheckoutOnMain(customerId: String?, amount: Int, resolve: @escaping RCTPromiseResolveBlock, reject: @escaping RCTPromiseRejectBlock) {
-    guard let windowScene = UIApplication.shared.connectedScenes
-      .compactMap({ $0 as? UIWindowScene })
-      .first(where: { $0.activationState == .foregroundActive }),
-          let rootVC = windowScene.windows.first(where: { $0.isKeyWindow })?.rootViewController else {
-      reject("NO_ROOT_VC", "Could not find root view controller to present checkout", nil)
+  @objc public
+  func presentCart(from viewController: UIViewController, customerId: NSObject?, items: NSArray, shippingAmountInCents: Int, resolver resolve: @escaping RCTPromiseResolveBlock, rejecter reject: @escaping RCTPromiseRejectBlock) {
+    guard let cartItems = parseCartItems(items) else {
+      reject("INVALID_ITEMS", "Invalid cart items array", nil)
       return
     }
-    var top = rootVC
-    while let presented = top.presentedViewController { top = presented }
-    let delegate = CheckoutDismissDelegate(resolve: resolve, reject: reject)
-    let checkoutView = FrameCheckoutView(
+    presentCartOnMain(from: viewController, customerId: customerId as? String, cartItems: cartItems, shippingAmountInCents: shippingAmountInCents, resolve: resolve, reject: reject)
+  }
+
+  @objc public
+  func presentOnboarding(from viewController: UIViewController, accountId: NSObject?, capabilities: NSArray, resolver resolve: @escaping RCTPromiseResolveBlock, rejecter reject: @escaping RCTPromiseRejectBlock) {
+    let parsedCapabilities = parseCapabilities(capabilities)
+    let accountIdString = accountId as? String
+    presentOnboardingOnMain(from: viewController, accountId: accountIdString, capabilities: parsedCapabilities, resolve: resolve, reject: reject)
+  }
+
+  // MARK: - Private helpers
+
+  private func presentCheckoutOnMain(from top: UIViewController, customerId: String?, amount: Int, resolve: @escaping RCTPromiseResolveBlock, reject: @escaping RCTPromiseRejectBlock) {
+    var hosting: CheckoutHostingController!
+    hosting = CheckoutHostingController(rootView: FrameCheckoutView(
       customerId: customerId,
       paymentAmount: amount,
-      checkoutCallback: { [weak top, weak delegate] chargeIntent in
-        delegate?.didComplete = true
-        top?.dismiss(animated: true)
-        if let dict = Self.encodeChargeIntent(chargeIntent) {
-          resolve(dict)
-        } else {
-          reject("ENCODE_ERROR", "Failed to encode charge intent", nil)
+      checkoutCallback: { [weak hosting] chargeIntent in
+        hosting?.didComplete = true
+        top.dismiss(animated: true)
+        DispatchQueue.main.async {
+          if let dict = Self.encodeChargeIntent(chargeIntent) {
+            resolve(dict)
+          } else {
+            reject("ENCODE_ERROR", "Failed to encode charge intent", nil)
+          }
         }
       }
-    )
-    let hosting = UIHostingController(rootView: checkoutView)
-    hosting.modalPresentationStyle = .pageSheet
+    ))
+    hosting.onCancel = {
+      DispatchQueue.main.async {
+        reject("USER_CANCELED", "User dismissed checkout without completing payment", nil)
+      }
+    }
+    hosting.modalPresentationStyle = UIModalPresentationStyle.pageSheet
     if let sheet = hosting.sheetPresentationController {
-      sheet.detents = [.large()]
+      sheet.detents = [UISheetPresentationController.Detent.large()]
+    }
+    top.present(hosting, animated: true) {
+      hosting.presentationController?.delegate = hosting
     }
-    objc_setAssociatedObject(hosting, &checkoutDismissKey, delegate, .OBJC_ASSOCIATION_RETAIN)
-    hosting.presentationController?.delegate = delegate
-    top.present(hosting, animated: true)
   }
 
   private static func encodeChargeIntent(_ intent: FrameObjects.ChargeIntent) -> [String: Any]? {
@@ -74,19 +86,6 @@ class FrameSDKBridge: NSObject {
     return try? JSONSerialization.jsonObject(with: data) as? [String: Any]
   }
 
-  @objc
-  func presentCart(_ customerId: NSObject, items: NSArray, shippingAmountInCents: NSNumber, resolver resolve: @escaping RCTPromiseResolveBlock, rejecter reject: @escaping RCTPromiseRejectBlock) {
-    let cId = customerId as? String
-    let shipping = shippingAmountInCents.intValue
-    guard let cartItems = parseCartItems(items) else {
-      reject("INVALID_ITEMS", "Invalid cart items array", nil)
-      return
-    }
-    DispatchQueue.main.async { [weak self] in
-      self?.presentCartOnMain(customerId: cId, cartItems: cartItems, shippingAmountInCents: shipping, resolve: resolve, reject: reject)
-    }
-  }
-
   private struct RNFrameCartItem: FrameCartItem {
     var id: String
     var imageURL: String
@@ -107,55 +106,135 @@ class FrameSDKBridge: NSObject {
     return result
   }
 
-  private func presentCartOnMain(customerId: String?, cartItems: [RNFrameCartItem], shippingAmountInCents: Int, resolve: @escaping RCTPromiseResolveBlock, reject: @escaping RCTPromiseRejectBlock) {
-    guard let windowScene = UIApplication.shared.connectedScenes
-      .compactMap({ $0 as? UIWindowScene })
-      .first(where: { $0.activationState == .foregroundActive }),
-          let rootVC = windowScene.windows.first(where: { $0.isKeyWindow })?.rootViewController else {
-      reject("NO_ROOT_VC", "Could not find root view controller to present cart", nil)
-      return
+  private func parseCapabilities(_ capabilities: NSArray) -> [FrameObjects.Capabilities] {
+    var result: [FrameObjects.Capabilities] = []
+    for item in capabilities {
+      guard let raw = item as? String,
+            let cap = FrameObjects.Capabilities(rawValue: raw) else { continue }
+      result.append(cap)
     }
-    var top = rootVC
-    while let presented = top.presentedViewController { top = presented }
+    return result
+  }
+
+  private func presentCartOnMain(from top: UIViewController, customerId: String?, cartItems: [RNFrameCartItem], shippingAmountInCents: Int, resolve: @escaping RCTPromiseResolveBlock, reject: @escaping RCTPromiseRejectBlock) {
     let cartView = FrameCartView(
       customer: nil,
       cartItems: cartItems,
       shippingAmountInCents: shippingAmountInCents
     )
     let hosting = UIHostingController(rootView: cartView)
-    hosting.modalPresentationStyle = .pageSheet
+    hosting.modalPresentationStyle = UIModalPresentationStyle.pageSheet
     if let sheet = hosting.sheetPresentationController {
-      sheet.detents = [.large()]
+      sheet.detents = [UISheetPresentationController.Detent.large()]
     }
     // When the sheet is dismissed (swipe or close), resolve. Note: FrameCartView does not expose ChargeIntent from nested checkout.
     let delegate = CartDismissDelegate(resolve: resolve)
     objc_setAssociatedObject(hosting, &cartDismissKey, delegate, .OBJC_ASSOCIATION_RETAIN)
-    hosting.presentationController?.delegate = delegate
-    top.present(hosting, animated: true)
+    top.present(hosting, animated: true) {
+      hosting.presentationController?.delegate = delegate
+    }
+  }
+
+  private func presentOnboardingOnMain(from top: UIViewController, accountId: String?, capabilities: [FrameObjects.Capabilities], resolve: @escaping RCTPromiseResolveBlock, reject: @escaping RCTPromiseRejectBlock) {
+    let hosting = OnboardingHostingController(
+      rootView: OnboardingContainerView(
+        accountId: accountId,
+        requiredCapabilities: capabilities
+      )
+    )
+    hosting.modalPresentationStyle = UIModalPresentationStyle.pageSheet
+    if let sheet = hosting.sheetPresentationController {
+      sheet.detents = [UISheetPresentationController.Detent.large()]
+    }
+    let delegate = OnboardingDismissDelegate(hosting: hosting, resolve: resolve)
+    objc_setAssociatedObject(hosting, &onboardingDismissKey, delegate, .OBJC_ASSOCIATION_RETAIN)
+    hosting.onProgrammaticDismiss = { [weak delegate] in
+      delegate?.finish(completed: true)
+    }
+    top.present(hosting, animated: true) {
+      hosting.presentationController?.delegate = delegate
+    }
   }
 }
 
-private final class CheckoutDismissDelegate: NSObject, UIAdaptivePresentationControllerDelegate {
-  let resolve: RCTPromiseResolveBlock
-  let reject: RCTPromiseRejectBlock
+// MARK: - CheckoutHostingController
+// Intercepts both dismiss paths for FrameCheckoutView:
+//   1. Programmatic: SwiftUI's @Environment(\.dismiss) routes through override dismiss().
+//   2. Swipe-to-dismiss: UIAdaptivePresentationControllerDelegate.presentationControllerDidDismiss fires.
+// In both cases, if the checkout callback hasn't fired, we reject the promise.
+// onCancel is guarded by `cancelled` so it only fires once regardless of dismiss path.
+
+private final class CheckoutHostingController: UIHostingController<FrameCheckoutView>, UIAdaptivePresentationControllerDelegate {
   var didComplete = false
-  init(resolve: @escaping RCTPromiseResolveBlock, reject: @escaping RCTPromiseRejectBlock) {
-    self.resolve = resolve
-    self.reject = reject
+  var onCancel: (() -> Void)?
+  private var cancelled = false
+
+  func cancel() {
+    guard !didComplete, !cancelled else { return }
+    cancelled = true
+    onCancel?()
+  }
+
+  override func dismiss(animated flag: Bool, completion: (() -> Void)? = nil) {
+    cancel()
+    super.dismiss(animated: flag, completion: completion)
   }
+
   func presentationControllerDidDismiss(_ presentationController: UIPresentationController) {
-    guard !didComplete else { return }
-    reject("USER_CANCELED", "User dismissed checkout without completing payment", nil)
+    cancel()
+  }
+}
+
+// MARK: - OnboardingHostingController
+// Subclass UIHostingController to intercept programmatic dismiss() calls from OnboardingContainerView.
+// When SwiftUI calls @Environment(\.dismiss), it routes through UIHostingController.dismiss(animated:).
+// We override this to set programmaticDismiss = true before forwarding.
+
+private final class OnboardingHostingController<V: View>: UIHostingController<V> {
+  var programmaticDismiss = false
+  var onProgrammaticDismiss: (() -> Void)?
+
+  override func dismiss(animated flag: Bool, completion: (() -> Void)? = nil) {
+    programmaticDismiss = true
+    super.dismiss(animated: flag, completion: { [weak self] in
+      self?.onProgrammaticDismiss?()
+      completion?()
+    })
   }
 }
 
+// MARK: - Delegates
+
 private final class CartDismissDelegate: NSObject, UIAdaptivePresentationControllerDelegate {
   let resolve: RCTPromiseResolveBlock
   init(resolve: @escaping RCTPromiseResolveBlock) { self.resolve = resolve }
   func presentationControllerDidDismiss(_ presentationController: UIPresentationController) {
-    resolve([String: Any]())
+    DispatchQueue.main.async { [resolve] in
+      resolve([String: Any]())
+    }
+  }
+}
+
+private final class OnboardingDismissDelegate: NSObject, UIAdaptivePresentationControllerDelegate {
+  let resolve: RCTPromiseResolveBlock
+  var didFinish = false
+
+  init(hosting: OnboardingHostingController<OnboardingContainerView>, resolve: @escaping RCTPromiseResolveBlock) {
+    self.resolve = resolve
+  }
+
+  func finish(completed: Bool) {
+    guard !didFinish else { return }
+    didFinish = true
+    DispatchQueue.main.async { [resolve, completed] in
+      resolve(["status": completed ? "completed" : "cancelled"])
+    }
+  }
+
+  func presentationControllerDidDismiss(_ presentationController: UIPresentationController) {
+    finish(completed: false)
   }
 }
 
 private var cartDismissKey: UInt8 = 0
-private var checkoutDismissKey: UInt8 = 0
+private var onboardingDismissKey: UInt8 = 0

package/ios/FrameVCHelper.h

@@ -0,0 +1,12 @@
+//
+//  FrameVCHelper.h
+//  FrameReactNative
+//
+
+#import <UIKit/UIKit.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+UIViewController * _Nullable FrameGetTopViewController(void);
+
+NS_ASSUME_NONNULL_END

package/ios/FrameVCHelper.m

@@ -0,0 +1,11 @@
+//
+//  FrameVCHelper.m
+//  FrameReactNative
+//
+
+#import "FrameVCHelper.h"
+#import <React/RCTUtils.h>
+
+UIViewController * _Nullable FrameGetTopViewController(void) {
+  return RCTPresentedViewController();
+}

package/lib/__tests__/native.test.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Unit tests for the native module bridge (initialize, presentCheckout, presentCart).
+ * NativeModules.FrameSDK is mocked.
+ */
+declare const mockInitialize: jest.Mock<Promise<void>, [_apiKey: string, _debugMode: boolean], any>;
+declare const mockPresentCheckout: jest.Mock<Promise<{
+    id: string;
+    amount: number;
+}>, [_customerId: unknown, _amount: number], any>;
+declare const mockPresentCart: jest.Mock<Promise<{
+    id: string;
+    amount: number;
+}>, [_customerId: unknown, _items: unknown[], _shipping: number], any>;
+declare let initialize: (opts: {
+    apiKey: string;
+    debugMode?: boolean;
+}) => void;
+declare let presentCheckout: (opts: {
+    customerId?: string | null;
+    amount: number;
+}) => Promise<unknown>;
+declare let presentCart: (opts: {
+    customerId?: string | null;
+    items: Array<{
+        id: string;
+        title: string;
+        amountInCents: number;
+        imageUrl: string;
+    }>;
+    shippingAmountInCents: number;
+}) => Promise<unknown>;
+//# sourceMappingURL=native.test.d.ts.map

package/lib/__tests__/native.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/native.test.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,QAAA,MAAM,cAAc,uEAAuE,CAAC;AAC5F,QAAA,MAAM,mBAAmB;;;iDAAqG,CAAC;AAC/H,QAAA,MAAM,eAAe;;;sEAA0H,CAAC;AAahJ,QAAA,IAAI,UAAU,EAAE,CAAC,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,KAAK,IAAI,CAAC;AACxE,QAAA,IAAI,eAAe,EAAE,CAAC,IAAI,EAAE;IAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAChG,QAAA,IAAI,WAAW,EAAE,CAAC,IAAI,EAAE;IACtB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,KAAK,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrF,qBAAqB,EAAE,MAAM,CAAC;CAC/B,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC"}