@whop/elements-react-native 0.1.0

package/src/core/address/use-suggestions.ts

@@ -0,0 +1,37 @@
+import { useEffect, useRef, useState } from 'react';
+
+import { WhopAddressSuggestions } from '../../native';
+import type { AddressSuggestion } from './suggest';
+
+/** Long enough that a geocoder has something to work with, short enough to feel live. */
+const MIN_QUERY_LENGTH = 3;
+const DEBOUNCE_MS = 250;
+
+export function useAddressSuggestions(enabled: boolean, query: string): AddressSuggestion[] {
+	const [rows, setRows] = useState<AddressSuggestion[]>([]);
+	const generation = useRef(0);
+
+	useEffect(() => {
+		// Advance BEFORE the early return: clearing the list does not cancel a lookup already in
+		// flight, so a generation that only moved when a new lookup was scheduled left the old one
+		// still matching, and deleting back to two characters repopulated the field.
+		const current = generation.current + 1;
+		generation.current = current;
+
+		const trimmed = query.trim();
+		if (!enabled || trimmed.length < MIN_QUERY_LENGTH) {
+			setRows([]);
+			return;
+		}
+		const timer = setTimeout(() => {
+			void WhopAddressSuggestions.suggest(trimmed).then((found) => {
+				// Geocoder latency is not ordered. Without this a slow lookup for "12 Ma" can land after
+				// "12 Main St" and put stale rows under a newer query.
+				if (generation.current === current) setRows(found);
+			});
+		}, DEBOUNCE_MS);
+		return () => clearTimeout(timer);
+	}, [enabled, query]);
+
+	return rows;
+}

package/src/core/payments/address-change.ts

@@ -0,0 +1,121 @@
+// ported verbatim from frontend/apps/web/src/elements/payments/lib/address-change.ts — keep in sync when the web element changes
+
+import type { EmittedAddress } from '../address/engine';
+
+import { createContext, useContext, useEffect, useMemo, useRef } from 'react';
+
+/**
+ * The postal address the payment element's `addressChange` event carries: every place-identifying
+ * field the billing block collects, with the optionality the form itself has. Only `country` is
+ * guaranteed — each country's format collects its own field set (no state in the Netherlands, no
+ * postal code in Ireland, no line2 unless the buyer fills one), so a key is absent whenever the
+ * form did not collect a value for it. Name, organization, and email are not part of an address
+ * and stay off this event.
+ */
+export interface PostalAddress {
+  line1?: string;
+  line2?: string;
+  city?: string;
+  state?: string;
+  postal_code?: string;
+  country: string;
+}
+
+export interface AddressChange {
+  complete: boolean;
+  address: PostalAddress;
+}
+
+/**
+ * A buyer typing a postal code produces one form snapshot per keystroke, and the consumer turns
+ * every emit into a tax quote or a shipping-rate lookup — one network call per character is the
+ * failure mode this guards. 300ms is the settle window: longer than the gap between keystrokes at
+ * any real typing speed (so a whole postal code collapses into ONE emit), short enough that the
+ * quote is back before the buyer reaches the pay button. TRAILING edge only — a leading emit would
+ * fire on the first character, which is the one value guaranteed to be useless.
+ */
+export const ADDRESS_CHANGE_DEBOUNCE_MS = 300;
+
+const OPTIONAL_ADDRESS_KEYS = ['line1', 'line2', 'city', 'state', 'postal_code'] as const;
+
+export function postalAddressOf(address: EmittedAddress): PostalAddress {
+  const out: PostalAddress = { country: address.country };
+  for (const key of OPTIONAL_ADDRESS_KEYS) {
+    const value = address[key];
+    if (value) out[key] = value;
+  }
+  return out;
+}
+
+function sameAddressChange(a: AddressChange, b: AddressChange): boolean {
+  return (
+    a.complete === b.complete &&
+    a.address.country === b.address.country &&
+    OPTIONAL_ADDRESS_KEYS.every((key) => a.address[key] === b.address[key])
+  );
+}
+
+export interface AddressChangePublisher {
+  publish: (owner: string, change: AddressChange) => void;
+  /**
+   * The owner's block stopped being the address in force before its queued change settled — drop
+   * it. Scoped to the OWNER, not to the change object: a deselected block can still deliver one
+   * last snapshot in the very commit that deselects it (the form dispatches from a child effect,
+   * which flushes before this block's own), so a queue keyed on the change would miss the one
+   * actually in flight. A no-op once another block has queued its own — whichever order the two
+   * blocks' effects run in during a switch.
+   */
+  abandon: (owner: string) => void;
+}
+
+const AddressChangePublishContext = createContext<AddressChangePublisher>({
+  publish: () => {},
+  abandon: () => {},
+});
+
+export const AddressChangePublishProvider = AddressChangePublishContext.Provider;
+
+export function usePublishAddressChange(): AddressChangePublisher {
+  return useContext(AddressChangePublishContext);
+}
+
+/**
+ * ELEMENT-SCOPED on purpose: every method tile mounts its own billing block, so the debounce
+ * timer and the last-emitted memory have to be shared across them — a per-block memory would
+ * suppress the republish that a tile switch back to an earlier address depends on.
+ */
+export function useAddressChangePublisher(emit: (change: AddressChange) => void): AddressChangePublisher {
+  const emitRef = useRef(emit);
+  const pendingRef = useRef<{ owner: string; change: AddressChange } | undefined>(undefined);
+  const emittedRef = useRef<AddressChange | undefined>(undefined);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+
+  useEffect(() => {
+    emitRef.current = emit;
+  });
+  useEffect(() => () => clearTimeout(timerRef.current), []);
+
+  return useMemo<AddressChangePublisher>(
+    () => ({
+      publish: (owner, change) => {
+        pendingRef.current = { owner, change };
+        clearTimeout(timerRef.current);
+        timerRef.current = setTimeout(() => {
+          const next = pendingRef.current?.change;
+          if (!next) return;
+          if (emittedRef.current && sameAddressChange(emittedRef.current, next)) return;
+          emittedRef.current = next;
+          // a fresh payload per delivery: the retained dedupe value must not alias an object a
+          // direct-mode consumer holds and could mutate
+          emitRef.current({ complete: next.complete, address: { ...next.address } });
+        }, ADDRESS_CHANGE_DEBOUNCE_MS);
+      },
+      abandon: (owner) => {
+        if (pendingRef.current?.owner !== owner) return;
+        pendingRef.current = undefined;
+        clearTimeout(timerRef.current);
+      },
+    }),
+    [],
+  );
+}

