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

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,
@@ -159,12 +160,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;
+}

package/src/config/businessSteps.ts

@@ -86,10 +86,21 @@ export type BusinessSectionStep =
 /** The ordered business-application steps this workflow configures. */
 export function businessSectionSteps(
   business: WorkflowBusinessConfig | undefined,
-): BusinessSectionStep[] {
-  const steps: BusinessSectionStep[] = ['business-details'];
-  if (hasKeyPeopleCollection(business)) steps.push('business-key-people');
+  withQuestionnaire = false,
+): (BusinessSectionStep | 'questionnaire')[] {
+  const steps: (BusinessSectionStep | 'questionnaire')[] = ['business-details'];
+  // Documents BEFORE key people: they are about the company the applicant has
+  // just identified, so they follow that thread, and the register's officer
+  // list - which the key-people step is a confirmation of - is what should
+  // still be in mind when they get to naming people.
   if (hasBusinessDocumentsStep(business)) steps.push('business-documents');
+  // The questionnaire BEFORE key people: its questions are about the COMPANY
+  // (volumes, source of funds), so they belong with the company section — and
+  // naming the directors leads into their verification, which is where the
+  // application hands over to other people and stops being the applicant's
+  // own form to finish. Mirrors the web SDK.
+  if (withQuestionnaire) steps.push('questionnaire');
+  if (hasKeyPeopleCollection(business)) steps.push('business-key-people');
   if (hasApplicantVerification(business)) steps.push('applicant-role');
   return steps;
 }

package/src/config/keyPeople.ts

@@ -8,7 +8,12 @@
 // names is a risk signal the server flags as `undisclosed`.
 // ---------------------------------------------------------------------------
 
-import type { KeyPersonRole } from '../types/business';
+export { looksCorporate } from './keyPeopleCorporate';
+import { ownersPayload } from './keyPeopleOwners';
+export { emptyKeyPersonOwner } from './keyPeopleOwnerTypes';
+export type { KeyPersonOwnerEntry } from './keyPeopleOwnerTypes';
+import type { KeyPersonOwnerEntry } from './keyPeopleOwnerTypes';
+import type { KeyPersonRole, WorkflowBusinessConfig } from '../types/business';
 import { isValidContactEmail } from './contact';
 
 /** UI cap on applicant-entered rows (the server accepts ≤20). */
