@primer-io/react-native 2.46.0 → 3.0.0-beta.0

package/src/Components/internal/ui/index.ts

@@ -0,0 +1,4 @@
+export { CheckoutButton } from './CheckoutButton';
+export type { CheckoutButtonProps } from './CheckoutButton';
+export { VaultedCardCvvRow } from './VaultedCardCvvRow';
+export type { VaultedCardCvvRowProps } from './VaultedCardCvvRow';

package/src/Components/internal/utils/errors.ts

@@ -0,0 +1,9 @@
+/**
+ * Normalizes an unknown thrown/rejected value into an `Error` instance.
+ *
+ * Use at catch/reject boundaries to avoid exposing arbitrary thrown values
+ * (strings, objects, `undefined`) through a typed `Error` surface.
+ */
+export function toError(value: unknown): Error {
+  return value instanceof Error ? value : new Error(String(value));
+}

package/src/Components/internal/utils/formatting.ts

@@ -0,0 +1,32 @@
+/**
+ * Formats a date for display using locale conventions.
+ *
+ * @param date - The Date object to format
+ * @param locale - BCP 47 locale tag (e.g., "en-US", "de-DE")
+ * @param options - Optional Intl.DateTimeFormat options for customization
+ * @returns Formatted date string
+ */
+export function formatDate(date: Date, locale: string, options?: Intl.DateTimeFormatOptions): string {
+  try {
+    return new Intl.DateTimeFormat(locale, options).format(date);
+  } catch (error) {
+    console.warn(`[Primer] Failed to format date for locale "${locale}"`, error);
+    return date.toISOString();
+  }
+}
+
+/**
+ * Converts a SCREAMING_SNAKE_CASE payment method type to a human-readable label.
+ *
+ * Used as a fallback when a resource-provided `paymentMethodName` is unavailable.
+ *
+ * @example titleCaseFromType('PAYMENT_CARD') // 'Payment Card'
+ */
+export function titleCaseFromType(type: string): string {
+  return type
+    .toLowerCase()
+    .split(/[_\s]+/)
+    .filter(Boolean)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(' ');
+}

package/src/Components/status/PrimerErrorScreen.tsx

@@ -0,0 +1,77 @@
+import React, { useMemo } from 'react';
+import { Image, View, StyleSheet } from 'react-native';
+
+import { usePrimerTheme } from '../internal/theme';
+import type { PrimerTokens } from '../internal/theme';
+import { usePrimerLocalization } from '../internal/localization';
+import { STATUS_SCREEN_ICON_SIZE } from '../internal/screens/constants';
+import { CheckoutButton } from '../internal/ui';
+import { PrimerStatusScreenLayout } from './PrimerStatusScreenLayout';
+
+const errorIcon = require('../internal/screens/assets/error-large.png');
+
+export interface PrimerErrorScreenProps {
+  title?: string;
+  subtitle?: string;
+  icon?: React.ReactNode;
+  onRetry?: () => void;
+  onChooseOtherMethod?: () => void;
+  retryLabel?: string;
+  otherMethodLabel?: string;
+}
+
+export function PrimerErrorScreen({
+  title,
+  subtitle,
+  icon,
+  onRetry,
+  onChooseOtherMethod,
+  retryLabel,
+  otherMethodLabel,
+}: PrimerErrorScreenProps) {
+  const tokens = usePrimerTheme();
+  const { t } = usePrimerLocalization();
+  const styles = useMemo(() => createStyles(tokens), [tokens]);
+
+  const resolvedTitle = title ?? t('primer_checkout_error_title');
+  const resolvedSubtitle = subtitle ?? t('primer_checkout_error_subtitle');
+  const resolvedIcon = icon ?? <Image source={errorIcon} style={styles.icon} />;
+
+  const hasButtons = onRetry != null || onChooseOtherMethod != null;
+
+  return (
+    <PrimerStatusScreenLayout icon={resolvedIcon} title={resolvedTitle} subtitle={resolvedSubtitle}>
+      {hasButtons && (
+        <View style={styles.buttonGroup}>
+          {onRetry != null && (
+            <CheckoutButton title={retryLabel ?? t('primer_common_button_retry')} variant="primary" onPress={onRetry} />
+          )}
+          {onChooseOtherMethod != null && (
+            <CheckoutButton
+              title={otherMethodLabel ?? t('primer_checkout_error_button_other_methods')}
+              variant="outlined"
+              onPress={onChooseOtherMethod}
+            />
+          )}
+        </View>
+      )}
+    </PrimerStatusScreenLayout>
+  );
+}
+
+function createStyles(tokens: PrimerTokens) {
+  const { spacing } = tokens;
+
+  /* eslint-disable react-native/no-unused-styles */
+  return StyleSheet.create({
+    buttonGroup: {
+      gap: spacing.small,
+      width: '100%',
+    },
+    icon: {
+      height: STATUS_SCREEN_ICON_SIZE,
+      width: STATUS_SCREEN_ICON_SIZE,
+    },
+  });
+  /* eslint-enable react-native/no-unused-styles */
+}

