@whop/elements-react-native 0.1.0

package/src/core/payments/detail.ts

@@ -0,0 +1,204 @@
+// gating rules ported from frontend/apps/web/src/elements/payments/lib/detail.tsx — keep in sync
+
+import type { PaymentMethodConfigurationShape, PaymentMethodTypeResource } from '../../api/types';
+import { currencyMinorDigits } from './currency';
+
+export type MatrixEntry = PaymentMethodTypeResource & {
+	next_action_render_modes?: string[];
+	supports_fresh_collection?: boolean;
+	submit_button?: { label?: string; kind?: string };
+};
+
+export type { PaymentMethodConfigurationShape };
+
+/**
+ * Which checkout is asking. The matrix leaves out methods that do not serve the named surface, and
+ * the axis is who BUILT the checkout, not where it runs.
+ *
+ * A React Native mount is `direct_checkout`: it owns its own presentation the way a first-party
+ * whop.com document does, and unlike an iframe it can hand a full-page step to the system browser.
+ * Sending `external_checkout` would drop every `full_page`-only method from the list.
+ */
+export type CheckoutSurface = 'direct_checkout' | 'embedded_checkout' | 'modal_checkout' | 'external_checkout';
+
+const TAB_OWNING_SURFACES: readonly CheckoutSurface[] = ['direct_checkout', 'modal_checkout'];
+
+/**
+ * The categories this build can actually collect. An entry from a newer matrix in a category this
+ * build does not implement is a rail it cannot run, so it is skipped rather than rendered as a
+ * broken tile — the same gate web added in #25658 (apps/web/src/elements/payments/lib/detail.tsx).
+ *
+ * `balance` is web's list minus one: ledger-balance payment is not in this release (README), so
+ * claiming it here would render a tile that cannot complete.
+ */
+const IMPLEMENTED_CATEGORIES: readonly string[] = [
+	'card',
+	'wallet',
+	'bank_debit',
+	'bank_transfer',
+	'voucher',
+	'redirect',
+	'crypto',
+];
+
+const TEMPLATES = ['redirect', 'bnpl_confirm', 'bank_connect', 'bank_wire', 'wallet_sheet', 'none'] as const;
+export type DetailTemplate = (typeof TEMPLATES)[number];
+
+export interface WalletAvailability {
+	applePay?: boolean;
+	googlePay?: boolean;
+}
+
+export function detailTemplate(entry: MatrixEntry): DetailTemplate {
+	const declared = entry.detail?.template;
+	if (declared && (TEMPLATES as readonly string[]).includes(declared)) return declared as DetailTemplate;
+	// An unknown template is a newer matrix than this build; redirect copy is the safe read.
+	return 'redirect';
+}
+
+export function passesConfiguration(
+	type: string,
+	configuration: PaymentMethodConfigurationShape | undefined,
+	platformDefault?: boolean,
+): boolean {
+	if (!configuration) return platformDefault ?? true;
+	const enabled = configuration.enabled ?? [];
+	if (!(configuration.include_platform_defaults ?? true)) return enabled.includes(type);
+	// (platform defaults − disabled + enabled): an off-by-default type needs an explicit enable,
+	// so "not disabled" alone is not an allow.
+	return ((platformDefault ?? true) && !(configuration.disabled ?? []).includes(type)) || enabled.includes(type);
+}
+
+/** The entry's category-keyed config block, read generically. */
+export function methodConfigBlock(entry: MatrixEntry): Record<string, unknown> {
+	const block = (entry as unknown as Record<string, unknown>)[entry.category];
+	return block && typeof block === 'object' ? (block as Record<string, unknown>) : {};
+}
+
+export function methodTokenizerKey(entry: MatrixEntry): string | undefined {
+	const key = methodConfigBlock(entry).public_key;
+	return typeof key === 'string' ? key : undefined;
+}
+
+/**
+ * Whether the entry is offered for this charge on this surface.
+ *
+ * Amount-gated methods are excluded outright rather than rendered disabled, and every absent field
+ * reads as unrestricted so an older matrix keeps its behavior.
+ */
+export function presentMethod(
+	entry: MatrixEntry,
+	currency: string,
+	amount: number,
+	setupFutureUsage: 'off_session' | 'on_session' | undefined,
+	walletAvailability: WalletAvailability | undefined,
+	configuration: PaymentMethodConfigurationShape | undefined,
+	surface: CheckoutSurface,
+	country?: string,
+): boolean {
+	// A category this build does not implement is a rail it cannot collect — an entry from a newer
+	// matrix must be skipped, never rendered as a broken tile.
+	if (!IMPLEMENTED_CATEGORIES.includes(entry.category)) return false;
+	if (
+		!TAB_OWNING_SURFACES.includes(surface) &&
+		entry.next_action_render_modes &&
+		!entry.next_action_render_modes.includes('inline')
+	) {
+		return false;
+	}
+	if (!passesConfiguration(entry.type, configuration, entry.platform_default)) return false;
+	if (!entry.usage?.one_time) return false;
+	if (setupFutureUsage === 'off_session' && !entry.usage?.off_session) return false;
+	if (setupFutureUsage === 'on_session' && !entry.usage?.on_session) return false;
+	if (entry.category === 'card' && !entry.card?.public_key) return false;
+	// A secure declared field tokenizes into the config block's key at collect time; without the key
+	// the method is broken at confirm, so it is never offered.
+	if ((entry.required_fields ?? []).some((field) => field.secure) && !methodTokenizerKey(entry)) return false;
+	if (detailTemplate(entry) === 'wallet_sheet') {
+		if (entry.type === 'apple_pay' && !walletAvailability?.applePay) return false;
+		if (entry.type === 'google_pay' && !walletAvailability?.googlePay) return false;
+	}
+	const bounds = entry.currencies?.[currency.toLowerCase()];
+	if (!bounds) return false;
+	const { min, max } = amountBounds(bounds, country);
+	if (min != null && amount < min) return false;
+	if (max != null && amount > max) return false;
+	return true;
+}
+
+/**
+ * A currency's limits, narrowed to the billing country when the matrix publishes a row for it.
+ *
+ * Reading only the currency-level pair offered methods that the selected country cannot actually
+ * take at this amount, which the buyer discovers at confirm rather than in the list. Mirrors
+ * `amountBounds` in apps/web/src/elements/payments/lib/detail.tsx.
+ */
+function amountBounds(
+	bounds: NonNullable<MatrixEntry['currencies']>[string],
+	country: string | undefined,
+): { min: number | null | undefined; max: number | null | undefined } {
+	const code = country?.toLowerCase();
+	const row = code ? bounds.countries?.find((candidate) => candidate.country?.toLowerCase() === code) : undefined;
+	if (!row) return { min: bounds.min_amount, max: bounds.max_amount };
+	return { min: row.min_amount, max: row.max_amount };
+}
+
+/** Listed types take their list position; unlisted types share the tail rank, so a stable sort
+ *  preserves their incoming order. */
+export function orderRank(type: string, order: readonly string[]): number {
+	const index = order.indexOf(type);
+	return index === -1 ? order.length : index;
+}
+
+export function formatMinorAmount(amount: number, currency: string, locale: string): string {
+	// The divisor is the backend-mirrored factor; the display digits are Intl's. They disagree for
+	// currencies like huf, and the backend's answer is the one that priced the charge.
+	const major = amount / 10 ** currencyMinorDigits(currency);
+	try {
+		return new Intl.NumberFormat(locale, { style: 'currency', currency: currency.toUpperCase() }).format(major);
+	} catch {
+		return `${major} ${currency.toUpperCase()}`;
+	}
+}
+
+export function fieldLabel(name: string): string {
+	const spaced = name.replace(/_/g, ' ').replace(/\bid\b/gi, 'ID');
+	return spaced.charAt(0).toUpperCase() + spaced.slice(1);
+}
+
+/** A declared field's country-keyed pattern, `*` as the fallback. Never throws on a bad pattern. */
+export function fieldMatches(
+	formats: Record<string, string> | undefined,
+	country: string | undefined,
+	value: string,
+): boolean {
+	if (!formats) return true;
+	const trimmed = value.trim();
+	const patterns = [formats[(country ?? '').toLowerCase()], formats['*']].filter(
+		(p): p is string => typeof p === 'string',
+	);
+	return patterns.length === 0 || patterns.some((pattern) => safeTest(pattern, trimmed));
+}
+
+function safeTest(pattern: string, value: string): boolean {
+	try {
+		return new RegExp(pattern).test(value);
+	} catch {
+		return true;
+	}
+}
+
+/**
+ * The billing countries a method constrains the buyer to, or null when it constrains nothing.
+ *
+ * `*` anywhere in the entry's per-currency list means unrestricted, and so does an empty list — a
+ * method that names countries names ALL of the ones it serves. The address element intersects the
+ * result with the integrator's own `allowedCountries` rather than replacing it.
+ */
+export function methodBillingCountries(
+	entry: Pick<PaymentMethodTypeResource, 'currencies'> | undefined,
+	currency: string,
+): string[] | null {
+	const codes = (entry?.currencies?.[currency]?.countries ?? []).map((row) => row.country);
+	return codes.length === 0 || codes.includes('*') ? null : codes;
+}

