@whop/elements-react-native 0.1.0

package/src/core/payments/plan.ts

@@ -0,0 +1,198 @@
+// ported verbatim from frontend/apps/web/src/elements/payments/lib/plan.ts — keep in sync when the web element changes
+
+import type { PaymentMethodConfigurationShape, PlanResource } from '../../api/types';
+import type { WhopClient } from '../../api/client';
+
+import { currencyMinorDigits } from './currency';
+import { ChargeConfigError, apiErrorMessage } from './errors';
+
+/** The widened props bag both runtimes hand to the charge resolution — the controller seed's
+ *  `ctx.props` and the host sources' live props view are each one branch of the plan-vs-inline
+ *  union, so every key is optional here and `chargeInputOf` decides which branch is in force. */
+export interface ChargeProps {
+  accountId?: string;
+  plan?: string;
+  currency?: string;
+  amount?: number;
+  setupFutureUsage?: 'off_session' | 'on_session';
+  paymentMethodConfiguration?: PaymentMethodConfigurationShape;
+}
+
+/** `config = resolve(plan)`: the ONE normalized charge config every downstream path consumes —
+ *  the inline props ARE the degenerate case (`plan` undefined, fields verbatim), and a plan is
+ *  a preset that resolves to this same shape. */
+export interface ResolvedCharge {
+  configured: true;
+  plan: string | undefined;
+  currency: string;
+  amount: number;
+  setupFutureUsage: 'off_session' | 'on_session' | undefined;
+  paymentMethodConfiguration: PaymentMethodConfigurationShape | undefined;
+}
+
+/** The optionless statics-rail boot (`WhopElements.payments.handleNextAction` — the namespace
+ *  handle mounts with an EMPTY options bag): no charge input exists and none is needed, the
+ *  static flow never collects. Collection-face projections refuse on it, loudly. */
+export interface UnconfiguredCharge {
+  configured: false;
+  plan: undefined;
+  currency: undefined;
+  amount: undefined;
+  setupFutureUsage: undefined;
+  paymentMethodConfiguration: undefined;
+}
+
+export type ChargeState = ResolvedCharge | UnconfiguredCharge;
+
+export const UNCONFIGURED_CHARGE: UnconfiguredCharge = Object.freeze({
+  configured: false,
+  plan: undefined,
+  currency: undefined,
+  amount: undefined,
+  setupFutureUsage: undefined,
+  paymentMethodConfiguration: undefined,
+});
+
+/** ZERO charge inputs mounted — the only shape that resolves to UNCONFIGURED_CHARGE; any
+ *  PARTIAL config still throws the loud ChargeConfigError (a half-config is a consumer bug). */
+export function chargeless(props: ChargeProps): boolean {
+  return (
+    props.accountId === undefined &&
+    props.plan === undefined &&
+    props.currency === undefined &&
+    props.amount === undefined &&
+    props.paymentMethodConfiguration === undefined
+  );
+}
+
+interface ChargeInput {
+  accountId: string | undefined;
+  plan: string | undefined;
+  currency: string | undefined;
+  amount: number | undefined;
+  setupFutureUsage: 'off_session' | 'on_session' | undefined;
+  paymentMethodConfiguration: PaymentMethodConfigurationShape | undefined;
+}
+
+/** The plan-XOR-inline gate: `plan` alongside any inline charge key is a conflict, and neither
+ *  is a missing config — both refuse LOUDLY with a coded `ChargeConfigError`. */
+export function chargeInputOf(props: ChargeProps): ChargeInput {
+  const input: ChargeInput = {
+    accountId: props.accountId,
+    plan: props.plan,
+    currency: props.currency,
+    amount: props.amount,
+    setupFutureUsage: props.setupFutureUsage,
+    paymentMethodConfiguration: props.paymentMethodConfiguration,
+  };
+  if (input.plan !== undefined) {
+    const inlineKeys = (['currency', 'amount', 'paymentMethodConfiguration'] as const).filter(
+      (key) => input[key] !== undefined,
+    );
+    if (inlineKeys.length > 0) {
+      throw new ChargeConfigError(
+        'PLAN_INLINE_CONFLICT',
+        `Pass a plan OR an inline charge config, never both — ${inlineKeys.join(', ')} conflict with plan ${input.plan}. The plan resolves to the same shape client-side.`,
+      );
+    }
+    return input;
+  }
+  if (input.currency === undefined || input.amount === undefined) {
+    throw new ChargeConfigError(
+      'CHARGE_CONFIG_MISSING',
+      'Pass a plan id, or an inline charge config with both currency and amount — neither is mounted.',
+    );
+  }
+  return input;
+}
+
+export function inlineCharge(input: ChargeInput): ResolvedCharge {
+  return {
+    configured: true,
+    plan: undefined,
+    currency: (input.currency ?? '').toLowerCase(),
+    amount: input.amount ?? 0,
+    setupFutureUsage: input.setupFutureUsage,
+    paymentMethodConfiguration: input.paymentMethodConfiguration,
+  };
+}
+
+/** The slice of the SDK's own plan the charge resolution reads — the schema is the author,
+ *  nothing hand-typed to drift. `effective_payment_method_configuration` is the GOVERNING
+ *  configuration resolved server-side through every layer; `null` means platform defaults, and
+ *  there is no fallback to the plan's own editable override — the backend publishing the field
+ *  deploys BENEATH this code by PR stacking. */
+export type RetrievedPlan = Pick<
+  PlanResource,
+  'id' | 'currency' | 'initial_price' | 'plan_type' | 'account' | 'effective_payment_method_configuration'
+>;
+
+/**
+ * Normalize a retrieved plan into the inline shape. The plan's `account_id` must MATCH the
+ * mounted `accountId` — the handle's account stays the mount key, and a foreign plan is a coded
+ * refusal, never a silent re-key. A renewing plan attests `off_session` save-consent unless the
+ * consumer set the attestation explicitly (the charge vaults the method for renewals).
+ */
+export function chargeFromPlan(resource: RetrievedPlan, input: ChargeInput): ResolvedCharge {
+  const planId = resource.id ?? input.plan;
+  const planAccount = resource.account?.id;
+  if (!planAccount || planAccount !== input.accountId) {
+    throw new ChargeConfigError(
+      'PLAN_ACCOUNT_MISMATCH',
+      `Plan ${planId} belongs to ${planAccount ?? 'no account'}, not the mounted accountId ${input.accountId} — mount the element on the plan's own account.`,
+    );
+  }
+  const currency = resource.currency?.toLowerCase();
+  const initialPrice = resource.initial_price;
+  if (!currency || typeof initialPrice !== 'number' || !Number.isFinite(initialPrice)) {
+    throw new ChargeConfigError(
+      'PLAN_RESOLUTION_FAILED',
+      `Plan ${planId} resolved without a currency and initial price.`,
+    );
+  }
+  return {
+    configured: true,
+    plan: planId,
+    currency,
+    // Truncate, never round — the backend's Utils.amount_in_cents is (amount.to_d * factor).to_i;
+    // toFixed(4) re-quantizes the float product to the exact decimal before the truncate.
+    amount: Math.trunc(Number((initialPrice * 10 ** currencyMinorDigits(currency)).toFixed(4))),
+    setupFutureUsage: input.setupFutureUsage ?? (resource.plan_type === 'renewal' ? 'off_session' : undefined),
+    // The GOVERNING configuration, resolved server-side — the same read a session mount gets
+    // from its own payment_method_configuration. A null answer is trusted as platform defaults;
+    // the elements NEVER re-derive a configuration layer client-side. Sliced to exactly the
+    // three known keys.
+    paymentMethodConfiguration: slicedConfiguration(resource.effective_payment_method_configuration),
+  };
+}
+
+function slicedConfiguration(
+  configuration: PaymentMethodConfigurationShape | null | undefined,
+): PaymentMethodConfigurationShape | undefined {
+  if (!configuration) return undefined;
+  return {
+    enabled: configuration.enabled,
+    disabled: configuration.disabled,
+    include_platform_defaults: configuration.include_platform_defaults,
+  };
+}
+
+/** The one charge resolution. Inline props resolve with no network; a plan costs one GET. */
+export async function resolveCharge(client: WhopClient, props: ChargeProps): Promise<ChargeState> {
+  // The statics rail's lazy open-handle boots with an EMPTY options bag and DOES run the
+  // h.sync charge gate — a chargeless boot resolves the unconfigured sentinel there exactly
+  // like the controller seed does. Partial config still throws.
+  if (chargeless(props)) return UNCONFIGURED_CHARGE;
+  const input = chargeInputOf(props);
+  if (input.plan === undefined) return inlineCharge(input);
+  let plan: PlanResource;
+  try {
+    plan = await client.plans.retrieve(input.plan);
+  } catch (err) {
+    throw new ChargeConfigError(
+      'PLAN_RESOLUTION_FAILED',
+      apiErrorMessage(err, `plan ${input.plan} could not be resolved`),
+    );
+  }
+  return chargeFromPlan(plan, input);
+}

