framepayments-react-native 3.0.0 → 4.0.0

package/ios/ProveAuthBridge.swift

@@ -0,0 +1,318 @@
+//
+//  ProveAuthBridge.swift
+//  FrameReactNative
+//
+//  Bridges Prove's iOS ProveAuth SDK to React Native. The JS surface:
+//
+//   - authenticate(authToken: String) → Promise<{ status: 'success' | 'failed' }>
+//   - submitOtp(code: String) → void   (call when JS shows the OTP fallback UI)
+//   - cancelOtp() → void
+//   - cancelAuth() → void              (force-cancel the in-flight authentication)
+//
+//   Event: `FrameProveOtpNeeded` — fires when the Prove SDK falls back to OTP.
+//   JS listens for the event, shows the OTP entry sheet, and calls submitOtp.
+//
+//  The Frame backend's confirmVerification call is NOT performed here — JS
+//  handles it via PhoneVerificationsAPI after authenticate() resolves success.
+//  We pass a no-op confirmHandler to AuthFinishStep so the SDK's state machine
+//  resolves the authenticate promise as soon as Prove finishes its part.
+//
+//  ProveAuth is loaded behind `#if canImport(ProveAuth)`; when the SDK isn't
+//  linked, authenticate() resolves PROVE_UNAVAILABLE so JS can fall back to
+//  the Frame OTP path.
+//
+//  Protocol shapes are verified against the Frame iOS 3.0.0 reference at
+//  Sources/FrameOnboarding/Services/ProveAuthService.swift:
+//    - ProveAuthFinishStep.execute(authId:)
+//    - OtpStartStep.execute(phoneNumberNeeded:phoneValidationError:callback:)
+//    - OtpFinishStep.execute(otpError:callback:)
+//
+
+import Foundation
+import React
+
+#if canImport(ProveAuth)
+import ProveAuth
+#endif
+
+@objc(FrameProveAuth)
+public class FrameProveAuth: RCTEventEmitter {
+
+  private static let EVENT_OTP_NEEDED = "FrameProveOtpNeeded"
+
+#if canImport(ProveAuth)
+  private var proveAuth: ProveAuth?
+  private var authFinishStep: BridgeAuthFinishStep?
+  private var otpStartStep: BridgeOtpStartStep?
+  private var otpFinishStep: BridgeOtpFinishStep?
+#endif
+
+  // Single-resume guard around the JS promise. Both the SDK completion
+  // callback and the AuthFinishStep onResult closure can fire — first one
+  // wins, the other no-ops via this nil-check.
+  private var authResolve: RCTPromiseResolveBlock?
+  private var authReject: RCTPromiseRejectBlock?
+
+  // Continuation handed to the OTP-finish step. Captured when the SDK calls
+  // OtpFinishStep.execute(...) and resumed by submitOtp/cancelOtp from JS.
+  // The Prove SDK can re-request OTP if the first code fails validation, so
+  // the bridge guards against an existing continuation by error-resuming the
+  // old one before installing the new one.
+  private var otpContinuation: ((String?) -> Void)?
+
+  // MARK: - RCTEventEmitter
+
+  public override static func requiresMainQueueSetup() -> Bool {
+    return false
+  }
+
+  public override func supportedEvents() -> [String] {
+    return [FrameProveAuth.EVENT_OTP_NEEDED]
+  }
+
+  // MARK: - JS API
+
+  @objc public func authenticate(_ authToken: String,
+                                  resolver resolve: @escaping RCTPromiseResolveBlock,
+                                  rejecter reject: @escaping RCTPromiseRejectBlock) {
+#if canImport(ProveAuth)
+    DispatchQueue.main.async { [weak self] in
+      guard let self = self else {
+        reject("PROVE_BRIDGE_GONE", "Prove bridge was deallocated.", nil)
+        return
+      }
+      guard self.authResolve == nil else {
+        reject("PROVE_BUSY", "A Prove authentication is already in flight.", nil)
+        return
+      }
+      self.authResolve = resolve
+      self.authReject = reject
+      self.startProveAuth(authToken: authToken)
+    }
+#else
+    // Prove SDK not linked in this build. Return a clean failure so JS can
+    // fall back to the Frame OTP path without surfacing a crash.
+    reject("PROVE_UNAVAILABLE", "Prove SDK is not linked in this app.", nil)
+#endif
+  }
+
+  @objc public func submitOtp(_ code: String,
+                               resolver resolve: @escaping RCTPromiseResolveBlock,
+                               rejecter reject: @escaping RCTPromiseRejectBlock) {
+    DispatchQueue.main.async { [weak self] in
+      guard let self = self else {
+        reject("PROVE_BRIDGE_GONE", "Prove bridge was deallocated.", nil)
+        return
+      }
+      guard let cont = self.otpContinuation else {
+        // OTP wasn't requested; treat as a no-op so JS error handlers don't
+        // double-throw on a stale OTP submit.
+        resolve(nil)
+        return
+      }
+      self.otpContinuation = nil
+      cont(code)
+      resolve(nil)
+    }
+  }
+
+  @objc public func cancelOtp(_ resolve: @escaping RCTPromiseResolveBlock,
+                               rejecter reject: @escaping RCTPromiseRejectBlock) {
+    DispatchQueue.main.async { [weak self] in
+      self?.otpContinuation?(nil)
+      self?.otpContinuation = nil
+      resolve(nil)
+    }
+  }
+
+  @objc public func cancelAuth(_ resolve: @escaping RCTPromiseResolveBlock,
+                                rejecter reject: @escaping RCTPromiseRejectBlock) {
+    DispatchQueue.main.async { [weak self] in
+      self?.otpContinuation?(nil)
+      self?.otpContinuation = nil
+      self?.handleAuthFailure(message: "Prove authentication canceled by user.")
+      resolve(nil)
+    }
+  }
+
+  // MARK: - Prove orchestration
+
+#if canImport(ProveAuth)
+  private func startProveAuth(authToken: String) {
+    // AuthFinishStep fires when Prove signals "device auth ok"; JS owns the
+    // backend confirm step, so we hand the SDK a no-op confirmHandler that
+    // returns success immediately.
+    let bridge = BridgeWeakBox(self)
+
+    self.authFinishStep = BridgeAuthFinishStep(
+      confirmHandler: { _, _ in /* JS owns the confirm step */ },
+      onResult: { result in
+        DispatchQueue.main.async {
+          bridge.value?.handleAuthResult(result)
+        }
+      }
+    )
+    self.otpStartStep = BridgeOtpStartStep(onOtpNeeded: {
+      DispatchQueue.main.async {
+        bridge.value?.emitOtpNeeded()
+      }
+    })
+    self.otpFinishStep = BridgeOtpFinishStep(otpProvider: {
+      // Suspend until submitOtp/cancelOtp resolves the continuation. If a
+      // prior continuation is somehow still live (Prove re-requested OTP
+      // before the first one was answered), fail the old one so it doesn't
+      // hang the SDK state machine.
+      return await withCheckedContinuation { cont in
+        DispatchQueue.main.async {
+          if let stale = bridge.value?.otpContinuation {
+            bridge.value?.otpContinuation = nil
+            stale(nil)
+          }
+          bridge.value?.otpContinuation = { code in cont.resume(returning: code) }
+        }
+      }
+    })
+
+    guard let authFinishStep = self.authFinishStep,
+          let otpStartStep = self.otpStartStep,
+          let otpFinishStep = self.otpFinishStep else { return }
+
+    self.proveAuth = ProveAuth.builder(authFinish: authFinishStep)
+      .withOtpFallback(otpStart: otpStartStep, otpFinish: otpFinishStep)
+      .build()
+
+    DispatchQueue.global(qos: .userInitiated).async { [weak self] in
+      guard let prove = self?.proveAuth else { return }
+      prove.authenticate(authToken: authToken) { error in
+        // Some Prove SDK versions deliver completion via AuthFinishStep;
+        // others surface terminal errors here. Both paths converge on the
+        // single-resume handleAuthFailure / handleAuthResult guard.
+        if error.errorDescription != nil {
+          DispatchQueue.main.async {
+            self?.handleAuthFailure(message: error.errorDescription ?? "Prove authentication failed.")
+          }
+        }
+      }
+    }
+  }
+
+  private func handleAuthResult(_ result: Result<Bool, Error>) {
+    switch result {
+    case .success:
+      finishAuthSuccess()
+    case .failure(let error):
+      handleAuthFailure(message: error.localizedDescription)
+    }
+  }
+#endif
+
+  private func emitOtpNeeded() {
+    self.sendEvent(withName: FrameProveAuth.EVENT_OTP_NEEDED, body: [:])
+  }
+
+  private func finishAuthSuccess() {
+    guard let resolve = self.authResolve else { return }
+    self.authResolve = nil
+    self.authReject = nil
+    resolve(["status": "success"])
+    // Defer SDK release until after the JS promise has resolved so any
+    // in-flight step closures aren't reading dangling references.
+    DispatchQueue.main.async { [weak self] in
+      self?.releaseRetainedSDKObjects()
+    }
+  }
+
+  private func handleAuthFailure(message: String) {
+    guard let resolve = self.authResolve else { return }
+    self.authResolve = nil
+    self.authReject = nil
+    resolve(["status": "failed", "message": message])
+    DispatchQueue.main.async { [weak self] in
+      self?.releaseRetainedSDKObjects()
+    }
+  }
+
+  private func releaseRetainedSDKObjects() {
+#if canImport(ProveAuth)
+    self.proveAuth = nil
+    self.authFinishStep = nil
+    self.otpStartStep = nil
+    self.otpFinishStep = nil
+#endif
+    self.otpContinuation = nil
+  }
+}
+
+// Weak wrapper used to thread the bridge through Prove SDK step closures
+// without creating retain cycles.
+private final class BridgeWeakBox<T: AnyObject> {
+  weak var value: T?
+  init(_ value: T) { self.value = value }
+}
+
+#if canImport(ProveAuth)
+
+// MARK: - Prove SDK step adapters (mirror Frame iOS ProveAuthService.swift)
+
+/// AuthFinishStep — fires `onResult(.success)` after Prove signals the device
+/// auth is complete and our (no-op) confirmHandler returns.
+private final class BridgeAuthFinishStep: NSObject, ProveAuthFinishStep, @unchecked Sendable {
+  private let confirmHandler: @Sendable (String, String) async throws -> Void
+  private let onResult: @Sendable (Result<Bool, Error>) -> Void
+
+  init(
+    confirmHandler: @escaping @Sendable (String, String) async throws -> Void,
+    onResult: @escaping @Sendable (Result<Bool, Error>) -> Void
+  ) {
+    self.confirmHandler = confirmHandler
+    self.onResult = onResult
+  }
+
+  func execute(authId: String) {
+    Task {
+      do {
+        try await confirmHandler("", "")
+        onResult(.success(true))
+      } catch {
+        onResult(.failure(error))
+      }
+    }
+  }
+}
+
+/// OtpStartStep — Prove tells us OTP fallback is starting. The phone number
+/// is already known to Prove (it came from authToken's claims), so we accept
+/// the start; phoneNumberNeeded=true is a misconfiguration → error.
+private final class BridgeOtpStartStep: NSObject, OtpStartStep, @unchecked Sendable {
+  private let onOtpNeeded: @Sendable () -> Void
+  init(onOtpNeeded: @escaping @Sendable () -> Void) { self.onOtpNeeded = onOtpNeeded }
+
+  func execute(phoneNumberNeeded: Bool, phoneValidationError: ProveAuthError?, callback: any OtpStartStepCallback) {
+    if phoneNumberNeeded {
+      callback.onError()
+    } else {
+      onOtpNeeded()
+      callback.onSuccess(input: nil)
+    }
+  }
+}
+
+/// OtpFinishStep — Prove asks the host to collect the OTP from the user. We
+/// await JS via the continuation provider; null means cancel.
+private final class BridgeOtpFinishStep: NSObject, OtpFinishStep, @unchecked Sendable {
+  private let otpProvider: @Sendable () async -> String?
+  init(otpProvider: @escaping @Sendable () async -> String?) { self.otpProvider = otpProvider }
+
+  func execute(otpError: ProveAuthError?, callback: any OtpFinishStepCallback) {
+    Task { @MainActor in
+      let otp = await otpProvider()
+      if let otp = otp {
+        callback.onSuccess(input: OtpFinishInput(otp: otp))
+      } else {
+        callback.onError()
+      }
+    }
+  }
+}
+
+#endif

