@myazahq/kyc-sdk-react-native 2.4.0 → 2.6.0

package/src/components/icon-map.ts

@@ -0,0 +1,176 @@
+import {
+  Info, BadgeCheck, BookUser, Building2, Stamp, Calendar, Camera, CameraOff, ChevronDown,
+  ChevronLeft, ChevronRight, Car, Check, CircleAlert, Contact, CreditCard, Fingerprint,
+  FileText, FlaskConical, IdCard, Image as ImageIcon, Landmark, Lightbulb, LocateFixed, MapPin,
+  MapPinHouse, MapPinCheck, MapPinned, Radar, BellRing, SlidersHorizontal, Minus, Globe, House,
+  Mail, Maximize2, Lock, MessageCircle, MessageSquare, Moon, MoveLeft, Nfc, Filter, Pencil,
+  PencilLine, Smartphone, RefreshCw, RefreshCcw, ScanFace, ScanLine, Search, Zap, ZapOff,
+  CircleDashed, CircleCheck, CircleHelp, CircleX, ShieldCheck, Sun, Timer, Upload, Plus,
+  UserRound, UserRoundPlus, Link2, Copy, Share2, UsersRound, VideoOff, Vote, X,
+  type LucideIcon
+} from 'lucide-react-native';
+
+// Centralised icon set — the SAME Lucide icons the Flutter SDK uses
+// (`lucide_icons_flutter`) and the web SDK uses (`lucide-react`), so the
+// glyphs are pixel-identical across all three platforms. The component that
+// draws them is Icon.tsx (200-line split).
+
+export type IconName =
+  // chrome
+  | 'close'
+  | 'back'
+  | 'moon'
+  | 'sun'
+  | 'check'
+  | 'lock'
+  | 'alert'
+  | 'flask'
+  | 'refresh'
+  | 'refresh-ccw'
+  | 'maximize'
+  | 'calendar'
+  | 'image'
+  | 'chevron-left'
+  | 'chevron-right'
+  | 'chevron-down'
+  // consent hero + process steps
+  | 'shield'
+  | 'badge-check'
+  | 'circle-dashed'
+  | 'circle-check'
+  | 'circle-help'
+  | 'circle-x'
+  | 'building-2'
+  | 'stamp'
+  | 'user'
+  | 'user-plus'
+  | 'plus'
+  | 'info'
+  | 'users'
+  | 'scan-line'
+  | 'scan-face'
+  | 'nfc'
+  | 'filter'
+  | 'pencil'
+  | 'pencil-line'
+  | 'search'
+  | 'zap'
+  | 'link'
+  | 'copy'
+  | 'share'
+  | 'zap-off'
+  | 'timer'
+  // id-type glyphs
+  | 'fingerprint'
+  | 'credit-card'
+  | 'globe'
+  | 'car'
+  | 'vote'
+  | 'file-text'
+  | 'house'
+  | 'landmark'
+  | 'id-card'
+  | 'contact'
+  | 'passport'
+  | 'camera'
+  | 'camera-off'
+  | 'video-off'
+  | 'upload'
+  | 'x'
+  // address collection (map picker + the presence milestone track)
+  | 'map-pin'
+  | 'map-pin-house'
+  | 'map-pin-check'
+  | 'map-pinned'
+  | 'radar'
+  | 'bell-ring'
+  | 'sliders'
+  | 'locate'
+  | 'minus'
+  | 'lightbulb'
+  // contact verification (OTP channels + step footer)
+  | 'mail'
+  | 'smartphone'
+  | 'message-square'
+  | 'message-circle';
+
+// Maps each name to its Lucide component. Names mirror the Flutter SDK exactly:
+//   shieldCheck · badgeCheck · userRound · scanLine · scanFace · fingerprint ·
+//   creditCard · globe · car · vote · fileText  (+ chrome: X / ArrowLeft /
+//   Moon / Sun / Check / Lock / CircleAlert / RefreshCw / Camera).
+export const ICONS: Record<IconName, LucideIcon> = {
+  close: X,
+  back: MoveLeft, // longer-shaft left arrow, matching Flutter's keyboard_backspace
+  moon: Moon,
+  sun: Sun,
+  check: Check,
+  lock: Lock,
+  alert: CircleAlert,
+  // The environment banner's mark, shared with the web SDK (same lucide glyph)
+  // and mirrored by Flutter's Icons.science_outlined.
+  flask: FlaskConical,
+  refresh: RefreshCw,
+  'refresh-ccw': RefreshCcw,
+  maximize: Maximize2,
+  calendar: Calendar,
+  image: ImageIcon,
+  'chevron-left': ChevronLeft,
+  'chevron-right': ChevronRight,
+  'chevron-down': ChevronDown,
+  shield: ShieldCheck,
+  'badge-check': BadgeCheck,
+  'circle-dashed': CircleDashed,
+  'circle-check': CircleCheck,
+  'circle-help': CircleHelp,
+  'circle-x': CircleX,
+  'building-2': Building2,
+  stamp: Stamp,
+  user: UserRound,
+  info: Info,
+  'user-plus': UserRoundPlus,
+  plus: Plus,
+  link: Link2,
+  copy: Copy,
+  share: Share2,
+  users: UsersRound,
+  'scan-line': ScanLine,
+  'scan-face': ScanFace,
+  nfc: Nfc,
+  filter: Filter,
+  pencil: Pencil,
+  'pencil-line': PencilLine,
+  search: Search,
+  zap: Zap,
+  'zap-off': ZapOff,
+  timer: Timer,
+  fingerprint: Fingerprint,
+  'credit-card': CreditCard,
+  globe: Globe,
+  car: Car,
+  vote: Vote,
+  'file-text': FileText,
+  house: House,
+  landmark: Landmark,
+  'map-pin': MapPin,
+  'map-pin-house': MapPinHouse,
+  'map-pin-check': MapPinCheck,
+  'map-pinned': MapPinned,
+  radar: Radar,
+  'bell-ring': BellRing,
+  sliders: SlidersHorizontal,
+  locate: LocateFixed,
+  minus: Minus,
+  'id-card': IdCard,
+  contact: Contact,
+  passport: BookUser,
+  camera: Camera,
+  'camera-off': CameraOff,
+  'video-off': VideoOff,
+  upload: Upload,
+  x: X,
+  lightbulb: Lightbulb,
+  mail: Mail,
+  smartphone: Smartphone,
+  'message-square': MessageSquare,
+  'message-circle': MessageCircle,
+};