package/src/core/payments/billing-merge.ts

@@ -0,0 +1,91 @@
+// ported verbatim from frontend/apps/web/src/elements/payments/lib/billing-merge.ts — keep in sync when the web element changes
+
+/**
+ * The billing-details precedence merge for the confirm rail: explicit
+ * `createConfirmationToken({ billingDetails })` input > standalone address element values >
+ * the payment element's internal billing block. Applied twice along the cascade (controller
+ * merges the address element under the input; the payment element merges its block under the
+ * result) — scalars merge field-level, the address object is ATOMIC per source (a mixed-source
+ * address would be incoherent), which keeps the two applications associative.
+ */
+import type { EmittedAddress } from '../address/engine';
+
+interface BillingAddressBag {
+  country?: string;
+  line1?: string;
+  line2?: string;
+  city?: string;
+  state?: string;
+  postal_code?: string;
+}
+
+export interface BillingDetailsBag {
+  email?: string;
+  name?: string;
+  phone?: string;
+  address?: BillingAddressBag;
+}
+
+export interface CollectedAddressSnapshot {
+  complete: boolean;
+  completeWithoutPhone?: boolean;
+  phoneRequired?: boolean;
+  address: EmittedAddress;
+  phone?: string;
+}
+
+function billingNameOf(address: EmittedAddress): string | undefined {
+  if (address.name) return address.name;
+  const joined = [address.first_name, address.last_name].filter(Boolean).join(' ');
+  return joined || undefined;
+}
+
+function billingAddressOf(address: EmittedAddress): BillingAddressBag | undefined {
+  const bag: BillingAddressBag = {};
+  if (address.country) bag.country = address.country;
+  if (address.line1) bag.line1 = address.line1;
+  if (address.line2) bag.line2 = address.line2;
+  if (address.city) bag.city = address.city;
+  if (address.state) bag.state = address.state;
+  if (address.postal_code) bag.postal_code = address.postal_code;
+  return Object.keys(bag).length > 0 ? bag : undefined;
+}
+
+function hasAddressValues(address: BillingAddressBag | undefined): boolean {
+  return Boolean(
+    address && Object.values(address).some((value) => typeof value === 'string' && value.trim().length > 0),
+  );
+}
+
+/**
+ * Merge a collected form snapshot UNDER an explicit billing-details bag. When the collected
+ * form is the address source actually being used and it is incomplete, the merge throws — a
+ * confirm over a half-filled form must fail loud, exactly like the surfaces' own validation
+ * (an explicit complete input keeps winning silently).
+ */
+export function mergeBillingWithCollected(
+  explicit: BillingDetailsBag | undefined,
+  collected: CollectedAddressSnapshot | undefined,
+): BillingDetailsBag | undefined {
+  if (!collected) return explicit;
+  const explicitAddress = hasAddressValues(explicit?.address) ? explicit?.address : undefined;
+  const explicitCompletesPhone = Boolean(explicit?.phone && collected.completeWithoutPhone);
+  const requiredPhoneMissing = collected.phoneRequired && !explicit?.phone && !collected.phone;
+  if (requiredPhoneMissing) {
+    throw new Error('The address form is incomplete — finish it or pass billingDetails to createConfirmationToken');
+  }
+  if (!explicitAddress && !explicitCompletesPhone && !collected.complete) {
+    throw new Error('The address form is incomplete — finish it or pass billingDetails to createConfirmationToken');
+  }
+  const merged: BillingDetailsBag = { ...explicit };
+  if (!merged.phone && collected.phone) merged.phone = collected.phone;
+  if (!merged.name) {
+    const name = billingNameOf(collected.address);
+    if (name) merged.name = name;
+    else delete merged.name;
+  }
+  const address = explicitAddress ?? billingAddressOf(collected.address);
+  if (address) merged.address = address;
+  else delete merged.address;
+  return Object.keys(merged).length > 0 ? merged : explicit;
+}