package/lib/__mocks__/react-native-svg.d.ts

@@ -0,0 +1,19 @@
+import { View } from 'react-native';
+declare const Stub: typeof View;
+export declare const SvgXml: typeof View;
+export declare const Svg: typeof View;
+export declare const Circle: typeof View;
+export declare const Rect: typeof View;
+export declare const Path: typeof View;
+export declare const G: typeof View;
+export declare const Line: typeof View;
+export declare const Text: typeof View;
+export declare const Defs: typeof View;
+export declare const ClipPath: typeof View;
+export declare const LinearGradient: typeof View;
+export declare const Stop: typeof View;
+export declare const Polygon: typeof View;
+export declare const Polyline: typeof View;
+export declare const Ellipse: typeof View;
+export default Stub;
+//# sourceMappingURL=react-native-svg.d.ts.map

package/lib/__mocks__/react-native-svg.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react-native-svg.d.ts","sourceRoot":"","sources":["../../src/__mocks__/react-native-svg.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAEpC,QAAA,MAAM,IAAI,aAAO,CAAC;AAElB,eAAO,MAAM,MAAM,aAAO,CAAC;AAC3B,eAAO,MAAM,GAAG,aAAO,CAAC;AACxB,eAAO,MAAM,MAAM,aAAO,CAAC;AAC3B,eAAO,MAAM,IAAI,aAAO,CAAC;AACzB,eAAO,MAAM,IAAI,aAAO,CAAC;AACzB,eAAO,MAAM,CAAC,aAAO,CAAC;AACtB,eAAO,MAAM,IAAI,aAAO,CAAC;AACzB,eAAO,MAAM,IAAI,aAAO,CAAC;AACzB,eAAO,MAAM,IAAI,aAAO,CAAC;AACzB,eAAO,MAAM,QAAQ,aAAO,CAAC;AAC7B,eAAO,MAAM,cAAc,aAAO,CAAC;AACnC,eAAO,MAAM,IAAI,aAAO,CAAC;AACzB,eAAO,MAAM,OAAO,aAAO,CAAC;AAC5B,eAAO,MAAM,QAAQ,aAAO,CAAC;AAC7B,eAAO,MAAM,OAAO,aAAO,CAAC;AAE5B,eAAe,IAAI,CAAC"}