package/src/core/payments/errors.ts

@@ -0,0 +1,171 @@
+// ported verbatim from frontend/apps/web/src/elements/payments/lib/errors.ts — keep in sync when the web element changes
+
+import { WhopError } from '../../api/client';
+
+export type ChargeConfigErrorCode =
+  | 'PLAN_INLINE_CONFLICT'
+  | 'CHARGE_CONFIG_MISSING'
+  | 'PLAN_ACCOUNT_MISMATCH'
+  | 'PLAN_RESOLUTION_FAILED';
+
+/** The plan/inline charge-config refusals — CODED like the framework's lifecycle refusals
+ *  (switch on `code`, never string-match). The message carries the code prefix too because a
+ *  wire boot failure (`controller-failed`) delivers the MESSAGE alone to the handle's onError. */
+export class ChargeConfigError extends Error {
+  readonly code: ChargeConfigErrorCode;
+
+  constructor(code: ChargeConfigErrorCode, message: string) {
+    super(`[${code}] ${message}`);
+    this.code = code;
+    this.name = 'ChargeConfigError';
+  }
+}
+
+export type BrandingRequiredErrorCode = 'BRANDING_NOT_MOUNTED' | 'BRANDING_HIDDEN';
+
+/** The merchant-of-record refusal. `BRANDING_NOT_MOUNTED` remains in the error-code contract for
+ *  clients compiled against 1.0.0-beta.1; the compatibility runtime only emits `BRANDING_HIDDEN`
+ *  when a mounted notice has been CSS-hidden or shrunk. */
+export class BrandingRequiredError extends Error {
+  readonly code: BrandingRequiredErrorCode;
+
+  constructor(code: BrandingRequiredErrorCode, message: string) {
+    super(`[${code}] ${message}`);
+    this.code = code;
+    this.name = 'BrandingRequiredError';
+  }
+}
+
+export type SelectErrorCode = 'METHOD_NOT_OFFERED';
+
+/** The `select` action's refusals — the same coded shape as ChargeConfigError (switch on `code`;
+ *  the message carries the code prefix because the wire rpc rail delivers the message alone). */
+export class SelectError extends Error {
+  readonly code: SelectErrorCode;
+
+  constructor(code: SelectErrorCode, message: string) {
+    super(`[${code}] ${message}`);
+    this.code = code;
+    this.name = 'SelectError';
+  }
+}
+
+export type SecureFieldErrorCode = 'SECURE_FIELD_TOKENIZER_UNAVAILABLE' | 'SECURE_FIELD_TOKENIZE_FAILED';
+
+/** The secure declared-field refusals (a secure value could not be tokenized, so the confirm
+ *  never ran) — the same coded shape as the other refusal families. */
+export class SecureFieldError extends Error {
+  readonly code: SecureFieldErrorCode;
+
+  constructor(code: SecureFieldErrorCode, message: string) {
+    super(`[${code}] ${message}`);
+    this.code = code;
+    this.name = 'SecureFieldError';
+  }
+}
+
+export type PaymentTokenizationFailureStage =
+  | 'card_fields'
+  | 'card_tokenizer_session'
+  | 'card_number'
+  | 'card_session_authorization'
+  | 'card_expiry'
+  | 'card_cvc'
+  | 'confirmation_token_create';
+
+export type PaymentTokenizationErrorCode =
+  | 'card_fields_not_ready'
+  | 'card_tokenizer_session_failed'
+  | 'card_number_validation_failed'
+  | 'card_number_tokenization_failed'
+  | 'card_session_authorization_failed'
+  | 'card_expiry_validation_failed'
+  | 'card_expiry_tokenization_failed'
+  | 'card_cvc_validation_failed'
+  | 'card_cvc_tokenization_failed'
+  | 'confirmation_token_create_failed';
+
+interface PaymentTokenizationFailure {
+  code: PaymentTokenizationErrorCode;
+  failureStage: PaymentTokenizationFailureStage;
+  message: string;
+}
+
+const tokenizationStageByCode: Record<PaymentTokenizationErrorCode, PaymentTokenizationFailureStage> = {
+  card_fields_not_ready: 'card_fields',
+  card_tokenizer_session_failed: 'card_tokenizer_session',
+  card_number_validation_failed: 'card_number',
+  card_number_tokenization_failed: 'card_number',
+  card_session_authorization_failed: 'card_session_authorization',
+  card_expiry_validation_failed: 'card_expiry',
+  card_expiry_tokenization_failed: 'card_expiry',
+  card_cvc_validation_failed: 'card_cvc',
+  card_cvc_tokenization_failed: 'card_cvc',
+  confirmation_token_create_failed: 'confirmation_token_create',
+};
+
+export class PaymentTokenizationError extends Error {
+  readonly code: PaymentTokenizationErrorCode;
+  readonly failureStage: PaymentTokenizationFailureStage;
+  readonly buyerMessage: string;
+
+  constructor(code: PaymentTokenizationErrorCode, message: string) {
+    super(`[${code}] ${message}`);
+    this.code = code;
+    this.failureStage = tokenizationStageByCode[code];
+    this.buyerMessage = message;
+    this.name = 'PaymentTokenizationError';
+  }
+}
+
+export function paymentTokenizationFailureOf(error: unknown): PaymentTokenizationFailure | undefined {
+  if (error instanceof PaymentTokenizationError) {
+    return { code: error.code, failureStage: error.failureStage, message: error.buyerMessage };
+  }
+  const message = error instanceof Error ? error.message : '';
+  const match = /^\[([a-z_]+)\] ([\s\S]*)$/.exec(message);
+  const code = match?.[1];
+  if (!code || !Object.hasOwn(tokenizationStageByCode, code)) return undefined;
+  const typedCode = code as PaymentTokenizationErrorCode;
+  return { code: typedCode, failureStage: tokenizationStageByCode[typedCode], message: match[2] ?? '' };
+}
+
+export function paymentTokenizationBuyerMessage(error: unknown, fallback: string): string {
+  return (
+    paymentTokenizationFailureOf(error)?.message ?? (error instanceof Error && error.message ? error.message : fallback)
+  );
+}
+
+export type NextActionErrorCode = 'FULL_PAGE_STEP_IN_FRAME';
+
+/** handleNextAction's posture refusal (a full_page-only step reached a document that cannot
+ *  navigate the whole tab, so nothing ran) — the same coded shape as the other refusal
+ *  families. */
+export class NextActionError extends Error {
+  readonly code: NextActionErrorCode;
+
+  constructor(code: NextActionErrorCode, message: string) {
+    super(`[${code}] ${message}`);
+    this.code = code;
+    this.name = 'NextActionError';
+  }
+}
+
+/** Whether a caught error is this family's refusal for `code`, wherever it was caught: the
+ *  structured `code` survives an in-process throw, and the `[CODE]` message prefix is the
+ *  family's own WIRE encoding — the rpc rail re-mints a rejection from `.message` alone, which
+ *  is the whole reason these constructors bake the code into the message. Decoding the prefix
+ *  here is reading that contract, not string-matching prose. */
+export function isNextActionRefusal(error: unknown, code: NextActionErrorCode): boolean {
+  if ((error as { code?: unknown } | null)?.code === code) return true;
+  const message = error instanceof Error ? error.message : '';
+  return message.startsWith(`[${code}]`);
+}
+
+export function apiErrorMessage(err: unknown, fallback: string): string {
+  if (err instanceof WhopError) {
+    const body = err.body as { error?: { message?: string } } | null | undefined;
+    return body?.error?.message ?? `${fallback} (${err.statusCode})`;
+  }
+  return err instanceof Error ? err.message : fallback;
+}

