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

package/src/components/StepView.tsx

@@ -12,6 +12,12 @@ import { SubmittedStep } from '../screens/SubmittedStep';
 import { QuestionnaireStep } from '../screens/QuestionnaireStep';
 import { ContactVerificationStep } from '../screens/ContactVerificationStep';
 import { ProofOfAddressStep } from '../screens/ProofOfAddressStep';
+import {
+  AddressEntranceStep,
+  AddressPinStep,
+  AddressReviewStep,
+  AddressSearchStep,
+} from '../screens/address';
 import { CountrySelectStep } from '../screens/CountrySelectStep';
 import { BusinessDetailsStep } from '../screens/BusinessDetailsStep';
 import { BusinessKeyPeopleStep } from '../screens/BusinessKeyPeopleStep';
@@ -78,6 +84,17 @@ function stepScreen(step: KYCStep, onClose: () => void): React.ReactElement {
       return <ContactVerificationStep key="contact-phone" channel="phone" />;
     case 'proof-of-address':
       return <ProofOfAddressStep />;
+    // The address flow, in order: find it, confirm it, show it, commit it.
+    // 'address-collection' is the PIN step and keeps that wire name so older
+    // session progress restores cleanly.
+    case 'address-search':
+      return <AddressSearchStep />;
+    case 'address-collection':
+      return <AddressPinStep />;
+    case 'address-entrance':
+      return <AddressEntranceStep />;
+    case 'address-review':
+      return <AddressReviewStep />;
     case 'country-select':
       return <CountrySelectStep />;
     case 'business-details':

package/src/components/StickyActions.tsx

@@ -0,0 +1,56 @@
+import React from 'react';
+import { ScrollView, StyleSheet, View } from 'react-native';
+
+import { spacing } from '../config/theme';
+import { useTheme } from './runtime';
+
+/**
+ * A step's primary actions, held at the bottom edge of a viewport-filling
+ * body. Mirrors the web SDK's StickyActions.
+ *
+ * A step that carries a map or a street panorama fills a phone with a surface
+ * that OWNS every touch: dragging it moves the map, never the page, so on a
+ * small screen the Continue button beneath it could only be reached by finding
+ * a strip of margin to scroll on. Holding the actions under a bounded scroll
+ * view means the applicant never has to get past the map to move on, and
+ * everything else still scrolls under them.
+ *
+ * Needs a BOUNDED parent: the step must be listed in KycFlow's fillsViewport
+ * set, where the sheet hands it a flex:1 box padded `spacing.md`. The footer's
+ * negative margins cancel that padding so the bar meets the sheet's edge, and
+ * the same padding is restored inside so the buttons keep their gutter.
+ */
+export function StickyActions({
+  children,
+  actions,
+}: {
+  children: React.ReactNode;
+  actions: React.ReactNode;
+}): React.ReactElement {
+  const { colors } = useTheme();
+  return (
+    <View style={{ flex: 1 }}>
+      <ScrollView
+        style={{ flex: 1 }}
+        contentContainerStyle={{ paddingBottom: spacing.sm }}
+        keyboardShouldPersistTaps="handled"
+      >
+        {children}
+      </ScrollView>
+      <View
+        style={{
+          marginHorizontal: -spacing.md,
+          marginBottom: -spacing.md,
+          paddingHorizontal: spacing.md,
+          paddingTop: spacing.sm,
+          paddingBottom: spacing.md,
+          backgroundColor: colors.background,
+          borderTopWidth: StyleSheet.hairlineWidth,
+          borderTopColor: colors.border,
+        }}
+      >
+        {actions}
+      </View>
+    </View>
+  );
+}

package/src/components/dialCodeRows.ts

@@ -0,0 +1,64 @@
+import { groupCountriesByRegion, pinGeoRow } from '../config/regions';
+import type { DialCodeOption } from './DialCodePicker';
+
+// ---------------------------------------------------------------------------
+// What the country sheet lists, as data. Extracted from DialCodePicker
+// (200-line rule) so the FlatList only renders: the search, the pinned geo
+// row and the optional REGION grouping all decide here, and a unit test reads
+// the result without mounting a sheet. Grouping is what the address-scope
+// country control asks for (user decision 2026-09-06): its sheet reads like
+// the web's region menu and the country-select step — a continent header,
+// then its countries A–Z — rather than one 240-row alphabet. Mirrors
+// Flutter's dial_code_rows.dart.
+// ---------------------------------------------------------------------------
+
+export type DialCodeItem =
+  | { kind: 'row'; option: DialCodeOption }
+  | { kind: 'header'; region: string };
+
+/**
+ * Match the name, the ISO code, or the dial code with or without its '+',
+ * because people search for "+234", "234" and "Nigeria" in equal measure.
+ */
+export function filterDialCodeOptions(options: DialCodeOption[], query: string): DialCodeOption[] {
+  const q = query.trim().toLowerCase();
+  if (!q) return options;
+  const bare = q.replace(/^\+/, '');
+  return options.filter(
+    (o) =>
+      o.name.toLowerCase().includes(q) ||
+      o.code.toLowerCase() === q ||
+      (o.dialCode != null && o.dialCode.replace(/^\+/, '').startsWith(bare)),
+  );
+}
+
+/**
+ * The sheet's items over the ALREADY-FILTERED options: where they appear to be
+ * first (lifted out of the alphabet, still subject to the search), then the
+ * rest — flat in the given order, or under region headers when `grouped`.
+ */
+export function buildDialCodeItems(
+  visible: DialCodeOption[],
+  geoCountry: string | null | undefined,
+  grouped: boolean,
+): { geo: DialCodeOption | null; items: DialCodeItem[] } {
+  const { pinned: geo, rest } = pinGeoRow(visible, geoCountry, (o) => o.code);
+  const items: DialCodeItem[] = geo ? [{ kind: 'row', option: geo }] : [];
+  if (!grouped) {
+    for (const option of rest) items.push({ kind: 'row', option });
+    return { geo, items };
+  }
+  const byCode = new Map(rest.map((o) => [o.code.toUpperCase(), o]));
+  for (const group of groupCountriesByRegion(rest.map((o) => o.code))) {
+    items.push({ kind: 'header', region: group.region });
+    for (const entry of group.countries) {
+      const option = byCode.get(entry.code);
+      if (option) items.push({ kind: 'row', option });
+    }
+  }
+  return { geo, items };
+}
+
+export function dialCodeItemKey(item: DialCodeItem): string {
+  return item.kind === 'header' ? `region:${item.region}` : item.option.code;
+}

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,13 +35,36 @@ 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 };
@@ -68,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

@@ -36,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',
@@ -91,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];
 }