@whop/elements-react-native 0.1.0

package/src/core/payments/wallet-contact.ts

@@ -0,0 +1,56 @@
+/** The contact fields an OS wallet sheet collected, in the wire keys the mint sends. */
+export interface WalletContact {
+	email?: string;
+	name?: string;
+	address?: {
+		line1?: string;
+		line2?: string;
+		city?: string;
+		state?: string;
+		postal_code?: string;
+		country?: string;
+	};
+}
+
+/**
+ * The native envelope, read tolerantly.
+ *
+ * Both platform modules answer with `{ paymentData, email?, name?, address? }`. Anything else is
+ * treated as the bare token, so an app whose native side has not been rebuilt still tokenizes — it
+ * just gets no contacts, which is exactly the behaviour it had before.
+ */
+export function readSheetResult(raw: string): { paymentData: string } & WalletContact {
+	try {
+		const parsed: unknown = JSON.parse(raw);
+		if (
+			parsed !== null &&
+			typeof parsed === 'object' &&
+			typeof (parsed as { paymentData?: unknown }).paymentData === 'string'
+		) {
+			return parsed as { paymentData: string } & WalletContact;
+		}
+	} catch {
+		// Not JSON at all: Google Pay's opaque gateway token.
+	}
+	return { paymentData: raw };
+}
+
+/**
+ * Folds the sheet's own contacts under whatever the caller and the mounted elements already supply.
+ *
+ * Explicit input always wins. The sheet is only ever asked for an email or an address when no
+ * element is mounted to collect them, so in practice it fills exactly the gaps — which is the whole
+ * point: without this the mint refused a buyer who had just typed their email into Apple Pay.
+ */
+export function mergeWalletContact(
+	explicit: Partial<{ email: string; name: string }> | undefined,
+	contact: WalletContact,
+): Partial<{ email: string; name: string }> & { address?: WalletContact['address'] } {
+	const merged: Partial<{ email: string; name: string }> & { address?: WalletContact['address'] } = {
+		...explicit,
+	};
+	if (!merged.email && contact.email) merged.email = contact.email;
+	if (!merged.name && contact.name) merged.name = contact.name;
+	if (contact.address && !merged.address) merged.address = contact.address;
+	return merged;
+}

package/src/elements/address.tsx