package/src/Components/status/PrimerLoadingScreen.tsx

@@ -0,0 +1,43 @@
+import type { ReactNode } from 'react';
+import { ActivityIndicator, View, StyleSheet } from 'react-native';
+
+import { usePrimerTheme } from '../internal/theme';
+import { usePrimerLocalization } from '../internal/localization';
+import { STATUS_SCREEN_ICON_SIZE } from '../internal/screens/constants';
+import { PrimerStatusScreenLayout } from './PrimerStatusScreenLayout';
+
+const SPINNER_SCALE = 1.1;
+
+export interface PrimerLoadingScreenProps {
+  title?: string;
+  subtitle?: string;
+  /** Custom loading visual rendered in the centered slot. Defaults to the SDK spinner. */
+  icon?: ReactNode;
+}
+
+export function PrimerLoadingScreen({ title, subtitle, icon }: PrimerLoadingScreenProps) {
+  const tokens = usePrimerTheme();
+  const { t } = usePrimerLocalization();
+
+  const resolvedTitle = title ?? t('primer_checkout_loading_indicator');
+  const resolvedSubtitle = subtitle ?? t('primer_checkout_loading_subtitle');
+  const resolvedIcon = icon ?? (
+    <View style={styles.iconWrapper}>
+      <ActivityIndicator size="large" color={tokens.colors.primary} style={styles.spinner} />
+    </View>
+  );
+
+  return <PrimerStatusScreenLayout icon={resolvedIcon} title={resolvedTitle} subtitle={resolvedSubtitle} />;
+}
+
+const styles = StyleSheet.create({
+  iconWrapper: {
+    alignItems: 'center',
+    height: STATUS_SCREEN_ICON_SIZE,
+    justifyContent: 'center',
+    width: STATUS_SCREEN_ICON_SIZE,
+  },
+  spinner: {
+    transform: [{ scale: SPINNER_SCALE }],
+  },
+});

package/src/Components/status/PrimerStatusScreenLayout.tsx