package/src/core/payments/refusals.ts

@@ -0,0 +1,24 @@
+/**
+ * Refusals that exist only on React Native, kept out of the ported `errors.ts` so that file stays a
+ * clean mirror of the web element's.
+ *
+ * Every one is coded, so a caller switches on `code` and never string-matches a message.
+ */
+export type PaymentsRefusalCode =
+	| 'CONFIRMATION_IN_FLIGHT'
+	| 'NEXT_ACTION_IN_FLIGHT'
+	| 'NEXT_ACTION_PRESENTATION_FAILED'
+	| 'CHARGE_CONFIG_MISSING'
+	| 'NO_COLLECTION_SURFACE'
+	| 'NATIVE_MODULE_MISSING'
+	| 'WALLET_UNAVAILABLE';
+
+export class PaymentsRefusalError extends Error {
+	readonly code: PaymentsRefusalCode;
+
+	constructor(code: PaymentsRefusalCode, message: string) {
+		super(`[${code}] ${message}`);
+		this.code = code;
+		this.name = 'PaymentsRefusalError';
+	}
+}

package/src/core/payments/secure-fields.ts

@@ -0,0 +1,85 @@
+// ported verbatim from frontend/apps/web/src/elements/payments/lib/secure-fields.ts — keep in sync when the web element changes
+
+/**
+ * The secure declared-field rail (payment-api.md §4): a matrix field marked `secure: true`
+ * renders as a Basis Theory hosted text element wearing the suite's input chrome, so the raw
+ * value NEVER exists in our JavaScript — at collect time the selected method's element
+ * INSTANCES are tokenized into ONE Basis Theory token intent, keyed by field name
+ * (`{ type: 'token', data: { bank_account: <element> } }`; BT interpolates each element's value
+ * server-side, producing exactly the legacy checkout's additional-data shape, so the
+ * checkout.com mandate interpolation `$.data.<name>` consumes it unchanged), and the category
+ * payload carries `{ token }`. The create rides the web-elements SDK's element path under the
+ * method's config-block publishable key (`tokenizer` + `public_key`, the card block's source).
+ * Intents expire on BT's default clock (24h) — the confirm consumes one long before that.
+ */
+import type { BasisTheoryElements } from './bt';
+
+import { SecureFieldError } from './errors';
+
+/** A hosted text element instance. Opaque by construction — it carries an id and a formatter, never
+ *  the value the buyer typed. */
+type ITextElement = unknown;
+
+const BT_TOKEN_INTENTS_URL = 'https://api.basistheory.com/token-intents';
+
+/** Applied by BT inside the hosted element at tokenization (String.replace semantics):
+ *  whitespace stripped — buyers type the spaced IBAN print format, the electronic format rides. */
+export const secureValueTransform = /\s+/g;
+
+// BT runs the validation regex against the value AS TYPED, while `transform` applies only at
+// tokenization (developers.basistheory.com/docs/sdks/web/web-elements/components). The matrix
+// publishes both truths ready to use: `input_formats` (what a buyer may type — whitespace
+// tolerant, authored star-height 1 because BT's frame rejects nested quantifiers as unsafe)
+// and `formats` (the stored electronic value, the fallback where no typing tolerance is
+// declared). Patterns ride verbatim — the backend is the only author.
+export function secureFieldValidation(field: {
+  formats?: Record<string, string> | null;
+  input_formats?: Record<string, string> | null;
+}): RegExp | undefined {
+  const typed = Object.values(field.input_formats ?? {});
+  const patterns = typed.length > 0 ? typed : Object.values(field.formats ?? {});
+  if (patterns.length === 0) return undefined;
+  try {
+    return new RegExp(patterns.map((pattern) => `(?:${pattern})`).join('|'));
+  } catch {
+    return undefined;
+  }
+}
+
+/** Raw-data token intents ride BT's REST surface with the publishable key — the wallet sheets'
+ *  leg alone (Google's tokenizationData.token is a raw string, no hosted element exists to
+ *  reference). */
+export async function createRawTokenIntent(publicKey: string, data: unknown): Promise<string> {
+  const response = await fetch(BT_TOKEN_INTENTS_URL, {
+    method: 'POST',
+    headers: { 'BT-API-KEY': publicKey, 'Content-Type': 'application/json' },
+    body: JSON.stringify({ type: 'token', data }),
+  });
+  if (!response.ok) throw new Error(`token intent creation failed (${response.status})`);
+  const intent = (await response.json().catch(() => null)) as { id?: string } | null;
+  if (!intent?.id) throw new Error('token intent creation returned no id');
+  return intent.id;
+}
+
+export async function tokenizeSecureFields(
+  bt: BasisTheoryElements | undefined,
+  elements: Record<string, ITextElement>,
+  /** The method's OWN config-block key. Passed per call because Basis Theory's client is a
+   *  module-level singleton — the first key constructed wins for the whole process. */
+  apiKey: string,
+): Promise<string> {
+  if (!bt) {
+    throw new SecureFieldError(
+      'SECURE_FIELD_TOKENIZER_UNAVAILABLE',
+      'This method declares a secure field but its tokenizer is not available',
+    );
+  }
+  try {
+    const intent = await bt.tokenIntents.create({ type: 'token', data: elements as never }, { apiKey });
+    if (!intent?.id) throw new Error('token intent creation returned no id');
+    return intent.id;
+  } catch (err) {
+    const detail = err instanceof Error && err.message ? `: ${err.message}` : '';
+    throw new SecureFieldError('SECURE_FIELD_TOKENIZE_FAILED', `Secure field tokenization failed${detail}`);
+  }
+}