@@ -31,22 +36,100 @@ export const KEY_PERSON_ROLES: KeyPersonRole[] = [
 /** One row as typed. Everything is a string so a half-filled row is editable. */
 export interface KeyPersonEntry {
   name: string;
+  /** The headline role — derived from `roles` by precedence (mirrors the
+   *  server's role/roles pair). One-role surfaces read it. */
   role: KeyPersonRole;
+  /** Every hat this person wears: a director AND a 30% owner is one human,
+   *  filed twice — never two entries. Never empty. */
+  roles: KeyPersonRole[];
+  /** Their own words for the position ("CFO, Board Member"). Display only. */
+  title: string;
   email: string;
   /** The person's own ISO-2 country — a foreign director cannot verify with a
    *  local ID, so this drives their invite's country. */
   country: string;
   ownershipPct: string;
+  /**
+   * This party is a company, not a person.
+   *
+   * A company can never be a beneficial owner, so it is screened as an entity
+   * and never asked to verify an identity it does not have. Saying so is what
+   * stops the flow sending a document-and-selfie link to a limited company and
+   * then waiting for it.
+   */
+  isCorporate: boolean;
+  /** A corporate party's own registration number, as typed. */
+  registrationNumber: string;
+  /**
+   * The people who own a corporate party, as the applicant knows them. The only
+   * route to the humans above a parent no register we serve can be asked about.
+   */
+  owners: KeyPersonOwnerEntry[];
 }
 
 export function emptyKeyPerson(role: KeyPersonRole = 'director'): KeyPersonEntry {
-  return { name: '', role, email: '', country: '', ownershipPct: '' };
+  return {
+    name: '',
+    role,
+    roles: [role],
+    title: '',
+    email: '',
+    country: '',
+    ownershipPct: '',
+    isCorporate: false,
+    registrationNumber: '',
+    owners: [],
+  };
 }
 
-/** Whether a row is complete enough to submit. */
-export function isKeyPersonRowValid(row: KeyPersonEntry): boolean {
+
+const EMPTY_ROLES: ReadonlySet<KeyPersonRole> = new Set();
+
+/**
+ * The roles whose EMAIL is mandatory: the ones that are actually sent a
+ * verification link. Asking a screening-only signatory for an address blocks
+ * the form over a field nothing will read. Mirrors the web SDK's
+ * keyPeopleRequireEmail — keep the two in lockstep.
+ */
+export function keyPeopleRequireEmail(
+  business: WorkflowBusinessConfig | undefined,
+): Set<KeyPersonRole> {
+  const kp = business?.keyPeople;
+  if (!kp?.enabled || !kp.collect || !kp.requireEmail) return new Set();
+  if (kp.requireEmailRoles?.length) return new Set(kp.requireEmailRoles);
+  return new Set(
+    KEY_PERSON_ROLES.filter(
+      (r) => (kp.perRole?.[r] ?? kp.level ?? 'screening_only') === 'full_kyc',
+    ),
+  );
+}
+
+/** Whether THIS row must carry an email. A company has no inbox and is never
+ *  invited, so a corporate row is always exempt. */
+export function rowNeedsEmail(
+  row: KeyPersonEntry,
+  emailRequiredFor: ReadonlySet<KeyPersonRole>,
+): boolean {
+  const roles = row.roles && row.roles.length > 0 ? row.roles : [row.role];
+  return !row.isCorporate && roles.some((r) => emailRequiredFor.has(r));
+}
+
+/**
+ * Whether a row is complete enough to submit.
+ *
+ * `emailRequiredFor` makes the address mandatory rather than merely
+ * well-formed. The server enforces it too, but only at SUBMIT — several steps
+ * later, as a generic failure, with no way back to the row that is missing
+ * one. Blocking here is where the person can still fix it.
+ */
+export function isKeyPersonRowValid(
+  row: KeyPersonEntry,
+  emailRequiredFor: ReadonlySet<KeyPersonRole> = EMPTY_ROLES,
+): boolean {
   if (row.name.trim().length < 2) return false;
-  if (!KEY_PERSON_ROLES.includes(row.role)) return false;
+  const roles = row.roles && row.roles.length > 0 ? row.roles : [row.role];
+  if (!roles.every((r) => KEY_PERSON_ROLES.includes(r))) return false;
+  if (rowNeedsEmail(row, emailRequiredFor) && row.email.trim() === '') return false;
   if (row.email.trim() !== '' && !isValidContactEmail(row.email.trim())) return false;
   if (row.ownershipPct.trim() !== '') {
     const pct = Number(row.ownershipPct);
@@ -69,9 +152,14 @@ export function isKeyPersonRowBlank(row: KeyPersonEntry): boolean {
 }
 
 /** Rows the user has begun but not made valid — what blocks Continue. */
-export function invalidKeyPersonRows(rows: KeyPersonEntry[]): number[] {
+export function invalidKeyPersonRows(
+  rows: KeyPersonEntry[],
+  emailRequiredFor: ReadonlySet<KeyPersonRole> = EMPTY_ROLES,
+): number[] {
   return rows
-    .map((row, i) => (!isKeyPersonRowBlank(row) && !isKeyPersonRowValid(row) ? i : -1))
+    .map((row, i) =>
+      !isKeyPersonRowBlank(row) && !isKeyPersonRowValid(row, emailRequiredFor) ? i : -1,
+    )
     .filter((i) => i >= 0);
 }
 
@@ -87,9 +175,14 @@ export function keyPeoplePayload(
 ): Array<{
   name: string;
   role: KeyPersonRole;
+  roles: KeyPersonRole[];
+  title?: string;
   email?: string;
   country?: string;
   ownershipPct?: number;
+  isCorporate?: boolean;
+  registrationNumber?: string;
+  owners?: Array<{ name: string; ownershipPct?: number; email?: string; country?: string }>;
   isApplicant?: boolean;
 }> {
   return rows
@@ -99,9 +192,20 @@ export function keyPeoplePayload(
     .map(({ row, index }) => ({
       name: row.name.trim(),
       role: row.role,
+      // Every hat they wear - the server merges the set with its own
+      // ownership escalation and derives the headline by precedence.
+      roles: row.roles && row.roles.length > 0 ? row.roles : [row.role],
+      ...(row.title?.trim() ? { title: row.title.trim() } : {}),
       ...(row.email.trim() !== '' ? { email: row.email.trim() } : {}),
       ...(row.country.trim() !== '' ? { country: row.country.trim().toUpperCase() } : {}),
       ...(row.ownershipPct.trim() !== '' ? { ownershipPct: Number(row.ownershipPct) } : {}),
+      // A company cannot also be the person filling in the form, so the
+      // applicant's own entry is never sent as one.
+      ...(row.isCorporate && index !== applicantIndex ? { isCorporate: true } : {}),
+      ...(row.isCorporate && row.registrationNumber.trim() !== ''
+        ? { registrationNumber: row.registrationNumber.trim() }
+        : {}),
+      ...(row.isCorporate && index !== applicantIndex ? ownersPayload(row.owners) : {}),
       ...(index === applicantIndex ? { isApplicant: true } : {}),
     }));
 }

package/src/config/keyPeopleCorporate.ts

@@ -0,0 +1,19 @@
+// Telling a company apart from a person in a register's officer list.
+
+/**
+ * Corporate designators, matched only at the END of a name.
+ *
+ * End-anchored on purpose: "Trust", "Grace" and "Precious" are ordinary
+ * Nigerian given names, and nobody is called "X Limited".
+ */
+const CORPORATE_SUFFIXES = [
+  'limited', 'ltd', 'plc', 'inc', 'incorporated', 'llc', 'llp', 'gmbh', 'nv', 'bv', 'pty',
+  'corporation', 'corp', 'nominees', 'holdings', 'trustees', 'ventures', 'enterprises',
+];
+
+/** Whether a registry name reads as a company. */
+export function looksCorporate(name: string): boolean {
+  const parts = name.toLowerCase().replace(/[.,()]/g, ' ').split(/\s+/).filter(Boolean);
+  const last = parts[parts.length - 1];
+  return last != null && CORPORATE_SUFFIXES.includes(last);
+}

package/src/config/keyPeopleOwnerTypes.ts

@@ -0,0 +1,12 @@
+/** One declared owner of a corporate key person. */
+export interface KeyPersonOwnerEntry {
+  name: string;
+  /** Their share OF THE COMPANY above. The server multiplies it down the chain. */
+  ownershipPct: string;
+  email: string;
+  country: string;
+}
+
+export function emptyKeyPersonOwner(): KeyPersonOwnerEntry {
+  return { name: '', ownershipPct: '', email: '', country: '' };
+}

package/src/config/keyPeopleOwners.ts

@@ -0,0 +1,26 @@
+import type { KeyPersonOwnerEntry } from './keyPeopleOwnerTypes';
+
+// The people an applicant says own a corporate shareholder. Declared,
+// corroborated by nothing, and recorded as exactly that.
+
+/** Declared owners, dropping the half-typed rows. Absent when none are valid. */
+export function ownersPayload(
+  owners: KeyPersonOwnerEntry[] | undefined,
+): { owners?: Array<{ name: string; ownershipPct?: number; email?: string; country?: string }> } {
+  const valid = (owners ?? [])
+    .filter((o) => o.name.trim().length >= 2)
+    .slice(0, 10)
+    .map((o) => {
+      const pct = Number(o.ownershipPct);
+      return {
+        name: o.name.trim(),
+        ...(o.ownershipPct.trim() !== '' && Number.isFinite(pct) && pct >= 0 && pct <= 100
+          ? { ownershipPct: pct }
+          : {}),
+        ...(o.email.trim() !== '' ? { email: o.email.trim() } : {}),
+        ...(o.country.trim() !== '' ? { country: o.country.trim().toUpperCase() } : {}),
+      };
+    });
+  return valid.length > 0 ? { owners: valid } : {};
+}
+

package/src/config/keyPeoplePrefill.ts

@@ -0,0 +1,138 @@
+import type { KeyPersonEntry } from './keyPeople';
+import type { KeyPersonRole } from '../types/business';
+import { looksCorporate } from './keyPeopleCorporate';
+import { primaryRole } from './keyPeopleSections';
+import type { RegistryOfficer } from '../services/api';
+
+// ---------------------------------------------------------------------------
+// Turning the register's officer list into rows the applicant confirms.
+//
+// This is the whole point of checking at selection: the question stops being
+// "who are your directors?", which is a memory test, and becomes "are these
+// right?", which is a confirmation. It also makes a removal meaningful —
+// taking a name out of a list you were shown is a decision, and the server
+// records it as one (keyPeople.removedFromRegistry).
+//
+// Ported from the web SDK's key-people-prefill.ts — keep the two in lockstep.
+// ---------------------------------------------------------------------------
+
+/**
+ * People a register names who are not parties to the business: the agent who
+ * filed the papers, the witness to a signature, the lawyer who drew them up,
+ * the deponent who swore the declaration. Prefilled as directors, an applicant
+ * confirming what looked like their own board would hand us the filing agent
+ * as an officer.
+ */
+/** The closed role vocabulary a served role must belong to. */
+const VALID_ROLES: KeyPersonRole[] = ['director', 'beneficial_owner', 'signatory', 'shareholder'];
+
+const NOT_A_PARTY = ['presenter', 'witness', 'lawyer', 'deponent', 'solicitor', 'notary'];
+
+/**
+ * A registry designation in our role vocabulary.
+ *
+ * Falls back to `director` rather than dropping a person: an officer we cannot
+ * classify still has to appear, because an unlisted one reads as an omission.
+ */
+export function roleFromDesignation(designation: string | null): KeyPersonRole {
+  const d = (designation ?? '').toLowerCase();
+  // Nigeria's beneficial-ownership register, in CAMA 2020's own words.
+  if (d.includes('significant control') || d.includes('psc') || d.includes('beneficial')) {
+    return 'beneficial_owner';
+  }
+  if (d.includes('shareholder') || d.includes('owner') || d.includes('member')) return 'shareholder';
+  if (d.includes('secretary') || d.includes('signator')) return 'signatory';
+  return 'director';
+}
+
+/**
+ * Two spellings of one name: enough shared words, and no CONFLICT.
+ *
+ * Counting shared words alone merged siblings — a double-barrelled family
+ * surname supplies two shared words by itself. Each side holding a word the
+ * other lacks is a different person; one side holding extras is the fuller
+ * spelling. Mirrors the server's namesLikelySame.
+ */
+function samePerson(a: string, b: string): boolean {
+  const words = (s: string) =>
+    new Set(
+      s
+        .toLowerCase()
+        .replace(/[^a-z\s]/g, ' ')
+        .split(/\s+/)
+        .filter((w) => w.length >= 2),
+    );
+  const wa = words(a);
+  const wb = words(b);
+  if (wa.size === 0 || wb.size === 0) return false;
+  let shared = 0;
+  for (const w of wa) if (wb.has(w)) shared += 1;
+  if (shared === 1 && Math.min(wa.size, wb.size) === 1) return true;
+  if (shared < 2) return false;
+  return shared === wa.size || shared === wb.size;
+}
+
+/**
+ * Build the rows to start the step with.
+ *
+ * ONE ROW PER PERSON: a register files one designation per entry and the same
+ * human several times over, so entries are merged by name, keeping the
+ * classification that asks the most of them.
+ */
+export function prefillKeyPeople(
+  officers: readonly RegistryOfficer[],
+  defaultCountry: string,
+): KeyPersonEntry[] {
+  const rows: KeyPersonEntry[] = [];
+  for (const o of officers) {
+    const name = (o.name ?? '').trim();
+    if (!name) continue;
+    const d = (o.designation ?? '').toLowerCase();
+    if (NOT_A_PARTY.some((h) => d.includes(h))) continue;
+
+    // A newer server sends the merged role set; an older one sends the raw
+    // designation per entry and the merge below reassembles the person.
+    const served = (o.roles ?? []).filter((r): r is KeyPersonRole =>
+      VALID_ROLES.includes(r as KeyPersonRole),
+    );
+    const roles = served.length > 0 ? served : [roleFromDesignation(o.designation)];
+    const existing = rows.find((r) => samePerson(r.name, name));
+    if (existing) {
+      // The register filed the same human under another designation - that is
+      // another HAT, not another person. Union the roles; the headline keeps
+      // the classification that asks the most of them.
+      existing.roles = [...new Set([...existing.roles, ...roles])];
+      existing.role = primaryRole(existing.roles);
+      if (name.length > existing.name.length) existing.name = name;
+      continue;
+    }
+    rows.push({
+      name,
+      role: primaryRole(roles),
+      roles,
+      title: '',
+      // Fill what the register actually said - the ownership split it
+      // computed from the share counts, an email when one is on file - and
+      // invent nothing: a value it did not give stays for the applicant.
+      email: (o.email ?? '').trim(),
+      country: defaultCountry,
+      ownershipPct:
+        o.ownershipPct != null && Number.isFinite(o.ownershipPct)
+          ? String(o.ownershipPct)
+          : '',
+      isCorporate: o.isCorporate ?? looksCorporate(name),
+      registrationNumber: (o.registrationNumber ?? '').trim(),
+      owners: [],
+    });
+  }
+  return rows;
+}
+
+/**
+ * Whether prefilling would overwrite work. Only ever fills an empty list:
+ * someone who already typed a name has told us something the register did
+ * not, and replacing it would lose both their input and the signal in it.
+ */
+export function shouldPrefill(existing: readonly KeyPersonEntry[]): boolean {
+  return existing.every((r) => r.name.trim() === '' && r.email.trim() === '');
+}

package/src/config/keyPeopleSectionDefs.ts

@@ -0,0 +1,65 @@
+import type { KeyPeopleSection } from './keyPeopleSections';
+import type { WorkflowBusinessConfig } from '../types/business';
+
+// The step's section definitions — which sections show and what they say.
+// Split from keyPeopleSections.ts (200-line rule).
+
+/**
+ * The register's default beneficial-ownership line, when the workflow does
+ * not set its own. Mirrors the server's `uboThresholdFor`: 25 is the
+ * FATF/EU/FinCEN indicative figure; Nigeria's CAMA files significant control
+ * from a lower bar, so NG defaults to 10. Keep in lockstep with the web SDK.
+ */
+export function defaultUboThreshold(country?: string | null): number {
+  return (country ?? '').toUpperCase() === 'NG' ? 10 : 25;
+}
+
+export interface KeyPeopleSectionDef {
+  key: KeyPeopleSection;
+  title: string;
+  description: string;
+  addLabel: string;
+}
+
+/**
+ * Which sections the step shows, with their plain-language definitions. The
+ * definitions carry the REAL threshold (workflow override or the register's
+ * default) — a printed band the server does not enforce would be a lie the
+ * applicant plans around. Scope follows the workflow's `keyPeople.roles`.
+ */
+export function keyPeopleSectionList(
+  business: WorkflowBusinessConfig | undefined,
+  threshold: number,
+): KeyPeopleSectionDef[] {
+  const scoped = business?.keyPeople?.roles;
+  const inScope = (roles: string[]): boolean =>
+    !scoped || scoped.length === 0 || roles.some((r) => scoped.includes(r as never));
+
+  const t = String(threshold);
+  const out: KeyPeopleSectionDef[] = [];
+  if (inScope(['beneficial_owner'])) {
+    out.push({
+      key: 'ubos',
+      title: 'Beneficial owners',
+      description: `Individuals who own ${t}% or more of the company.`,
+      addLabel: 'Add a beneficial owner',
+    });
+  }
+  if (inScope(['shareholder'])) {
+    out.push({
+      key: 'shareholders',
+      title: 'Shareholders',
+      description: `People or companies holding under ${t}%.`,
+      addLabel: 'Add a shareholder',
+    });
+  }
+  if (inScope(['director', 'signatory'])) {
+    out.push({
+      key: 'representatives',
+      title: 'Directors & representatives',
+      description: 'People who act on behalf of the company.',
+      addLabel: 'Add a representative',
+    });
+  }
+  return out;
+}