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

package/src/store/state.ts

@@ -0,0 +1,253 @@
+import type { FlashHole } from '../components/flashHoleGeometry';
+// ---------------------------------------------------------------------------
+// The flow's state shapes.
+//
+// Split from kycStore.ts (200-line rule). These are pure type declarations plus
+// their empty values — no store, no actions — so any module can describe the
+// state without importing the store and its whole dependency graph.
+// ---------------------------------------------------------------------------
+
+import type { StoreApi } from 'zustand/vanilla';
+
+import type { KYCApi, KeyPersonInvite } from '../services/api';
+import type { IdType, KYCStep, ResolvedKYCConfig } from '../types/config';
+import type { PoaDocumentType } from '../types/workflow';
+import type { ApplicantRole } from '../types/business';
+import type { QuestionnaireAnswers } from '../config/questionnaire';
+import type { ContactChallenge } from '../config/contact';
+import type { QuestionnaireAnswerValue } from '../types/workflow';
+import type { KeyPersonEntry } from '../config/keyPeople';
+import type { ServerConfigState } from './serverConfig';
+import type { CaptureIntegrity } from '../liveness/integritySignals';
+import type { MrzScan } from '../mrz/parse';
+import type { EmrtdReadResult } from '../emrtd';
+
+export interface KYCMediaIds {
+  /** Proof-of-address document (image or PDF). */
+  proofOfAddress?: string;
+  documentFront?: string;
+  documentBack?: string;
+  selfie?: string;
+  documentFrontVideo?: string;
+  documentBackVideo?: string;
+  livenessVideo?: string;
+}
+
+export interface KYCSubmissionResult {
+  verificationId: string;
+  status: 'pending';
+}
+
+export type DocumentScanPhase = 'front' | 'back' | 'complete';
+
+/** What the business-details step (and the KYB application steps) collect. */
+export interface BusinessState {
+  /** Picked registry country — null until chosen on a multi-registry flow. */
+  country: string | null;
+  /** Picked product key — null until chosen / defaulted. */
+  product: string | null;
+  registrationNumber: string;
+  registrationName: string;
+  /** Where key-people invite links are emailed. */
+  contactEmail: string;
+  address: string;
+  email: string;
+  phone: string;
+  website: string;
+}
+
+/** One uploaded supporting document. */
+export interface BusinessDocumentUpload {
+  type: string;
+  mediaId: string;
+  fileName: string;
+  /**
+   * Local URI of the picked image, for the slot thumbnail. Kept on the RECORD
+   * (not screen state) so the preview survives leaving and re-entering the
+   * step. Never submitted.
+   */
+  previewUri?: string;
+  isPdf?: boolean;
+}
+
+/** The KYB application beyond the registry details. */
+export interface BusinessApplicationState {
+  keyPeople: KeyPersonEntry[];
+  documents: BusinessDocumentUpload[];
+  applicantRole: ApplicantRole | null;
+  applicantName: string;
+  /**
+   * The applicant picked THEMSELVES from the entered key people (index into
+   * `keyPeople`). Null = they're someone else / nothing picked. The flagged
+   * entry is merged server-side with the applicant row — one person, one KYC,
+   * one screening, no duplicate invite.
+   */
+  applicantKeyPersonIndex: number | null;
+}
+
+export const EMPTY_BUSINESS_APPLICATION: BusinessApplicationState = {
+  keyPeople: [],
+  documents: [],
+  applicantRole: null,
+  applicantName: '',
+  applicantKeyPersonIndex: null,
+};
+
+export const EMPTY_BUSINESS: BusinessState = {
+  country: null,
+  product: null,
+  registrationNumber: '',
+  registrationName: '',
+  contactEmail: '',
+  address: '',
+  email: '',
+  phone: '',
+  website: '',
+};
+
+export interface ContactState {
+  emailAddress?: string;
+  phoneNumber?: string;
+  /** Single-use proof from a passed email check. */
+  emailToken?: string;
+  /** Single-use proof from a passed phone check. */
+  phoneToken?: string;
+}
+
+/** Document-capture sub-phase — drives the sheet header title/description. */
+export type DocumentCapturePhase = 'front' | 'front-preview' | 'back' | 'review';
+
+/** The mediaIds keys settable via `setMediaId`. */
+export type MediaIdKey = keyof KYCMediaIds;
+
+export interface KycState {
+  config: ResolvedKYCConfig;
+  api: KYCApi;
+
+  currentStep: KYCStep;
+  /**
+   * The country picked on the multi-region country-select step. Null on a
+   * single-country flow, where `config.country` is the answer.
+   */
+  selectedCountry: string | null;
+  selectedIdType: IdType | null;
+  idNumber: string | null;
+  mediaIds: KYCMediaIds;
+  submissionResult: KYCSubmissionResult | null;
+  serverConfig: ServerConfigState;
+  documentScanPhase: DocumentScanPhase;
+  /** Sub-phase of the document-capture step — synced by the screen so the header
+   *  title/description can be phase-aware (mirrors Flutter's docReviewPhase). */
+  documentCapturePhase: DocumentCapturePhase;
+  /**
+   * True while a full-bleed camera owns the screen.
+   *
+   * The sheet's header, padding and scroll view are what force a small
+   * viewfinder on a short phone — and a camera you have to SCROLL to is a
+   * broken camera. When this is set the shell steps out of the way entirely.
+   */
+  immersiveCapture: boolean;
+  /**
+   * What the flash overlay should paint, hoisted OUT of the liveness step.
+   *
+   * It has to be drawn at the sheet root, not inside the step: the step sits in
+   * a padded, scrolling body, so an overlay there lights only a fraction of the
+   * display — and the screen IS the light source for this check.
+   *
+   * It cannot be drawn in a modal of its own either. iOS scales a presenting
+   * sheet back when a modal appears over it, and RN's `measureInWindow` reports
+   * Yoga LAYOUT coordinates, which never reflect that UIKit transform. The
+   * cutout would be measured at full size while the preview renders at ~0.77 of
+   * it — off by the transform, with no reading that can ever converge. Painting
+   * in the same tree means the hole and the preview scale together, so the two
+   * agree by construction rather than by measurement.
+   */
+  flashPaint: { color: string | null; hole: FlashHole | null } | null;
+  /**
+   * Which way the user last moved through the flow.
+   *
+   * A step that SKIPS ITSELF (no NFC radio, a disabled feature) must skip the
+   * way the user was already going. Always advancing forward makes such a step
+   * a one-way valve: pressing Back onto it bounces you straight forward again,
+   * so the steps before it become unreachable.
+   */
+  navDirection: 'forward' | 'back';
+  /** Answers to the workflow's compliance questionnaire, keyed by field key. */
+  questionnaireAnswers: QuestionnaireAnswers;
+  /** Business (KYB) registry details. Unused on an individual flow. */
+  business: BusinessState;
+  /** The rest of the KYB application: people, documents, applicant role. */
+  businessApplication: BusinessApplicationState;
+  /**
+   * Set by a KYB submission that requires applicant verification — the
+   * KeyPerson id the applicant's own individual check links back to.
+   */
+  applicantKeyPersonId: string | null;
+  /** Per-person hosted-KYC links returned by a KYB submission. */
+  keyPeopleInvites: KeyPersonInvite[];
+  /**
+   * What the client observed while capturing — the flash claim in particular.
+   * Sent as CONTEXT, never as a verdict: the server re-analyses the recorded
+   * video against the sequence claimed here.
+   */
+  captureIntegrity: CaptureIntegrity | null;
+  /**
+   * The MRZ read off the document photo. It is the KEY that unlocks the chip —
+   * possession of the document is the access control — and it is also what the
+   * server checks the chip's own DG1 against.
+   */
+  mrzScan: MrzScan | null;
+  /** What the chip returned. Absent when it was skipped or unreadable. */
+  chipData: EmrtdReadResult | null;
+  /** Which kind of document was uploaded as proof of address. */
+  poaDocumentType: PoaDocumentType | null;
+  /** Its file name, so the uploaded state can name what it has. */
+  poaFileName: string | null;
+  /**
+   * Contact-verification results. The proofs are single-use and ride the
+   * /verify submission; the addresses are kept so returning to the step (or a
+   * retry) shows what the user already typed rather than a blank field.
+   */
+  contact: ContactState;
+  /** Outstanding contact code, for the header. Null while entering a destination. */
+  contactChallenge: ContactChallenge | null;
+  isLoading: boolean;
+  error: string | null;
+
+  // Actions
+  loadServerConfig: () => Promise<void>;
+  setCountry: (country: string) => void;
+  setIdType: (idType: IdType) => void;
+  setIdNumber: (idNumber: string) => void;
+  setMediaId: (key: MediaIdKey, mediaId: string) => void;
+  setDocumentMediaId: (mediaId: string, side: 'front' | 'back') => void;
+  setQuestionnaireAnswer: (key: string, value: QuestionnaireAnswerValue | undefined) => void;
+  setContactVerified: (channel: 'email' | 'phone', destination: string, token: string) => void;
+  setContactDestination: (channel: 'email' | 'phone', destination: string) => void;
+  setBusinessField: <K extends keyof BusinessState>(key: K, value: BusinessState[K]) => void;
+  setKeyPeople: (rows: KeyPersonEntry[]) => void;
+  setBusinessDocument: (doc: BusinessDocumentUpload) => void;
+  removeBusinessDocument: (type: string) => void;
+  setApplicant: (role: ApplicantRole, name: string, keyPersonIndex?: number | null) => void;
+  setCaptureIntegrity: (integrity: CaptureIntegrity) => void;
+  setMrzScan: (scan: MrzScan) => void;
+  setChipData: (data: EmrtdReadResult) => void;
+  setProofOfAddress: (mediaId: string, docType: PoaDocumentType, fileName: string) => void;
+  clearProofOfAddress: () => void;
+  setDocumentCapturePhase: (phase: DocumentCapturePhase) => void;
+  setContactChallenge: (challenge: ContactChallenge | null) => void;
+  setImmersiveCapture: (immersive: boolean) => void;
+  setFlashPaint: (paint: { color: string | null; hole: FlashHole | null } | null) => void;
+  nextStep: () => void;
+  previousStep: () => void;
+  goToStep: (step: KYCStep) => void;
+  submitAsync: (onRetry?: (attempt: number, total: number) => void) => Promise<KYCSubmissionResult>;
+  reset: () => void;
+}
+
+
+// ---------------------------------------------------------------------------
+// Flow navigation — single source of truth for the 5-step sequence.
+// ---------------------------------------------------------------------------
+
+export type KycStore = StoreApi<KycState>;