@@ -0,0 +1,77 @@
+import React, { useMemo } from 'react';
+import { View, Text, StyleSheet } from 'react-native';
+import type { TextStyle } from 'react-native';
+import { usePrimerTheme } from '../internal/theme';
+import type { PrimerTokens } from '../internal/theme';
+
+export interface PrimerStatusScreenLayoutProps {
+  icon: React.ReactNode;
+  title: string;
+  subtitle: string;
+  children?: React.ReactNode;
+}
+
+export function PrimerStatusScreenLayout({ icon, title, subtitle, children }: PrimerStatusScreenLayoutProps) {
+  const tokens = usePrimerTheme();
+  const styles = useMemo(() => createStyles(tokens), [tokens]);
+
+  return (
+    <View style={styles.container}>
+      <View style={styles.messageArea}>
+        {icon}
+        <View style={styles.textContent}>
+          <Text style={styles.title}>{title}</Text>
+          <Text style={styles.subtitle}>{subtitle}</Text>
+        </View>
+      </View>
+      {children != null && <View style={styles.childrenArea}>{children}</View>}
+    </View>
+  );
+}
+
+function createStyles(tokens: PrimerTokens) {
+  const { colors, spacing, typography } = tokens;
+
+  /* eslint-disable react-native/no-unused-styles */
+  return StyleSheet.create({
+    childrenArea: {
+      paddingHorizontal: spacing.large,
+      paddingTop: spacing.large,
+      width: '100%',
+    },
+    container: {
+      alignItems: 'center',
+      width: '100%',
+    },
+    messageArea: {
+      alignItems: 'center',
+      gap: spacing.small,
+      paddingHorizontal: spacing.xxxlarge,
+      paddingVertical: spacing.xlarge,
+    },
+    subtitle: {
+      color: colors.textSecondary,
+      fontFamily: typography.bodyMedium.fontFamily,
+      fontSize: typography.bodyMedium.fontSize,
+      fontWeight: typography.bodyMedium.fontWeight as TextStyle['fontWeight'],
+      letterSpacing: typography.bodyMedium.letterSpacing,
+      lineHeight: typography.bodyMedium.lineHeight,
+      textAlign: 'center',
+    },
+    textContent: {
+      alignItems: 'center',
+      gap: spacing.xsmall,
+      width: '100%',
+    },
+    title: {
+      color: colors.textPrimary,
+      fontFamily: typography.bodyLarge.fontFamily,
+      fontSize: typography.bodyLarge.fontSize,
+      fontWeight: typography.bodyLarge.fontWeight as TextStyle['fontWeight'],
+      letterSpacing: typography.bodyLarge.letterSpacing,
+      lineHeight: typography.bodyLarge.lineHeight,
+      textAlign: 'center',
+    },
+  });
+  /* eslint-enable react-native/no-unused-styles */
+}

package/src/Components/status/PrimerSuccessScreen.tsx

@@ -0,0 +1,39 @@
+import React, { useEffect } from 'react';
+import { Image, StyleSheet } from 'react-native';
+
+import { usePrimerLocalization } from '../internal/localization';
+import { STATUS_SCREEN_ICON_SIZE } from '../internal/screens/constants';
+import { PrimerStatusScreenLayout } from './PrimerStatusScreenLayout';
+
+const checkCircleIcon = require('../internal/screens/assets/check-circle-large.png');
+
+export interface PrimerSuccessScreenProps {
+  title?: string;
+  subtitle?: string;
+  icon?: React.ReactNode;
+  onDismiss?: () => void;
+  autoDismissMs?: number;
+}
+
+export function PrimerSuccessScreen({ title, subtitle, icon, onDismiss, autoDismissMs }: PrimerSuccessScreenProps) {
+  const { t } = usePrimerLocalization();
+
+  useEffect(() => {
+    if (!onDismiss || autoDismissMs == null) return;
+    const id = setTimeout(onDismiss, autoDismissMs);
+    return () => clearTimeout(id);
+  }, [onDismiss, autoDismissMs]);
+
+  const resolvedTitle = title ?? t('primer_checkout_success_title');
+  const resolvedSubtitle = subtitle ?? t('primer_checkout_success_subtitle');
+  const resolvedIcon = icon ?? <Image source={checkCircleIcon} style={styles.icon} />;
+
+  return <PrimerStatusScreenLayout icon={resolvedIcon} title={resolvedTitle} subtitle={resolvedSubtitle} />;
+}
+
+const styles = StyleSheet.create({
+  icon: {
+    height: STATUS_SCREEN_ICON_SIZE,
+    width: STATUS_SCREEN_ICON_SIZE,
+  },
+});

package/src/Components/status/index.ts

@@ -0,0 +1,8 @@
+export { PrimerStatusScreenLayout } from './PrimerStatusScreenLayout';
+export type { PrimerStatusScreenLayoutProps } from './PrimerStatusScreenLayout';
+export { PrimerLoadingScreen } from './PrimerLoadingScreen';
+export type { PrimerLoadingScreenProps } from './PrimerLoadingScreen';
+export { PrimerSuccessScreen } from './PrimerSuccessScreen';
+export type { PrimerSuccessScreenProps } from './PrimerSuccessScreen';
+export { PrimerErrorScreen } from './PrimerErrorScreen';
+export type { PrimerErrorScreenProps } from './PrimerErrorScreen';

