@myazahq/kyc-sdk-react-native 2.0.2 → 2.2.0

package/src/config/currencyFlags.ts

@@ -0,0 +1,144 @@
+// ---------------------------------------------------------------------------
+// Currency → flag country
+//
+// ISO 4217 currency codes are built from the ISO 3166 country code plus a
+// letter for the currency itself (NG + N = NGN, US + D = USD), so the first two
+// characters give the right flag for almost every real currency.
+//
+// Two exceptions matter and are handled explicitly:
+//   • EUR — no country prefix; use the EU flag.
+//   • X-prefixed codes — supranational/commodity (XOF, XAF, XCD, XAU…). These
+//     have no single country, so they get NO flag rather than a wrong one
+//     (XO isn't a country; rendering something arbitrary is worse than blank).
+//
+// Ported from the Flutter SDK's `config/currency_flags.dart` — keep the two in
+// step, since a currency that flags differently per platform is a visible bug.
+// ---------------------------------------------------------------------------
+
+const EXPLICIT: Record<string, string> = {
+  EUR: 'EU',
+};
+
+/**
+ * ISO-3166 alpha-2 code whose flag represents `currency`, or null when no
+ * single country does.
+ */
+export function currencyFlagCountry(currency: string): string | null {
+  const code = currency.trim().toUpperCase();
+  if (code.length < 3) return null;
+
+  const explicit = EXPLICIT[code];
+  if (explicit) return explicit;
+
+  // Supranational / metal codes carry no country.
+  if (code.startsWith('X')) return null;
+
+  return code.slice(0, 2);
+}
+
+// ---------------------------------------------------------------------------
+// Currency → full name
+//
+// The picker shows the name beside the code, because "GHS" and "GMD" are one
+// letter apart and mean different money. Covers Myaza's operating region in
+// full plus the majors and the currencies a workflow is realistically offered;
+// an unlisted code falls back to the code alone rather than a guess.
+//
+// Keep in step with the Flutter SDK's `config/currency_flags.dart`.
+// ---------------------------------------------------------------------------
+
+const CURRENCY_NAMES: Record<string, string> = {
+  // Africa
+  NGN: 'Nigerian Naira',
+  GHS: 'Ghanaian Cedi',
+  KES: 'Kenyan Shilling',
+  ZAR: 'South African Rand',
+  XOF: 'West African CFA Franc',
+  XAF: 'Central African CFA Franc',
+  EGP: 'Egyptian Pound',
+  MAD: 'Moroccan Dirham',
+  TND: 'Tunisian Dinar',
+  DZD: 'Algerian Dinar',
+  ETB: 'Ethiopian Birr',
+  UGX: 'Ugandan Shilling',
+  TZS: 'Tanzanian Shilling',
+  RWF: 'Rwandan Franc',
+  ZMW: 'Zambian Kwacha',
+  BWP: 'Botswana Pula',
+  NAD: 'Namibian Dollar',
+  MUR: 'Mauritian Rupee',
+  MWK: 'Malawian Kwacha',
+  MZN: 'Mozambican Metical',
+  AOA: 'Angolan Kwanza',
+  SLL: 'Sierra Leonean Leone',
+  SLE: 'Sierra Leonean Leone',
+  LRD: 'Liberian Dollar',
+  GMD: 'Gambian Dalasi',
+  GNF: 'Guinean Franc',
+  CDF: 'Congolese Franc',
+  BIF: 'Burundian Franc',
+  SOS: 'Somali Shilling',
+  SDG: 'Sudanese Pound',
+  LYD: 'Libyan Dinar',
+  ZWL: 'Zimbabwean Dollar',
+  SZL: 'Swazi Lilangeni',
+  LSL: 'Lesotho Loti',
+  CVE: 'Cape Verdean Escudo',
+  STN: 'São Tomé & Príncipe Dobra',
+  SCR: 'Seychellois Rupee',
+  DJF: 'Djiboutian Franc',
+  ERN: 'Eritrean Nakfa',
+  MGA: 'Malagasy Ariary',
+  MRU: 'Mauritanian Ouguiya',
+  KMF: 'Comorian Franc',
+  SSP: 'South Sudanese Pound',
+
+  // Majors / widely held
+  USD: 'US Dollar',
+  EUR: 'Euro',
+  GBP: 'British Pound',
+  CAD: 'Canadian Dollar',
+  AUD: 'Australian Dollar',
+  NZD: 'New Zealand Dollar',
+  CHF: 'Swiss Franc',
+  JPY: 'Japanese Yen',
+  CNY: 'Chinese Yuan',
+  HKD: 'Hong Kong Dollar',
+  SGD: 'Singapore Dollar',
+  INR: 'Indian Rupee',
+  AED: 'UAE Dirham',
+  SAR: 'Saudi Riyal',
+  QAR: 'Qatari Riyal',
+  KWD: 'Kuwaiti Dinar',
+  TRY: 'Turkish Lira',
+  ILS: 'Israeli Shekel',
+  SEK: 'Swedish Krona',
+  NOK: 'Norwegian Krone',
+  DKK: 'Danish Krone',
+  PLN: 'Polish Zloty',
+  CZK: 'Czech Koruna',
+  RON: 'Romanian Leu',
+  BRL: 'Brazilian Real',
+  MXN: 'Mexican Peso',
+  ARS: 'Argentine Peso',
+  CLP: 'Chilean Peso',
+  COP: 'Colombian Peso',
+  ZMK: 'Zambian Kwacha',
+  PKR: 'Pakistani Rupee',
+  BDT: 'Bangladeshi Taka',
+  LKR: 'Sri Lankan Rupee',
+  PHP: 'Philippine Peso',
+  THB: 'Thai Baht',
+  MYR: 'Malaysian Ringgit',
+  IDR: 'Indonesian Rupiah',
+  VND: 'Vietnamese Dong',
+  KRW: 'South Korean Won',
+};
+
+/**
+ * Full name for a currency code, or null when we don't have one — callers show
+ * the bare code rather than inventing a name.
+ */
+export function currencyName(currency: string): string | null {
+  return CURRENCY_NAMES[currency.trim().toUpperCase()] ?? null;
+}

