framepayments-react-native 1.0.0

package/ios/FrameSDKBridge.swift

@@ -0,0 +1,161 @@
+//
+//  FrameSDKBridge.swift
+//  FrameReactNative
+//
+//  Bridges Frame iOS SDK to React Native.
+//
+
+import Foundation
+import React
+import UIKit
+import SwiftUI
+import Frame
+
+@objc(FrameSDK)
+class FrameSDKBridge: NSObject {
+
+  @objc static func requiresMainQueueSetup() -> Bool {
+    return true
+  }
+
+  @objc
+  func initialize(_ apiKey: String, debugMode: Bool, resolver resolve: @escaping RCTPromiseResolveBlock, rejecter reject: @escaping RCTPromiseRejectBlock) {
+    DispatchQueue.main.async {
+      FrameNetworking.shared.initializeWithAPIKey(apiKey, debugMode: debugMode)
+      resolve(nil)
+    }
+  }
+
+  @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)
+    }
+  }
+
+  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)
+      return
+    }
+    var top = rootVC
+    while let presented = top.presentedViewController { top = presented }
+    let delegate = CheckoutDismissDelegate(resolve: resolve, reject: reject)
+    let checkoutView = 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)
+        }
+      }
+    )
+    let hosting = UIHostingController(rootView: checkoutView)
+    hosting.modalPresentationStyle = .pageSheet
+    if let sheet = hosting.sheetPresentationController {
+      sheet.detents = [.large()]
+    }
+    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]? {
+    guard let data = try? JSONEncoder().encode(intent) else { return nil }
+    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
+    var title: String
+    var amountInCents: Int
+  }
+
+  private func parseCartItems(_ items: NSArray) -> [RNFrameCartItem]? {
+    var result: [RNFrameCartItem] = []
+    for item in items {
+      guard let dict = item as? NSDictionary,
+            let id = dict["id"] as? String,
+            let title = dict["title"] as? String,
+            let amountInCents = dict["amountInCents"] as? Int else { return nil }
+      let imageURL = (dict["imageUrl"] as? String) ?? (dict["imageURL"] as? String) ?? ""
+      result.append(RNFrameCartItem(id: id, imageURL: imageURL, title: title, amountInCents: amountInCents))
+    }
+    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
+    }
+    var top = rootVC
+    while let presented = top.presentedViewController { top = presented }
+    let cartView = FrameCartView(
+      customer: nil,
+      cartItems: cartItems,
+      shippingAmountInCents: shippingAmountInCents
+    )
+    let hosting = UIHostingController(rootView: cartView)
+    hosting.modalPresentationStyle = .pageSheet
+    if let sheet = hosting.sheetPresentationController {
+      sheet.detents = [.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)
+  }
+}
+
+private final class CheckoutDismissDelegate: NSObject, UIAdaptivePresentationControllerDelegate {
+  let resolve: RCTPromiseResolveBlock
+  let reject: RCTPromiseRejectBlock
+  var didComplete = false
+  init(resolve: @escaping RCTPromiseResolveBlock, reject: @escaping RCTPromiseRejectBlock) {
+    self.resolve = resolve
+    self.reject = reject
+  }
+  func presentationControllerDidDismiss(_ presentationController: UIPresentationController) {
+    guard !didComplete else { return }
+    reject("USER_CANCELED", "User dismissed checkout without completing payment", nil)
+  }
+}
+
+private final class CartDismissDelegate: NSObject, UIAdaptivePresentationControllerDelegate {
+  let resolve: RCTPromiseResolveBlock
+  init(resolve: @escaping RCTPromiseResolveBlock) { self.resolve = resolve }
+  func presentationControllerDidDismiss(_ presentationController: UIPresentationController) {
+    resolve([String: Any]())
+  }
+}
+
+private var cartDismissKey: UInt8 = 0
+private var checkoutDismissKey: UInt8 = 0

