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

package/src/config/businessSteps.ts

@@ -86,10 +86,27 @@ 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,
+  withAddressCollection = false,
+): (BusinessSectionStep | 'questionnaire' | 'address-collection')[] {
+  const steps: (BusinessSectionStep | 'questionnaire' | 'address-collection')[] = [
+    'business-details',
+  ];
+  // The premises pin follows the company details it is about — before the
+  // paperwork, and long before the application hands over to other people.
+  if (withAddressCollection) steps.push('address-collection');
+  // 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/consentStep.ts

@@ -0,0 +1,19 @@
+import type { KYCStep } from '../types/config';
+
+// ─── The consent screen switch (`consentStep`) ──────────────────────────────
+//
+// A workflow can switch the opening consent (welcome) screen off, for a host
+// app that has already asked: the flow then opens on its first real step.
+// Mirrors the server's `WorkflowConfigSchema.consentStep` and the web /
+// Flutter helpers of the same name; keep the default in lockstep.
+
+/** Whether the flow opens on the consent screen. Absent = yes. */
+export function hasConsentStep(config: { consentStep?: boolean | null }): boolean {
+  return config.consentStep !== false;
+}
+
+/** The step a built order opens on; 'consent' for an empty order, which no
+ *  flow produces. */
+export function openingStepOf(order: readonly KYCStep[]): KYCStep {
+  return order[0] ?? 'consent';
+}

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;
+}

package/src/config/keyPeopleSections.ts