package/src/Components/types/BillingAddressFormTypes.ts

@@ -0,0 +1,77 @@
+import type { StyleProp, ViewStyle } from 'react-native';
+import type { PrimerAddress } from '../../models/PrimerClientSession';
+import type { BillingAddressVisibility } from '../internal/billingAddressOptions';
+import type { CountryCode } from '../internal/countries';
+
+export type BillingAddressField =
+  | 'firstName'
+  | 'lastName'
+  | 'addressLine1'
+  | 'addressLine2'
+  | 'city'
+  | 'state'
+  | 'postalCode'
+  | 'countryCode';
+
+export type BillingAddressFormErrors = Partial<Record<BillingAddressField, string>>;
+
+export interface UsePrimerBillingAddressFormOptions {
+  /** Called when the billing-address validity changes. */
+  onValidationChange?: (isValid: boolean, errors: BillingAddressFormErrors) => void;
+}
+
+export interface UsePrimerBillingAddressFormReturn {
+  firstName: string;
+  lastName: string;
+  addressLine1: string;
+  addressLine2: string;
+  city: string;
+  state: string;
+  postalCode: string;
+  countryCode: string;
+
+  updateFirstName: (value: string) => void;
+  updateLastName: (value: string) => void;
+  updateAddressLine1: (value: string) => void;
+  updateAddressLine2: (value: string) => void;
+  updateCity: (value: string) => void;
+  updateState: (value: string) => void;
+  updatePostalCode: (value: string) => void;
+  /** Accepts only valid ISO 3166-1 alpha-2 codes from `COUNTRIES`. */
+  updateCountryCode: (value: CountryCode) => void;
+
+  /** Overall validity — all visible required fields are non-blank. */
+  isValid: boolean;
+  /** Per-field errors, surfaced only for touched + visible required fields. */
+  errors: BillingAddressFormErrors;
+  /** Marks a field as touched so its error can appear on blur. */
+  markFieldTouched: (field: BillingAddressField) => void;
+
+  /** Per-field visibility derived from the client session's `BILLING_ADDRESS` checkout module. */
+  visibleFields: BillingAddressVisibility;
+  /** Whether any billing field is visible. False ⇒ host should hide the entire billing block. */
+  sectionVisible: boolean;
+
+  /** Flush any pending debounced `setBillingAddress` call to the native manager. */
+  flush: () => Promise<void>;
+
+  /** Snapshot of the current fields as a `PrimerAddress`. */
+  getAddress: () => PrimerAddress;
+
+  /** Clear all fields and reset local state. */
+  reset: () => void;
+}
+
+/** Merchant-facing props for the composed `<PrimerBillingAddressForm />` component. */
+export interface PrimerBillingAddressFormProps {
+  /**
+   * The billing-address state returned by `usePrimerBillingAddressForm()`. Hoisted so the host screen
+   * can share it with a Pay button rendered outside the form and coordinate submission with
+   * other forms (e.g. the card form).
+   */
+  billingForm: UsePrimerBillingAddressFormReturn;
+  /** Optional outer container style. */
+  style?: StyleProp<ViewStyle>;
+  /** Test ID root for the form. Nested elements derive suffixed IDs. */
+  testID?: string;
+}

package/src/Components/types/CardFormTypes.ts