package/src/core/payments/browser-info.ts

@@ -0,0 +1,43 @@
+import { Dimensions, NativeModules, PixelRatio, Platform } from 'react-native';
+
+import type { BrowserInfo } from '../../api/types';
+
+/**
+ * The React Native counterpart of the web element's `browser_info` capture.
+ *
+ * The field names are the wire's, because the backend feeds them to 3DS, which was specified for
+ * browsers. An app has no `navigator`, so each value is the nearest honest platform fact rather
+ * than a fabricated browser one — omitted where there is no honest answer.
+ */
+export function capturedBrowserInfo(): BrowserInfo {
+	const { width, height } = Dimensions.get('screen');
+	const scale = PixelRatio.get();
+
+	return {
+		platform: Platform.OS === 'ios' ? 'iPhone' : 'Linux armv8l',
+		color_depth: 24,
+		screen_width: Math.round(width * scale),
+		screen_height: Math.round(height * scale),
+		language: resolveLanguage(),
+		java_enabled: false,
+		browser_time_difference: new Date().getTimezoneOffset(),
+		user_agent: `WhopElementsReactNative/${Platform.OS} ${String(Platform.Version)}`,
+	};
+}
+
+function resolveLanguage(): string {
+	const tag = deviceLocale();
+	return tag ? tag.replace(/_/g, '-') : 'en-US';
+}
+
+/** The one platform read; kept separate so the locale default can reuse it. */
+export function deviceLocale(): string | undefined {
+	if (Platform.OS === 'ios') {
+		const settings = NativeModules.SettingsManager?.settings as
+			| { AppleLocale?: string; AppleLanguages?: string[] }
+			| undefined;
+		return settings?.AppleLocale ?? settings?.AppleLanguages?.[0];
+	}
+	const i18n = NativeModules.I18nManager as { localeIdentifier?: string } | undefined;
+	return i18n?.localeIdentifier;
+}

package/src/core/payments/bt.ts