package/src/components/stepHeaderMeta.tsx

@@ -1,10 +1,11 @@
 import { ID_TYPES } from '../config/idTypes';
-import { poaMaxAgeDays } from '../config/proofOfAddress';
+import { poaDocumentTypes, poaMaxAgeDays, poaNamePolicy } from '../config/proofOfAddress';
 import { documentCaptureMeta } from '../screens/DocumentCaptureStep';
 import { questionnaireMeta } from '../screens/QuestionnaireStep';
 import { contactCodeLength, contactMeta, type ContactChallenge } from '../config/contact';
 
 import { proofOfAddressMeta } from '../screens/ProofOfAddressStep';
+import { addressStepMeta } from '../screens/address';
 import { countrySelectMeta } from '../screens/CountrySelectStep';
 import { businessDetailsMeta } from '../screens/BusinessDetailsStep';
 import { businessKeyPeopleMeta } from '../screens/BusinessKeyPeopleStep';
@@ -34,20 +35,45 @@ export interface StepHeaderContext {
   documentCapturePhase: DocumentCapturePhase;
   /** Outstanding contact code — lets the header describe the OTP in flight. */
   contactChallenge: ContactChallenge | null;
+  /**
+   * The presence primer is on screen in place of the address step's body.
+   *
+   * It carries its own title, so the step's would sit above it saying something
+   * else about a screen that is not showing. Blanking the header leaves just
+   * the back arrow, the way the consent step does.
+   */
+  addressIntroPending?: boolean;
+  /** The entrance step is framing street imagery rather than asking for a photo. */
+  addressEntranceFraming?: boolean;
+  /** The proof-of-address kind the applicant has picked, so the header can ask
+   *  for what the workflow's name rule wants on THAT document. */
+  poaDocumentType?: string | null;
 }
 
 export function stepHeaderMeta(
   currentStep: KYCStep,
-  { config, country, selectedIdType, documentCapturePhase, contactChallenge }: StepHeaderContext,
+  {
+    config,
+    country,
+    selectedIdType,
+    documentCapturePhase,
+    contactChallenge,
+    addressIntroPending,
+    addressEntranceFraming,
+    poaDocumentType,
+  }: StepHeaderContext,
 ): { title: string; description: string | null } {
   const label = labelFor(country, selectedIdType);
+  if (addressIntroPending) return { title: '', description: null };
     switch (currentStep) {
       case 'consent':
         return { title: '', description: null as string | null };
       case 'id-type':
         return { title: 'Select ID Type', description: "Choose the type of identification document you'd like to use." };
       case 'id-input':
-        return { title: 'Enter Your Details', description: `Provide your ${label} for verification.` };
+        // The number is all this step asks for. The name comes from the
+        // integrator (mount props / the session), never the applicant.
+        return { title: `Enter your ${label}`, description: 'We’ll check this against the official record.' };
       case 'document-capture':
         // Phase-aware title/description live in the header (synced from the
         // capture screen via `documentCapturePhase`) — mirrors Flutter.
@@ -66,8 +92,22 @@ export function stepHeaderMeta(
           codeLength: contactCodeLength(config.phoneVerification),
           challenge: contactChallenge,
         });
-      case 'proof-of-address':
-        return proofOfAddressMeta(poaMaxAgeDays(config.proofOfAddress));
+      case 'proof-of-address': {
+        // Word the ask by the rule the server will judge THIS document under:
+        // the picked kind, else the first the country offers (what the screen
+        // preselects). Under `off` the header stops asking for the name.
+        const poa = config.proofOfAddress;
+        const kind = poaDocumentType ?? poaDocumentTypes(poa, country)[0];
+        return proofOfAddressMeta(
+          poaMaxAgeDays(poa),
+          poaNamePolicy(poa, country, kind as Parameters<typeof poaNamePolicy>[2]) !== 'off',
+        );
+      }
+      case 'address-search':
+      case 'address-collection':
+      case 'address-entrance':
+      case 'address-review':
+        return addressStepMeta(currentStep, config.subjectType === 'business', { framing: addressEntranceFraming });
       case 'country-select':
         return countrySelectMeta;
       case 'business-details':

package/src/config/addressCollection.ts

@@ -0,0 +1,125 @@
+// ---------------------------------------------------------------------------
+// Address Intelligence — the pure half.
+//
+// A smart address is a map pin (+ optional door photo and directions) the
+// server corroborates against the evidence it already holds. 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 beyond what the config
+// explicitly requires (`requirePin`, required photo/directions).
+//
+// Mirrors the web SDK's address handling — keep the two in lockstep.
+// ---------------------------------------------------------------------------
+
+import { addressFlowOptions, type AddressFlowOptions } from '../lib/address-flow';
+import { requiredPrefillSubmission } from '../lib/address-field-modes';
+import { isBusinessFlow } from './business';
+import type { SubjectType, WorkflowBusinessConfig } from '../types/business';
+import type { AddressCollectionConfig } from '../types/workflow';
+import type { AddressState } from '../store/state';
+import type { VerifyRequest } from '../services/api-verify-types';
+
+export type AddressFieldMode = 'off' | 'optional' | 'required';
+
+/** Whether the step is part of the flow. */
+export function hasAddressCollectionStep(
+  address: AddressCollectionConfig | undefined | null,
+): boolean {
+  return address?.enabled === true;
+}
+
+/**
+ * Which address screens this flow has — ONE call, read by the step-order
+ * builder AND by the address steps themselves, so the two can never disagree
+ * about which screens exist.
+ *
+ * KYB collapses to the single premises step: the pin plus its directions ARE
+ * the capture, and the business flow already has its own section rhythm.
+ */
+export function addressFlowFor(
+  config: {
+    subjectType?: SubjectType;
+    business?: WorkflowBusinessConfig;
+    addressCollection?: AddressCollectionConfig;
+  },
+  /** The server offers a forward-search backend. */
+  serverSearch: boolean,
+  /** SANDBOX keys stub the vendor surfaces (addressVendorsStubbed). */
+  stubbed = false,
+  /** A maps frame URL this install can render (a WebView is installed): the
+   *  framed street-view page carries the panorama for it. */
+  hasStreetViewFrame = false,
+): AddressFlowOptions {
+  if (isBusinessFlow(config)) {
+    return { searchAvailable: false, photoMode: 'off', streetViewOffered: false };
+  }
+  return addressFlowOptions({
+    photo: config.addressCollection?.photo,
+    streetView: config.addressCollection?.streetView,
+    serverSearch: serverSearch && !stubbed,
+    // The builder's live preview and the in-document Google key are web-only
+    // surfaces, so neither flag can ever be true here. Passing them
+    // explicitly keeps the rule a mirror.
+    previewMode: false,
+    hasGoogleKey: false,
+    hasStreetViewFrame,
+  });
+}
+
+// The old single-screen Continue gate (canContinueAddress and the two mode
+// helpers that fed it) was deleted with the four-step flow: each step now
+// gates itself, and a helper stating the old combined rule is a trap for
+// whoever wires it back up. The Flutter port removed its copies for the same
+// reason.
+
+/**
+ * The wire block. `config` is the flow's address step: a workflow-REQUIRED
+ * field the applicant left on its map prefill rides that prefill (they saw
+ * it filled and confirmed by continuing, and the server 422s a required
+ * field that never arrives). Session progress passes no config and stays
+ * raw, so a resume never confuses a prefill with a claim.
+ */
+export function addressPayload(
+  address: AddressState,
+  config?: AddressCollectionConfig | null,
+): NonNullable<VerifyRequest['address']> {
+  return {
+    lat: address.lat,
+    lng: address.lng,
+    // The line the applicant CONFIRMED: the server prefers it over its own
+    // reverse geocode, whose coverage drops whole streets in our markets.
+    ...(address.label?.trim() ? { label: address.label.trim() } : {}),
+    ...(typeof address.accuracy === 'number' ? { accuracy: address.accuracy } : {}),
+    ...(address.directions.trim() ? { directions: address.directions.trim() } : {}),
+    ...(address.propertyName.trim() ? { propertyName: address.propertyName.trim() } : {}),
+    ...(address.propertyNumber.trim() ? { propertyNumber: address.propertyNumber.trim() } : {}),
+    ...(address.street?.trim() ? { street: address.street.trim() } : {}),
+    // The rest of the edit-details form — claims, sent only when typed.
+    ...(address.unit?.trim() ? { unit: address.unit.trim() } : {}),
+    ...(address.neighbourhood?.trim() ? { neighbourhood: address.neighbourhood.trim() } : {}),
+    ...(address.city?.trim() ? { city: address.city.trim() } : {}),
+    ...(address.state?.trim() ? { state: address.state.trim() } : {}),
+    ...(address.postcode?.trim() ? { postcode: address.postcode.trim() } : {}),
+    // Required-but-untouched prefills, LAST among the typed fields: the helper
+    // never carries a typed value, so nothing above is overridden.
+    ...requiredPrefillSubmission(config, address),
+    ...(address.streetView ? { streetView: address.streetView } : {}),
+    ...(typeof address.deviceLat === 'number' && typeof address.deviceLng === 'number'
+      ? {
+          deviceLat: address.deviceLat,
+          deviceLng: address.deviceLng,
+          ...(typeof address.deviceAccuracy === 'number'
+            ? { deviceAccuracy: address.deviceAccuracy }
+            : {}),
+          ...(address.capturedAt ? { capturedAt: address.capturedAt } : {}),
+        }
+      : {}),
+  };
+}
+
+/** Accepted door-photo types — an image, never a PDF. */
+export const ADDRESS_PHOTO_MIME_TYPES = ['image/jpeg', 'image/png', 'image/webp'] as const;
+
+export function isAcceptedAddressPhotoMimeType(mimeType: string | undefined): boolean {
+  const base = (mimeType?.split(';')[0] ?? '').trim().toLowerCase();
+  return (ADDRESS_PHOTO_MIME_TYPES as readonly string[]).includes(base);
+}

package/src/config/biometricOptions.ts

@@ -0,0 +1,100 @@
+import { configScope } from '../lib/scope';
+
+// ─── The biometric scopes' flow options ─────────────────────────────────────
+//
+// Mirrors the server's lib/workflows/biometric-options.ts; keep the defaults
+// in lockstep. All three are UX policy this SDK enforces (user decision
+// 2026-09-07, React Native first). A published workflow sets them in the
+// builder's Presence Intelligence panel; a prop-configured mount passes the
+// same `biometric` block.
+//
+//   selfieReview    Show the captured selfie with Retake and Continue before
+//                   submitting. OFF by default on both biometric scopes: a
+//                   re-authentication is a few-second check, and a review
+//                   screen is a stop in the middle of it. The liveness step
+//                   hands straight over once the ring has closed.
+//   resultDelivery  WHERE the verdict lands. 'both' (the default) and 'app'
+//                   both hold the person on one loading screen from the
+//                   shutter to the verdict, polling the publishable status
+//                   endpoint until the check settles, because a
+//                   re-authentication is answered NOW or it is useless; they
+//                   differ only on the SERVER, which sends no webhook for an
+//                   'app' check. 'webhook' is the fire-and-forget model every
+//                   other flow runs. Enrolment has no verdict to deliver, so
+//                   it never waits.
+//   doneButton      Whether the final screen carries a Done button (default
+//                   ON). Off when the host app dismisses the flow itself from
+//                   `onResult` (or `onSubmit` on a webhook delivery), so the
+//                   person is never shown a button the app is about to act
+//                   for. The screen then stays until the host closes the SDK.
+
+/** One screen's words. A field absent (or blank) means the SDK's default
+ *  shows. `{firstName}` / `{lastName}` tokens fill from `userData`, exactly as
+ *  the consent and success copy do. */
+export interface BiometricCopyText {
+  title?: string;
+  description?: string;
+}
+
+/**
+ * The org's own words on the biometric screens (the builder's "Face check
+ * screens" fields; user decision 2026-09-07). `waiting` is the ONE loading
+ * screen from the shutter to the verdict, on both scopes; `verified` and
+ * `declined` are the in-flow verdict screens, so they apply to a
+ * re-authentication only (publish refuses them on enrolment, which shows no
+ * verdict). A `declined` description wins over the server's reason: the org
+ * chose to say that. Resolved for rendering by lib/biometric-copy.ts.
+ */
+export interface BiometricCopy {
+  waiting?: BiometricCopyText;
+  verified?: BiometricCopyText;
+  declined?: BiometricCopyText;
+}
+
+export interface BiometricFlowConfig {
+  selfieReview?: boolean;
+  resultDelivery?: 'app' | 'webhook' | 'both';
+  doneButton?: boolean;
+  copy?: BiometricCopy;
+}
+
+export interface BiometricFlowOptions {
+  selfieReview: boolean;
+  /** Null on enrolment: nothing is delivered, so there is nothing to wait for. */
+  resultDelivery: 'app' | 'webhook' | 'both' | null;
+  doneButton: boolean;
+}
+
+type BiometricConfigLike = { scope?: string; biometric?: BiometricFlowConfig | null };
+
+/** The effective options, or null when the flow is not a biometric scope. */
+export function biometricFlowOptions(config: BiometricConfigLike): BiometricFlowOptions | null {
+  const scope = configScope(config);
+  if (scope !== 'biometric-authentication' && scope !== 'biometric-enrollment') return null;
+  const block = config.biometric ?? {};
+  return {
+    selfieReview: block.selfieReview ?? false,
+    resultDelivery: scope === 'biometric-authentication' ? (block.resultDelivery ?? 'both') : null,
+    doneButton: block.doneButton ?? true,
+  };
+}
+
+/** Whether the liveness step shows the selfie review before handing over. A
+ *  full verification always does; only the biometric scopes can switch it off. */
+export function showsSelfieReview(config: BiometricConfigLike): boolean {
+  return biometricFlowOptions(config)?.selfieReview ?? true;
+}
+
+/** Whether the submitted step waits for the verdict in the flow ('app' and
+ *  'both') rather than leaving it to the webhook. Only a re-authentication
+ *  ever does. */
+export function waitsForResult(config: BiometricConfigLike): boolean {
+  const delivery = biometricFlowOptions(config)?.resultDelivery;
+  return delivery === 'app' || delivery === 'both';
+}
+
+/** Whether the final screen carries a Done button. Always on off the
+ *  biometric scopes; only they can hide it. */
+export function showsDoneButton(config: BiometricConfigLike): boolean {
+  return biometricFlowOptions(config)?.doneButton ?? true;
+}

package/src/config/business.ts

@@ -7,6 +7,7 @@
 // here needs to be authoritative, only honest about what to type.
 // ---------------------------------------------------------------------------
 
+import { COMPANY_INFO_FIELDS } from '../types/business';
 import type {
   CompanyInfoField,
   CompanyInfoMode,
@@ -35,6 +36,20 @@ export const BUSINESS_PRODUCTS: readonly BusinessProductDef[] = [
     inputLabel: 'Registration number',
     placeholder: 'e.g. RC0000000',
   },
+  {
+    key: 'business-address',
+    label: 'Business Address',
+    inputLabel: 'Registration number',
+    placeholder: 'e.g. 201133333323',
+    countries: ['ZA'],
+  },
+  {
+    key: 'business-filings',
+    label: 'Company Filings',
+    inputLabel: 'Registration number',
+    placeholder: 'e.g. CI-ABJ-03-2023-B17-00120',
+    countries: ['CI'],
+  },
   {
     key: 'business-tax',
     label: 'Business + Tax ID',
@@ -90,7 +105,12 @@ export function businessProductsForCountry(
 ): string[] {
   const offered = businessProductsFor(business).filter((key) => {
     const def = BUSINESS_PRODUCTS.find((p) => p.key === key);
-    return !def?.countries || def.countries.includes(country);
+    // A key this build does not know is HIDDEN, never offered everywhere: the
+    // server rejects a wrong-country pick at verify (product_unsupported), so
+    // over-offering dead-ends the applicant, while hiding degrades to the
+    // standard lookup until the SDK updates.
+    if (!def) return false;
+    return !def.countries || def.countries.includes(country);
   });
   return offered.length > 0 ? offered : [DEFAULT_BUSINESS_PRODUCT];
 }
@@ -159,12 +179,11 @@ export function companyInfoFieldModes(
 ): Record<CompanyInfoField, CompanyInfoMode> {
   const off = business?.collectCompanyInfo === false;
   const modes = business?.companyInfo ?? {};
-  return {
-    address: off ? 'off' : (modes.address ?? 'optional'),
-    email: off ? 'off' : (modes.email ?? 'optional'),
-    phone: off ? 'off' : (modes.phone ?? 'optional'),
-    website: off ? 'off' : (modes.website ?? 'optional'),
-  };
+  // Built from the field list so adding one on the server means adding it in a
+  // single place here, rather than a line that is easy to forget.
+  return Object.fromEntries(
+    COMPANY_INFO_FIELDS.map((f) => [f, off ? 'off' : (modes[f] ?? 'optional')]),
+  ) as Record<CompanyInfoField, CompanyInfoMode>;
 }
 
 /** Company-profile fields still missing that the workflow marks required. */

package/src/config/businessDetailsValidity.ts

@@ -0,0 +1,52 @@
+import { isValidContactEmail } from './contact';
+import { isValidWebsite } from './website';
+import type { CompanyInfoField, CompanyInfoMode } from '../types/business';
+import type { BusinessCheckState, BusinessState } from '../store/state';
+
+// ---------------------------------------------------------------------------
+// Per-phase validity for the business-details step (200-line rule split).
+//
+// Gated per phase: on the pick screen the detail fields do not exist yet, so
+// holding Continue until they are filled would be waiting on inputs that are
+// not on screen. Empty is fine (optional unless the workflow says otherwise);
+// a malformed value is not. Mirrors the web SDK's isFormValid exactly.
+// ---------------------------------------------------------------------------
+
+export function businessDetailsValid(input: {
+  phase: 'pick' | 'details';
+  business: BusinessState;
+  modes: Record<CompanyInfoField, CompanyInfoMode>;
+  product: string | null | undefined;
+  numberValid: boolean;
+  nameRequired: boolean;
+  showContactEmail: boolean;
+}): boolean {
+  const { business, modes } = input;
+  const pickValid =
+    !!input.product &&
+    input.numberValid &&
+    (!input.nameRequired || business.registrationName.trim() !== '');
+  if (input.phase === 'pick') return pickValid;
+
+  const showCompanyInfo = Object.values(modes).some((m) => m !== 'off');
+  const contactEmailValid =
+    business.contactEmail.trim() === '' || isValidContactEmail(business.contactEmail.trim());
+  const businessEmailValid =
+    business.email.trim() === '' || isValidContactEmail(business.email.trim());
+  const companyInfoComplete = (Object.keys(modes) as CompanyInfoField[]).every(
+    (f) => modes[f] !== 'required' || business[f].trim() !== '',
+  );
+  return (
+    pickValid &&
+    (!input.showContactEmail || contactEmailValid) &&
+    (!showCompanyInfo ||
+      (businessEmailValid && isValidWebsite(business.website) && companyInfoComplete))
+  );
+}
+
+/** Whether the check panel has anything to say. Found/skipped/idle stay
+ *  silent, and so does 'checking' — the loader lives INSIDE the Continue
+ *  button, since that is the thing the person just pressed. */
+export function checkPanelVisible(status: BusinessCheckState['status']): boolean {
+  return status === 'not_found' || status === 'limit_reached' || status === 'unavailable';
+}

package/src/config/businessPrefill.ts

@@ -0,0 +1,72 @@
+import type { BusinessCompanyRecord } from '../services/api';
+import type { BusinessState } from '../store/state';
+
+// ---------------------------------------------------------------------------
+// Copy what the register returned into the form, without overwriting anything.
+//
+// Only empty fields are filled: an applicant who typed something before the
+// lookup meant it, and the register is a starting point here rather than the
+// last word. Every value stays editable either way. Returns the patch AND the
+// keys it filled, so a company change can clear exactly those and leave the
+// applicant's own answers alone. Mirrors the web SDK's prefillFromRegister.
+// ---------------------------------------------------------------------------
+
+export function registerPrefillPatch(
+  company: BusinessCompanyRecord | null,
+  current: BusinessState,
+): { patch: Partial<BusinessState>; prefilled: (keyof BusinessState)[] } {
+  const patch: Partial<BusinessState> = {};
+  if (!company) return { patch, prefilled: [] };
+
+  // Field by field, from the register's answer to the form's question. The
+  // register does not answer all of these for every company, so each is
+  // filled only when it actually came back.
+  const fill = (
+    key:
+      | 'registrationName' | 'address' | 'companyType' | 'email' | 'phone'
+      | 'taxId' | 'vatNumber' | 'dateOfIncorporation' | 'natureOfBusiness',
+    value: string | null | undefined,
+  ): void => {
+    if (value && !current[key].trim()) patch[key] = value;
+  };
+  fill('registrationName', company.name);
+  // The register splits the address across lines; the form has one box, so
+  // they are joined rather than dropping the parts that did not fit.
+  fill(
+    'address',
+    [company.address, company.city, company.state].filter(Boolean).join(', ') || null,
+  );
+  fill('companyType', company.typeOfEntity);
+  fill('email', company.email);
+  fill('phone', company.phone);
+  fill('taxId', company.taxId);
+  fill('vatNumber', company.vatNumber);
+  fill('natureOfBusiness', company.natureOfBusiness);
+  // The register gives an incorporation DATE; the field wants YYYY-MM-DD, and
+  // anything it cannot be read as is left blank rather than guessed at.
+  fill('dateOfIncorporation', isoDateOnly(company.registrationDate));
+
+  return { patch, prefilled: Object.keys(patch) as (keyof BusinessState)[] };
+}
+
+/**
+ * The date part of an ISO timestamp, or null.
+ *
+ * Deliberately NOT `new Date(value)`. That parser is lenient in exactly the
+ * wrong direction: it reads "12/03/2018" as 2 December (US order, when a
+ * register returning DD/MM means 12 March), "sometime in 2018" as 2017-12-31,
+ * and "March 2018" as the 28th. Each of those is a confidently wrong date
+ * written into a compliance form, which is worse than an empty field somebody
+ * fills in themselves. So only an unambiguous ISO date is accepted, and the
+ * calendar is checked afterwards so 2018-02-31 does not roll into March.
+ */
+export function isoDateOnly(value: string | null | undefined): string | null {
+  if (!value) return null;
+  const match = /^(\d{4})-(\d{2})-(\d{2})(?:[T\s]|$)/.exec(value.trim());
+  if (!match) return null;
+  const [, y, m, d] = match;
+  const parsed = new Date(`${y}-${m}-${d}T00:00:00Z`);
+  if (Number.isNaN(parsed.getTime())) return null;
+  // A real date, not one that rolled over into the next month.
+  return parsed.toISOString().slice(0, 10) === `${y}-${m}-${d}` ? `${y}-${m}-${d}` : null;
+}