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

package/src/services/api-types.ts

@@ -47,9 +47,32 @@ export interface KeyPersonInvite {
   inviteUrl: string;
 }
 
+/**
+ * The one status vocabulary, shared by `GET /api/kyc/status/:id`, the
+ * secret-key result route and every verification webhook.
+ *
+ * `status` is what happened; `checkStatus` beside it is what the CHECKS found.
+ * They differ when a person overrode the automated result, which is the case
+ * worth being able to see: `approved` with `checkStatus: 'failed'` means
+ * somebody accepted the applicant despite a failed check, and the reason says
+ * what they accepted them despite.
+ */
+export type SessionStatus =
+  | 'not_started'
+    | 'in_progress'
+    | 'processing'
+    | 'in_review'
+    | 'awaiting_resubmission'
+    | 'approved'
+    | 'declined'
+    | 'abandoned'
+    | 'expired'
+    | 'error';
+
 export interface VerifyResponse {
   verificationId: string;
-  status: 'pending';
+  /** Always `processing`: accepted, checks running. */
+  status: 'processing';
   /**
    * KYB with applicant verification: the KeyPerson row the applicant's OWN
    * identity check must link back to, via `metadata.userId` on a second,
@@ -66,7 +89,9 @@ export interface VerifyResponse {
  */
 export interface VerificationStatusResponse {
   verificationId: string;
-  status: 'pending' | 'verified' | 'failed' | 'not_found' | 'error';
+  status: SessionStatus;
+  /** What the CHECKS found, unchanged by any later decision. */
+  checkStatus?: 'pending' | 'verified' | 'failed' | 'not_found' | 'error';
   reason?: string | null;
   reasonCode?: string | null;
   createdAt: string;
@@ -109,6 +134,14 @@ export interface SdkConfigResponse {
   environment: 'DEVELOPMENT' | 'SANDBOX' | 'PRODUCTION';
   idTypes: SdkConfigIdType[];
   branding?: SdkConfigBranding;
+  /**
+   * The visitor's country, resolved from their IP.
+   *
+   * A GUESS and only ever a DEFAULT — nothing branches on it and it never
+   * reaches a verification. Deliberately not evidence: device intelligence
+   * carries the same lookup as a RISK signal, and the two must not be confused.
+   */
+  geoCountry?: string | null;
 }
 
 /**
@@ -141,6 +174,14 @@ export interface WorkflowResolutionResponse {
   /** Org allowlist + per-ID feature flags (same shape as /config). */
   idTypes: SdkConfigIdType[];
   branding?: SdkConfigBranding;
+  /**
+   * The visitor's country, resolved from their IP.
+   *
+   * A GUESS and only ever a DEFAULT — nothing branches on it and it never
+   * reaches a verification. Deliberately not evidence: device intelligence
+   * carries the same lookup as a RISK signal, and the two must not be confused.
+   */
+  geoCountry?: string | null;
   /** KYB only: the mapped applicant workflow, when configured and resolvable. */
   applicantWorkflow?: ApplicantWorkflowPayload | null;
 }
@@ -157,8 +198,123 @@ export interface ContactCheckResponse {
   token: string;
 }
 
+/**
+ * A server-issued Active-Authentication challenge. `challenge` is base64 of the
+ * 8 bytes handed to the chip; `challengeId` is what rides the submission so the
+ * server can spend it (single-use — a replayed one is refused).
+ */
+export interface NfcChallengeResponse {
+  challengeId: string;
+  challenge: string;
+  expiresAt: string;
+}
+
 export interface HealthResponse {
   status: string;
 }
 
 // The mime types the server accepts (must mirror the server's upload allowlist).
+
+/** `POST /session/start` — mint (or resume) an attempt session. */
+export interface SessionStartResponse {
+  sessionId: string;
+  expiresAt: string;
+  resumed: boolean;
+  /** The session's own hosted web page. After a KYB submission it is the
+   *  rehydrated success screen with every key person's invite link — the
+   *  applicant's way back to those links once the app closes. */
+  url?: string;
+  /** Where the user got to, when resuming. Media references are already
+   *  pruned server-side of anything that has since expired. */
+  progress?: {
+    step?: string;
+    mediaIds?: Record<string, string>;
+    data?: Record<string, unknown>;
+  };
+}
+
+/** One person a submitted KYB application is still waiting on (the server's
+ *  reconciled view — registry discovery can add people the applicant never
+ *  listed, so this list supersedes the submit-time invites). */
+export interface AwaitingPersonPayload {
+  id: string;
+  name: string;
+  role: string;
+  ownershipPct: number | null;
+  /** ISO-2, or null when the register gave free text no flag matches. */
+  country: string | null;
+  status: 'verified' | 'failed' | 'submitted' | 'pending' | 'not_needed';
+  /** Null once their check is done, or when they never needed one. */
+  inviteUrl: string | null;
+  isApplicant: boolean;
+  /** A company completes a KYB application, not a KYC - the list labels it so. */
+  isCorporate?: boolean;
+}
+
+/** `GET /session/:sessionId/summary` — a submitted session, rebuilt server-side. */
+export interface SessionSummaryResponse {
+  status: 'completed';
+  /** False while registry discovery is still reconciling the people list. */
+  keyPeopleSettled?: boolean;
+  keyPeople: AwaitingPersonPayload[];
+}
+
+/** One officer as the register names them — the key-people prefill's input. */
+export interface RegistryOfficer {
+  name: string | null;
+  designation: string | null;
+  /** Everything else the register said about them (older servers omit these). */
+  roles?: string[] | null;
+  ownershipPct?: number | null;
+  email?: string | null;
+  isCorporate?: boolean | null;
+  registrationNumber?: string | null;
+}
+
+/** What the register holds about a company, when it answered. Everything is
+ *  nullable because no register answers all of it for every company. */
+export interface BusinessCompanyRecord {
+  name: string | null;
+  registrationNumber: string;
+  registrationDate: string | null;
+  typeOfEntity: string | null;
+  companyStatus: string | null;
+  address: string | null;
+  email: string | null;
+  phone: string | null;
+  taxId: string | null;
+  vatNumber: string | null;
+  natureOfBusiness: string | null;
+  city: string | null;
+  state: string | null;
+}
+
+/** `POST /business/select` — the paid registry check at selection. */
+export interface BusinessSelectResponse {
+  checked: boolean;
+  /** Why the pre-flight did not run (`checked: false`) — the submit-time lookup
+   *  still happens, so this is informational, never an error. */
+  reason?: string;
+  found?: boolean;
+  charged?: boolean;
+  business?: (BusinessCompanyRecord & { keyPeople: RegistryOfficer[] }) | null;
+}
+
+/** One candidate from the FREE name search — picking one is what runs the paid check. */
+export interface BusinessSearchHit {
+  name: string;
+  registrationNumber: string;
+  status?: string;
+}
+
+/** `GET /business/search` — find a business by name. */
+export interface BusinessSearchResponse {
+  results: BusinessSearchHit[];
+  /** Which source answered; a degraded fallback names itself here. */
+  source: string;
+}
+
+/** `GET /business/regions` — the registry regions of a split register. */
+export interface BusinessRegionsResponse {
+  regions: { code: string; name: string }[];
+}

package/src/services/api-verify-types.ts

@@ -10,7 +10,26 @@
 export interface VerifyRequest {
   country: string;
   idType: string;
+  /** The attempt session this run happened under — the verification adopts its
+   *  id, and a registry check paid at selection is not paid again at submit. */
+  sessionId?: string;
   idNumber?: string;
+  /**
+   * Multi-ID: every check in the run, in pick order (2–3). ONE verification
+   * comes back, judged by the workflow's pass policy. The top-level
+   * idType/idNumber mirror the first entry.
+   */
+  idChecks?: Array<{
+    idType: string;
+    idNumber?: string;
+    documentFront?: string;
+    documentBack?: string;
+    /** Each check's OWN document recording. */
+    documentFrontVideo?: string;
+    documentBackVideo?: string;
+    /** This check's own chip read — the chip belongs to a PARTICULAR document. */
+    nfc?: VerifyRequest['nfc'];
+  }>;
   /** The org's user reference → Entity.externalUserId at the seam (not matched). */
   userId?: string;
   userData?: {
@@ -50,6 +69,13 @@ export interface VerifyRequest {
     email?: string;
     phone?: string;
     website?: string;
+    /** Registry facts the applicant states (the extended collectCompanyInfo
+     *  fields) — where they differ from the register, that is the finding. */
+    dateOfIncorporation?: string;
+    taxId?: string;
+    vatNumber?: string;
+    companyType?: string;
+    natureOfBusiness?: string;
     /** Uploaded supporting documents (honoured only when the workflow's
      *  `business.documents` block configures them). */
     documents?: Array<{ type: string; mediaId: string }>;
@@ -77,7 +103,33 @@ export interface VerifyRequest {
    * signer — and only the server may conclude a chip is genuine. `chipAuth`
    * reports how the chip was unlocked and is informational.
    */
-  nfc?: { dg1: string; sod?: string; dg2?: string; chipAuth?: string };
+  nfc?: {
+    dg1: string;
+    sod?: string;
+    dg2?: string;
+    dg7?: string;
+    dg11?: string;
+    dg12?: string;
+    /**
+     * DG15 (the chip's Active-Authentication public key) and its signature over
+     * the challenge the server issued — the ANTI-CLONE proof. Passive
+     * authentication proves the issuing state signed this data; only these
+     * prove it is the chip they signed it onto. Verified server-side against a
+     * SOD-bound DG15: a client that checked its own chip could be patched.
+     */
+    dg15?: string;
+    aaChallengeId?: string;
+    aaSignature?: string;
+    chipAuth?: string;
+    /**
+     * WHY the session is on that protocol. A chip reading over BAC because it
+     * offers no PACE is nothing to act on; one reading over BAC because our
+     * PACE broke is a bug, and `chipAuth` alone cannot tell them apart.
+     * Diagnostic only — the server records it and never judges on it.
+     */
+    paceOutcome?: string;
+    paceDetail?: string;
+  };
   /** The workflow that drove this flow — attributes the submission to it. */
   workflowId?: string;
   /**

package/src/services/api.ts

@@ -1,10 +1,16 @@
 import { SDK_VERSION } from './deviceMetadata';
 import type {
+  BusinessRegionsResponse,
+  BusinessSearchResponse,
+  BusinessSelectResponse,
   ContactCheckResponse,
+  NfcChallengeResponse,
   ContactSendResponse,
   HealthResponse,
   MediaUploadType,
   SdkConfigResponse,
+  SessionStartResponse,
+  SessionSummaryResponse,
   UploadFile,
   UploadResponse,
   VerificationStatusResponse,
@@ -234,6 +240,18 @@ export function createKYCApi(baseUrl: string, apiKey: string) {
       });
     },
 
+    /**
+     * A fresh Active-Authentication challenge for a chip read — the nonce the
+     * chip signs to prove it is the original document rather than a copy of
+     * one. It has to come from the SERVER: a nonce the client chose would let
+     * a captured signature be replayed forever, which is the clone the check
+     * exists to catch. Best-effort by contract at every call site — a chip
+     * read without one is exactly the read we did before.
+     */
+    async nfcChallenge(): Promise<NfcChallengeResponse> {
+      return request<NfcChallengeResponse>('/nfc/challenge', { method: 'POST' });
+    },
+
     async config(signal?: AbortSignal): Promise<SdkConfigResponse> {
       return request<SdkConfigResponse>('/config', signal ? { signal } : {});
     },
@@ -250,6 +268,92 @@ export function createKYCApi(baseUrl: string, apiKey: string) {
       );
     },
 
+    /**
+     * Begin (or resume) a verification ATTEMPT session. Best-effort by
+     * contract: sessions power resumability, the dashboard's live attempt
+     * view, and the registry check at selection — verifying is never
+     * conditional on one existing.
+     */
+    async startSession(input: {
+      externalUserId?: string;
+      workflowId?: string;
+      /** Persistent device id — the anonymous-mount resume fallback. */
+      deviceRef?: string;
+    }): Promise<SessionStartResponse> {
+      return request<SessionStartResponse>('/session/start', {
+        method: 'POST',
+        body: JSON.stringify(input),
+      });
+    },
+
+    /**
+     * A submitted session, rebuilt server-side — the reconciled key-people
+     * list the success screen polls. Same body a hosted link reads by token,
+     * so mobile and hosted success screens cannot tell different stories
+     * about one application.
+     */
+    async sessionSummary(sessionId: string): Promise<SessionSummaryResponse> {
+      return request<SessionSummaryResponse>(`/session/${sessionId}/summary`);
+    },
+
+    /**
+     * Save where the user has got to. Losing a save costs some re-typing on
+     * resume and must never interrupt them now — callers swallow failures.
+     */
+    async saveProgress(sessionId: string, progress: unknown): Promise<void> {
+      await request(`/session/${encodeURIComponent(sessionId)}/progress`, {
+        method: 'PUT',
+        body: JSON.stringify(progress),
+      });
+    },
+
+    /**
+     * Find a business by name. FREE — no provider charge here or upstream, so
+     * the applicant may look as many times as they need. Throws on a provider
+     * failure so the caller can show "unavailable" rather than an empty list,
+     * which would read as "this business is not registered".
+     */
+    async businessSearch(params: {
+      country: string;
+      subdivisionCode?: string;
+      query: string;
+      limit?: number;
+    }): Promise<BusinessSearchResponse> {
+      const qs = new URLSearchParams({ country: params.country, query: params.query });
+      if (params.subdivisionCode) qs.set('subdivisionCode', params.subdivisionCode);
+      if (params.limit) qs.set('limit', String(params.limit));
+      return request<BusinessSearchResponse>(`/business/search?${qs.toString()}`);
+    },
+
+    /** Registry regions for a country. Empty when it has a single register. */
+    async businessRegions(country: string): Promise<BusinessRegionsResponse> {
+      return request<BusinessRegionsResponse>(
+        `/business/regions?country=${encodeURIComponent(country)}`,
+      );
+    },
+
+    /**
+     * The PAID registry check for the company the applicant identified, run at
+     * selection so the register's key people come back BEFORE the form asks
+     * for them. Never fails the flow: a short balance, unconfigured pricing or
+     * a spent lookup budget returns `checked: false` and the lookup happens at
+     * submit as before.
+     */
+    async businessSelect(body: {
+      sessionId: string;
+      country: string;
+      subdivisionCode?: string;
+      product?: string;
+      registrationNumber: string;
+      registrationName?: string;
+      sandboxOutcome?: string;
+    }): Promise<BusinessSelectResponse> {
+      return request<BusinessSelectResponse>('/business/select', {
+        method: 'POST',
+        body: JSON.stringify(body),
+      });
+    },
+
     async health(): Promise<HealthResponse> {
       // Public endpoint — no auth needed, but the shared headers are harmless.
       return request<HealthResponse>('/health');

package/src/services/deviceMetadata.ts

@@ -15,7 +15,7 @@ export type DeviceType = 'mobile' | 'tablet' | 'desktop' | 'unknown';
  * Single source of truth for the SDK version — also used by `services/api.ts`
  * for the `X-SDK-Version` header. Keep in sync with `package.json`.
  */
-export const SDK_VERSION = '2.4.0';
+export const SDK_VERSION = '2.5.0';
 
 export interface ReactNativeDeviceMetadata {
   sdkType: 'react-native';

package/src/services/errors.ts

@@ -74,8 +74,16 @@ export function mapToKycError(err: unknown, context: ErrorContext): KYCError {
               : err.message || 'This verification feature is currently disabled for your organization.';
       return new KYCError('feature_disabled', message);
     }
-    if (err.statusCode >= 500 || err.statusCode === 0) {
-      // Transient server error that survived retries.
+    // Nothing came back at all — DNS, routing, a refused connection. Kept
+    // SEPARATE from a 5xx: telling somebody the server errored when their
+    // request never arrived sends them looking through server logs for a
+    // request that was never made.
+    if (err.statusCode === 0) {
+      const code: KYCErrorCode = context === 'upload' ? 'upload_failed' : 'network_error';
+      return new KYCError(code, "Couldn't reach the server. Check your connection and try again.");
+    }
+    if (err.statusCode >= 500) {
+      // Transient server error that survived retries — the request DID arrive.
       const code: KYCErrorCode = context === 'upload' ? 'upload_failed' : 'network_error';
       return new KYCError(code, 'A server error occurred. Please try again in a moment.');
     }

package/src/services/workflowGate.ts

@@ -102,6 +102,7 @@ export async function resolveWorkflow(
         status: 'ready',
         idTypes: res.idTypes,
         branding: res.branding,
+        geoCountry: res.geoCountry,
         environment: res.environment,
         fatal: false,
       },

package/src/specs/MyazaFaceDetector.nitro.ts

@@ -51,4 +51,33 @@ export interface MyazaFaceDetector extends HybridObject<{ ios: 'swift'; android:
    * `faceCount: 0` when no face is present.
    */
   detectFace(frame: Frame): FaceResult;
+
+  /**
+   * Whether the detector can run RIGHT NOW.
+   *
+   * Android fetches its model through Google Play Services rather than bundling
+   * it (see android/build.gradle), so there is a window — first launch, or a
+   * device with no GMS at all — where detection cannot work. This MUST be
+   * checked before the camera opens: `detectFace` can only answer in
+   * `FaceResult`, where "model missing" and "no face in frame" are the same
+   * `faceCount: 0`, so relying on it would leave the user staring at
+   * "position your face" forever with nothing to explain why.
+   *
+   * iOS is always true — Apple Vision is a system framework with nothing to
+   * fetch.
+   */
+  isModelReady(): boolean;
+
+  /**
+   * Ask Play Services to download the model, resolving `true` once it is usable
+   * and `false` if it cannot be obtained (no GMS, no network, user declined).
+   *
+   * Call this EARLY — the SDK primes it at flow start, so the download overlaps
+   * the consent and ID-type screens and the model is warm by the time liveness
+   * runs. This mirrors the web SDK, which calls `primeFaceMesh()` on mount for
+   * exactly the same reason.
+   *
+   * Safe to call repeatedly; resolves immediately when already ready.
+   */
+  prepareModel(): Promise<boolean>;
 }

package/src/store/businessCheck.ts

@@ -0,0 +1,113 @@
+import type { BusinessCheckResult, KycState } from './state';
+import { EMPTY_BUSINESS_CHECK } from './state';
+
+// ---------------------------------------------------------------------------
+// The paid registry check at SELECTION, split from kycStore.ts (200-line rule).
+//
+// Run when the applicant confirms their company, so the register answers
+// BEFORE the details screen asks them to confirm what it said — and its key
+// people arrive before that step asks for them. Only a definitive "not on the
+// register" stops the flow: everything else (a short balance, an outage, a
+// spent lookup budget) continues and is checked at submission, exactly as it
+// was before this existed. Mirrors the web SDK's useBusinessCheck — keep the
+// two in lockstep.
+// ---------------------------------------------------------------------------
+
+type Set = (partial: Partial<KycState> | ((s: KycState) => Partial<KycState>)) => void;
+
+export async function runBusinessCheck(
+  get: () => KycState,
+  set: Set,
+): Promise<BusinessCheckResult> {
+  const s = get();
+  const registrationNumber = s.business.registrationNumber?.trim();
+  if (!registrationNumber) return { canContinue: true, company: null };
+
+  // Already checked this exact company — do not pay to be told again.
+  //
+  // Only a SETTLED answer is reused. 'unavailable' is deliberately not one: an
+  // outage said nothing about the company, so a repeat press retries the
+  // register rather than replaying the outage. And a remembered answer keeps
+  // its meaning — a stored not_found still blocks.
+  const normalized = registrationNumber.toUpperCase();
+  const settled =
+    s.businessCheck.status !== 'idle' &&
+    s.businessCheck.status !== 'checking' &&
+    s.businessCheck.status !== 'unavailable';
+  if (s.businessCheck.checkedNumber === normalized && settled) {
+    return {
+      canContinue: s.businessCheck.status !== 'not_found',
+      company: s.businessCheck.company,
+    };
+  }
+
+  // No session means no anchor for the charge, so there is nothing to run
+  // against. The check happens at submission, exactly as it did before.
+  if (!s.sessionId) return { canContinue: true, company: null };
+
+  set((cur) => ({
+    businessCheck: { ...cur.businessCheck, status: 'checking', checkedNumber: normalized },
+  }));
+  try {
+    const res = await s.api.businessSelect({
+      sessionId: s.sessionId,
+      country: s.business.country || s.config.business?.country || '',
+      ...(s.business.subdivisionCode.trim()
+        ? { subdivisionCode: s.business.subdivisionCode.trim() }
+        : {}),
+      ...(s.business.registrationName.trim()
+        ? { registrationName: s.business.registrationName.trim() }
+        : {}),
+      ...(s.business.product ? { product: s.business.product } : {}),
+      registrationNumber,
+    });
+
+    if (!res.checked) {
+      // The organisation could not be charged. Not the applicant's problem and
+      // not something they can fix, so it is not shown as an error — the flow
+      // continues and the check runs at submission. `lookup_limit_reached` is
+      // the one they DID cause, by re-picking company after company, and the
+      // one they can act on: check the number rather than keep trying.
+      set((cur) => ({
+        businessCheck: {
+          ...cur.businessCheck,
+          status: res.reason === 'lookup_limit_reached' ? 'limit_reached' : 'skipped',
+        },
+      }));
+      return { canContinue: true, company: null };
+    }
+
+    if (!res.found) {
+      // A definitive "not on the register" is worth stopping for: continuing
+      // would spend the applicant's time on documents for a company that will
+      // fail anyway.
+      set((cur) => ({
+        businessCheck: { ...cur.businessCheck, status: 'not_found', company: null, officers: [] },
+      }));
+      return { canContinue: false, company: null };
+    }
+
+    const { keyPeople, ...company } = res.business!;
+    set((cur) => ({
+      businessCheck: {
+        ...cur.businessCheck,
+        status: 'found',
+        company,
+        officers: keyPeople ?? [],
+      },
+    }));
+    return { canContinue: true, company };
+  } catch {
+    // A register outage is NOT "this company does not exist" — telling the
+    // applicant their business is unregistered on the strength of a 503 is the
+    // one wrong answer here. Retryable, and it never blocks: the check still
+    // happens at submission.
+    set((cur) => ({ businessCheck: { ...cur.businessCheck, status: 'unavailable' } }));
+    return { canContinue: true, company: null };
+  }
+}
+
+/** Back to square one — called when WHICH company this is about changes. */
+export function resetBusinessCheck(set: Set): void {
+  set({ businessCheck: { ...EMPTY_BUSINESS_CHECK } });
+}

package/src/store/derive.ts

@@ -76,6 +76,10 @@ export function stepOrderOptions(state: KycState): StepOrderOptions {
     hasPhoneVerification: config.phoneVerification?.enabled === true,
     hasPoa: hasProofOfAddressStep(config.proofOfAddress),
     hasQuestionnaire: hasActiveQuestionnaire(config.questionnaire),
+    // Present only on a session a reviewer sent back. Narrows the order to the
+    // steps they ticked, so somebody fixing one blurry photo is not walked
+    // through the whole flow again.
+    resubmit: config.resubmit,
   };
 }
 
@@ -148,6 +152,15 @@ export function businessSubmission(state: KycState): {
       ...(text(b.email) ? { email: text(b.email) } : {}),
       ...(text(b.phone) ? { phone: text(b.phone) } : {}),
       ...(text(b.website) ? { website: text(b.website) } : {}),
+      // The five registry facts, sent only when filled. The server drops any
+      // the workflow has switched off, so an over-send is validate-and-drop
+      // rather than an error, and an under-send is what the required-field
+      // 422 is for.
+      ...(text(b.dateOfIncorporation) ? { dateOfIncorporation: text(b.dateOfIncorporation) } : {}),
+      ...(text(b.taxId) ? { taxId: text(b.taxId) } : {}),
+      ...(text(b.vatNumber) ? { vatNumber: text(b.vatNumber) } : {}),
+      ...(text(b.companyType) ? { companyType: text(b.companyType) } : {}),
+      ...(text(b.natureOfBusiness) ? { natureOfBusiness: text(b.natureOfBusiness) } : {}),
       // Extras ride along ONLY when the workflow configures them — the server
       // ignores an unconfigured block, but sending one is a claim we did not
       // collect properly.
@@ -155,6 +168,8 @@ export function businessSubmission(state: KycState): {
         ? { documents: app.documents.map((d) => ({ type: d.type, mediaId: d.mediaId })) }
         : {}),
       ...(hasKeyPeopleCollection(config) && people.length > 0 ? { keyPeople: people } : {}),
+      // The FATF fallback, attested: no natural person qualifies as a UBO.
+      ...(app.uboUnidentifiable ? { uboUnidentifiable: true } : {}),
       ...(hasApplicantVerification(config) && app.applicantRole
         ? {
             applicant: {