package/src/config/font-resolve.ts

@@ -0,0 +1,78 @@
+import type { TextStyle } from 'react-native';
+
+/**
+ * PURE font-name resolution — no expo/RN runtime imports, so it is unit
+ * testable. `components/fonts.ts` owns the loading; this owns the naming.
+ *
+ * The invariant both sides depend on: a weight is resolved INTO the family
+ * name, never left for the platform to synthesise. Synthetic bold smears
+ * glyphs wider than they were measured, which clips text.
+ */
+
+/** The weights the SDK actually renders (see VARIANTS in Typography). */
+export const BRAND_WEIGHTS = [400, 500, 600, 700] as const;
+
+/** Registered family name for one weight — 400 keeps the bare name. */
+export function brandFamilyName(family: string, weight: number): string {
+  return weight === 400 ? family : `${family}__${weight}`;
+}
+
+/**
+ * The family for the Myaza MARK itself — always the bundled Karla, never the
+ * org's font.
+ *
+ * "TRUST" is part of a wordmark, not body copy. Rendering it in whatever
+ * typeface the workflow chose redraws someone else's logo in the customer's
+ * font, which is both wrong as attribution and inconsistent with the same
+ * lockup on the web and in the dashboard sidebar. So this deliberately ignores
+ * the brand-font override that `fontFamilyFor` honours.
+ *
+ * The web equivalent is `BRAND_FONT_STACK` ('"Karla", system-ui, sans-serif').
+ * RN has no stack — `fontFamily` matches one registered family or nothing — so
+ * an unloaded font returns undefined and the platform face stands in, which is
+ * exactly what the web's `system-ui` fallback does.
+ */
+export function markFamilyName(
+  weight: TextStyle['fontWeight'],
+  loaded: boolean,
+): string | undefined {
+  if (!loaded) return undefined;
+  const w = String(weight ?? '400');
+  if (w === '700' || w === '800' || w === '900' || w === 'bold') return 'Karla_700Bold';
+  if (w === '600') return 'Karla_600SemiBold';
+  if (w === '500') return 'Karla_500Medium';
+  return 'Karla_400Regular';
+}
+
+export function fontFamilyFor(
+  isHeading: boolean,
+  weight: TextStyle['fontWeight'],
+  loaded: boolean,
+  override?: { body?: string; heading?: string },
+): string | undefined {
+  const w = String(weight ?? '400');
+  const bold = w === '700' || w === '800' || w === '900' || w === 'bold';
+
+  // An org font wins. Its weights are registered as SEPARATE families (see
+  // brand-font.ts), exactly like the bundled ones — so the weight is resolved
+  // into the family name here and never left for the platform to synthesise.
+  // Synthetic bold smears glyphs wider than they were measured, which clips
+  // text; picking a real weight cannot.
+  const brand = isHeading ? (override?.heading ?? override?.body) : override?.body;
+  if (brand && brand.trim()) {
+    const family = brand.trim();
+    const target = bold ? 700 : w === '600' ? 600 : w === '500' ? 500 : 400;
+    return brandFamilyName(family, target);
+  }
+
+  if (!loaded) return undefined;
+  if (isHeading) {
+    if (bold) return 'SpaceGrotesk_700Bold';
+    if (w === '500') return 'SpaceGrotesk_500Medium';
+    return 'SpaceGrotesk_600SemiBold'; // 600 default for headings
+  }
+  if (bold) return 'Karla_700Bold';
+  if (w === '600') return 'Karla_600SemiBold';
+  if (w === '500') return 'Karla_500Medium';
+  return 'Karla_400Regular';
+}