package/src/core/payments/tax-id-catalog.ts

@@ -0,0 +1,320 @@
+// ported verbatim from frontend/apps/web/src/elements/payments/lib/tax-id-catalog.ts — keep in sync when the web element changes
+
+import { useMemo } from 'react';
+
+import { useT } from '../../i18n';
+
+/**
+ * The registration types the API accepts for `tax_id.type`. The backend owns the set
+ * (`TaxIdentifier::TAX_ID_TYPES`); this package has no generated enum to derive it from, so the
+ * catalog below IS the set. `useTaxIdTypeLabels` keeps the half of the exhaustiveness gate that
+ * still applies: a catalog row with no label refuses to compile.
+ */
+export type TaxIdType = keyof typeof TAX_ID_TYPE_META;
+
+interface TaxIdTypeMeta {
+  /** The ISO 3166-1 alpha-2 region the registration belongs to — `EU` for the union-wide
+   *  registrations, `XI` for Northern Ireland's post-Brexit VAT scheme. */
+  region: string;
+  /** A format specimen for the value input's placeholder — a shape, never prose, so it is not
+   *  translated. Sourced from the dashboard's tax-settings country map (the legacy per-type
+   *  metadata) where a row exists; `pl_nip` and `xi_vat` follow the same published formats. */
+  placeholder: string;
+}
+
+/** Display metadata per wire type. */
+export const TAX_ID_TYPE_META = {
+  ad_nrt: { region: 'AD', placeholder: 'A-123456-B' },
+  ae_trn: { region: 'AE', placeholder: '123456789012345' },
+  al_tin: { region: 'AL', placeholder: 'J12345678N' },
+  am_tin: { region: 'AM', placeholder: '12345678' },
+  ao_tin: { region: 'AO', placeholder: '1234567890' },
+  ar_cuit: { region: 'AR', placeholder: '20-12345678-9' },
+  au_abn: { region: 'AU', placeholder: '12345678901' },
+  au_arn: { region: 'AU', placeholder: '12345678901' },
+  aw_tin: { region: 'AW', placeholder: '1234567' },
+  az_tin: { region: 'AZ', placeholder: '1234567890' },
+  ba_tin: { region: 'BA', placeholder: '1234567890123' },
+  bb_tin: { region: 'BB', placeholder: '1234567890' },
+  bd_bin: { region: 'BD', placeholder: '123456789' },
+  bf_ifu: { region: 'BF', placeholder: '12345678901234' },
+  bg_uic: { region: 'BG', placeholder: '123456789' },
+  bh_vat: { region: 'BH', placeholder: '123456789012345' },
+  bj_ifu: { region: 'BJ', placeholder: '1234567890123' },
+  bo_tin: { region: 'BO', placeholder: '1234567' },
+  br_cnpj: { region: 'BR', placeholder: '12.345.678/0001-00' },
+  br_cpf: { region: 'BR', placeholder: '123.456.789-00' },
+  bs_tin: { region: 'BS', placeholder: '123456789' },
+  by_tin: { region: 'BY', placeholder: '123456789' },
+  ca_bn: { region: 'CA', placeholder: '123456789' },
+  ca_gst_hst: { region: 'CA', placeholder: '123456789RT0001' },
+  ca_pst_bc: { region: 'CA', placeholder: 'PST-1234-5678' },
+  ca_pst_mb: { region: 'CA', placeholder: '123456-7' },
+  ca_pst_sk: { region: 'CA', placeholder: '1234567' },
+  ca_qst: { region: 'CA', placeholder: '1234567890TQ1234' },
+  cd_nif: { region: 'CD', placeholder: 'A1234567B' },
+  ch_uid: { region: 'CH', placeholder: 'CHE-123.456.789' },
+  ch_vat: { region: 'CH', placeholder: 'CHE-123.456.789 MWST' },
+  cl_tin: { region: 'CL', placeholder: '12.345.678-9' },
+  cm_niu: { region: 'CM', placeholder: 'M012345678901A' },
+  cn_tin: { region: 'CN', placeholder: '123456789012345678' },
+  co_nit: { region: 'CO', placeholder: '123.456.789-0' },
+  cr_tin: { region: 'CR', placeholder: '1-234-567890' },
+  cv_nif: { region: 'CV', placeholder: '123456789' },
+  de_stn: { region: 'DE', placeholder: '12/345/67890' },
+  do_rcn: { region: 'DO', placeholder: '123-4567890-1' },
+  ec_ruc: { region: 'EC', placeholder: '1234567890001' },
+  eg_tin: { region: 'EG', placeholder: '123456789' },
+  es_cif: { region: 'ES', placeholder: 'A12345678' },
+  et_tin: { region: 'ET', placeholder: '1234567890' },
+  eu_oss_vat: { region: 'EU', placeholder: 'FR12345678901' },
+  eu_vat: { region: 'EU', placeholder: 'DE123456789' },
+  gb_vat: { region: 'GB', placeholder: 'GB123456789' },
+  ge_vat: { region: 'GE', placeholder: '123456789' },
+  gh_tin: { region: 'GH', placeholder: 'C0001234567' },
+  gn_nif: { region: 'GN', placeholder: '123456789' },
+  hk_br: { region: 'HK', placeholder: '12345678' },
+  hr_oib: { region: 'HR', placeholder: '12345678901' },
+  hu_tin: { region: 'HU', placeholder: '12345678' },
+  id_npwp: { region: 'ID', placeholder: '12.345.678.9-012.345' },
+  il_vat: { region: 'IL', placeholder: '123456789' },
+  in_gst: { region: 'IN', placeholder: '22AAAAA0000A1Z5' },
+  is_vat: { region: 'IS', placeholder: '123456' },
+  jp_cn: { region: 'JP', placeholder: '1234-56-7890' },
+  jp_rn: { region: 'JP', placeholder: '12345' },
+  jp_trn: { region: 'JP', placeholder: 'T1234567890123' },
+  ke_pin: { region: 'KE', placeholder: 'P000123456A' },
+  kg_tin: { region: 'KG', placeholder: '12345678' },
+  kh_tin: { region: 'KH', placeholder: 'K001-234567890' },
+  kr_brn: { region: 'KR', placeholder: '123-45-67890' },
+  kz_bin: { region: 'KZ', placeholder: '123456789012' },
+  la_tin: { region: 'LA', placeholder: '1234567890' },
+  li_uid: { region: 'LI', placeholder: 'CHE-123.456.789' },
+  li_vat: { region: 'LI', placeholder: '12345' },
+  ma_vat: { region: 'MA', placeholder: '12345678' },
+  md_vat: { region: 'MD', placeholder: '1234567' },
+  me_pib: { region: 'ME', placeholder: '12345678' },
+  mk_vat: { region: 'MK', placeholder: 'MK1234567890123' },
+  mr_nif: { region: 'MR', placeholder: '12345678' },
+  mx_rfc: { region: 'MX', placeholder: 'XAXX010101000' },
+  my_frp: { region: 'MY', placeholder: '12345678' },
+  my_itn: { region: 'MY', placeholder: 'C1234567890' },
+  my_sst: { region: 'MY', placeholder: 'A12-3456-78901234' },
+  ng_tin: { region: 'NG', placeholder: '12345678-0001' },
+  no_vat: { region: 'NO', placeholder: '123456789MVA' },
+  no_voec: { region: 'NO', placeholder: '1234567' },
+  np_pan: { region: 'NP', placeholder: '123456789' },
+  nz_gst: { region: 'NZ', placeholder: '123456789' },
+  om_vat: { region: 'OM', placeholder: 'OM1234567890' },
+  pe_ruc: { region: 'PE', placeholder: '12345678901' },
+  ph_tin: { region: 'PH', placeholder: '123-456-789-000' },
+  pl_nip: { region: 'PL', placeholder: '1234567890' },
+  ro_tin: { region: 'RO', placeholder: '1234567890' },
+  rs_pib: { region: 'RS', placeholder: '123456789' },
+  ru_inn: { region: 'RU', placeholder: '1234567890' },
+  ru_kpp: { region: 'RU', placeholder: '123456789' },
+  sa_vat: { region: 'SA', placeholder: '123456789012345' },
+  sg_gst: { region: 'SG', placeholder: 'M12345678X' },
+  sg_uen: { region: 'SG', placeholder: '123456789A' },
+  si_tin: { region: 'SI', placeholder: '12345678' },
+  sn_ninea: { region: 'SN', placeholder: '12345678901' },
+  sr_fin: { region: 'SR', placeholder: '12345678' },
+  sv_nit: { region: 'SV', placeholder: '0614-123456-123-4' },
+  th_vat: { region: 'TH', placeholder: '1234567890123' },
+  tj_tin: { region: 'TJ', placeholder: '123456789' },
+  tr_tin: { region: 'TR', placeholder: '1234567890' },
+  tw_vat: { region: 'TW', placeholder: '12345678' },
+  tz_vat: { region: 'TZ', placeholder: '12-345-6789' },
+  ua_vat: { region: 'UA', placeholder: '1234567890' },
+  ug_tin: { region: 'UG', placeholder: '1234567890' },
+  us_ein: { region: 'US', placeholder: '12-3456789' },
+  uy_ruc: { region: 'UY', placeholder: '123456789012' },
+  uz_tin: { region: 'UZ', placeholder: '123456789' },
+  uz_vat: { region: 'UZ', placeholder: '123456789012' },
+  ve_rif: { region: 'VE', placeholder: 'J-12345678-9' },
+  vn_tin: { region: 'VN', placeholder: '1234567890' },
+  xi_vat: { region: 'XI', placeholder: 'XI123456789' },
+  za_vat: { region: 'ZA', placeholder: '4123456789' },
+  zm_tin: { region: 'ZM', placeholder: '1234567890' },
+  zw_tin: { region: 'ZW', placeholder: '1234567890' },
+} satisfies Record<string, TaxIdTypeMeta>;
+
+export const TAX_ID_TYPES = Object.keys(TAX_ID_TYPE_META) as readonly TaxIdType[];
+
+export function isTaxIdType(value: string): value is TaxIdType {
+  return Object.prototype.hasOwnProperty.call(TAX_ID_TYPE_META, value);
+}
+
+const EU_COUNTRIES = new Set([
+  'AT',
+  'BE',
+  'BG',
+  'HR',
+  'CY',
+  'CZ',
+  'DK',
+  'EE',
+  'FI',
+  'FR',
+  'DE',
+  'GR',
+  'HU',
+  'IE',
+  'IT',
+  'LV',
+  'LT',
+  'LU',
+  'MT',
+  'NL',
+  'PL',
+  'PT',
+  'RO',
+  'SK',
+  'SI',
+  'ES',
+  'SE',
+]);
+
+/**
+ * The registration type a buyer country preselects: EU countries stay on `eu_vat` (a member
+ * state's domestic registration like `de_stn` is the rarer intent, and `eu_vat` was the only
+ * type the surface ever sent, so it is the floor); a country with exactly ONE catalog type
+ * preselects it (`AR` → `ar_cuit`, `US` → `us_ein`); everything else — unknown country, or one
+ * with several registrations to pick from — falls back to `eu_vat`, today's bare default.
+ */
+export function defaultTaxIdType(country: string | undefined): TaxIdType {
+  if (!country) return 'eu_vat';
+  const iso = country.toUpperCase();
+  if (EU_COUNTRIES.has(iso)) return 'eu_vat';
+  const matches = TAX_ID_TYPES.filter((type) => TAX_ID_TYPE_META[type].region === iso);
+  return matches.length === 1 ? (matches[0] ?? 'eu_vat') : 'eu_vat';
+}
+
+/**
+ * The buyer-facing name of each registration, the way the world abbreviates them (`EU VAT`,
+ * `AR CUIT`, `US EIN`) — the same labels the dashboard's tax settings use. Localized copy, so a
+ * hook: the labels ride the element's message catalog like every other user-facing string. The
+ * `Record<TaxIdType, …>` return type is the second half of the exhaustiveness gate — a new wire
+ * type without a label refuses to compile.
+ */
+export function useTaxIdTypeLabels(): Record<TaxIdType, string> {
+  const t = useT();
+  return useMemo(
+    () => ({
+      ad_nrt: t('AD NRT'),
+      ae_trn: t('AE TRN'),
+      al_tin: t('AL TIN'),
+      am_tin: t('AM TIN'),
+      ao_tin: t('AO TIN'),
+      ar_cuit: t('AR CUIT'),
+      au_abn: t('AU ABN'),
+      au_arn: t('AU ARN'),
+      aw_tin: t('AW TIN'),
+      az_tin: t('AZ TIN'),
+      ba_tin: t('BA TIN'),
+      bb_tin: t('BB TIN'),
+      bd_bin: t('BD BIN'),
+      bf_ifu: t('BF IFU'),
+      bg_uic: t('BG UIC'),
+      bh_vat: t('BH VAT'),
+      bj_ifu: t('BJ IFU'),
+      bo_tin: t('BO TIN'),
+      br_cnpj: t('BR CNPJ'),
+      br_cpf: t('BR CPF'),
+      bs_tin: t('BS TIN'),
+      by_tin: t('BY TIN'),
+      ca_bn: t('CA BN'),
+      ca_gst_hst: t('CA GST/HST'),
+      ca_pst_bc: t('CA PST BC'),
+      ca_pst_mb: t('CA PST MB'),
+      ca_pst_sk: t('CA PST SK'),
+      ca_qst: t('CA QST'),
+      cd_nif: t('CD NIF'),
+      ch_uid: t('CH UID'),
+      ch_vat: t('CH VAT'),
+      cl_tin: t('CL TIN'),
+      cm_niu: t('CM NIU'),
+      cn_tin: t('CN TIN'),
+      co_nit: t('CO NIT'),
+      cr_tin: t('CR TIN'),
+      cv_nif: t('CV NIF'),
+      de_stn: t('DE STN'),
+      do_rcn: t('DO RCN'),
+      ec_ruc: t('EC RUC'),
+      eg_tin: t('EG TIN'),
+      es_cif: t('ES CIF'),
+      et_tin: t('ET TIN'),
+      eu_oss_vat: t('EU OSS VAT'),
+      eu_vat: t('EU VAT'),
+      gb_vat: t('GB VAT'),
+      ge_vat: t('GE VAT'),
+      gh_tin: t('GH TIN'),
+      gn_nif: t('GN NIF'),
+      hk_br: t('HK BR'),
+      hr_oib: t('HR OIB'),
+      hu_tin: t('HU TIN'),
+      id_npwp: t('ID NPWP'),
+      il_vat: t('IL VAT'),
+      in_gst: t('IN GST'),
+      is_vat: t('IS VAT'),
+      jp_cn: t('JP CN'),
+      jp_rn: t('JP RN'),
+      jp_trn: t('JP TRN'),
+      ke_pin: t('KE PIN'),
+      kg_tin: t('KG TIN'),
+      kh_tin: t('KH TIN'),
+      kr_brn: t('KR BRN'),
+      kz_bin: t('KZ BIN'),
+      la_tin: t('LA TIN'),
+      li_uid: t('LI UID'),
+      li_vat: t('LI VAT'),
+      ma_vat: t('MA VAT'),
+      md_vat: t('MD VAT'),
+      me_pib: t('ME PIB'),
+      mk_vat: t('MK VAT'),
+      mr_nif: t('MR NIF'),
+      mx_rfc: t('MX RFC'),
+      my_frp: t('MY FRP'),
+      my_itn: t('MY ITN'),
+      my_sst: t('MY SST'),
+      ng_tin: t('NG TIN'),
+      no_vat: t('NO VAT'),
+      no_voec: t('NO VOEC'),
+      np_pan: t('NP PAN'),
+      nz_gst: t('NZ GST'),
+      om_vat: t('OM VAT'),
+      pe_ruc: t('PE RUC'),
+      ph_tin: t('PH TIN'),
+      pl_nip: t('PL NIP'),
+      ro_tin: t('RO TIN'),
+      rs_pib: t('RS PIB'),
+      ru_inn: t('RU INN'),
+      ru_kpp: t('RU KPP'),
+      sa_vat: t('SA VAT'),
+      sg_gst: t('SG GST'),
+      sg_uen: t('SG UEN'),
+      si_tin: t('SI TIN'),
+      sn_ninea: t('SN NINEA'),
+      sr_fin: t('SR FIN'),
+      sv_nit: t('SV NIT'),
+      th_vat: t('TH VAT'),
+      tj_tin: t('TJ TIN'),
+      tr_tin: t('TR TIN'),
+      tw_vat: t('TW VAT'),
+      tz_vat: t('TZ VAT'),
+      ua_vat: t('UA VAT'),
+      ug_tin: t('UG TIN'),
+      us_ein: t('US EIN'),
+      uy_ruc: t('UY RUC'),
+      uz_tin: t('UZ TIN'),
+      uz_vat: t('UZ VAT'),
+      ve_rif: t('VE RIF'),
+      vn_tin: t('VN TIN'),
+      xi_vat: t('XI VAT'),
+      za_vat: t('ZA VAT'),
+      zm_tin: t('ZM TIN'),
+      zw_tin: t('ZW TIN'),
+    }),
+    [t],
+  );
+}