@@ -0,0 +1,167 @@
+import type { KeyPersonEntry } from './keyPeople';
+import type { KeyPersonRole } from '../types/business';
+
+/**
+ * The sectioned key-people model: UBOs / Shareholders / Directors &
+ * representatives as VIEWS over one shared list of people.
+ *
+ * A section is not a bucket. One human is a director AND a 30% owner, and the
+ * register files them that way, so an entry appears in every section whose
+ * definition it meets — membership is derived from the roles it holds and the
+ * stake it declares, never stored. Quick-add grants an existing person another
+ * hat instead of retyping them; classification by ownership happens here
+ * exactly as the server escalates it, so the screen never disagrees with what
+ * the submission will be read as.
+ */
+
+export type KeyPeopleSection = 'ubos' | 'shareholders' | 'representatives';
+
+/** Strongest first — the headline role on one-role surfaces. Mirrors the
+ *  server's precedence in `key-people/roles.ts`; keep the two in lockstep. */
+const ROLE_PRECEDENCE: KeyPersonRole[] = [
+  'beneficial_owner',
+  'director',
+  'signatory',
+  'shareholder',
+];
+
+export function primaryRole(roles: KeyPersonRole[]): KeyPersonRole {
+  for (const role of ROLE_PRECEDENCE) if (roles.includes(role)) return role;
+  return 'shareholder';
+}
+
+/** The roles an entry actually holds; falls back to the headline for rows
+ *  minted before `roles` existed (restored sessions). */
+export function rolesOf(entry: Pick<KeyPersonEntry, 'role' | 'roles'>): KeyPersonRole[] {
+  return entry.roles && entry.roles.length > 0 ? entry.roles : [entry.role];
+}
+
+/** The declared stake as a number, or null when blank/unparseable. */
+export function stakeOf(entry: Pick<KeyPersonEntry, 'ownershipPct'>): number | null {
+  const raw = entry.ownershipPct.trim();
+  if (raw === '') return null;
+  const n = Number(raw);
+  return Number.isFinite(n) ? n : null;
+}
+
+/**
+ * Which sections this entry belongs to.
+ *
+ * - UBOs: a natural person holding the beneficial-owner role OR a stake at or
+ *   above the threshold — the same escalation the server performs, so a
+ *   shareholder who types 60% moves up on screen exactly as they will in the
+ *   submission. A company never qualifies (a beneficial owner is a natural
+ *   person in every regime that defines one).
+ * - Shareholders: every corporate holder (whatever its stake — the never-a-UBO
+ *   rule made visible), plus people with a declared holding or shareholder
+ *   role below the threshold. A person the UBO section claimed is not ALSO a
+ *   plain shareholder: same stake, one classification.
+ * - Representatives: anyone holding director or signatory.
+ */
+export function sectionsFor(
+  entry: KeyPersonEntry,
+  threshold: number,
+): Set<KeyPeopleSection> {
+  const roles = rolesOf(entry);
+  const stake = stakeOf(entry);
+  const out = new Set<KeyPeopleSection>();
+
+  const isUbo =
+    !entry.isCorporate &&
+    (roles.includes('beneficial_owner') || (stake != null && stake >= threshold));
+  if (isUbo) out.add('ubos');
+  if (
+    entry.isCorporate ||
+    (!isUbo && (roles.includes('shareholder') || (stake != null && stake > 0)))
+  ) {
+    out.add('shareholders');
+  }
+  if (roles.includes('director') || roles.includes('signatory')) {
+    out.add('representatives');
+  }
+  return out;
+}
+
+/** Indices of the entries each section shows, in list order. */
+export function sectionMembers(
+  rows: KeyPersonEntry[],
+  threshold: number,
+): Record<KeyPeopleSection, number[]> {
+  const out: Record<KeyPeopleSection, number[]> = {
+    ubos: [],
+    shareholders: [],
+    representatives: [],
+  };
+  rows.forEach((row, index) => {
+    for (const section of sectionsFor(row, threshold)) out[section].push(index);
+  });
+  return out;
+}
+
+/** The role a section's add-tile (and quick-add chip) grants. */
+export const SECTION_ROLE: Record<KeyPeopleSection, KeyPersonRole> = {
+  ubos: 'beneficial_owner',
+  shareholders: 'shareholder',
+  representatives: 'director',
+};
+
+/**
+ * Entries offerable as quick-add chips for a section: already entered, named,
+ * not yet a member, and eligible (a company can never be quick-added as a
+ * UBO). One tap grants the section's role — the Didit chip, minus its
+ * duplicate-name bug.
+ */
+export function quickAddCandidates(
+  rows: KeyPersonEntry[],
+  section: KeyPeopleSection,
+  threshold: number,
+): number[] {
+  const members = new Set(sectionMembers(rows, threshold)[section]);
+  return rows
+    .map((row, index) => ({ row, index }))
+    .filter(({ row, index }) => {
+      if (members.has(index)) return false;
+      if (row.name.trim().length < 2) return false;
+      if (section === 'ubos' && row.isCorporate) return false;
+      // Only offer a chip that would DO something. Membership is derived, so
+      // granting a role does not always produce it: a beneficial owner is not
+      // also a plain shareholder (same stake, one classification), so offering
+      // them under Shareholders gave a chip that could be tapped forever and
+      // never move anybody. An affordance that does nothing is worse than an
+      // absent one, because the applicant concludes the app is broken.
+      return sectionsFor(grantRole(row, section), threshold).has(section);
+    })
+    .map(({ index }) => index);
+}
+
+/** Grant an entry another hat (quick-add). The headline follows precedence. */
+export function grantRole(entry: KeyPersonEntry, section: KeyPeopleSection): KeyPersonEntry {
+  const roles = rolesOf(entry);
+  const granted = SECTION_ROLE[section];
+  const next = roles.includes(granted) ? roles : [...roles, granted];
+  return { ...entry, roles: next, role: primaryRole(next) };
+}
+
+/**
+ * Take an entry out of a section (the card's X). Removing the section's roles
+ * is enough when membership came from them; when it came from a declared
+ * stake (or nothing else keeps the row alive) the honest reading of "remove
+ * from UBOs" is "remove this person" — the caller deletes the row when this
+ * returns null.
+ */
+export function withoutSection(
+  entry: KeyPersonEntry,
+  section: KeyPeopleSection,
+  threshold: number,
+): KeyPersonEntry | null {
+  const dropped: KeyPersonRole[] =
+    section === 'representatives' ? ['director', 'signatory'] : [SECTION_ROLE[section]];
+  const remaining = rolesOf(entry).filter((r) => !dropped.includes(r));
+  if (remaining.length === 0) return null;
+  const next = { ...entry, roles: remaining, role: primaryRole(remaining) };
+  // Still a member by stake? Then role removal did not remove them, and the
+  // tap meant more than that.
+  if (sectionsFor(next, threshold).has(section)) return null;
+  return next;
+}
+