@@ -0,0 +1,176 @@
+import { sha256 } from '@noble/hashes/sha2';
+import { bytesToHex } from '@noble/hashes/utils';
+import type { useBasisTheory } from '@basis-theory/react-native-elements';
+
+import type { WhopClient } from '../../api/client';
+import { apiErrorMessage } from './errors';
+import type { PaymentTokenizationErrorCode } from './errors';
+
+/** The package re-exports the hook but not its return type, so derive it rather than reach into a
+ *  deep path that could move. */
+export type BasisTheoryElements = NonNullable<ReturnType<typeof useBasisTheory>['bt']>;
+
+/** The opaque handle a Basis Theory element hands out. It carries an id and a formatter, never the
+ *  value the buyer typed — which is the whole isolation guarantee. */
+export interface CardRefs {
+	number: unknown;
+	expiryMonth: unknown;
+	expiryYear: unknown;
+	cvc: unknown;
+}
+
+export type CardFieldFailure = 'incomplete' | 'invalid' | undefined;
+
+export interface CardFieldFailures {
+	number?: CardFieldFailure;
+	expiry?: CardFieldFailure;
+	cvc?: CardFieldFailure;
+}
+
+export interface CardTokenizationFailure {
+	ok: false;
+	code: PaymentTokenizationErrorCode;
+	message: string;
+	fields?: CardFieldFailures;
+}
+
+export type CardTokenizationResult = { ok: true; token: string } | CardTokenizationFailure;
+
+const CARD_TOKEN_TTL_MS = 60 * 60 * 1000;
+
+/**
+ * Assemble one Basis Theory card token from the three field refs.
+ *
+ * This is the web ceremony (`card-fields/bt.ts`) with the frame hops removed: a BT session anchors
+ * a nonce-derived container, the number seeds an ephemeral token into it, the Whop backend
+ * authorizes the session for that container alone, and the remaining fields patch in under the
+ * session key. The web element splits these across three iframes and threads a serializable grant
+ * between them; here all three refs live in one realm, so the grant never leaves this function.
+ *
+ * The ceremony is kept rather than collapsed into a single create because it is what the
+ * card-assembly Basis Theory application is configured to permit: the backend authorizes
+ * `token:update` scoped to `starts_with` the derived container, for ten minutes.
+ */
+export async function tokenizeCard(
+	bt: BasisTheoryElements,
+	refs: CardRefs,
+	command: { accountId: string; publicKey: string },
+	sdk: WhopClient,
+): Promise<CardTokenizationResult> {
+	if (!refs.number || !refs.expiryMonth || !refs.expiryYear || !refs.cvc) {
+		return {
+			ok: false,
+			code: 'card_fields_not_ready',
+			message: 'Card fields are not ready yet',
+		};
+	}
+
+	let session: Awaited<ReturnType<BasisTheoryElements['sessions']['create']>>;
+	try {
+		session = await bt.sessions.create();
+	} catch (err) {
+		return collectFailure(err, 'card_tokenizer_session_failed', 'card_tokenizer_session_failed');
+	}
+	if (!session) {
+		return {
+			ok: false,
+			code: 'card_tokenizer_session_failed',
+			message: 'the tokenizer returned no session',
+		};
+	}
+
+	const container = `/card-assembly/${sha256Hex(session.nonce)}/`;
+
+	let tokenId: string;
+	try {
+		const token = await bt.tokens.create(
+			{
+				type: 'card',
+				data: { number: refs.number as never },
+				containers: [container],
+				expiresAt: new Date(Date.now() + CARD_TOKEN_TTL_MS).toISOString(),
+			},
+			// The key is passed per call, never left to the client's config: Basis Theory's client
+			// is a module-level singleton whose first key wins for the whole process, so a second
+			// client built with a different application's key (a method's secure fields) would
+			// otherwise silently sign these calls.
+			{ apiKey: command.publicKey },
+		);
+		if (!token?.id) {
+			return { ok: false, code: 'card_number_tokenization_failed', message: 'the tokenizer returned no token' };
+		}
+		tokenId = token.id;
+	} catch (err) {
+		return collectFailure(err, 'card_number_validation_failed', 'card_number_tokenization_failed');
+	}
+
+	try {
+		await sdk.paymentMethodTypes.createSession('card', { account_id: command.accountId, nonce: session.nonce });
+	} catch (err) {
+		return {
+			ok: false,
+			code: 'card_session_authorization_failed',
+			message: apiErrorMessage(err, 'card session authorization failed'),
+		};
+	}
+
+	try {
+		await bt.tokens.update(
+			tokenId,
+			{ data: { expiration_month: refs.expiryMonth as never, expiration_year: refs.expiryYear as never } },
+			{ apiKey: session.sessionKey },
+		);
+	} catch (err) {
+		return collectFailure(err, 'card_expiry_validation_failed', 'card_expiry_tokenization_failed');
+	}
+
+	try {
+		await bt.tokens.update(tokenId, { data: { cvc: refs.cvc as never } }, { apiKey: session.sessionKey });
+	} catch (err) {
+		return collectFailure(err, 'card_cvc_validation_failed', 'card_cvc_tokenization_failed');
+	}
+
+	return { ok: true, token: tokenId };
+}
+
+/**
+ * Must byte-match the backend's `Digest::SHA256.hexdigest` — lowercase hex, no separators.
+ *
+ * `@noble/hashes` UTF-8 encodes a string input itself, which is also why this does not reach for
+ * `TextEncoder`: React Native has no DOM and does not guarantee one.
+ */
+export function sha256Hex(value: string): string {
+	return bytesToHex(sha256(value));
+}
+
+interface ValidationDetails {
+	data?: Record<string, { type?: string } | undefined>;
+}
+
+function collectFailure(
+	err: unknown,
+	validationCode: PaymentTokenizationErrorCode,
+	failureCode: PaymentTokenizationErrorCode,
+): CardTokenizationFailure {
+	const details =
+		err instanceof Error && err.name === 'BasisTheoryValidationError'
+			? (err as Error & { details?: ValidationDetails }).details?.data
+			: undefined;
+	if (details) {
+		return {
+			ok: false,
+			code: validationCode,
+			message: 'Your card details are incomplete or invalid',
+			fields: {
+				number: fieldFailure(details.number),
+				cvc: fieldFailure(details.cvc),
+				expiry: fieldFailure(details.expiration_month) ?? fieldFailure(details.expiration_year),
+			},
+		};
+	}
+	return { ok: false, code: failureCode, message: err instanceof Error ? err.message : 'Card tokenization failed' };
+}
+
+function fieldFailure(detail: { type?: string } | undefined): CardFieldFailure {
+	return detail?.type === 'invalid' || detail?.type === 'incomplete' ? detail.type : undefined;
+}

