@myazahq/kyc-sdk-react-native 2.0.1 → 2.1.0

package/src/config/questionnaire.ts

@@ -0,0 +1,153 @@
+// ---------------------------------------------------------------------------
+// Extra-info questionnaire — the pure half.
+//
+// Compliance declarations (source of funds, expected volume, PEP status …) the
+// org authors in the workflow builder and the SDK asks just before submission.
+// Answer keys are a published contract: they land on the verification, ride the
+// webhook, and decision graphs branch on `questionnaire.<key>` — so a key must
+// never be repurposed once a workflow is live.
+//
+// Validation lives here rather than in the screen so it can be tested without a
+// renderer, and so the screen and the submission cannot disagree about what
+// counts as answered. The server re-validates against the published definition
+// regardless; this is for telling the user before they spend a round trip.
+// ---------------------------------------------------------------------------
+
+import type {
+  QuestionnaireAnswerValue,
+  QuestionnaireConfig,
+  QuestionnaireField,
+} from '../types/workflow';
+
+export type QuestionnaireAnswers = Record<string, QuestionnaireAnswerValue | undefined>;
+
+/**
+ * Whether the step appears in the flow.
+ *
+ * `enabled: false` turns the step off while KEEPING the questions configured —
+ * that is the builder's toggle, so a org can park a questionnaire without
+ * losing it. Single source of truth for the gate; the step order reads it too.
+ */
+export function hasActiveQuestionnaire(
+  questionnaire: QuestionnaireConfig | undefined | null,
+): boolean {
+  return questionnaire?.enabled !== false && (questionnaire?.fields?.length ?? 0) > 0;
+}
+
+/** The companion key a money answer stores its ISO currency under. */
+export function currencyKeyFor(field: QuestionnaireField): string {
+  return `${field.key}_currency`;
+}
+
+/**
+ * Every answer key a definition can produce — money questions contribute two.
+ * The server uses the same expansion to cross-check decision-graph references,
+ * so anything reasoning about "the keys this questionnaire yields" must use it
+ * rather than mapping over `fields`.
+ */
+export function questionnaireAnswerKeys(questionnaire: QuestionnaireConfig | undefined): string[] {
+  const keys: string[] = [];
+  for (const field of questionnaire?.fields ?? []) {
+    keys.push(field.key);
+    if (field.type === 'money') keys.push(currencyKeyFor(field));
+  }
+  return keys;
+}
+
+function isEmpty(value: QuestionnaireAnswerValue | undefined): boolean {
+  return value === undefined || value === '' || (Array.isArray(value) && value.length === 0);
+}
+
+/**
+ * Per-field error messages, keyed by field key. Empty means good to submit.
+ *
+ * A field that is not required and left blank is valid and simply not sent —
+ * an unanswered optional question must not become an empty string on the
+ * verification record.
+ */
+export function validateQuestionnaire(
+  fields: QuestionnaireField[],
+  answers: QuestionnaireAnswers,
+): Record<string, string> {
+  const errors: Record<string, string> = {};
+
+  for (const field of fields) {
+    const value = answers[field.key];
+    if (isEmpty(value)) {
+      if (field.required) errors[field.key] = 'This field is required.';
+      continue;
+    }
+
+    if (field.type === 'number' || field.type === 'money') {
+      const num = Number(value);
+      if (!Number.isFinite(num) || (field.type === 'money' && num < 0)) {
+        errors[field.key] =
+          field.type === 'money' ? 'Enter a valid amount.' : 'Enter a valid number.';
+      } else if (field.min !== undefined && num < field.min) {
+        errors[field.key] = `Must be at least ${field.min.toLocaleString()}.`;
+      } else if (field.max !== undefined && num > field.max) {
+        errors[field.key] = `Must be at most ${field.max.toLocaleString()}.`;
+      }
+      continue;
+    }
+
+    if (field.type === 'select' && field.options && field.options.length > 0) {
+      if (!field.options.some((o) => o.value === value)) {
+        errors[field.key] = 'Choose one of the listed options.';
+      }
+      continue;
+    }
+
+    if (field.type === 'multiselect' && field.options && field.options.length > 0) {
+      const chosen = Array.isArray(value) ? value : [];
+      if (chosen.some((v) => !field.options!.some((o) => o.value === v))) {
+        errors[field.key] = 'Choose from the listed options.';
+      }
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * The answers to submit.
+ *
+ * Blank optional answers are dropped, numbers are sent as numbers (a numeric
+ * field typed as text would break a `gt`/`lt` branch in a decision graph), and
+ * money amounts are rounded to 2dp and always paired with a currency — the
+ * definition's first is the default, because a user who never opened the picker
+ * still meant the one that was showing.
+ */
+export function questionnairePayload(
+  fields: QuestionnaireField[],
+  answers: QuestionnaireAnswers,
+): Record<string, QuestionnaireAnswerValue> {
+  const payload: Record<string, QuestionnaireAnswerValue> = {};
+
+  for (const field of fields) {
+    const value = answers[field.key];
+    if (isEmpty(value)) continue;
+
+    if (field.type === 'number') {
+      const num = Number(value);
+      if (!Number.isFinite(num)) continue;
+      payload[field.key] = num;
+      continue;
+    }
+
+    if (field.type === 'money') {
+      const num = Number(value);
+      if (!Number.isFinite(num)) continue;
+      payload[field.key] = Math.round(num * 100) / 100;
+      const currency = answers[currencyKeyFor(field)] ?? field.currencies?.[0];
+      if (typeof currency === 'string' && currency !== '') {
+        payload[currencyKeyFor(field)] = currency;
+      }
+      continue;
+    }
+
+    payload[field.key] = value as QuestionnaireAnswerValue;
+  }
+
+  return payload;
+}

package/src/config/regions.ts

@@ -0,0 +1,118 @@
+// ---------------------------------------------------------------------------
+// Full ISO region grouping for the country-select step.
+//
+// Global Documents let a workflow offer any of ~200 countries, and a flat list
+// that long is not a chooser — it is a scroll. Grouping by region (with search)
+// is what makes it usable. Identical to the web SDK's `lib/regions.ts` and the
+// dashboard's `lib/country-regions.ts`; keep the three in step.
+//
+// `Intl.DisplayNames` supplies the names. Hermes ships full-icu, so this works
+// on device — but it is guarded anyway, and falls back to the ISO code, because
+// a picker showing "NG" is worse than one showing "Nigeria" and much better
+// than one that throws.
+// ---------------------------------------------------------------------------
+
+import { COUNTRY_NAMES } from './countryNames.g';
+
+let cachedDn: Intl.DisplayNames | null | undefined;
+function displayNames(): Intl.DisplayNames | null {
+  if (cachedDn === undefined) {
+    try {
+      // `fallback: 'code'` returns the ISO code for a region CLDR does not
+      // know, instead of throwing. A row reading "QQ" is a poor label; a crash
+      // in the middle of a picker is a dead flow.
+      cachedDn = new Intl.DisplayNames(['en'], { type: 'region', fallback: 'code' });
+    } catch {
+      cachedDn = null;
+    }
+  }
+  return cachedDn ?? null;
+}
+
+/** English name for an ISO-2 code (falls back to the code itself). */
+export function regionCountryName(code: string): string {
+  const up = code.toUpperCase();
+  // The generated table FIRST. `Intl.DisplayNames` is not dependable on this
+  // runtime — Hermes may ship without region data, in which case every row read
+  // as a bare ISO code, which is what this fixes. The table is also shared with
+  // the Flutter SDK, so both label a country identically.
+  const known = COUNTRY_NAMES[up];
+  if (known) return known;
+  try {
+    const name = displayNames()?.of(up);
+    // CLDR maps the reserved code ZZ to the literal "Unknown Region", which as
+    // a picker row tells the user nothing at all — the code is more use.
+    if (!name || name === 'Unknown Region') return up;
+    return name;
+  } catch {
+    return up;
+  }
+}
+
+export type Region = 'Africa' | 'Europe' | 'Americas' | 'Middle East' | 'Asia & Pacific' | 'Other';
+
+const REGION_ORDER: Region[] = ['Africa', 'Europe', 'Americas', 'Middle East', 'Asia & Pacific', 'Other'];
+
+const REGION_SETS: Record<Exclude<Region, 'Other'>, string[]> = {
+  Africa: [
+    'DZ', 'AO', 'BJ', 'BW', 'BF', 'BI', 'CV', 'CM', 'CF', 'TD', 'KM', 'CG',
+    'CD', 'CI', 'DJ', 'EG', 'GQ', 'ER', 'SZ', 'ET', 'GA', 'GM', 'GH', 'GN',
+    'GW', 'KE', 'LS', 'LR', 'LY', 'MG', 'MW', 'ML', 'MR', 'MU', 'YT', 'MA',
+    'MZ', 'NA', 'NE', 'NG', 'RE', 'RW', 'SH', 'ST', 'SN', 'SC', 'SL', 'SO',
+    'ZA', 'SS', 'SD', 'TZ', 'TG', 'TN', 'UG', 'EH', 'ZM', 'ZW',
+  ],
+  'Middle East': [
+    'AE', 'BH', 'IL', 'IQ', 'IR', 'JO', 'KW', 'LB', 'OM', 'PS', 'QA', 'SA',
+    'SY', 'TR', 'YE',
+  ],
+  Europe: [
+    'AD', 'AL', 'AT', 'AX', 'BA', 'BE', 'BG', 'BY', 'CH', 'CY', 'CZ', 'DE',
+    'DK', 'EE', 'ES', 'FI', 'FO', 'FR', 'GB', 'GG', 'GI', 'GR', 'HR', 'HU',
+    'IE', 'IM', 'IS', 'IT', 'JE', 'LI', 'LT', 'LU', 'LV', 'MC', 'MD', 'ME',
+    'MK', 'MT', 'NL', 'NO', 'PL', 'PT', 'RO', 'RS', 'RU', 'SE', 'SI', 'SJ',
+    'SK', 'SM', 'UA', 'VA', 'XK',
+  ],
+  Americas: [
+    'AG', 'AI', 'AR', 'AW', 'BB', 'BL', 'BM', 'BO', 'BQ', 'BR', 'BS', 'BZ',
+    'CA', 'CL', 'CO', 'CR', 'CU', 'CW', 'DM', 'DO', 'EC', 'FK', 'GD', 'GF',
+    'GL', 'GP', 'GT', 'GY', 'HN', 'HT', 'JM', 'KN', 'KY', 'LC', 'MF', 'MQ',
+    'MS', 'MX', 'NI', 'PA', 'PE', 'PM', 'PR', 'PY', 'SR', 'SV', 'SX', 'TC',
+    'TT', 'US', 'UY', 'VC', 'VE', 'VG', 'VI',
+  ],
+  'Asia & Pacific': [
+    'AF', 'AM', 'AS', 'AU', 'AZ', 'BD', 'BN', 'BT', 'CK', 'CN', 'FJ', 'FM',
+    'GE', 'GU', 'HK', 'ID', 'IN', 'JP', 'KG', 'KH', 'KI', 'KP', 'KR', 'KZ',
+    'LA', 'LK', 'MH', 'MM', 'MN', 'MO', 'MP', 'MV', 'MY', 'NC', 'NF', 'NP',
+    'NR', 'NU', 'NZ', 'PF', 'PG', 'PH', 'PK', 'PN', 'PW', 'SB', 'SG', 'TH',
+    'TJ', 'TK', 'TL', 'TM', 'TO', 'TV', 'TW', 'UZ', 'VN', 'VU', 'WF', 'WS',
+  ],
+};
+
+const BY_CODE = new Map<string, Region>();
+for (const [region, codes] of Object.entries(REGION_SETS) as Array<[Region, string[]]>) {
+  for (const code of codes) BY_CODE.set(code, region);
+}
+
+/** Every ISO code in the region map — the "all countries" picker source. */
+export const ALL_REGION_CODES: string[] = Object.values(REGION_SETS).flat();
+
+export interface RegionGroup {
+  region: Region;
+  countries: Array<{ code: string; name: string }>;
+}
+
+/** Group ISO codes by region (Africa first, 'Other' last), names A→Z within. */
+export function groupCountriesByRegion(codes: string[]): RegionGroup[] {
+  const buckets = new Map<Region, Array<{ code: string; name: string }>>();
+  for (const raw of codes) {
+    const code = raw.toUpperCase();
+    const region = BY_CODE.get(code) ?? 'Other';
+    const list = buckets.get(region) ?? [];
+    list.push({ code, name: regionCountryName(code) });
+    buckets.set(region, list);
+  }
+  return REGION_ORDER.filter((r) => buckets.has(r)).map((region) => ({
+    region,
+    countries: buckets.get(region)!.sort((a, b) => a.name.localeCompare(b.name)),
+  }));
+}

package/src/config/registrationHint.ts

@@ -0,0 +1,87 @@
+import { businessCountryName, type BusinessProductDef } from './business';
+
+// ---------------------------------------------------------------------------
+// Country-aware guidance for the registration-number input.
+//
+// Nigeria's registry (CAC) prefixes every number by entity type — the provider
+// rejects a number whose prefix is missing or separated from the digits — so
+// NG gets explicit prefix guidance AND format validation. Other registries get
+// a placeholder + tip only; no format is enforced outside Nigeria.
+//
+// Ported from the web SDK's `lib/registration-hint.ts` — keep the two in step
+// (country examples/tips are registry-verified there).
+// ---------------------------------------------------------------------------
+
+export interface RegistrationHint {
+  placeholder: string;
+  /** Guidance rendered beneath the input (null = nothing to show). */
+  tip: string | null;
+  /** Format check for the typed value (null = only non-empty is required). */
+  isValidFormat: ((value: string) => boolean) | null;
+  /** Inline error when isValidFormat fails. */
+  formatError: string | null;
+}
+
+const NG_PREFIX_RE = /^(RC|BN|IT|LP|LLP)\d+$/i;
+
+const NG_TIP =
+  'Prefix your registration number with RC for private companies limited by shares, ' +
+  'BN for business names, IT for incorporated trustees, LP for limited partnerships or ' +
+  'LLP for limited liability partnerships — with no space or character between the ' +
+  'prefix and the number, e.g. RC0000000.';
+
+// Countries whose English name takes a definite article ("the United States").
+const THE_COUNTRIES = new Set([
+  'US', 'GB', 'AE', 'NL', 'PH', 'CZ', 'GM', 'BS', 'MV', 'CD', 'CF', 'DO', 'KM', 'MH', 'SB', 'CG',
+]);
+
+function countryName(code: string): string {
+  const name = businessCountryName(code);
+  return THE_COUNTRIES.has(code.toUpperCase()) ? `the ${name}` : name;
+}
+
+const COUNTRY_EXAMPLES: Record<string, string> = {
+  KE: 'PVT-JZUA6Z663',
+  ZA: '201133333323',
+};
+
+const COUNTRY_TIPS: Record<string, string> = {
+  KE: 'Your registration number as it appears on your certificate of incorporation, e.g. PVT-JZUA6Z663.',
+  ZA: 'Your CIPC registration number — printed as 2011/333333/23 on your documents; enter it without the slashes, e.g. 201133333323.',
+};
+
+export function registrationNumberHint(
+  country: string,
+  productDef: BusinessProductDef,
+): RegistrationHint {
+  // TIN-keyed products keep their own placeholder/format (not a registry number).
+  if (productDef.inputLabel === 'TIN') {
+    return {
+      placeholder: productDef.placeholder,
+      tip: 'Your tax identification number as issued by the tax authority, e.g. 01234567-0001.',
+      isValidFormat: null,
+      formatError: null,
+    };
+  }
+
+  if (country === 'NG') {
+    return {
+      placeholder: 'e.g. RC0000000',
+      tip: NG_TIP,
+      isValidFormat: (value) => NG_PREFIX_RE.test(value.trim()),
+      formatError:
+        'Start with RC, BN, IT, LP or LLP followed by the number — no spaces, e.g. RC0000000.',
+    };
+  }
+
+  const cc = country.toUpperCase();
+  const example = COUNTRY_EXAMPLES[cc];
+  return {
+    placeholder: example ? `e.g. ${example}` : 'Enter your registration number',
+    tip:
+      COUNTRY_TIPS[cc] ??
+      `Your official company registration number, exactly as issued by the business registry in ${countryName(country)}.`,
+    isValidFormat: null,
+    formatError: null,
+  };
+}

package/src/config/stepOrder.ts

@@ -0,0 +1,118 @@
+// ---------------------------------------------------------------------------
+// Flow step ordering + progress accounting.
+//
+// ONE definition of the sequence, which navigation, the back button and the
+// progress bar all read. The store used to carry a hand-written `switch` per
+// direction; every optional step added there was two more cases to keep in
+// agreement, and forward and backward could disagree. An explicit ordered list
+// with index ±1 cannot.
+//
+//   individual: consent → (email) → (phone) → (country-select) → id-type →
+//               capture → (nfc) → (liveness) → (poa) → (questionnaire) →
+//               submitted
+//   business:   consent → (email) → (phone) → business-details →
+//               (key-people) → (documents) → (applicant-role → capture leg) →
+//               (questionnaire) → submitted
+//
+// Mirrors the web SDK's `lib/step-order.ts`, plus the `nfc` step, which is a
+// real step here — the web SDK can't do ISO-DEP so it only previews the screen.
+// ---------------------------------------------------------------------------
+
+import type { WorkflowBusinessConfig } from '../types/business';
+import type { KYCStep } from '../types/config';
+import { businessSectionSteps, hasApplicantVerification } from './businessSteps';
+
+export interface StepOrderOptions {
+  isBusiness: boolean;
+  /** Business (KYB) configuration — drives the application-section steps. */
+  business?: WorkflowBusinessConfig;
+  hasDocCapture: boolean;
+  hasNfc: boolean;
+  hasLiveness: boolean;
+  hasCountrySelect: boolean;
+  hasEmailVerification: boolean;
+  hasPhoneVerification: boolean;
+  hasPoa: boolean;
+  hasQuestionnaire: boolean;
+}
+
+// Contact-verification OTP steps sit right after consent (both flows) — a cheap
+// pre-filter before capture/registry spend; email before phone.
+function contactSteps(o: StepOrderOptions): KYCStep[] {
+  return [
+    ...(o.hasEmailVerification ? (['email-verification'] as KYCStep[]) : []),
+    ...(o.hasPhoneVerification ? (['phone-verification'] as KYCStep[]) : []),
+  ];
+}
+
+/** The individual capture leg — shared by the KYC flow and the KYB applicant. */
+function captureLeg(o: StepOrderOptions): KYCStep[] {
+  const steps: KYCStep[] = [o.hasDocCapture ? 'document-capture' : 'id-input'];
+  // The chip read follows the photo: the MRZ from that capture is what unlocks
+  // the chip, so there is nothing to read before it.
+  if (o.hasNfc && o.hasDocCapture) steps.push('nfc');
+  if (o.hasLiveness) steps.push('liveness');
+  return steps;
+}
+
+export function buildStepOrder(o: StepOrderOptions): KYCStep[] {
+  // Business (KYB) flow — the application section, then (when the workflow
+  // requires applicant verification) the ordinary individual capture leg.
+  if (o.isBusiness) {
+    const steps: KYCStep[] = ['consent', ...contactSteps(o), ...businessSectionSteps(o.business)];
+    if (hasApplicantVerification(o.business)) {
+      // The applicant may hold an ID issued anywhere the org can verify —
+      // more than one granted country (hasCountrySelect, derived from the
+      // server config for business flows) means they pick theirs first,
+      // exactly like a multi-region individual flow.
+      if (o.hasCountrySelect) steps.push('country-select');
+      steps.push('id-type', ...captureLeg(o));
+    }
+    if (o.hasQuestionnaire) steps.push('questionnaire');
+    steps.push('submitted');
+    return steps;
+  }
+
+  const middle: KYCStep[] = [...captureLeg(o)];
+  if (o.hasPoa) middle.push('proof-of-address');
+  if (o.hasQuestionnaire) middle.push('questionnaire');
+  return [
+    'consent',
+    ...contactSteps(o),
+    ...(o.hasCountrySelect ? (['country-select'] as KYCStep[]) : []),
+    'id-type',
+    ...middle,
+    'submitted',
+  ];
+}
+
+/** Percentage complete for the progress bar. */
+export function getStepProgress(step: KYCStep, o: StepOrderOptions): number {
+  const order = buildStepOrder(o);
+  const index = order.indexOf(step);
+  if (index === -1) return 0;
+  return Math.round(((index + 1) / order.length) * 100);
+}
+
+/**
+ * The step that follows `step`.
+ *
+ * A step not in the order (a workflow toggled it off after the user reached it,
+ * or a preview jumped straight to it) is left where it is rather than guessed
+ * at — advancing from a step the flow does not contain has no correct answer,
+ * and moving somewhere arbitrary is worse than standing still.
+ */
+export function nextStepInOrder(step: KYCStep, o: StepOrderOptions): KYCStep {
+  const order = buildStepOrder(o);
+  const index = order.indexOf(step);
+  if (index === -1) return step;
+  return order[index + 1] ?? order[order.length - 1]!;
+}
+
+/** The step before `step` — what the back button goes to. */
+export function previousStepInOrder(step: KYCStep, o: StepOrderOptions): KYCStep {
+  const order = buildStepOrder(o);
+  const index = order.indexOf(step);
+  if (index <= 0) return order[0]!;
+  return order[index - 1]!;
+}

package/src/config/theme.ts

@@ -82,7 +82,38 @@ export const DARK_COLORS: MyazaColorScheme = {
 
 export type ThemeMode = 'light' | 'dark';
 
-export const radius = { xs: 8, sm: 12, md: 16, lg: 20, xl: 24, full: 999 } as const;
+// The shipped scale, and the basis every override derives from.
+const DEFAULT_RADIUS = { xs: 8, sm: 12, md: 16, lg: 20, xl: 24, full: 999 };
+
+/**
+ * MUTABLE, so `appearance.borderRadius` can scale it.
+ *
+ * A mutable module object is a real trade-off, taken deliberately: 43 call sites
+ * read `radius.md` directly, and threading it through context buys nothing here
+ * — exactly one KYC flow is on screen at a time, and the scale is set once from
+ * the resolved config before that flow renders. The alternative is a 43-site
+ * refactor carrying far more risk.
+ */
+export const radius = { ...DEFAULT_RADIUS };
+
+/**
+ * `sm` (12) is the base — what buttons, inputs and cards use — so it is the rung
+ * a consumer is choosing when they say "our corners are 4px". The scale moves
+ * proportionally, keeping a card rounder than an input at every setting.
+ *
+ * `full` is deliberately untouched: it renders avatars and the camera circle,
+ * and scaling it turns circles into squircles.
+ */
+export function applyRadiusScale(base?: number): void {
+  const b = base == null || !Number.isFinite(base) ? DEFAULT_RADIUS.sm : Math.min(Math.max(base, 0), 32);
+  const ratio = b / DEFAULT_RADIUS.sm;
+  radius.xs = DEFAULT_RADIUS.xs * ratio;
+  radius.sm = DEFAULT_RADIUS.sm * ratio;
+  radius.md = DEFAULT_RADIUS.md * ratio;
+  radius.lg = DEFAULT_RADIUS.lg * ratio;
+  radius.xl = DEFAULT_RADIUS.xl * ratio;
+  radius.full = DEFAULT_RADIUS.full;
+}
 export const spacing = { xs: 4, sm: 8, md: 16, lg: 24, xl: 32 } as const;
 export const sizing = {
   buttonHeight: 48,
@@ -173,7 +204,12 @@ export function applyAppearance(
 
 /** Resolves the active color scheme for a mode + appearance override. */
 export function resolveColors(mode: ThemeMode, appearance?: KYCAppearance): MyazaColorScheme {
-  return applyAppearance(mode === 'dark' ? DARK_COLORS : LIGHT_COLORS, appearance);
+  // The appearance is applied ON TOP of the active base scheme, so without the
+  // dark overrides an org's LIGHT background simply overwrote the dark one and
+  // the theme toggle stopped working for any branded flow.
+  const forMode =
+    mode === 'dark' && appearance?.dark ? { ...appearance, ...appearance.dark } : appearance;
+  return applyAppearance(mode === 'dark' ? DARK_COLORS : LIGHT_COLORS, forMode);
 }
 
 /**

package/src/config/workflowMerge.ts

@@ -0,0 +1,124 @@
+// ---------------------------------------------------------------------------
+// Merging a resolved workflow over the consumer's props.
+//
+// A published flow is the org's authored template; the props are the
+// developer's code. The flow WINS on every key it defines, and props fill the
+// gaps — so mounting with `workflowId` gives the org control over the flow's
+// shape without the developer having to mirror every builder change.
+//
+// Mirrors the web SDK's `lib/workflow-merge.ts`.
+// ---------------------------------------------------------------------------
+
+/**
+ * The prop keys a published flow may override. Exactly the template surface —
+ * runtime data (apiKey, devUrl, userId, userData, metadata, callbacks) is never
+ * flow-controlled and always comes from the consumer's code.
+ */
+export const WORKFLOW_KEYS = [
+  'subjectType',
+  'business',
+  'country',
+  'countries',
+  'idTypes',
+  'enableSelfie',
+  'enableDocumentCapture',
+  'allowDocumentUpload',
+  'enableLiveness',
+  'livenessMode',
+  'flashSequenceLength',
+  'deviceIntelligence',
+  'requireMobileDevice',
+  'voiceGuidance',
+  'showThemeToggle',
+  'disableClose',
+  'appearance',
+  'consent',
+  'success',
+  'emailVerification',
+  'phoneVerification',
+  'questionnaire',
+  'proofOfAddress',
+  'nfc',
+] as const;
+
+export type WorkflowKey = (typeof WORKFLOW_KEYS)[number];
+
+/**
+ * Merge a resolved flow config over the consumer's props — flow wins on every
+ * key it DEFINES; an absent key leaves the prop alone (which is how a flow that
+ * only sets, say, `livenessMode` doesn't wipe a prop-supplied `userId`).
+ *
+ * `appearance` merges shallowly with flow keys winning per-field, so a flow
+ * that only sets `primaryColor` doesn't wipe a prop-supplied `logo`.
+ *
+ * Pure and side-effect free.
+ */
+export function mergeWorkflowConfig<P extends Record<string, unknown>>(
+  flowConfig: Record<string, unknown>,
+  props: P,
+): P {
+  const merged: Record<string, unknown> = { ...props };
+
+  for (const key of WORKFLOW_KEYS) {
+    const value = flowConfig[key];
+    if (value === undefined) continue;
+    if (key === 'appearance') {
+      const propAppearance = props['appearance'];
+      merged[key] = {
+        ...(typeof propAppearance === 'object' && propAppearance !== null ? propAppearance : {}),
+        ...(value as Record<string, unknown>),
+      };
+    } else {
+      merged[key] = value;
+    }
+  }
+
+  // Business (KYB) workflows carry no top-level country — fall back to the
+  // registry country so downstream code that expects one never sees undefined.
+  // The business submission reads business.country anyway.
+  if (merged['country'] === undefined && flowConfig['subjectType'] === 'business') {
+    const business = flowConfig['business'] as { country?: string } | undefined;
+    if (business?.country) merged['country'] = business.country;
+  }
+
+  return merged as P;
+}
+
+/**
+ * The template keys a mapped APPLICANT workflow (business.applicant.workflowId)
+ * overlays onto a KYB mount — the individual capture-leg surface only. KYB
+ * publish REJECTS these keys on the business config itself, so the overlay is
+ * collision-free by construction. Contact OTPs, the questionnaire, branding and
+ * device policy stay the KYB workflow's own. Mirrors the web SDK.
+ */
+const APPLICANT_LEG_KEYS = [
+  'country',
+  'countries',
+  'idTypes',
+  'enableSelfie',
+  'enableDocumentCapture',
+  'allowDocumentUpload',
+  'enableLiveness',
+  'livenessMode',
+  'flashSequenceLength',
+  'nfc',
+] as const;
+
+/**
+ * Overlay a resolved applicant workflow's capture template over an (already
+ * workflow-merged) KYB config, recording its id as `applicantWorkflowId` so
+ * the applicant's own submission is stamped with it. No-op when nothing was
+ * mapped/resolved.
+ */
+export function overlayApplicantWorkflow<P extends Record<string, unknown>>(
+  applicantWorkflow: { id: string; config: Record<string, unknown> } | null | undefined,
+  merged: P,
+): P {
+  if (!applicantWorkflow) return merged;
+  const out: Record<string, unknown> = { ...merged, applicantWorkflowId: applicantWorkflow.id };
+  for (const key of APPLICANT_LEG_KEYS) {
+    const value = applicantWorkflow.config[key];
+    if (value !== undefined) out[key] = value;
+  }
+  return out as P;
+}