package/lib/__mocks__/react-native-svg.js

@@ -0,0 +1,21 @@
+// Jest stub for react-native-svg. The real package pulls in
+// `Touchable.Mixin` from react-native which is undefined under node, so we
+// short-circuit every public export to a no-op View component for tests.
+import { View } from 'react-native';
+const Stub = View;
+export const SvgXml = Stub;
+export const Svg = Stub;
+export const Circle = Stub;
+export const Rect = Stub;
+export const Path = Stub;
+export const G = Stub;
+export const Line = Stub;
+export const Text = Stub;
+export const Defs = Stub;
+export const ClipPath = Stub;
+export const LinearGradient = Stub;
+export const Stop = Stub;
+export const Polygon = Stub;
+export const Polyline = Stub;
+export const Ellipse = Stub;
+export default Stub;

package/lib/api-errors.d.ts

@@ -0,0 +1,6 @@
+import { type FrameErrorShape } from './errors';
+export declare const DEFAULT_TOAST_FALLBACK = "Something went wrong. Please try again.";
+export declare function toToastMessage(error: unknown, fallback?: string): string;
+export declare function isTransportError(error: unknown): boolean;
+export declare function toFrameError(error: unknown): FrameErrorShape;
+//# sourceMappingURL=api-errors.d.ts.map