package/src/store/submit.ts

@@ -0,0 +1,101 @@
+// ---------------------------------------------------------------------------
+// Building the /verify request.
+//
+// Split from kycStore.ts (200-line rule). Pure: state in, request out — so what
+// the SDK actually sends can be reasoned about (and tested) without a store, a
+// network, or a running flow.
+//
+// Two rules shape it. A KYB submission carries registry details instead of an
+// ID, so the country source, the `idType` slot and the media all differ. And
+// every optional block is sent ONLY when the flow collected it: an inactive
+// questionnaire must not put an empty object on the verification record, and an
+// unconfigured contact proof must not claim a check that never ran.
+// ---------------------------------------------------------------------------
+
+import { collectDeviceMetadata } from '../services/deviceMetadata';
+import { generateRequestId } from '../utils/uuid';
+import { hasActiveQuestionnaire, questionnairePayload } from '../config/questionnaire';
+import { isBusinessFlow } from '../config/business';
+import { businessSubmission, effectiveCountry } from './derive';
+import type { ClientFingerprint } from '../services/fingerprint';
+import type { VerifyRequest } from '../services/api';
+import type { KycState } from './state';
+
+export function buildVerifyRequest(
+  state: KycState,
+  fingerprint: ClientFingerprint | undefined,
+): VerifyRequest {
+  // A KYB flow submits registry details instead of an ID: a different country
+  // source (the picked registry), the product key riding on `idType`, and no
+  // capture media at all.
+  const business = isBusinessFlow(state.config) ? businessSubmission(state) : null;
+
+  return {
+  country: business ? business.country : effectiveCountry(state),
+  idType: business ? business.product : (state.selectedIdType ?? ''),
+  idNumber: business ? undefined : (state.idNumber ?? undefined),
+  ...(business ? { business: business.payload } : {}),
+  // The org's user reference (becomes Entity.externalUserId at the KYC seam).
+  ...(state.config.userId ? { userId: state.config.userId } : {}),
+  userData: business ? undefined : state.config.userData,
+  mediaIds: business ? {} : state.mediaIds,
+  ...(state.config.workflowId ? { workflowId: state.config.workflowId } : {}),
+  ...(state.poaDocumentType ? { proofOfAddressType: state.poaDocumentType } : {}),
+  ...(state.contact.emailToken || state.contact.phoneToken
+    ? {
+        contact: {
+          ...(state.contact.emailToken ? { emailToken: state.contact.emailToken } : {}),
+          ...(state.contact.phoneToken ? { phoneToken: state.contact.phoneToken } : {}),
+        },
+      }
+    : {}),
+  // The chip read, when one succeeded.
+  //
+  // This was the whole point of the NFC step and it was never sent: the read
+  // completed, `setChipData` stored the result, and nothing ever put it in the
+  // request. Every field the server wants was sitting in the store while the
+  // verification recorded no chip at all — passive authentication never ran,
+  // the assurance level never reached `chip`, and the dashboard showed nothing.
+  //
+  // Omitted entirely when absent rather than sent empty: the server treats a
+  // present-but-hollow block as a failed read, which is not the same as a
+  // document whose chip was never scanned.
+  ...(state.chipData
+    ? {
+        nfc: {
+          dg1: state.chipData.dg1,
+          ...(state.chipData.sod ? { sod: state.chipData.sod } : {}),
+          ...(state.chipData.dg2 ? { dg2: state.chipData.dg2 } : {}),
+          chipAuth: state.chipData.chipAuth,
+        },
+      }
+    : {}),
+  // Only sent when the flow actually asked — an inactive questionnaire
+  // must not put an empty object on the verification record.
+  ...(hasActiveQuestionnaire(state.config.questionnaire)
+    ? {
+        questionnaire: questionnairePayload(
+          state.config.questionnaire!.fields,
+          state.questionnaireAnswers,
+        ),
+      }
+    : {}),
+  // `metadata` is free-form passthrough. The SDK-owned keys (`requestId` —
+  // the server's idempotency key — and `device`) are written AFTER the
+  // caller's metadata so consumer keys can never clobber them. The user
+  // reference is the top-level `userId` above. Identical on web + Flutter.
+  metadata: {
+    ...(state.config.metadata ?? {}),
+    requestId: generateRequestId(),
+    device: {
+      ...(collectDeviceMetadata() as unknown as Record<string, unknown>),
+      // Device Intelligence rides the free-form device channel rather
+      // than a schema field, so an older server simply ignores it and
+      // an older SDK degrades to IP + user-agent only. Off when the
+      // workflow disables it — collecting signals nobody will score is
+      // data taken for nothing.
+      ...(fingerprint ? { fingerprint } : {}),
+    },
+  },
+  };
+}