@@ -0,0 +1,83 @@
+import type { PrimerBinData } from '../../models/PrimerBinData';
+import type { PrimerInputElementType } from '../../models/PrimerInputElementType';
+import type { CardNetworkDescriptor } from '../internal/cardNetwork';
+
+export type CardFormField = 'cardNumber' | 'expiryDate' | 'cvv' | 'cardholderName';
+
+export type CardFormErrors = Partial<Record<CardFormField, string>>;
+
+export interface UseCardFormOptions {
+  /** Called when validation state changes */
+  onValidationChange?: (isValid: boolean, errors: CardFormErrors) => void;
+  /** Called when card metadata changes (e.g., network detection) */
+  onMetadataChange?: (metadata: any) => void;
+  /** Called when BIN data changes */
+  onBinDataChange?: (binData: PrimerBinData) => void;
+}
+
+export interface UsePrimerCardFormReturn {
+  /** Formatted card number (with spaces). */
+  cardNumber: string;
+  /** Formatted expiry as MM/YY. */
+  expiryDate: string;
+  cvv: string;
+  cardholderName: string;
+
+  /** Auto-formats with spaces. */
+  updateCardNumber: (value: string) => void;
+  /** Auto-formats as MM/YY. */
+  updateExpiryDate: (value: string) => void;
+  updateCVV: (value: string) => void;
+  updateCardholderName: (value: string) => void;
+
+  /** Overall form validity as reported by the native SDK. */
+  isValid: boolean;
+  /**
+   * Per-field errors, surfaced under the rules: visible after a field has been focused
+   * and then blurred; hidden again when the user re-focuses the field; visible for all
+   * fields once `submit()` has been attempted (until `reset()`).
+   */
+  errors: CardFormErrors;
+  /** Mark a field focused. Re-focusing a previously-blurred field clears its error until next blur. */
+  markFieldFocused: (field: CardFormField) => void;
+  /** Mark a field blurred. The field's error becomes visible (unless re-focused). */
+  markFieldBlurred: (field: CardFormField) => void;
+  /** Force every field's errors to render. `submit()` calls this automatically; expose for custom submit buttons. */
+  markSubmitAttempted: () => void;
+
+  /** Trigger tokenization. No-op if invalid or already submitting; always flips submitAttempted. */
+  submit: () => Promise<void>;
+  isSubmitting: boolean;
+  /** True after the first `submit()` / `markSubmitAttempted()` call, until `reset()`. */
+  submitAttempted: boolean;
+
+  /** Fields the active client session requires. */
+  requiredFields: PrimerInputElementType[];
+
+  /** BIN / card network data from the native SDK. */
+  binData: PrimerBinData | null;
+
+  /**
+   * Traits for the detected network (PAN lengths, gap pattern, CVV length/label).
+   * Falls back to default traits when the network is unknown or BIN hasn't resolved yet.
+   */
+  descriptor: CardNetworkDescriptor;
+
+  /**
+   * Max length for the card-number TextInput (digits + gaps) derived from the
+   * current network. Use this for `maxLength` on custom card-number inputs so
+   * users can't type past the longest valid formatted PAN for their card.
+   */
+  cardNumberMaxLength: number;
+
+  /**
+   * Whether the cardholder-name field should be rendered. Driven by the
+   * `CARD_INFORMATION` checkout module (`options.cardHolderName`). Defaults to
+   * `true` when no module is present or the flag is unset; `false` only when
+   * the merchant explicitly disables the field.
+   */
+  isCardholderNameVisible: boolean;
+
+  /** Clear all fields and reset local state. */
+  reset: () => void;
+}

package/src/Components/types/CardInputTypes.ts