@@ -0,0 +1,570 @@
+import { type ReactNode, useCallback, useEffect, useMemo, useReducer, useRef, useState } from 'react';
+import { type StyleProp, View, type ViewStyle } from 'react-native';
+
+import {
+	type CountryFormat,
+	type EmittedAddress,
+	loadCountryCatalog,
+	normalizeCountry,
+	parseCountryFormat,
+	type RemoteCountryData,
+	type StateOption,
+} from '../core/address/engine';
+import {
+	type AddressFormAction,
+	type AddressFormConfig,
+	addressFormReducer,
+	type AddressSnapshot,
+	type AddressValueKey,
+	allowedCountryList,
+	type CustomFieldSpec,
+	pairedGridRows,
+	planFields,
+	requiredFloorFor,
+	seedAddressForm,
+	snapshotAddressForm,
+	placeAllowList,
+} from '../core/address/form-state';
+import { countryName } from '../core/address/country-name';
+import type { AddressSuggestion } from '../core/address/suggest';
+import { resolveSubdivision } from '../core/address/suggest';
+import { useAddressSuggestions } from '../core/address/use-suggestions';
+import { WhopAddressSuggestions } from '../native';
+import { SuggestionList } from '../ui/suggestions';
+import { detectIpCountry } from '../core/address/places';
+import { useLocale, useT } from '../i18n';
+import { usePaymentsState, usePaymentsStore } from '../namespace';
+import { useTheme } from '../theme/provider';
+import { ElementFrame } from '../ui/element-frame';
+import { Field, FieldSkeleton, Row, Stack, TextButton } from '../ui/primitives';
+import { Select } from '../ui/select';
+
+export interface AddressChangePayload {
+	complete: boolean;
+	address: EmittedAddress;
+	custom: Record<string, string>;
+}
+
+export interface AddressElementProps {
+	/** Autocomplete purpose: `billing` (default) or `shipping`. */
+	mode?: 'billing' | 'shipping';
+	/** `full` stacks labeled fields. `compact` groups placeholder-labeled fields. */
+	layout?: 'compact' | 'full';
+	/** `full` follows the country's complete format. `minimal` collects country and postal code. */
+	scope?: 'minimal' | 'full';
+	defaultValues?: { name?: string; address?: Partial<EmittedAddress> };
+	/** Default the country from the buyer's IP. Falls back to `countryHint`, then US. */
+	detectCountry?: boolean;
+	allowedCountries?: string[];
+	name?: 'combined' | 'split' | 'none';
+	organization?: 'none' | 'name' | 'name_with_type';
+	line2?: 'toggle' | 'always' | 'never';
+	/**
+	 * Street suggestions from the platform geocoder — MapKit on iOS, `android.location.Geocoder` on
+	 * Android. No API key and no account: where the web element asks Google Places, this asks the OS.
+	 * Falls back silently to manual entry on a device whose geocoder answers nothing.
+	 *
+	 * @default true — the same default the web element takes.
+	 */
+	autocomplete?: boolean;
+	customFields?: CustomFieldSpec[];
+	/** Fallback country after `defaultValues` and IP detection. ISO 3166-1 alpha-2. */
+	countryHint?: string;
+	style?: StyleProp<ViewStyle>;
+	fallback?: ReactNode;
+	onChange?: (payload: AddressChangePayload) => void;
+	onReady?: () => void;
+	onError?: (error: { message: string; code?: string }) => void;
+}
+
+/**
+ * Collects a postal address using the per-country format engine ported from the web element, so
+ * field order, labels, required-ness, postal validation, and the state lists are identical across
+ * the two surfaces for all 241 countries in the catalog.
+ */
+export function AddressElement({
+	mode = 'billing',
+	layout = 'full',
+	scope = 'full',
+	defaultValues,
+	detectCountry = true,
+	allowedCountries,
+	name = 'combined',
+	organization = 'none',
+	line2 = 'toggle',
+	autocomplete = true,
+	customFields,
+	countryHint = '',
+	style,
+	fallback,
+	onChange,
+	onReady,
+	onError,
+}: AddressElementProps) {
+	const t = useT();
+	const theme = useTheme();
+	const store = usePaymentsStore();
+	const methodCountries = usePaymentsState((s) => s.methodCountries);
+
+	const [catalog, setCatalog] = useState<Record<string, RemoteCountryData> | null>(null);
+	const [detected, setDetected] = useState<string | undefined>(undefined);
+	const [detecting, setDetecting] = useState(detectCountry);
+	const [failure, setFailure] = useState<{ message: string; code?: string } | null>(null);
+
+	useEffect(() => {
+		let alive = true;
+		loadCountryCatalog()
+			.then((data) => alive && setCatalog(data))
+			.catch((err: Error) => alive && setFailure({ message: err.message, code: 'ADDRESS_CATALOG_FAILED' }));
+		return () => {
+			alive = false;
+		};
+	}, []);
+
+	useEffect(() => {
+		if (!detectCountry) return;
+		let alive = true;
+		detectIpCountry()
+			.then((country) => {
+				if (!alive) return;
+				setDetected(country);
+				setDetecting(false);
+			})
+			.catch(() => alive && setDetecting(false));
+		return () => {
+			alive = false;
+		};
+	}, [detectCountry]);
+
+	// The method constraint NARROWS the consumer's allow list, never replaces it — replacing would
+	// let a tier's countries widen a restriction the integrator set deliberately.
+	const effectiveAllowed = useMemo(
+		() => effectiveAllowedCountries(methodCountries ?? undefined, allowedCountries),
+		[methodCountries, allowedCountries],
+	);
+
+	const config = useMemo<AddressFormConfig>(
+		() => ({
+			mode,
+			layout,
+			scope,
+			name,
+			organization,
+			line2,
+			autocomplete,
+			requiredFloor: requiredFloorFor(scope),
+			allowedCountries: effectiveAllowed,
+			customFields,
+		}),
+		[mode, layout, scope, name, organization, line2, autocomplete, effectiveAllowed, customFields],
+	);
+
+	const ready = Boolean(catalog) && !detecting;
+
+	if (!catalog || detecting) {
+		return (
+			<ElementFrame
+				style={style}
+				fallback={fallback}
+				skeleton={
+					<Stack>
+						<FieldSkeleton />
+						<FieldSkeleton />
+						<FieldSkeleton />
+					</Stack>
+				}
+				ready={false}
+				error={failure}
+				onReady={onReady}
+				onError={onError}
+			>
+				<View />
+			</ElementFrame>
+		);
+	}
+
+	return (
+		<AddressForm
+			catalog={catalog}
+			config={config}
+			detected={detected}
+			countryHint={countryHint}
+			defaultValues={defaultValues}
+			ready={ready}
+			style={style}
+			fallback={fallback}
+			onChange={onChange}
+			onReady={onReady}
+			onError={onError}
+			store={store}
+			t={t}
+			spacing={theme.tokens.spacing}
+		/>
+	);
+}
+
+/** Intersection when both exist; a disjoint pair keeps the consumer's list rather than widening. */
+export function effectiveAllowedCountries(
+	methodCountries: string[] | undefined,
+	allowedCountries: string[] | undefined,
+): string[] | undefined {
+	if (!methodCountries?.length) return allowedCountries;
+	if (!allowedCountries?.length) return methodCountries;
+	const consumerAllowed = new Set(allowedCountries.map((code) => code.toLowerCase()));
+	const intersection = methodCountries.filter((code) => consumerAllowed.has(code.toLowerCase()));
+	return intersection.length > 0 ? intersection : allowedCountries;
+}
+
+interface AddressFormProps {
+	catalog: Record<string, RemoteCountryData>;
+	config: AddressFormConfig;
+	detected: string | undefined;
+	countryHint: string;
+	defaultValues: AddressElementProps['defaultValues'];
+	ready: boolean;
+	style?: StyleProp<ViewStyle>;
+	fallback?: ReactNode;
+	onChange?: (payload: AddressChangePayload) => void;
+	onReady?: () => void;
+	onError?: (error: { message: string; code?: string }) => void;
+	store: ReturnType<typeof usePaymentsStore>;
+	t: ReturnType<typeof useT>;
+	spacing: number;
+}
+
+function AddressForm({
+	catalog,
+	config,
+	detected,
+	countryHint,
+	defaultValues,
+	ready,
+	style,
+	fallback,
+	onChange,
+	onReady,
+	onError,
+	store,
+	t,
+	spacing,
+}: AddressFormProps) {
+	const catalogCountries = useMemo(() => Object.keys(catalog), [catalog]);
+
+	const [state, rawDispatch] = useReducer(
+		addressFormReducer,
+		undefined,
+		() => seedAddressForm(config, { defaultValues, detectedCountry: detected, countryHint }, catalogCountries),
+	);
+
+	const format: CountryFormat = useMemo(
+		() => parseCountryFormat(state.country, catalog[state.country]),
+		[state.country, catalog],
+	);
+	const plan = useMemo(() => planFields(config, format), [config, format]);
+	const snapshot: AddressSnapshot = useMemo(
+		() => snapshotAddressForm(config, format, state),
+		[config, format, state],
+	);
+
+	const locale = useLocale();
+	const countryOptions = useMemo(() => {
+		const allowed = allowedCountryList(config, catalogCountries);
+		return allowed
+			.map((code) => ({ value: code, label: countryName(code, locale) }))
+			.sort((a, b) => a.label.localeCompare(b.label));
+	}, [config, catalogCountries, locale]);
+
+	const latestChange = useRef(onChange);
+	latestChange.current = onChange;
+
+	// The address element is the billing source while it is mounted, so the controller reads its
+	// snapshot at confirm rather than the payment element's internal block.
+	useEffect(() => {
+		store.patch({ addressLive: true });
+		return () => store.patch({ addressLive: false, addressCollected: undefined });
+	}, [store]);
+
+	useEffect(() => {
+		store.patch({
+			addressCollected: {
+				complete: snapshot.complete,
+				address: snapshot.address,
+				custom: snapshot.custom,
+			} as never,
+		});
+		latestChange.current?.({ complete: snapshot.complete, address: snapshot.address, custom: snapshot.custom });
+	}, [snapshot, store]);
+
+	const [line1Focused, setLine1Focused] = useState(false);
+	const suggestions = useAddressSuggestions(config.autocomplete, state.values.line1 ?? '');
+	const placeAllowed = useMemo(() => placeAllowList(config, catalogCountries), [config, catalogCountries]);
+	const showSuggestions = config.autocomplete && line1Focused && suggestions.length > 0;
+
+	// `apply-place` WHOLE-REPLACES the locality grid, so a resolve landing after the buyer moved on
+	// would silently rewrite line1, city, state and postal under them.
+	//
+	// The supersede is tracked with a counter bumped INSIDE dispatch rather than by reading the
+	// reducer's own `selecting` flag through a ref. A ref is only assigned during render, and an
+	// Android resolve is a cache hit that can settle before that render happens — which raced both
+	// ways: a fresh pick read a stale `false` and no-opped, and a superseding edit had not yet been
+	// seen, so a stale place still applied.
+	const pickSequence = useRef(0);
+	const dispatch = useCallback((action: AddressFormAction) => {
+		if (action.type === 'edit' || action.type === 'set-country') pickSequence.current += 1;
+		rawDispatch(action);
+	}, []);
+
+	const pickSuggestion = (suggestion: AddressSuggestion) => {
+		setLine1Focused(false);
+		const sequence = pickSequence.current + 1;
+		pickSequence.current = sequence;
+		dispatch({ type: 'begin-select' });
+		void WhopAddressSuggestions.resolve(suggestion.id, state.country).then((parsed) => {
+			if (pickSequence.current !== sequence) return;
+			if (!parsed) {
+				dispatch({ type: 'select-failed' });
+				return;
+			}
+			// The state Select is keyed on the catalog's sub_key, and a geocoder may answer with the
+			// display name instead, so an unresolved subdivision must not reach the form as-is.
+			dispatch({
+				type: 'apply-place',
+				parsed: { ...parsed, state: resolveSubdivision(parsed.state, format.stateOptions) },
+				allowed: placeAllowed,
+			});
+		});
+	};
+
+	const showError = (key: string) => (state.showAllErrors || state.touched[key] ? errorText(t, snapshot.errors[key]) : undefined);
+	const compact = config.layout === 'compact';
+
+	const textField = (key: AddressValueKey, label: string, extra?: Partial<Parameters<typeof Field>[0]>) => (
+		<Field
+			key={key}
+			label={compact ? undefined : label}
+			placeholder={compact ? label : undefined}
+			accessibilityLabel={label}
+			value={state.values[key] ?? ''}
+			onChangeText={(value) => dispatch({ type: 'edit', field: key, value })}
+			onBlur={() => dispatch({ type: 'blur', field: key })}
+			error={showError(key)}
+			containerStyle={{ flex: 1 }}
+			{...extra}
+		/>
+	);
+
+	const nameFields =
+		config.name === 'none'
+			? null
+			: config.name === 'split'
+				? (
+						<Row>
+							{textField('first_name', t('First name'), { autoComplete: 'given-name', textContentType: 'givenName' })}
+							{textField('last_name', t('Last name'), { autoComplete: 'family-name', textContentType: 'familyName' })}
+						</Row>
+					)
+				: textField('name', t('Name'), { autoComplete: 'name', textContentType: 'name' });
+
+	const organizationFields =
+		config.organization === 'none' ? null : (
+			<Stack gap={spacing * 2}>
+				{textField('organization', t('Organization'), { autoComplete: 'organization' })}
+				{config.organization === 'name_with_type' ? (
+					<Select
+						label={t('Organization type')}
+						value={state.organizationType || undefined}
+						options={[
+							{ value: 'business', label: t('Business') },
+							{ value: 'individual', label: t('Individual') },
+						]}
+						onChange={(value) =>
+							dispatch({ type: 'set-organization-type', value: value as 'business' | 'individual' })
+						}
+					/>
+				) : null}
+			</Stack>
+		);
+
+	const customAt = (position: CustomFieldSpec['position']) =>
+		(config.customFields ?? [])
+			.filter((field) => field.position === position)
+			.map((field) => {
+				const key = `custom:${field.key}`;
+				const value = state.custom[field.key] ?? '';
+				const onChange = (next: string) => dispatch({ type: 'edit-custom', key: field.key, value: next });
+				if (field.type === 'select') {
+					return (
+						<Select
+							key={key}
+							label={compact ? undefined : field.label}
+							placeholder={compact ? field.label : undefined}
+							accessibilityLabel={field.label}
+							value={value || undefined}
+							options={(field.options ?? []).map((option) => ({ value: option, label: option }))}
+							onChange={onChange}
+							error={showError(key)}
+							searchable={(field.options ?? []).length > 12}
+						/>
+					);
+				}
+				return (
+					<Field
+						key={key}
+						label={compact ? undefined : field.label}
+						placeholder={compact ? field.label : undefined}
+						accessibilityLabel={field.label}
+						value={value}
+						onChangeText={onChange}
+						onBlur={() => dispatch({ type: 'blur', field: key })}
+						error={showError(key)}
+						keyboardType={field.type === 'phone' ? 'phone-pad' : 'default'}
+						autoComplete={field.type === 'phone' ? 'tel' : undefined}
+					/>
+				);
+			});
+
+	const gridRows = pairedGridRows(plan.gridFields);
+
+	return (
+		<ElementFrame
+			style={style}
+			fallback={fallback}
+			skeleton={
+				<Stack>
+					<FieldSkeleton />
+					<FieldSkeleton />
+					<FieldSkeleton />
+				</Stack>
+			}
+			ready={ready}
+			onReady={onReady}
+			onError={onError}
+		>
+			<Stack>
+				{nameFields}
+				{customAt('after_name')}
+				{organizationFields}
+				{customAt('after_organization')}
+				{customAt('before_country')}
+				<Select
+					label={t('Country')}
+					value={state.country}
+					options={countryOptions}
+					onChange={(country) => dispatch({ type: 'set-country', country: normalizeCountry(country) ?? country })}
+					searchable
+					partName="whop-AddressCountrySelect"
+				/>
+				{plan.gridFields.includes('line1') ? (
+					<View>
+						{textField('line1', gridLabel(t, 'line1', format), {
+							...gridExtras('line1', format),
+							onFocus: () => setLine1Focused(true),
+							onBlur: () => {
+								setLine1Focused(false);
+								dispatch({ type: 'blur', field: 'line1' });
+							},
+						})}
+						{showSuggestions ? <SuggestionList suggestions={suggestions} onPick={pickSuggestion} /> : null}
+					</View>
+				) : null}
+				{config.line2 === 'always' || state.line2Open ? textField('line2', t('Address line 2')) : null}
+				{gridRows.map((row) => (
+					<Row key={row.join('-')}>
+						{row.map((key) =>
+							key === 'state' && format.stateOptions.length > 0
+								? (
+										<View key={key} style={{ flex: 1 }}>
+											<Select
+												label={compact ? undefined : stateLabel(t, format)}
+												placeholder={compact ? stateLabel(t, format) : undefined}
+												accessibilityLabel={stateLabel(t, format)}
+												value={state.values.state || undefined}
+												options={format.stateOptions.map(toOption)}
+												onChange={(value) => dispatch({ type: 'edit', field: 'state', value })}
+												error={showError('state')}
+												searchable={format.stateOptions.length > 12}
+											/>
+										</View>
+									)
+								: textField(key, gridLabel(t, key, format), gridExtras(key, format)),
+						)}
+					</Row>
+				))}
+				{customAt('after_address')}
+				{config.line2 === 'toggle' && !state.line2Open ? (
+					<TextButton label={t('Add address line 2')} onPress={() => dispatch({ type: 'toggle-line2' })} />
+				) : null}
+			</Stack>
+		</ElementFrame>
+	);
+}
+
+function toOption(option: StateOption): { value: string; label: string } {
+	// The engine keys options by the catalog's own sub_key; `iso` is display metadata, not the value
+	// the format engine validates against.
+	return { value: option.key, label: option.name };
+}
+
+function stateLabel(t: ReturnType<typeof useT>, format: CountryFormat): string {
+	switch (format.stateLabel) {
+		case 'province':
+			return t('Province');
+		case 'emirate':
+			return t('Emirate');
+		case 'county':
+			return t('County');
+		case 'prefecture':
+			return t('Prefecture');
+		case 'island':
+			return t('Island');
+		case 'parish':
+			return t('Parish');
+		case 'department':
+			return t('Department');
+		case 'do_si':
+			return t('Province');
+		case 'oblast':
+			return t('Oblast');
+		case 'area':
+			return t('Area');
+		default:
+			return t('State');
+	}
+}
+
+function gridLabel(t: ReturnType<typeof useT>, key: string, format: CountryFormat): string {
+	switch (key) {
+		case 'line1':
+			return t('Address line 1');
+		case 'city':
+			return t('City');
+		case 'state':
+			return stateLabel(t, format);
+		case 'postal_code':
+			return format.postalLabel === 'zip' ? t('ZIP code') : format.postalLabel === 'pin' ? t('PIN code') : t('Postal code');
+		default:
+			return key;
+	}
+}
+
+function gridExtras(key: string, format: CountryFormat): Partial<Parameters<typeof Field>[0]> {
+	if (key === 'postal_code') {
+		const field = format.fields.find((f) => f.type === 'postal_code');
+		return {
+			autoComplete: 'postal-code',
+			textContentType: 'postalCode',
+			autoCapitalize: 'characters',
+			placeholder: field?.postalPlaceholder,
+		};
+	}
+	if (key === 'line1') return { autoComplete: 'address-line1', textContentType: 'streetAddressLine1' };
+	if (key === 'city') return { autoComplete: 'postal-address-locality', textContentType: 'addressCity' };
+	return {};
+}
+
+function errorText(t: ReturnType<typeof useT>, code: string | undefined): string | undefined {
+	if (code === 'required') return t('Required');
+	if (code === 'invalid') return t("That doesn't look right");
+	return undefined;
+}
+