package/src/store/submitApplicant.ts

@@ -0,0 +1,81 @@
+// ---------------------------------------------------------------------------
+// The APPLICANT's own verification — a SECOND, ordinary INDIVIDUAL submission
+// fired after the business one succeeds, linked back to the application via
+// `metadata.userId = applicantKeyPersonId` (the server-side contract that binds
+// the applicant's KYC to their KeyPerson row). Mirrors the web SDK's
+// submitApplicantVerification and Flutter's _submitApplicantVerification.
+//
+// When the org mapped an applicant workflow (business.applicant.workflowId,
+// overlaid onto the config by the workflow gate), its id rides along so the
+// server applies THAT workflow's gates, pricing and decision graph.
+// ---------------------------------------------------------------------------
+
+import { collectDeviceMetadata } from '../services/deviceMetadata';
+import { generateRequestId } from '../utils/uuid';
+import { splitFullName } from '../config/keyPeople';
+import { effectiveCountry } from './derive';
+import type { ClientFingerprint } from '../services/fingerprint';
+import type { VerifyRequest } from '../services/api';
+import type { KycState } from './state';
+
+/** Whether the applicant capture leg actually produced something to submit. */
+export function applicantMediaCaptured(state: KycState): boolean {
+  return Boolean(
+    state.selectedIdType &&
+      (state.mediaIds.selfie || state.mediaIds.documentFront || (state.idNumber ?? '').trim() !== ''),
+  );
+}
+
+export function buildApplicantVerifyRequest(
+  state: KycState,
+  applicantKeyPersonId: string,
+  fingerprint: ClientFingerprint | undefined,
+): VerifyRequest {
+  // Name: the consumer's userData wins; the applicant-role step's optional
+  // full name fills the gaps. Same precedence as the web SDK.
+  const cfgUser = state.config.userData;
+  const split = splitFullName((state.businessApplication.applicantName ?? '').trim()) ?? {};
+  const firstName = cfgUser?.firstName?.trim() || split.firstName;
+  const lastName = cfgUser?.lastName?.trim() || split.lastName;
+  const userData =
+    firstName || lastName
+      ? { ...(firstName ? { firstName } : {}), ...(lastName ? { lastName } : {}) }
+      : undefined;
+
+  return {
+    // The applicant's own leg country — their country-select choice (or the
+    // overlaid applicant workflow's / registry fallback), never forced to the
+    // business registry country.
+    country: effectiveCountry(state),
+    idType: state.selectedIdType ?? '',
+    ...(state.idNumber?.trim() ? { idNumber: state.idNumber } : {}),
+    ...(state.config.applicantWorkflowId ? { workflowId: state.config.applicantWorkflowId } : {}),
+    ...(userData ? { userData } : {}),
+    mediaIds: state.mediaIds,
+    // The chip read, when the leg ran the NFC step (an overlaid applicant
+    // workflow can enable it). Same block as the individual flow's builder.
+    ...(state.chipData
+      ? {
+          nfc: {
+            dg1: state.chipData.dg1,
+            ...(state.chipData.sod ? { sod: state.chipData.sod } : {}),
+            ...(state.chipData.dg2 ? { dg2: state.chipData.dg2 } : {}),
+            chipAuth: state.chipData.chipAuth,
+          },
+        }
+      : {}),
+    // NO top-level `userId` here on purpose: the server prefers it over
+    // metadata.userId, so sending the org's own user ref would sever the
+    // KeyPerson link this submission exists to make.
+    metadata: {
+      ...(state.config.metadata ?? {}),
+      requestId: generateRequestId(),
+      device: {
+        ...(collectDeviceMetadata() as unknown as Record<string, unknown>),
+        ...(fingerprint ? { fingerprint } : {}),
+      },
+      // The link back to the application — written last so nothing clobbers it.
+      userId: applicantKeyPersonId,
+    },
+  };
+}