package/lib/errors.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Standard error codes and shape for the Frame React Native SDK.
+ */
+export declare const ErrorCodes: {
+    readonly NOT_INITIALIZED: "NOT_INITIALIZED";
+    readonly USER_CANCELED: "USER_CANCELED";
+    readonly NO_ROOT_VC: "NO_ROOT_VC";
+    readonly NO_ACTIVITY: "NO_ACTIVITY";
+    readonly INVALID_ITEMS: "INVALID_ITEMS";
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    readonly API_ERROR: "API_ERROR";
+    readonly PARSE_ERROR: "PARSE_ERROR";
+    readonly NO_RESULT: "NO_RESULT";
+    readonly INIT_FAILED: "INIT_FAILED";
+    readonly ENCODE_ERROR: "ENCODE_ERROR";
+};
+export type FrameErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+export interface FrameErrorShape {
+    code: string;
+    message: string;
+    nativeError?: string;
+}
+export declare function isFrameError(error: unknown): error is FrameErrorShape;
+export declare function normalizeToFrameError(reject: unknown): FrameErrorShape;
+//# sourceMappingURL=errors.d.ts.map

package/lib/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,eAAO,MAAM,UAAU;;;;;;;;;;;;CAYb,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,OAAO,UAAU,CAAC,CAAC;AAE1E,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CASrE;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,OAAO,GAAG,eAAe,CAetE"}

package/lib/errors.js

@@ -0,0 +1,40 @@
+/**
+ * Standard error codes and shape for the Frame React Native SDK.
+ */
+export const ErrorCodes = {
+    NOT_INITIALIZED: 'NOT_INITIALIZED',
+    USER_CANCELED: 'USER_CANCELED',
+    NO_ROOT_VC: 'NO_ROOT_VC',
+    NO_ACTIVITY: 'NO_ACTIVITY',
+    INVALID_ITEMS: 'INVALID_ITEMS',
+    NETWORK_ERROR: 'NETWORK_ERROR',
+    API_ERROR: 'API_ERROR',
+    PARSE_ERROR: 'PARSE_ERROR',
+    NO_RESULT: 'NO_RESULT',
+    INIT_FAILED: 'INIT_FAILED',
+    ENCODE_ERROR: 'ENCODE_ERROR',
+};
+export function isFrameError(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        'message' in error &&
+        typeof error.code === 'string' &&
+        typeof error.message === 'string');
+}
+export function normalizeToFrameError(reject) {
+    if (isFrameError(reject)) {
+        return reject;
+    }
+    if (reject instanceof Error) {
+        const code = reject.code ?? 'UNKNOWN_ERROR';
+        return { code, message: reject.message, nativeError: reject.stack };
+    }
+    if (typeof reject === 'object' && reject !== null && 'code' in reject && 'message' in reject) {
+        return reject;
+    }
+    return {
+        code: 'UNKNOWN_ERROR',
+        message: String(reject),
+    };
+}

package/lib/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @framepayments/react-native-frame
+ *
+ * React Native SDK for Frame Payments.
+ * - Initialize the SDK, then use presentCheckout / presentCart for payment UI.
+ * - For API calls (customers, charge intents, refunds), use the framepayments (frame-node) package from JS.
+ */
+export { initialize, presentCheckout, presentCart } from './native';
+export type { FrameCartItem, ChargeIntent, FrameError } from './types';
+export { ErrorCodes } from './errors';
+export type { FrameErrorShape, FrameErrorCode } from './errors';
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACpE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC"}

package/lib/index.js

@@ -0,0 +1,9 @@
+/**
+ * @framepayments/react-native-frame
+ *
+ * React Native SDK for Frame Payments.
+ * - Initialize the SDK, then use presentCheckout / presentCart for payment UI.
+ * - For API calls (customers, charge intents, refunds), use the framepayments (frame-node) package from JS.
+ */
+export { initialize, presentCheckout, presentCart } from './native';
+export { ErrorCodes } from './errors';

package/lib/native.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Native module bridge. Uses NativeModules for classic React Native bridge.
+ */
+import type { ChargeIntent, FrameCartItem } from './types';
+export declare function initialize(options: {
+    apiKey: string;
+    debugMode?: boolean;
+}): void;
+export declare function presentCheckout(options: {
+    customerId?: string | null;
+    amount: number;
+}): Promise<ChargeIntent>;
+export declare function presentCart(options: {
+    customerId?: string | null;
+    items: FrameCartItem[];
+    shippingAmountInCents: number;
+}): Promise<ChargeIntent>;
+//# sourceMappingURL=native.d.ts.map