package/lib/api-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-errors.d.ts","sourceRoot":"","sources":["../src/api-errors.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,UAAU,CAAC;AAElB,eAAO,MAAM,sBAAsB,4CAA4C,CAAC;AAehF,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,GAAE,MAA+B,GAAG,MAAM,CAUhG;AAID,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAKxD;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CAQ5D"}

package/lib/api-errors.js

@@ -0,0 +1,55 @@
+import { FrameAPIError } from 'framepayments';
+import { ErrorCodes, normalizeToFrameError, } from './errors';
+export const DEFAULT_TOAST_FALLBACK = 'Something went wrong. Please try again.';
+function extractFromEnvelope(raw) {
+    if (raw === null || typeof raw !== 'object')
+        return undefined;
+    const envelope = raw;
+    const details = envelope.error_details;
+    if (details && typeof details === 'object' && 'message' in details) {
+        const m = details.message;
+        if (typeof m === 'string' && m.length > 0)
+            return m;
+    }
+    if (typeof details === 'string' && details.length > 0)
+        return details;
+    if (typeof envelope.error === 'string' && envelope.error.length > 0)
+        return envelope.error;
+    return undefined;
+}
+export function toToastMessage(error, fallback = DEFAULT_TOAST_FALLBACK) {
+    if (error instanceof FrameAPIError) {
+        const fromEnvelope = extractFromEnvelope(error.raw);
+        if (fromEnvelope)
+            return `Error: ${fromEnvelope}`;
+        if (typeof error.message === 'string' && error.message.length > 0 && error.message !== 'An error occurred') {
+            return `Error: ${error.message}`;
+        }
+        return `Error: ${fallback}`;
+    }
+    return `Error: ${fallback}`;
+}
+// Non-FrameAPIError throws are treated as transport errors because they're
+// typically thrown before framepayments' interceptor wraps them.
+export function isTransportError(error) {
+    if (error instanceof FrameAPIError) {
+        return error.status === 0;
+    }
+    return true;
+}
+export function toFrameError(error) {
+    if (error instanceof FrameAPIError) {
+        return {
+            code: mapApiErrorCode(error),
+            message: extractFromEnvelope(error.raw) ?? error.message ?? DEFAULT_TOAST_FALLBACK,
+        };
+    }
+    return normalizeToFrameError(error);
+}
+function mapApiErrorCode(error) {
+    if (error.status === 0)
+        return ErrorCodes.API_NETWORK;
+    if (error.status >= 400 && error.status < 500)
+        return ErrorCodes.API_VALIDATION;
+    return ErrorCodes.API_ERROR;
+}