package/src/types/appearance.ts

@@ -0,0 +1,113 @@
+// ---------------------------------------------------------------------------
+// Presentation: branding, the copy an org can override, and voice guidance.
+//
+// Split from config.ts (200-line rule). These are the parts of the flow an org
+// makes its own — colours, logo, the words on the consent and success screens —
+// as opposed to what it VERIFIES, which lives in workflow.ts and business.ts.
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Appearance / theming
+// ---------------------------------------------------------------------------
+
+export interface KYCAppearance {
+  /** Brand color — drives buttons, selected states, focus rings. */
+  primaryColor?: string;
+  /** Text/icon color rendered on top of `primaryColor` (e.g. button labels). */
+  primaryTextColor?: string;
+  /** Accent color for subtle hover/active surfaces. */
+  accentColor?: string;
+  /** Modal/sheet background color. */
+  backgroundColor?: string;
+  /** Elevated surface color for cards/panels. */
+  surfaceColor?: string;
+  /** Border + input outline color. */
+  borderColor?: string;
+  /** Primary text color. */
+  textColor?: string;
+  /**
+   * Corner radius in px for buttons, inputs and cards — the whole scale derives
+   * from it, so 0 squares the flow off and 20 softens it. Circular elements
+   * (avatars, the camera frame) are never affected. Default 12.
+   */
+  borderRadius?: number;
+  /**
+   * Body font family.
+   *
+   * Unlike the web SDK this does NOT fetch the font: React Native renders from
+   * families registered by the HOST APP (the SDK's own Karla / Space Grotesk
+   * ship as bundled assets). Pass a family your app has loaded; an unknown name
+   * falls back to the SDK default rather than rendering nothing.
+   */
+  fontFamily?: string;
+  /** Heading font family. Falls back to {@link fontFamily} when only that is set. */
+  headingFontFamily?: string;
+  /**
+   * Colour overrides applied only in DARK mode.
+   *
+   * The colours above are the LIGHT palette. Without this block a branded flow
+   * keeps its light background after the theme toggle — the appearance is
+   * applied on top of whichever base scheme is active, so an org's light
+   * background simply overwrote the dark one.
+   */
+  dark?: Pick<
+    KYCAppearance,
+    | 'primaryColor'
+    | 'primaryTextColor'
+    | 'accentColor'
+    | 'backgroundColor'
+    | 'surfaceColor'
+    | 'borderColor'
+    | 'textColor'
+  >;
+  companyName?: string;
+  /**
+   * Logo to show in the flow.
+   * - An image URL renders that logo.
+   * - The literal `'default'` renders the org's own logo from the server config
+   *   response (falls back to the built-in shield if the org has none set).
+   * - Omitted renders the built-in shield badge.
+   */
+  logo?: string;
+  /** Initial mode. 'system' follows the device's colour scheme (live, until
+   *  the in-flow theme toggle picks one); applied on mount. */
+  theme?: 'light' | 'dark' | 'system';
+}
+
+// ---------------------------------------------------------------------------
+// Consent / success screen content
+// ---------------------------------------------------------------------------
+
+export interface KYCConsentContent {
+  /** Consent heading. Supports `{firstName}` / `{lastName}` tokens. */
+  title?: string;
+  /** Sub-text under the heading. Same tokens. */
+  description?: string;
+}
+
+export interface KYCSuccessContent {
+  /** Success heading. Supports `{firstName}` / `{lastName}` tokens. */
+  title?: string;
+  /** Sub-text under the heading. Same tokens. */
+  description?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Voice guidance (spoken liveness instructions — TTS output only, no mic)
+// ---------------------------------------------------------------------------
+
+/**
+ * Configuration for the spoken liveness instructions. TTS **output** for
+ * accessibility — it never records audio, so no microphone permission is
+ * involved. An object (not a bare boolean) so a `language` can be added later
+ * without a breaking change.
+ */
+export interface VoiceGuidanceConfig {
+  /** Whether spoken guidance plays. Default `true`. */
+  enabled?: boolean;
+  /** BCP-47 voice tag (e.g. `'en-US'`, `'fr-FR'`). Default `'en-US'`. */
+  language?: string;
+}
+
+/** Accepts a bare boolean for ergonomics or the full {@link VoiceGuidanceConfig}. */
+export type VoiceGuidanceOption = boolean | VoiceGuidanceConfig;

package/src/types/business.ts

@@ -0,0 +1,131 @@
+// ---------------------------------------------------------------------------
+// Business (KYB) workflow types
+//
+// LIVE business verification is WORKFLOW-REQUIRED: the server only accepts a
+// business submission with a published KYB workflow (workflowId or hosted
+// link). `subjectType`/`business` also exist as public props for the dashboard
+// builder's live preview (`previewMode`, where all writes are mocked).
+// ---------------------------------------------------------------------------
+
+/** What a workflow verifies. Absent = 'individual' (classic KYC). */
+export type SubjectType = 'individual' | 'business';
+
+/** Associated-party roles discovered from the registry lookup. */
+export type KeyPersonRole = 'director' | 'beneficial_owner' | 'signatory' | 'shareholder';
+
+/** Roles the APPLICANT (the person submitting) may declare — key-person roles
+ *  plus 'authorized_representative' (someone filing on the company's behalf). */
+export type ApplicantRole = KeyPersonRole | 'authorized_representative';
+
+/** Supporting-document kinds a KYB workflow can request from the applicant. */
+export const COMPANY_INFO_FIELDS = ['address', 'email', 'phone', 'website'] as const;
+export type CompanyInfoField = (typeof COMPANY_INFO_FIELDS)[number];
+export type CompanyInfoMode = 'off' | 'optional' | 'required';
+
+export type BusinessDocumentKey =
+  | 'incorporation_certificate'
+  | 'memart'
+  | 'proof_of_address'
+  | 'tax_document'
+  | 'regulatory_license'
+  | 'board_resolution'
+  | 'other';
+
+/** Verification depth for discovered key people. */
+export type KeyPeopleLevel = 'screening_only' | 'data' | 'full_kyc';
+
+/**
+ * Key-people (associated-party) verification block on a KYB workflow —
+ * template config that arrives via workflow resolution. Mirrors the server's
+ * `KeyPeopleConfigSchema`; the SDK only reads the email-invite gate.
+ */
+export interface WorkflowKeyPeopleConfig {
+  enabled?: boolean;
+  /** SDK collects the directors/owners from the applicant (adds the
+   *  business-key-people step to the flow). */
+  collect?: boolean;
+  /** Minimum people the applicant must list when collect is on (0 = skippable). */
+  minEntries?: number;
+  /** In-scope roles. Absent/empty = all four roles. */
+  roles?: KeyPersonRole[];
+  /** Shareholders at/above this % escalate to beneficial owner (default 25). */
+  ownershipThreshold?: number;
+  /** Default verification depth when a role has no `perRole` override. */
+  level?: KeyPeopleLevel;
+  requirement?: 'all_in_scope' | 'ubos_only' | 'advisory';
+  /** Per-role verification depth overrides (win over `level`). */
+  perRole?: Partial<Record<KeyPersonRole, KeyPeopleLevel>>;
+  /** Invite distribution for full-KYC people. */
+  invite?: {
+    channel?: string;
+    /** The KYC workflow the per-person invite links run through. */
+    workflowId?: string;
+  };
+}
+
+/**
+ * A KYB workflow's business configuration block. Business verification is a
+ * registry lookup — no ID types, no capture — and the block carries its own
+ * registry countries (any provider-supported ISO-2 codes, NOT limited to the
+ * individual-KYC catalogue).
+ */
+export interface WorkflowBusinessConfig {
+  /** ISO-2 PRIMARY registry country — the picker's default/pre-selected value. */
+  country: string;
+  /**
+   * Multi-registry: every country the visitor may pick from. Published
+   * workflows always carry an explicit list (the server materializes the
+   * "all supported countries" mode at publish); absent = just the primary.
+   */
+  countries?: string[];
+  /** Builder marker for "all supported countries" (materialized at publish). */
+  allCountries?: boolean;
+  /**
+   * Offered verification products (keys from the server's business-products
+   * catalog, e.g. 'business', 'business-tax'). Absent = just 'business'.
+   * The effective offering narrows per picked country (TIN is NG-only).
+   */
+  products?: string[];
+  /** Require the visitor to also type the registered business name. */
+  requireRegistrationName?: boolean;
+  /** Collect the company profile (address / email / phone / website) on the
+   *  business-details step. Default ON; false hides the whole section. */
+  collectCompanyInfo?: boolean;
+  /** Per-field mode: absent = 'optional'; 'required' blocks Continue without
+   *  it; 'off' hides the field. */
+  companyInfo?: Partial<Record<CompanyInfoField, CompanyInfoMode>>;
+  /** Key-people (director/owner) verification configuration. */
+  keyPeople?: WorkflowKeyPeopleConfig;
+  /** Supporting-document collection (business-documents step). */
+  documents?: WorkflowBusinessDocumentsConfig;
+  /** Applicant (submitter) identity verification (in-flow individual KYC). */
+  applicant?: WorkflowBusinessApplicantConfig;
+}
+
+/** One requested document slot on a KYB workflow's `documents` block. */
+export interface WorkflowBusinessDocumentTypeConfig {
+  key: BusinessDocumentKey;
+  /** Display label override (defaults per key, e.g. "Certificate of incorporation"). */
+  label?: string;
+  /** Submission is blocked (422 missing_documents) until this slot is uploaded. */
+  required?: boolean;
+}
+
+/**
+ * Supporting-document collection block on a KYB workflow. `enabled` with
+ * absent/empty `types` defaults to just a required incorporation certificate.
+ */
+export interface WorkflowBusinessDocumentsConfig {
+  enabled?: boolean;
+  types?: WorkflowBusinessDocumentTypeConfig[];
+}
+
+/**
+ * Applicant-verification block on a KYB workflow: when `verification` is true
+ * the applicant verifies their OWN identity in-flow (role declaration + the
+ * ordinary individual capture steps), linked back to the application via
+ * `metadata.userId = applicantKeyPersonId` on the second submission.
+ */
+export interface WorkflowBusinessApplicantConfig {
+  verification?: boolean;
+}