package/src/config/idTypes.ts

@@ -1,4 +1,4 @@
-import type { IdTypesByCountry } from '../types/config';
+import type { IdTypeDefinition, IdTypesByCountry } from '../types/config';
 
 /**
  * Source of truth for the supported `(country, idType)` matrix — identical to
@@ -47,6 +47,33 @@ export function isNumberOnlyIdType(idType: string): boolean {
   return def ? !def.requiresDocumentCapture : false;
 }
 
+/**
+ * ID keys whose physical document carries an ICAO 9303 eMRTD chip.
+ *
+ * A FALLBACK only. Chip capability is catalogue-driven SERVER-side and arrives
+ * per row on `/api/kyc/config` as `supportsNfc`; that answer is authoritative
+ * and covers documents this local list has never heard of (every country's
+ * passport, for one). This list is what the flow uses before config lands.
+ *
+ * Matches the Flutter SDK's `IdTypeConfig.supportsNfc`.
+ */
+const CHIP_CAPABLE_KEYS = new Set(['passport', 'ghana-card', 'cni']);
+
+/**
+ * Whether the document behind this ID has a readable chip.
+ *
+ * `serverSupportsNfc` is the row from `/api/kyc/config` when it has loaded —
+ * pass it and it wins outright, including its `false`.
+ */
+export function supportsNfcChip(
+  _country: string,
+  idType: string,
+  serverSupportsNfc?: boolean,
+): boolean {
+  if (serverSupportsNfc !== undefined) return serverSupportsNfc;
+  return CHIP_CAPABLE_KEYS.has(idType);
+}
+
 /** Returns true when the selected ID type requires a physical document scan. */
 export function requiresDocumentCapture(idType: string): boolean {
   const def = ALL_ID_TYPES.find((t) => t.key === idType);
@@ -62,6 +89,74 @@ export function getScanSides(idType: string): 'front_only' | 'front_and_back' {
   return def?.scanSides ?? 'front_only';
 }
 
+/**
+ * The document's name, short enough to sit in a pill beside a flag.
+ *
+ * The catalogue label is written for a PICKER, where "International Passport"
+ * disambiguates. Beside a flag it is redundant twice over — the country is
+ * already shown, and nobody is choosing anything at the camera. Keyed off the
+ * ID type rather than trimmed from the string, so it holds for every country's
+ * passport whatever its catalogue label says.
+ */
+export function shortDocumentLabel(idType: string | null, label: string): string {
+  return idType === 'passport' ? 'Passport' : label;
+}
+
+/** `drivers-license` → `Drivers License`. Last-resort label for an unknown key. */
+export function humanizeIdType(key: string): string {
+  return key
+    .replace(/[-_]+/g, ' ')
+    .trim()
+    .split(' ')
+    .filter(Boolean)
+    .map((w) => w[0]!.toUpperCase() + w.slice(1))
+    .join(' ');
+}
+
+/** The server-config metadata a row carries for one (country, idType) pair. */
+export interface IdTypeRowMeta {
+  label?: string;
+  requiresDocumentCapture?: boolean;
+  scanSides?: string;
+  supportsNfc?: boolean;
+}
+
+/**
+ * The definition for a (country, idType) pair.
+ *
+ * A curated entry wins; otherwise one is SYNTHESIZED from the server row. That
+ * fallback is the whole point: the curated table only covers the five gov-DB
+ * countries, while Global Documents lets a workflow offer any of ~240. Without
+ * it, every country outside that table renders an empty ID list — the flow
+ * looks like the org has no access when it simply has no curated entry.
+ *
+ * Mirrors the Flutter SDK's `resolveIdTypeDefinition`.
+ */
+export function resolveIdTypeDefinition(
+  country: string,
+  key: string,
+  meta: IdTypeRowMeta = {},
+): IdTypeDefinition {
+  // Indexed loosely on purpose: `IdTypesByCountry` is keyed by the five curated
+  // countries, and the whole point here is being asked about the other ~235.
+  const table = ID_TYPES as Record<string, readonly IdTypeDefinition[] | undefined>;
+  const curated = (table[country.toUpperCase()] ?? []).find((t) => t.key === key);
+  if (curated) return curated;
+
+  // Default to needing a document: an unknown ID is far more likely to be a
+  // physical card than a number the user can type, and asking for a photo that
+  // wasn't needed is recoverable in a way that skipping capture is not.
+  const needsCapture = meta.requiresDocumentCapture ?? true;
+  return {
+    key: key as IdTypeDefinition['key'],
+    label: meta.label && meta.label.length > 0 ? meta.label : humanizeIdType(key),
+    requiresDocumentCapture: needsCapture,
+    ...(needsCapture
+      ? { scanSides: meta.scanSides === 'front_and_back' ? 'front_and_back' : 'front_only' }
+      : {}),
+  } as IdTypeDefinition;
+}
+
 // Card-guide / crop aspect (width ÷ height) for the live camera. Mirrors the
 // Flutter SDK's documentGuideAspect: ID-1 cards use 1.586; passports use a taller
 // 1.42 so the data page's bottom MRZ band isn't cropped off.

package/src/config/keyPeople.ts

@@ -0,0 +1,162 @@
+// ---------------------------------------------------------------------------
+// Applicant-declared key people (directors, owners, signatories) — the pure
+// half.
+//
+// Regulators require identifying the natural persons who own or control a
+// business. The registry lookup discovers some of them; this is what the
+// APPLICANT declares, and a person the applicant omits who the registry then
+// names is a risk signal the server flags as `undisclosed`.
+// ---------------------------------------------------------------------------
+
+import type { KeyPersonRole } from '../types/business';
+import { isValidContactEmail } from './contact';
+
+/** UI cap on applicant-entered rows (the server accepts ≤20). */
+export const MAX_KEY_PEOPLE_ROWS = 10;
+
+export const KEY_PERSON_ROLE_LABELS: Record<KeyPersonRole, string> = {
+  director: 'Director',
+  beneficial_owner: 'Beneficial owner (UBO)',
+  signatory: 'Signatory',
+  shareholder: 'Shareholder',
+};
+
+export const KEY_PERSON_ROLES: KeyPersonRole[] = [
+  'director',
+  'beneficial_owner',
+  'signatory',
+  'shareholder',
+];
+
+/** One row as typed. Everything is a string so a half-filled row is editable. */
+export interface KeyPersonEntry {
+  name: string;
+  role: KeyPersonRole;
+  email: string;
+  /** The person's own ISO-2 country — a foreign director cannot verify with a
+   *  local ID, so this drives their invite's country. */
+  country: string;
+  ownershipPct: string;
+}
+
+export function emptyKeyPerson(role: KeyPersonRole = 'director'): KeyPersonEntry {
+  return { name: '', role, email: '', country: '', ownershipPct: '' };
+}
+
+/** Whether a row is complete enough to submit. */
+export function isKeyPersonRowValid(row: KeyPersonEntry): boolean {
+  if (row.name.trim().length < 2) return false;
+  if (!KEY_PERSON_ROLES.includes(row.role)) return false;
+  if (row.email.trim() !== '' && !isValidContactEmail(row.email.trim())) return false;
+  if (row.ownershipPct.trim() !== '') {
+    const pct = Number(row.ownershipPct);
+    if (!Number.isFinite(pct) || pct < 0 || pct > 100) return false;
+  }
+  return true;
+}
+
+/**
+ * A blank row is not an error — it is a row the user started and abandoned, and
+ * it is simply dropped. Only a row with SOMETHING in it can be invalid.
+ */
+export function isKeyPersonRowBlank(row: KeyPersonEntry): boolean {
+  return (
+    row.name.trim() === '' &&
+    row.email.trim() === '' &&
+    row.country.trim() === '' &&
+    row.ownershipPct.trim() === ''
+  );
+}
+
+/** Rows the user has begun but not made valid — what blocks Continue. */
+export function invalidKeyPersonRows(rows: KeyPersonEntry[]): number[] {
+  return rows
+    .map((row, i) => (!isKeyPersonRowBlank(row) && !isKeyPersonRowValid(row) ? i : -1))
+    .filter((i) => i >= 0);
+}
+
+/**
+ * The valid rows, in the shape the verify payload wants. `applicantIndex`
+ * (into the UNfiltered `rows`) flags the entry the applicant picked as
+ * themselves — the server merges it with the applicant row so one human
+ * never becomes two KeyPerson records (one KYC, one screening, no invite).
+ */
+export function keyPeoplePayload(
+  rows: KeyPersonEntry[],
+  applicantIndex: number | null = null,
+): Array<{
+  name: string;
+  role: KeyPersonRole;
+  email?: string;
+  country?: string;
+  ownershipPct?: number;
+  isApplicant?: boolean;
+}> {
+  return rows
+    .map((row, index) => ({ row, index }))
+    .filter(({ row }) => isKeyPersonRowValid(row))
+    .slice(0, 20)
+    .map(({ row, index }) => ({
+      name: row.name.trim(),
+      role: row.role,
+      ...(row.email.trim() !== '' ? { email: row.email.trim() } : {}),
+      ...(row.country.trim() !== '' ? { country: row.country.trim().toUpperCase() } : {}),
+      ...(row.ownershipPct.trim() !== '' ? { ownershipPct: Number(row.ownershipPct) } : {}),
+      ...(index === applicantIndex ? { isApplicant: true } : {}),
+    }));
+}
+
+/** "Richard Ingwe" → "RI" — the avatar monogram used on person cards. */
+export function initialsOf(name: string): string {
+  return name
+    .trim()
+    .split(/\s+/)
+    .slice(0, 2)
+    .map((t) => t[0]?.toUpperCase() ?? '')
+    .join('');
+}
+
+/** Split a typed full name into first/last (best-effort). */
+export function splitFullName(name: string): { firstName?: string; lastName?: string } | undefined {
+  const trimmed = name.trim();
+  if (!trimmed) return undefined;
+  const [firstName, ...rest] = trimmed.split(/\s+/);
+  return { firstName, ...(rest.length > 0 ? { lastName: rest.join(' ') } : {}) };
+}
+
+/**
+ * Loose "is this the same person?" match used ONLY to PRE-SELECT the
+ * applicant's own entry on the applicant-role step (from the consumer's
+ * userData). Every token of the shorter name must appear in the longer one,
+ * so "Richard Ingwe" matches "Richard A. Ingwe" but never "Jane Ingwe". The
+ * user still confirms explicitly — this never merges anything by itself.
+ */
+export function namesLooselyMatch(a: string, b: string): boolean {
+  const tokens = (s: string): string[] =>
+    s
+      .toLowerCase()
+      .normalize('NFKD')
+      .replace(/[^\p{L}\p{N}\s]/gu, '')
+      .split(/\s+/)
+      .filter((t) => t.length > 1);
+  const ta = tokens(a);
+  const tb = tokens(b);
+  if (ta.length === 0 || tb.length === 0) return false;
+  const [shorter, longer] = ta.length <= tb.length ? [ta, tb] : [tb, ta];
+  return shorter.every((t) => longer.includes(t));
+}
+
+/**
+ * The self-selected key person's ID-issuing country (uppercase ISO-2), when
+ * the applicant picked themselves AND that entry carries one. The applicant
+ * leg then SKIPS the country-select step — they already answered "where was
+ * your ID issued?" on the key-people step.
+ */
+export function applicantSelfCountry(app: {
+  keyPeople: KeyPersonEntry[];
+  applicantKeyPersonIndex: number | null;
+}): string | null {
+  if (app.applicantKeyPersonIndex === null) return null;
+  const country = app.keyPeople[app.applicantKeyPersonIndex]?.country.trim();
+  return country ? country.toUpperCase() : null;
+}

package/src/config/phone.ts

@@ -0,0 +1,39 @@
+import { AsYouType, getCountryCallingCode, type CountryCode } from 'libphonenumber-js/min';
+
+// ---------------------------------------------------------------------------
+// National-format a phone number as it is typed.
+//
+// libphonenumber's national formats are keyed to the country's TRUNK PREFIX —
+// the leading 0 in "0803 123 4567". Feed it a Nigerian number the way a picker
+// UI collects it (dial code chosen separately, so "8031234567"), and no format
+// matches: it hands back the raw digits and the field looks broken.
+//
+// So: try the country formatter first, because it is the only thing that knows
+// per-country rules — including the countries where the leading 0 is genuinely
+// part of the number (Italy: "06 1234 5678"). If it grouped nothing, re-run it
+// on the international form and drop the "+CC " prefix, which yields the same
+// grouping Flutter's formatNsn() produces.
+// ---------------------------------------------------------------------------
+
+/** True once the formatter has actually grouped something. */
+const isGrouped = (value: string): boolean => /[\s\-()./]/.test(value);
+
+export function formatNationalNumber(typed: string, country: CountryCode): string {
+  const digits = typed.replace(/\D+/g, '');
+  if (!digits) return '';
+
+  // AsYouType is stateful per instance — never reuse one across keystrokes.
+  const direct = new AsYouType(country).input(digits);
+  if (isGrouped(direct)) return direct;
+
+  try {
+    const prefix = `+${getCountryCallingCode(country)}`;
+    const international = new AsYouType().input(`${prefix}${digits}`);
+    return international.startsWith(prefix)
+      ? international.slice(prefix.length).trim()
+      : direct;
+  } catch {
+    // Unknown country code — leave the digits alone rather than mangling them.
+    return direct;
+  }
+}

package/src/config/proofOfAddress.ts

@@ -0,0 +1,75 @@
+// ---------------------------------------------------------------------------
+// Proof of Address — the pure half.
+//
+// A recent utility bill / bank statement / tenancy document, read server-side
+// and cross-checked against the subject's name and a recency window. The result
+// is a SOFT sub-result: it never changes the verification's own status, it
+// feeds decisioning. So nothing here should block a user over a judgement the
+// server is going to make anyway.
+// ---------------------------------------------------------------------------
+
+import type { PoaDocumentType, ProofOfAddressConfig } from '../types/workflow';
+
+export const POA_TYPE_LABELS: Record<PoaDocumentType, string> = {
+  utility_bill: 'Utility bill',
+  bank_statement: 'Bank statement',
+  tenancy_agreement: 'Tenancy agreement',
+  other: 'Other document',
+};
+
+const ALL_POA_TYPES: PoaDocumentType[] = [
+  'utility_bill',
+  'bank_statement',
+  'tenancy_agreement',
+  'other',
+];
+
+/** Default recency window the server checks the document date against. */
+export const DEFAULT_POA_MAX_AGE_DAYS = 90;
+
+/** Whether the step is part of the flow. */
+export function hasProofOfAddressStep(poa: ProofOfAddressConfig | undefined | null): boolean {
+  return poa?.enabled === true;
+}
+
+/** The document kinds on offer. An absent or empty list means all of them. */
+export function poaDocumentTypes(poa: ProofOfAddressConfig | undefined): PoaDocumentType[] {
+  const configured = poa?.documentTypes;
+  return configured && configured.length > 0 ? configured : ALL_POA_TYPES;
+}
+
+/**
+ * The label for a kind.
+ *
+ * `otherLabel` lets an org name what "other" means for them ("Council tax
+ * letter"), which is the difference between a user knowing what to upload and
+ * guessing.
+ */
+export function poaTypeLabel(type: PoaDocumentType, poa: ProofOfAddressConfig | undefined): string {
+  const custom = poa?.otherLabel?.trim();
+  if (type === 'other' && custom) return custom;
+  return POA_TYPE_LABELS[type];
+}
+
+export function poaMaxAgeDays(poa: ProofOfAddressConfig | undefined): number {
+  return poa?.maxAgeDays ?? DEFAULT_POA_MAX_AGE_DAYS;
+}
+
+/** Accepted upload types — the only media kind that takes a PDF. */
+export const POA_ACCEPTED_MIME_TYPES = [
+  'image/jpeg',
+  'image/png',
+  'image/webp',
+  'application/pdf',
+] as const;
+
+/**
+ * Local size cap, matching the web SDK. The server allows more, but rejecting
+ * here gives an immediate, specific message instead of a slow 413.
+ */
+export const POA_MAX_BYTES = 20 * 1024 * 1024;
+
+export function isAcceptedPoaMimeType(mimeType: string | undefined): boolean {
+  const base = (mimeType?.split(';')[0] ?? '').trim().toLowerCase();
+  return (POA_ACCEPTED_MIME_TYPES as readonly string[]).includes(base);
+}