framepayments-react-native 2.1.0 → 2.1.2

package/src/native.ts

@@ -4,7 +4,6 @@
 
 import { NativeModules, Platform } from 'react-native';
 import type {
-  ChargeIntent,
   FrameCartItem,
   FrameTheme,
   OnboardingCapability,
@@ -14,6 +13,20 @@ import type {
 } from './types';
 import { ErrorCodes } from './errors';
 
+/**
+ * Throw a coded error from synchronous JS validation. Mirrors the `code`/`message`
+ * shape that native rejections produce so consumers can catch `e.code === 'INVALID_*'`
+ * uniformly.
+ */
+function throwCoded(code: string, message: string): never {
+  const err = new Error(message) as Error & { code: string };
+  err.code = code;
+  throw err;
+}
+
+// theme is iOS-only today: frame-android does not yet have a matching theme API,
+// so the field is accepted on both platforms but ignored on Android until it does.
+
 const LINKING_ERROR =
   `The package 'framepayments-react-native' doesn't seem to be linked. Make sure you have run 'pod install' (iOS) or rebuilt the app (Android).`;
 
@@ -34,18 +47,29 @@ export function initialize(options: {
   secretKey: string;
   publishableKey: string;
   debugMode?: boolean;
+  /**
+   * Optional theme applied SDK-wide to Frame's reusable iOS components
+   * (checkout, cart, onboarding). Pass any subset — unspecified tokens fall
+   * back to SDK defaults. No-op on Android until frame-android ships a
+   * matching theme API.
+   */
+  theme?: FrameTheme;
 }): Promise<void> {
   if (!options?.secretKey) {
-    throw new Error('Frame.initialize requires secretKey');
+    throwCoded(ErrorCodes.INIT_FAILED, 'Frame.initialize requires secretKey');
   }
   if (!options?.publishableKey) {
-    throw new Error('Frame.initialize requires publishableKey');
+    throwCoded(ErrorCodes.INIT_FAILED, 'Frame.initialize requires publishableKey');
+  }
+  if (options.theme !== undefined && (typeof options.theme !== 'object' || Array.isArray(options.theme))) {
+    throwCoded(ErrorCodes.INIT_FAILED, 'Frame.initialize: theme must be an object');
   }
   return wrapPromise(
     FrameSDK.initialize(
       options.secretKey,
       options.publishableKey,
-      options.debugMode ?? false
+      options.debugMode ?? false,
+      options.theme ?? null
     )
   ).then(() => {
     isInitialized = true;
@@ -74,25 +98,46 @@ function wrapPromise<T>(p: Promise<T>): Promise<T> {
   });
 }
 
+/**
+ * Presents the Frame checkout sheet for the given account. Resolves with the
+ * created Transfer's id string on success, or rejects with `USER_CANCELED` if
+ * the user dismisses the sheet.
+ *
+ * `accountId` is required: the bundled checkout creates a `Transfer`, which is
+ * account-scoped. Callers needing a customer/ChargeIntent flow should use
+ * `presentApplePay` / `presentGooglePay` directly with a customer owner.
+ */
 export function presentCheckout(options: {
-  customerId?: string | null;
+  accountId: string;
   amount: number;
-}): Promise<ChargeIntent> {
+}): Promise<string> {
   guardInitialized();
+  if (!options?.accountId) {
+    throwCoded(ErrorCodes.INVALID_ACCOUNT, 'Frame.presentCheckout requires accountId');
+  }
   return wrapPromise(
-    FrameSDK.presentCheckout(options.customerId ?? null, options.amount)
+    FrameSDK.presentCheckout(options.accountId, options.amount)
   );
 }
 
+/**
+ * Presents the Frame cart UI; tapping checkout routes through the same flow
+ * as `presentCheckout` and resolves with the created Transfer's id string.
+ *
+ * `accountId` is required for the same reason as `presentCheckout`.
+ */
 export function presentCart(options: {
-  customerId?: string | null;
+  accountId: string;
   items: FrameCartItem[];
   shippingAmountInCents: number;
-}): Promise<ChargeIntent> {
+}): Promise<string> {
   guardInitialized();
+  if (!options?.accountId) {
+    throwCoded(ErrorCodes.INVALID_ACCOUNT, 'Frame.presentCart requires accountId');
+  }
   return wrapPromise(
     FrameSDK.presentCart(
-      options.customerId ?? null,
+      options.accountId,
       options.items,
       options.shippingAmountInCents
     )
@@ -124,16 +169,24 @@ export function presentOnboarding(options: {
   );
 }
 
-export function presentApplePay(options: PresentApplePayOptions): Promise<ChargeIntent> {
+/**
+ * Presents the Apple Pay sheet and creates a charge from the resulting wallet
+ * payment method. Resolves with the created resource's id string on success,
+ * or rejects with `USER_CANCELED` if the sheet is dismissed.
+ *
+ *  - `owner.type === 'customer'` → creates a `ChargeIntent`; resolves with its id.
+ *  - `owner.type === 'account'`  → creates a `Transfer`;     resolves with its id.
+ */
+export function presentApplePay(options: PresentApplePayOptions): Promise<string> {
   guardInitialized();
   if (!options?.owner || (options.owner.type !== 'customer' && options.owner.type !== 'account')) {
-    throw new Error('Frame.presentApplePay requires owner: { type: "customer" | "account", id: string }');
+    throwCoded(ErrorCodes.INVALID_OWNER, 'Frame.presentApplePay requires owner: { type: "customer" | "account", id: string }');
   }
   if (!options.owner.id) {
-    throw new Error('Frame.presentApplePay requires owner.id');
+    throwCoded(ErrorCodes.INVALID_OWNER, 'Frame.presentApplePay requires owner.id');
   }
   if (!options.merchantId) {
-    throw new Error('Frame.presentApplePay requires merchantId');
+    throwCoded(ErrorCodes.INVALID_MERCHANT_ID, 'Frame.presentApplePay requires merchantId');
   }
   return wrapPromise(
     FrameSDK.presentApplePay(
@@ -146,30 +199,28 @@ export function presentApplePay(options: PresentApplePayOptions): Promise<Charge
   );
 }
 
-export function presentGooglePay(options: PresentGooglePayOptions): Promise<ChargeIntent> {
+/**
+ * Presents Google Pay and creates a charge from the resulting wallet payment method.
+ * Resolves with the created resource's id string on success.
+ *
+ *  - `owner.type === 'customer'` → creates a `ChargeIntent`; resolves with its id.
+ *  - `owner.type === 'account'`  → creates a `Transfer`;     resolves with its id.
+ */
+export function presentGooglePay(options: PresentGooglePayOptions): Promise<string> {
   guardInitialized();
+  if (!options?.owner || (options.owner.type !== 'customer' && options.owner.type !== 'account')) {
+    throwCoded(ErrorCodes.INVALID_OWNER, 'Frame.presentGooglePay requires owner: { type: "customer" | "account", id: string }');
+  }
+  if (!options.owner.id) {
+    throwCoded(ErrorCodes.INVALID_OWNER, 'Frame.presentGooglePay requires owner.id');
+  }
   return wrapPromise(
     FrameSDK.presentGooglePay(
       options.amountCents,
-      options.customerId ?? null,
+      options.owner.type,
+      options.owner.id,
       options.currencyCode ?? 'USD',
       options.googlePayMerchantId ?? null
     )
   );
 }
-
-/**
- * Configure colors, fonts, and corner radii for Frame's reusable iOS
- * components. Applied to every subsequent `present*` call; an in-flight modal
- * is not re-themed mid-flow.
- *
- * Pass `null` or `{}` to reset to SDK defaults. Android is a no-op until
- * frame-android ships a matching theme API.
- */
-export function setTheme(theme: FrameTheme | null): Promise<void> {
-  if (theme !== null && (typeof theme !== 'object' || Array.isArray(theme))) {
-    throw new Error('Frame.setTheme requires a theme object or null');
-  }
-  if (Platform.OS !== 'ios') return Promise.resolve();
-  return wrapPromise(FrameSDK.setTheme(theme ?? {}));
-}

package/src/types.ts

@@ -11,18 +11,6 @@ export interface FrameCartItem {
   imageUrl: string;
 }
 
-export type ChargeIntentStatus =
-  | 'canceled'
-  | 'disputed'
-  | 'failed'
-  | 'incomplete'
-  | 'pending'
-  | 'refunded'
-  | 'reversed'
-  | 'succeeded';
-
-export type AuthorizationMode = 'automatic' | 'manual';
-
 export interface BillingAddress {
   city?: string;
   country?: string;
@@ -62,46 +50,6 @@ export interface PaymentMethod {
   billing?: BillingAddress;
 }
 
-export interface Customer {
-  id: string;
-  object: string;
-  created: number;
-  updated: number;
-  livemode: boolean;
-  name?: string;
-  email?: string;
-  phone?: string;
-}
-
-export interface Charge {
-  id: string;
-  object: string;
-  amount: number;
-  currency: string;
-  status: string;
-  created: number;
-  livemode: boolean;
-}
-
-/** Charge intent returned from presentCheckout / presentCart */
-export interface ChargeIntent {
-  id: string;
-  currency: string;
-  amount: number;
-  status: ChargeIntentStatus;
-  created: number;
-  updated: number;
-  livemode: boolean;
-  object: string;
-  description?: string;
-  authorizationMode?: AuthorizationMode;
-  failureDescription?: string;
-  customer?: Customer;
-  paymentMethod?: PaymentMethod;
-  latestCharge?: Charge;
-  shipping?: BillingAddress;
-}
-
 /** Error shape when native module rejects (same as FrameErrorShape from errors.ts) */
 export interface FrameError {
   code: string;
@@ -134,19 +82,32 @@ export interface OnboardingResult {
   paymentMethodId?: string;
 }
 
-/** Identifies who the Apple Pay payment method belongs to. */
-export type ApplePayOwner =
+/**
+ * Identifies who the wallet payment method belongs to and which downstream
+ * resource is created when the user authorizes payment. Used by both
+ * `presentApplePay` and `presentGooglePay`.
+ *
+ *  - `{ type: 'customer', id }` → creates a `ChargeIntent`; promise resolves with the ChargeIntent id.
+ *  - `{ type: 'account',  id }` → creates a `Transfer`;     promise resolves with the Transfer id.
+ *
+ * The promise always resolves with a string id; the caller knows which resource
+ * it refers to based on the owner type they passed in.
+ */
+export type WalletOwner =
   | { type: 'customer'; id: string }
   | { type: 'account'; id: string };
 
+/** @deprecated Use {@link WalletOwner}. Retained as an alias for source compatibility. */
+export type ApplePayOwner = WalletOwner;
+
 /** Options for Frame.presentApplePay. */
 export interface PresentApplePayOptions {
   /** Payment amount in cents. */
   amount: number;
   /** ISO 4217 currency code. Defaults to 'usd'. */
   currency?: string;
-  /** Customer or account that owns the resulting payment method. */
-  owner: ApplePayOwner;
+  /** Customer or account that owns the resulting payment method and charge. */
+  owner: WalletOwner;
   /** Apple Pay merchant ID configured in your Apple Developer account. */
   merchantId: string;
 }
@@ -155,8 +116,8 @@ export interface PresentApplePayOptions {
 export interface PresentGooglePayOptions {
   /** Payment amount in cents. */
   amountCents: number;
-  /** Optional Frame customer ID to associate the resulting payment method with. */
-  customerId?: string | null;
+  /** Customer or account that owns the resulting payment method and charge. */
+  owner: WalletOwner;
   /** ISO 4217 currency code. Defaults to 'USD'. */
   currencyCode?: string;
   /** Optional override for the Google Pay merchant ID. */