package/src/core/payments/currency.ts

@@ -0,0 +1,54 @@
+// ported verbatim from frontend/apps/web/src/elements/payments/lib/currency.ts — keep in sync when the web element changes
+
+/**
+ * The minor-unit factor, mirroring the BACKEND's conversion exactly (Utils.amount_in_cents /
+ * stripe_factor_decimal over ZERO_DECIMAL_CURRENCIES + THREE_DECIMAL_CURRENCIES in
+ * backend/lib/application_constants.rb) — the backend is the authority on a currency's factor,
+ * NOT Intl/CLDR: several acceptable plan currencies (huf, cop, idr, pkr, all) are zero-decimal
+ * in CLDR but charged in 1/100ths by the backend, so an Intl-derived factor is 100× off for
+ * them. Keep these lists in lockstep with the backend constants.
+ */
+
+const ZERO_DECIMAL_CURRENCIES = new Set([
+  'bif',
+  'clp',
+  'djf',
+  'gnf',
+  'jpy',
+  'kmf',
+  'krw',
+  'mga',
+  'pyg',
+  'rwf',
+  'ugx',
+  'vnd',
+  'vuv',
+  'xaf',
+  'xof',
+  'xpf',
+]);
+
+const THREE_DECIMAL_CURRENCIES = new Set(['bhd', 'jod', 'kwd', 'omr', 'tnd']);
+
+export function currencyMinorDigits(currency: string): number {
+  const code = currency.toLowerCase();
+  if (ZERO_DECIMAL_CURRENCIES.has(code)) return 0;
+  if (THREE_DECIMAL_CURRENCIES.has(code)) return 3;
+  return 2;
+}
+
+/** Major-unit decimal (how money rides the wire) → the minor-unit integer a charge takes, on the
+ *  backend's factor above — never Intl's. toFixed(4) first (kills float-scale artifacts like
+ *  29.99×100 → 2998.999…), then trunc (a genuinely sub-minor fraction never rounds the charge UP). */
+export function toMinorUnits(majorAmount: number, currency: string): number {
+  return Math.trunc(Number((majorAmount * 10 ** currencyMinorDigits(currency)).toFixed(4)));
+}
+
+// Charged in minor units but shown without them (PaymentsConstants::NO_MINOR_UNIT_CURRENCIES).
+const NO_MINOR_UNIT_CURRENCIES = new Set(['cop']);
+
+export function currencyDisplayDigits(currency: string): number {
+  const code = currency.toLowerCase();
+  if (NO_MINOR_UNIT_CURRENCIES.has(code)) return 0;
+  return currencyMinorDigits(code);
+}