@@ -0,0 +1,90 @@
+import type { ReactNode } from 'react';
+import type { KeyboardTypeOptions, StyleProp, TextInputProps, TextStyle, ViewStyle } from 'react-native';
+
+export interface PrimerTextInputTheme {
+  primaryColor?: string;
+  textColor?: string;
+  labelColor?: string;
+  placeholderColor?: string;
+  backgroundColor?: string;
+  disabledBackgroundColor?: string;
+  borderColor?: string;
+  disabledBorderColor?: string;
+  /** Border color used when the input has an error. Falls back to the semantic `colors.borderError` token. */
+  errorColor?: string;
+  /** Color for the helper/error text below the input. Falls back to the semantic `colors.textNegative` token. */
+  errorTextColor?: string;
+  borderWidth?: number;
+  focusedBorderWidth?: number;
+  borderRadius?: number;
+  fontSize?: number;
+  labelFontSize?: number;
+  fontFamily?: string;
+  fieldHeight?: number;
+}
+
+export type CardInputTheme = PrimerTextInputTheme;
+
+export interface PrimerTextInputProps {
+  value: string;
+  onChangeText: (text: string) => void;
+  onBlur?: () => void;
+  onFocus?: () => void;
+  editable?: boolean;
+  keyboardType?: KeyboardTypeOptions;
+  maxLength?: number;
+  secureTextEntry?: boolean;
+  autoComplete?: TextInputProps['autoComplete'];
+  autoCapitalize?: TextInputProps['autoCapitalize'];
+  label?: string;
+  showLabel?: boolean;
+  placeholder?: string;
+  /**
+   * Error message shown below the input. When present, the input border adopts the error color
+   * (even over the focused state) and the accessibility tree marks the field invalid. Pass `undefined`
+   * to clear the error state.
+   */
+  error?: string;
+  trailingContent?: ReactNode;
+  onSelectionChange?: TextInputProps['onSelectionChange'];
+  selectionColor?: string;
+  returnKeyType?: TextInputProps['returnKeyType'];
+  onSubmitEditing?: TextInputProps['onSubmitEditing'];
+  theme?: PrimerTextInputTheme;
+  style?: StyleProp<ViewStyle>;
+  inputStyle?: StyleProp<TextStyle>;
+  labelStyle?: StyleProp<TextStyle>;
+  /** Style override for the error helper text below the input. */
+  errorStyle?: StyleProp<TextStyle>;
+  /** Accessibility label for the underlying TextInput; falls back to `label` when omitted. */
+  accessibilityLabel?: string;
+  testID?: string;
+}
+
+export interface PrimerTextInputRef {
+  setCaret: (start: number, end?: number) => void;
+  focus: () => void;
+  blur: () => void;
+}
+
+export interface PrimerCardInputProps {
+  theme?: PrimerTextInputTheme;
+  editable?: boolean;
+  label?: string;
+  showLabel?: boolean;
+  placeholder?: string;
+  returnKeyType?: TextInputProps['returnKeyType'];
+  onSubmitEditing?: TextInputProps['onSubmitEditing'];
+  style?: StyleProp<ViewStyle>;
+  inputStyle?: StyleProp<TextStyle>;
+  labelStyle?: StyleProp<TextStyle>;
+  testID?: string;
+}
+
+export type PrimerCardNumberInputProps = PrimerCardInputProps;
+
+export type PrimerExpiryDateInputProps = PrimerCardInputProps;
+
+export type PrimerCVVInputProps = PrimerCardInputProps;
+
+export type PrimerCardholderNameInputProps = PrimerCardInputProps;

package/src/Components/types/CardNetworkSelection.ts

@@ -0,0 +1,64 @@
+/**
+ * Public types for co-badged card-network selection in Checkout Components.
+ *
+ * The data shapes here are surfaced through the `usePrimerCardNetworkSelection()` hook
+ * and consumed by both the drop-in `<PrimerCardNetworkSelector />` and merchant-built
+ * custom UIs (headless integration). All fields are `readonly`; mutations happen
+ * exclusively via `selectNetwork(identifier)` on the hook return value.
+ *
+ * Data sources (under the hood — not part of the public contract):
+ *   - Available networks + currently-selected network come from the existing
+ *     BinData event flow (`binData.alternatives` + `binData.preferred`).
+ *   - `selectNetwork()` records the pick provider-side; it rides every raw-data
+ *     payload as `cardNetwork` and reaches tokenization as `preferredNetwork`.
+ */
+
+import type { CardNetworkId } from '../internal/cardNetwork';
+
+/** A card network surfaced to merchants. Identifier vocabulary follows {@link CardNetworkId}. */
+export interface CardNetworkDetails {
+  /** Stable, uppercase identifier (e.g. "VISA", "CARTES_BANCAIRES"). */
+  readonly identifier: CardNetworkId;
+  /** Human-readable name (e.g. "Visa", "Cartes Bancaires"). */
+  readonly displayName: string;
+  /** Local file URI for the network's logo asset, or null if no asset is available. */
+  readonly logoUri: string | null;
+  /** True when the merchant accepts this network for the current session. */
+  readonly allowed: boolean;
+  /** True unless the network is auto-routed (e.g. EFTPOS). */
+  readonly allowsUserSelection: boolean;
+}
+
+/** Return value of `usePrimerCardNetworkSelection()`. */
+export interface UsePrimerCardNetworkSelectionReturn {
+  /** Networks detected for the current PAN that the merchant accepts. */
+  readonly availableNetworks: ReadonlyArray<CardNetworkDetails>;
+  /**
+   * The shopper's explicit pick. `null` until the shopper taps a network in the popover.
+   * Source of truth for the backend / tokenization payload — `null` means "no shopper
+   * preference yet, the SDK should route on the BIN's default rail".
+   */
+  readonly selectedNetwork: CardNetworkDetails | null;
+  /** Identifier form of {@link selectedNetwork}. `null` until the shopper picks. */
+  readonly selectedIdentifier: CardNetworkId | null;
+  /**
+   * What the UI should currently render as the active network. Falls back to
+   * `availableNetworks[0]` (the SDK's BIN-derived default) when the shopper hasn't
+   * picked yet, so the input adornment is never blank on a co-badged card.
+   * Becomes the shopper's pick after they tap a network.
+   */
+  readonly displayedNetwork: CardNetworkDetails | null;
+  /** Identifier form of {@link displayedNetwork}. */
+  readonly displayedIdentifier: CardNetworkId | null;
+  /** True when 2+ allowed networks are detected AND all permit user selection. */
+  readonly isSelectorVisible: boolean;
+  /** True when 2+ allowed networks are detected AND at least one is non-selectable (e.g. EFTPOS). */
+  readonly isDualBadge: boolean;
+  /**
+   * Set the shopper's preferred card network on the active card form.
+   * Resolves once the pick has been applied to the card's raw data.
+   * Rejects (`NO_ACTIVE_CARD_FORM`) when the form has been torn down, or if
+   * re-sending the raw data to the native SDK fails.
+   */
+  selectNetwork(identifier: CardNetworkId): Promise<void>;
+}