package/lib/native.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native.d.ts","sourceRoot":"","sources":["../src/native.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAmB3D,wBAAgB,UAAU,CAAC,OAAO,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAMjF;AAwBD,wBAAgB,eAAe,CAAC,OAAO,EAAE;IACvC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC,YAAY,CAAC,CAKxB;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE;IACnC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,qBAAqB,EAAE,MAAM,CAAC;CAC/B,GAAG,OAAO,CAAC,YAAY,CAAC,CASxB"}

package/lib/native.js

@@ -0,0 +1,49 @@
+/**
+ * Native module bridge. Uses NativeModules for classic React Native bridge.
+ */
+import { NativeModules } from 'react-native';
+import { ErrorCodes } from './errors';
+const LINKING_ERROR = `The package '@framepayments/react-native-frame' doesn't seem to be linked. Make sure you have run 'pod install' (iOS) or rebuilt the app (Android).`;
+const FrameSDK = NativeModules.FrameSDK
+    ? NativeModules.FrameSDK
+    : new Proxy({}, {
+        get() {
+            throw new Error(LINKING_ERROR);
+        },
+    });
+let isInitialized = false;
+export function initialize(options) {
+    if (!options?.apiKey) {
+        throw new Error('Frame.initialize requires apiKey');
+    }
+    FrameSDK.initialize(options.apiKey, options.debugMode ?? false);
+    isInitialized = true;
+}
+function guardInitialized() {
+    if (!isInitialized) {
+        const message = 'Frame SDK must be initialized before calling presentCheckout or presentCart. Call Frame.initialize({ apiKey }) first.';
+        const err = new Error(message);
+        err.code = ErrorCodes.NOT_INITIALIZED;
+        throw err;
+    }
+}
+function wrapPromise(p) {
+    return p.catch((err) => {
+        let code = 'UNKNOWN_ERROR';
+        let message = String(err?.message ?? err);
+        if (err?.code)
+            code = err.code;
+        if (typeof err === 'object' && err !== null && 'message' in err) {
+            message = String(err.message);
+        }
+        throw Object.assign(new Error(message), { code, message });
+    });
+}
+export function presentCheckout(options) {
+    guardInitialized();
+    return wrapPromise(FrameSDK.presentCheckout(options.customerId ?? null, options.amount));
+}
+export function presentCart(options) {
+    guardInitialized();
+    return wrapPromise(FrameSDK.presentCart(options.customerId ?? null, options.items, options.shippingAmountInCents));
+}