package/lib/applePay.d.ts

@@ -0,0 +1,57 @@
+import type { PresentApplePayOptions, WalletOwner } from './types';
+export interface ApplePayBridgePresentArgs {
+    amount: number;
+    currency: string;
+    applePayMerchantId: string;
+    countryCode?: string;
+    supportedNetworks?: ReadonlyArray<string>;
+}
+export interface ApplePayBridgeToken {
+    paymentData: string;
+    paymentMethod: {
+        displayName: string;
+        network: string;
+        type: string;
+    };
+    transactionIdentifier: string;
+}
+export interface ApplePayBridgeResponse {
+    token: ApplePayBridgeToken;
+    billingContact?: {
+        addressLines?: string[];
+        locality?: string;
+        administrativeArea?: string;
+        postalCode?: string;
+        countryCode?: string;
+    };
+    payerName?: string;
+    payerEmail?: string;
+}
+export declare function canMakeApplePay(): Promise<boolean>;
+/**
+ * Apple Pay token-out flow.
+ *   1. Ensure the device is attested (App Attest).
+ *   2. Present the PKPaymentAuthorizationController sheet via the bridge.
+ *   3. Generate a device assertion bound to the payment token.
+ *   4. Create the Apple Pay payment method via frame-node (publishable key).
+ *   5. Create a ChargeIntent (customer owner) or Transfer (account owner).
+ *   6. Settle the still-open Apple Pay sheet — success on success, failure on
+ *      any exception — so the spinner-stays-up UX matches the native flow.
+ */
+export declare function presentApplePayFlow(options: PresentApplePayOptions): Promise<string>;
+/**
+ * Apple Pay "add to owner" flow. Presents the sheet, attests the device,
+ * creates a tokenized Apple Pay payment method via frame-node, then settles
+ * the sheet — but does NOT create a ChargeIntent or Transfer. Used by the
+ * onboarding AddPaymentMethod screen so the host app can collect a saved
+ * Apple Pay token for the account / customer.
+ *
+ * The presented sheet renders a $1.00 placeholder line item because Apple
+ * Pay requires a non-zero amount to draw the authorization UI. The amount
+ * is never charged.
+ */
+export declare function addApplePayToOwnerFlow(options: {
+    owner: WalletOwner;
+    currency?: string;
+}): Promise<string>;
+//# sourceMappingURL=applePay.d.ts.map

package/lib/applePay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"applePay.d.ts","sourceRoot":"","sources":["../src/applePay.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAKnE,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACtE,qBAAqB,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,mBAAmB,CAAC;IAC3B,cAAc,CAAC,EAAE;QACf,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;QACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAuBD,wBAAsB,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC,CAGxD;AAED;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,MAAM,CAAC,CAiC1F;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GACjD,OAAO,CAAC,MAAM,CAAC,CA8CjB"}