package/src/Components/types/PaymentMethodTypes.ts

@@ -0,0 +1,51 @@
+import type {
+  IPrimerAsset,
+  PrimerPaymentMethodAsset,
+  PrimerPaymentMethodNativeView,
+} from '../../models/PrimerPaymentMethodResource';
+import type {
+  IPrimerHeadlessUniversalCheckoutPaymentMethod,
+  PrimerPaymentMethodManagerCategoryName,
+  PrimerSessionIntentName,
+} from '../../models/PrimerHeadlessUniversalCheckoutPaymentMethod';
+
+// Mirrors the Android SDK's `Surcharge` sealed interface.
+// - `flat`: single amount on non-card methods (PAYPAL, APPLE_PAY, …)
+// - `perNetwork`: PAYMENT_CARD surcharge keyed by card network (VISA, MASTERCARD, …)
+export type PaymentMethodSurcharge =
+  | { kind: 'flat'; amount: number }
+  | { kind: 'perNetwork'; amounts: Record<string, number> };
+
+export interface PaymentMethodItem {
+  type: string;
+  name: string;
+  // Theme-aware URL picked for the current color scheme (colored → dark/light).
+  // For all variants, read `resource.paymentMethodLogo` (see `IPrimerAsset`).
+  logo?: string;
+  backgroundColor?: string;
+  nativeViewName?: string;
+  categories: PrimerPaymentMethodManagerCategoryName[];
+  intents: PrimerSessionIntentName[];
+  surcharge?: PaymentMethodSurcharge;
+  resource?: PrimerPaymentMethodAsset | PrimerPaymentMethodNativeView;
+  paymentMethod: IPrimerHeadlessUniversalCheckoutPaymentMethod;
+}
+
+// Re-exported so `IPrimerAsset` is reachable for consumers that want all logo variants.
+export type { IPrimerAsset };
+
+export interface UsePrimerPaymentMethodsOptions {
+  include?: string[];
+  exclude?: string[];
+  onLoad?: (methods: PaymentMethodItem[]) => void;
+}
+
+export interface UsePrimerPaymentMethodsReturn {
+  paymentMethods: PaymentMethodItem[];
+  isLoading: boolean;
+  error: Error | null;
+  resourcesError: Error | null;
+  selectedMethod: PaymentMethodItem | null;
+  selectMethod: (method: PaymentMethodItem | null) => void;
+  clearSelection: () => void;
+}