package/lib/types.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Types for the Frame React Native SDK modal APIs.
+ * For other types (Customer, Refund, etc.), use the framepayments (frame-node) package when calling APIs from JS.
+ */
+/** Cart item for presentCart({ items }) */
+export interface FrameCartItem {
+    id: string;
+    title: string;
+    amountInCents: number;
+    imageUrl: string;
+}
+/** Charge intent returned from presentCheckout / presentCart */
+export interface ChargeIntent {
+    id: string;
+    currency: string;
+    amount: number;
+    status: string;
+    created: number;
+    updated: number;
+    livemode: boolean;
+    object: string;
+    description?: string;
+    customer?: Record<string, unknown>;
+    payment_method?: Record<string, unknown>;
+    latest_charge?: Record<string, unknown>;
+    authorization_mode?: string;
+    failure_description?: string;
+    shipping?: Record<string, unknown>;
+}
+/** Error shape when native module rejects (same as FrameErrorShape from errors.ts) */
+export interface FrameError {
+    code: string;
+    message: string;
+    nativeError?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,2CAA2C;AAC3C,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,gEAAgE;AAChE,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,sFAAsF;AACtF,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB"}

package/lib/types.js

@@ -0,0 +1,5 @@
+/**
+ * Types for the Frame React Native SDK modal APIs.
+ * For other types (Customer, Refund, etc.), use the framepayments (frame-node) package when calling APIs from JS.
+ */
+export {};

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "framepayments-react-native",
+  "version": "1.0.0",
+  "description": "React Native SDK for Frame Payments - modal checkout and cart, with API usage via frame-node.",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --ext .ts,.tsx",
+    "test": "jest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "react-native",
+    "frame",
+    "payments",
+    "framepayments"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Frame-Payments/frame-react-native.git"
+  },
+  "author": "Frame Payments <engineering@framepayments.com>",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/Frame-Payments/frame-react-native/issues"
+  },
+  "homepage": "https://github.com/Frame-Payments/frame-react-native#readme",
+  "peerDependencies": {
+    "react": "*",
+    "react-native": ">=0.72.0",
+    "framepayments": "*"
+  },
+  "peerDependenciesMeta": {
+    "framepayments": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "eslint": "^8.57.0",
+    "@typescript-eslint/eslint-plugin": "^6.21.0",
+    "@typescript-eslint/parser": "^6.21.0",
+    "@types/jest": "^29.5.0",
+    "@types/react": "^18.2.0",
+    "@types/react-native": "^0.72.0",
+    "jest": "^29.7.0",
+    "react": "18.2.0",
+    "react-native": "0.72.0",
+    "ts-jest": "^29.1.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "files": [
+    "src",
+    "lib",
+    "ios",
+    "android",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/__tests__/native.test.ts

@@ -0,0 +1,116 @@
+/**
+ * Unit tests for the native module bridge (initialize, presentCheckout, presentCart).
+ * NativeModules.FrameSDK is mocked.
+ */
+
+const mockInitialize = jest.fn((_apiKey: string, _debugMode: boolean) => Promise.resolve());
+const mockPresentCheckout = jest.fn((_customerId: unknown, _amount: number) => Promise.resolve({ id: 'ci_1', amount: 10000 }));
+const mockPresentCart = jest.fn((_customerId: unknown, _items: unknown[], _shipping: number) => Promise.resolve({ id: 'ci_2', amount: 15000 }));
+
+jest.mock('react-native', () => ({
+  NativeModules: {
+    FrameSDK: {
+      initialize: mockInitialize,
+      presentCheckout: mockPresentCheckout,
+      presentCart: mockPresentCart,
+    },
+  },
+}));
+
+// Re-import after mock so we get the mocked NativeModules
+let initialize: (opts: { apiKey: string; debugMode?: boolean }) => void;
+let presentCheckout: (opts: { customerId?: string | null; amount: number }) => Promise<unknown>;
+let presentCart: (opts: {
+  customerId?: string | null;
+  items: Array<{ id: string; title: string; amountInCents: number; imageUrl: string }>;
+  shippingAmountInCents: number;
+}) => Promise<unknown>;
+
+beforeEach(() => {
+  jest.resetModules();
+  mockInitialize.mockClear();
+  mockPresentCheckout.mockClear();
+  mockPresentCart.mockClear();
+  const native = require('../native');
+  initialize = native.initialize;
+  presentCheckout = native.presentCheckout;
+  presentCart = native.presentCart;
+});
+
+describe('initialize', () => {
+  it('calls native FrameSDK.initialize with apiKey and debugMode', () => {
+    initialize({ apiKey: 'sk_test_xxx', debugMode: true });
+    expect(mockInitialize).toHaveBeenCalledTimes(1);
+    expect(mockInitialize).toHaveBeenCalledWith('sk_test_xxx', true);
+  });
+
+  it('defaults debugMode to false', () => {
+    initialize({ apiKey: 'sk_test_yyy' });
+    expect(mockInitialize).toHaveBeenCalledWith('sk_test_yyy', false);
+  });
+
+  it('throws if apiKey is missing', () => {
+    expect(() => initialize({ apiKey: '' })).toThrow();
+    expect(() => (initialize as any)({})).toThrow();
+    expect(mockInitialize).not.toHaveBeenCalled();
+  });
+});
+
+describe('presentCheckout', () => {
+  it('throws NOT_INITIALIZED if initialize was not called', async () => {
+    try {
+      await presentCheckout({ amount: 10000 });
+      expect(true).toBe(false);
+    } catch (e: any) {
+      expect(e.code).toBe('NOT_INITIALIZED');
+      expect(e.message).toContain('initialized');
+    }
+    expect(mockPresentCheckout).not.toHaveBeenCalled();
+  });
+
+  it('calls native presentCheckout with customerId and amount after initialize', async () => {
+    initialize({ apiKey: 'sk_xxx' });
+    const result = await presentCheckout({ customerId: 'cus_1', amount: 10000 });
+    expect(mockPresentCheckout).toHaveBeenCalledWith('cus_1', 10000);
+    expect(result).toEqual({ id: 'ci_1', amount: 10000 });
+  });
+
+  it('passes null for customerId when not provided', async () => {
+    initialize({ apiKey: 'sk_xxx' });
+    await presentCheckout({ amount: 5000 });
+    expect(mockPresentCheckout).toHaveBeenCalledWith(null, 5000);
+  });
+});
+
+describe('presentCart', () => {
+  const items = [
+    { id: '1', title: 'Item A', amountInCents: 1000, imageUrl: 'https://example.com/a.jpg' },
+  ];
+
+  it('throws NOT_INITIALIZED if initialize was not called', async () => {
+    try {
+      await presentCart({ items, shippingAmountInCents: 500 });
+      expect(true).toBe(false);
+    } catch (e: any) {
+      expect(e.code).toBe('NOT_INITIALIZED');
+    }
+    expect(mockPresentCart).not.toHaveBeenCalled();
+  });
+
+  it('calls native presentCart with customerId, items, shipping after initialize', async () => {
+    initialize({ apiKey: 'sk_xxx' });
+    const result = await presentCart({
+      customerId: 'cus_2',
+      items,
+      shippingAmountInCents: 500,
+    });
+    expect(mockPresentCart).toHaveBeenCalledWith('cus_2', items, 500);
+    expect(result).toEqual({ id: 'ci_2', amount: 15000 });
+  });
+
+  it('passes null for customerId when not provided', async () => {
+    initialize({ apiKey: 'sk_xxx' });
+    await presentCart({ items, shippingAmountInCents: 0 });
+    expect(mockPresentCart).toHaveBeenCalledWith(null, items, 0);
+  });
+});

package/src/errors.ts

@@ -0,0 +1,53 @@
+/**
+ * Standard error codes and shape for the Frame React Native SDK.
+ */
+
+export const ErrorCodes = {
+  NOT_INITIALIZED: 'NOT_INITIALIZED',
+  USER_CANCELED: 'USER_CANCELED',
+  NO_ROOT_VC: 'NO_ROOT_VC',
+  NO_ACTIVITY: 'NO_ACTIVITY',
+  INVALID_ITEMS: 'INVALID_ITEMS',
+  NETWORK_ERROR: 'NETWORK_ERROR',
+  API_ERROR: 'API_ERROR',
+  PARSE_ERROR: 'PARSE_ERROR',
+  NO_RESULT: 'NO_RESULT',
+  INIT_FAILED: 'INIT_FAILED',
+  ENCODE_ERROR: 'ENCODE_ERROR',
+} as const;
+
+export type FrameErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+
+export interface FrameErrorShape {
+  code: string;
+  message: string;
+  nativeError?: string;
+}
+
+export function isFrameError(error: unknown): error is FrameErrorShape {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    'code' in error &&
+    'message' in error &&
+    typeof (error as FrameErrorShape).code === 'string' &&
+    typeof (error as FrameErrorShape).message === 'string'
+  );
+}
+
+export function normalizeToFrameError(reject: unknown): FrameErrorShape {
+  if (isFrameError(reject)) {
+    return reject;
+  }
+  if (reject instanceof Error) {
+    const code = (reject as Error & { code?: string }).code ?? 'UNKNOWN_ERROR';
+    return { code, message: reject.message, nativeError: reject.stack };
+  }
+  if (typeof reject === 'object' && reject !== null && 'code' in reject && 'message' in reject) {
+    return reject as FrameErrorShape;
+  }
+  return {
+    code: 'UNKNOWN_ERROR',
+    message: String(reject),
+  };
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+/**
+ * @framepayments/react-native-frame
+ *
+ * React Native SDK for Frame Payments.
+ * - Initialize the SDK, then use presentCheckout / presentCart for payment UI.
+ * - For API calls (customers, charge intents, refunds), use the framepayments (frame-node) package from JS.
+ */
+
+export { initialize, presentCheckout, presentCart } from './native';
+export type { FrameCartItem, ChargeIntent, FrameError } from './types';
+export { ErrorCodes } from './errors';
+export type { FrameErrorShape, FrameErrorCode } from './errors';