package/src/core/payments/mint.ts

@@ -0,0 +1,130 @@
+// ported verbatim from frontend/apps/web/src/elements/payments/lib/mint.ts — keep in sync when the web element changes
+
+import type { WhopClient } from '../../api/client';
+
+import { capturedBrowserInfo } from './browser-info';
+import { PaymentTokenizationError, apiErrorMessage } from './errors';
+
+export interface MintBillingDetails {
+  email: string;
+  name?: string;
+  phone?: string;
+  address?: { country?: string; line1?: string; city?: string; postal_code?: string };
+}
+
+export interface MintContext {
+  accountId: string | undefined;
+  returnUrl: string | undefined;
+  setupFutureUsage: 'off_session' | 'on_session' | undefined;
+}
+
+/** The collected bag a surface's `collect` verb returns — everything the CONTROLLER needs to
+ *  mint: the assembled payment_method slice, the surface-validated billing block, and any
+ *  declared inputs that belong on billing_details. Serializable — it crosses the surface's
+ *  frame into the controller frame. */
+export interface CollectedPayment {
+  paymentMethod: { type: string; category: string } & Record<string, unknown>;
+  billingDetails: MintBillingDetails;
+  billingExtra?: Record<string, string>;
+}
+
+/** The ONE confirmation-token mint — run by the CONTROLLER's internal action only, in the
+ *  controller frame, with the controller's sdk + accountId/returnUrl/setupFutureUsage context.
+ *  (Exception: WhopPaymentRequest tokenizes + mints host-side — it must run without a mounted
+ *  controller.) */
+export async function mintConfirmationToken(
+  sdk: WhopClient,
+  context: MintContext,
+  paymentMethod: { type: string; category: string } & Record<string, unknown>,
+  billingDetails: MintBillingDetails,
+  billingExtra?: Record<string, string>,
+): Promise<{ confirmationToken: string; type: string }> {
+  if (!context.accountId) throw new Error('No seller account is in scope for this surface');
+  // A SAVED reference states less than a collected one, and the API REFUSES the difference rather
+  // than ignoring it: the type is read off the stored row, and consent to store was given when the
+  // method was first saved. Sending either back is a 400 telling us the element misread the flow —
+  // so the type is dropped from the body (it is still returned to the caller from the selection)
+  // and `setup_future_usage` never rides along. A BALANCE reference keeps its type (single-valued,
+  // server-verified) but is never vaulted, so the attested consent is refused there too.
+  const saved = paymentMethod.category === 'saved';
+  const referenced = saved || paymentMethod.category === 'balance';
+  const { type: _selectedType, ...savedPayload } = paymentMethod;
+  const token = await sdk.confirmationTokens
+    .create({
+      account_id: context.accountId,
+      // The generated params type CLOSES payment_method over the category blocks, but the
+      // design of record sends method-DECLARED dynamic fields as top-level keys (INVENTORY
+      // backend obligation: the schema must admit them; strong params must not drop them).
+      payment_method: (saved ? savedPayload : paymentMethod) as unknown as Parameters<
+        typeof sdk.confirmationTokens.create
+      >[0]['payment_method'],
+      billing_details: {
+        ...billingDetails,
+        ...billingExtra,
+      },
+      return_url: context.returnUrl,
+      setup_future_usage: referenced ? undefined : context.setupFutureUsage,
+      browser_info: capturedBrowserInfo(),
+    })
+    .catch((err: unknown) => {
+      throw new PaymentTokenizationError('confirmation_token_create_failed', apiErrorMessage(err, 'collection failed'));
+    });
+  return { confirmationToken: token.id, type: paymentMethod.type };
+}
+
+export function validateBillingEmail(billing: { email?: string } | undefined): MintBillingDetails {
+  if (!billing?.email) throw new Error('billingDetails.email is required');
+  return { ...billing, email: billing.email };
+}
+
+export function assertCardBilling(billing: MintBillingDetails): void {
+  if (!billing.name) throw new Error('billingDetails.name is required for card payments');
+}
+
+interface CollectionSurface {
+  /** advisory CLAIM-axis liveness (`ctx.children.<key>.created`) — "may I address it". */
+  created: boolean;
+  collect: (input: unknown) => Promise<unknown>;
+}
+
+export interface CollectionSurfaces {
+  /** the payment element's collect (a.controllerOnly — it orchestrates its own selection). */
+  payment: CollectionSurface;
+  /** the fused card element's collect (a.controllerOnly). */
+  card: CollectionSurface;
+  /** the exploded card-fields sub's collect (a.controller — the only parent-reachable action
+   *  kind on a sub: `ctx.children.<sub>` routes through `runtime.dispatch`, which refuses
+   *  internal). */
+  cardFields: CollectionSurface;
+}
+
+/** The framework's CODED lifecycle refusals (`childRefusal`, controller-core): switch on
+ *  `code`, never string-match — the message is the human channel. */
+export function isChildRefusal(err: unknown): boolean {
+  const code = (err as { code?: unknown } | null)?.code;
+  return code === 'CHILD_NOT_CREATED' || code === 'CHILD_DESTROYED';
+}
+
+/**
+ * The delegation cascade: COLLECTION belongs to the active surface, tried in precedence order —
+ * payment element, fused card element, exploded card-fields unit; each validates its own
+ * requirements and returns the serializable collected bag, and the CONTROLLER mints from it.
+ * Occupancy is DECIDED, not caught: `.created` (the advisory claim-axis probe) picks the live
+ * face; a coded lifecycle refusal (the check→invoke race — a face destroyed in between) falls
+ * through to the next; a live surface's own error re-throws untouched — its refusal is the
+ * answer.
+ */
+export async function collectThroughLiveSurface(
+  surfaces: CollectionSurfaces,
+  input: unknown,
+): Promise<CollectedPayment> {
+  for (const surface of [surfaces.payment, surfaces.card, surfaces.cardFields]) {
+    if (!surface.created) continue;
+    try {
+      return (await surface.collect(input)) as CollectedPayment;
+    } catch (err) {
+      if (!isChildRefusal(err)) throw err;
+    }
+  }
+  throw new Error('Mount a collection surface first — the payment element, the card element, or the card-fields unit');
+}