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

package/src/screens/useAwaitingPeople.ts

@@ -0,0 +1,90 @@
+import { useEffect, useState } from 'react';
+import { AppState } from 'react-native';
+import type { KYCApi } from '../services/api';
+import type { AwaitingPersonPayload } from '../services/api-types';
+
+// The SERVER's list of who a submitted KYB application is waiting on — mirrors
+// the web SDK's use-awaiting-people 1:1.
+//
+// MEMBERSHIP settles once: registry discovery runs after submission and can
+// add people the applicant never listed, so nothing renders until the server
+// says it has finished (`keyPeopleSettled`). A list shown earlier is one
+// director short and would be contradicted moments later.
+//
+// STATUS stays live: the people named go and verify after this screen is first
+// shown, so once settled the list re-reads slowly while anybody still owes a
+// check — and re-reads on foreground, which is exactly when a stale badge
+// would be noticed.
+
+/** How often to re-ask while the server says it is still reconciling. */
+const RETRY_MS = 1500;
+/** How long to wait before showing whatever there is (discovery's final write
+ *  is best-effort; a spinner forever is worse than a list that might be short). */
+const GIVE_UP_MS = 15_000;
+/** Status-refresh cadence once settled, while anybody owes a check. */
+const POLL_MS = 20_000;
+
+function anyoneStillOwes(people: AwaitingPersonPayload[]): boolean {
+  return people.some(
+    (p) => p.status === 'pending' || p.status === 'submitted' || p.status === 'failed',
+  );
+}
+
+export function useAwaitingPeople(
+  api: KYCApi,
+  sessionId: string | null,
+  enabled: boolean,
+): AwaitingPersonPayload[] | null {
+  const [people, setPeople] = useState<AwaitingPersonPayload[] | null>(null);
+
+  useEffect(() => {
+    if (!sessionId || !enabled) return undefined;
+    let cancelled = false;
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    let committed = false;
+    const startedAt = Date.now();
+
+    const read = async (): Promise<void> => {
+      if (cancelled) return;
+      const summary = await api.sessionSummary(sessionId).catch(() => null);
+      if (cancelled) return;
+      const expired = Date.now() - startedAt > GIVE_UP_MS;
+
+      if (summary && (summary.keyPeopleSettled !== false || expired)) {
+        committed = true;
+        setPeople(summary.keyPeople);
+        if (anyoneStillOwes(summary.keyPeople)) {
+          timer = setTimeout(() => void read(), POLL_MS);
+        }
+        return;
+      }
+      if (committed) {
+        // One failed refresh must not end the updates: the list on screen is
+        // still true, only a little older.
+        timer = setTimeout(() => void read(), POLL_MS);
+        return;
+      }
+      if (expired) {
+        // Nothing readable at all — leave the list absent rather than empty,
+        // which would claim there is nobody to verify.
+        return;
+      }
+      timer = setTimeout(() => void read(), RETRY_MS);
+    };
+
+    const sub = AppState.addEventListener('change', (state) => {
+      if (state !== 'active') return;
+      if (timer) clearTimeout(timer);
+      void read();
+    });
+
+    void read();
+    return () => {
+      cancelled = true;
+      if (timer) clearTimeout(timer);
+      sub.remove();
+    };
+  }, [api, sessionId, enabled]);
+
+  return people;
+}

package/src/screens/useBusinessDocumentAttach.ts

@@ -0,0 +1,93 @@
+import { useCallback } from 'react';
+import * as ImagePicker from 'expo-image-picker';
+
+import type { ResolvedBusinessDocumentType } from '../config/businessSteps';
+import { isAcceptedPoaMimeType, POA_ACCEPTED_MIME_TYPES } from '../config/proofOfAddress';
+import { uploadSizeError } from '../config/uploadLimits';
+import { loadDocumentPicker } from '../services/documentPicker';
+
+// ---------------------------------------------------------------------------
+// Getting a company document off the device — the business-documents step's
+// twin of usePoaAttach (extracted from BusinessDocumentsStep, 200-line rule).
+// Three sources, one shape handed to the step's uploader. Every pick is judged
+// against the shared upload caps BEFORE anything is compressed or sent, so
+// the refusal names the file that was chosen (images 5 MB, PDFs 15 MB).
+// ---------------------------------------------------------------------------
+
+export type AttachBusinessDocument = (
+  slot: ResolvedBusinessDocumentType,
+  uri: string,
+  mimeType: string | undefined,
+  name: string,
+) => Promise<void>;
+
+type Pick = (slot: ResolvedBusinessDocumentType) => Promise<void>;
+
+export function useBusinessDocumentAttach(
+  attach: AttachBusinessDocument,
+  setError: (message: string) => void,
+): { takePhoto: Pick; choosePhoto: Pick; chooseFile: Pick } {
+  const tooLarge = useCallback(
+    (mime: string | undefined, size: number | undefined): boolean => {
+      const message = uploadSizeError(mime, size);
+      if (message) setError(message);
+      return message !== null;
+    },
+    [setError],
+  );
+
+  const takePhoto = useCallback<Pick>(
+    async (slot) => {
+      const permission = await ImagePicker.requestCameraPermissionsAsync();
+      if (!permission.granted) {
+        setError('Camera access is needed to photograph the document.');
+        return;
+      }
+      const result = await ImagePicker.launchCameraAsync({ mediaTypes: ['images'], quality: 1 });
+      const asset = result.canceled ? undefined : result.assets[0];
+      if (!asset || tooLarge(asset.mimeType, asset.fileSize)) return;
+      // A FRIENDLY name, not the picker's temp junk — camera/library assets
+      // carry generated names; the slot key says what the file IS.
+      await attach(slot, asset.uri, asset.mimeType ?? 'image/jpeg', `${slot.key}.jpg`);
+    },
+    [attach, setError, tooLarge],
+  );
+
+  const choosePhoto = useCallback<Pick>(
+    async (slot) => {
+      const result = await ImagePicker.launchImageLibraryAsync({ mediaTypes: ['images'], quality: 1 });
+      const asset = result.canceled ? undefined : result.assets[0];
+      if (!asset || tooLarge(asset.mimeType, asset.fileSize)) return;
+      await attach(slot, asset.uri, asset.mimeType ?? 'image/jpeg', `${slot.key}.jpg`);
+    },
+    [attach, tooLarge],
+  );
+
+  const chooseFile = useCallback<Pick>(
+    async (slot) => {
+      const picker = loadDocumentPicker();
+      if (!picker) {
+        setError('Choosing a file is not available in this app. Please photograph the document.');
+        return;
+      }
+      const result = await picker.getDocumentAsync({
+        type: [...POA_ACCEPTED_MIME_TYPES],
+        copyToCacheDirectory: true,
+        multiple: false,
+      });
+      const asset = result.canceled ? undefined : result.assets?.[0];
+      if (!asset) return;
+      // The picker's `type` filter is advisory on some platforms, so what came
+      // back is re-checked rather than trusted.
+      if (!isAcceptedPoaMimeType(asset.mimeType)) {
+        setError('Please choose a PDF, JPG or PNG file.');
+        return;
+      }
+      if (tooLarge(asset.mimeType, asset.size)) return;
+      await attach(slot, asset.uri, asset.mimeType, asset.name ?? slot.key);
+    },
+    [attach, setError, tooLarge],
+  );
+
+  return { takePhoto, choosePhoto, chooseFile };
+}

package/src/screens/usePoaAttach.ts

@@ -1,11 +1,8 @@
 import { useCallback, useState } from 'react';
 import * as ImagePicker from 'expo-image-picker';
 
-import {
-  isAcceptedPoaMimeType,
-  POA_ACCEPTED_MIME_TYPES,
-  POA_MAX_BYTES,
-} from '../config/proofOfAddress';
+import { isAcceptedPoaMimeType, POA_ACCEPTED_MIME_TYPES } from '../config/proofOfAddress';
+import { uploadSizeError } from '../config/uploadLimits';
 import { loadDocumentPicker } from '../services/documentPicker';
 
 // ---------------------------------------------------------------------------
@@ -38,13 +35,13 @@ export function usePoaAttach(
   takePhoto: () => Promise<void>;
   chooseFile: () => Promise<void>;
 } {
+  // Judged against the shared caps BEFORE anything is compressed or sent, so
+  // the refusal names the file that was chosen (images 5 MB, PDFs 15 MB).
   const tooLarge = useCallback(
-    (size: number | undefined): boolean => {
-      if (typeof size === 'number' && size > POA_MAX_BYTES) {
-        setError('File is too large (max 20MB).');
-        return true;
-      }
-      return false;
+    (mime: string | undefined, size: number | undefined): boolean => {
+      const message = uploadSizeError(mime, size);
+      if (message) setError(message);
+      return message !== null;
     },
     [setError],
   );
@@ -58,7 +55,7 @@ export function usePoaAttach(
     const result = await ImagePicker.launchCameraAsync({ mediaTypes: ['images'], quality: 1 });
     const asset = result.canceled ? undefined : result.assets[0];
     if (!asset) return;
-    if (tooLarge(asset.fileSize)) return;
+    if (tooLarge(asset.mimeType, asset.fileSize)) return;
     await upload({
       uri: asset.uri,
       mimeType: asset.mimeType ?? 'image/jpeg',
@@ -73,7 +70,7 @@ export function usePoaAttach(
     });
     const asset = result.canceled ? undefined : result.assets[0];
     if (!asset) return;
-    if (tooLarge(asset.fileSize)) return;
+    if (tooLarge(asset.mimeType, asset.fileSize)) return;
     await upload({
       uri: asset.uri,
       mimeType: asset.mimeType ?? 'image/jpeg',
@@ -97,10 +94,10 @@ export function usePoaAttach(
     // The picker's `type` filter is advisory on some platforms, so what came
     // back is re-checked rather than trusted.
     if (!isAcceptedPoaMimeType(asset.mimeType)) {
-      setError('Please choose a photo (JPEG, PNG or WebP) or a PDF.');
+      setError('Please choose a PDF, JPG or PNG file.');
       return;
     }
-    if (tooLarge(asset.size)) return;
+    if (tooLarge(asset.mimeType, asset.size)) return;
     await upload({
       uri: asset.uri,
       mimeType: asset.mimeType,

package/src/services/api-biometric.ts

@@ -0,0 +1,37 @@
+import type {
+  BiometricAuthRequest,
+  BiometricAuthResponse,
+  BiometricStatusResponse,
+} from './api-types-biometric';
+
+// ---------------------------------------------------------------------------
+// The biometric re-authentication calls, split out of createKYCApi (200-line
+// rule). Given the client's own `request`, so they ride the same base URL,
+// bearer key, SDK-version header and error mapping as everything else.
+// ---------------------------------------------------------------------------
+
+export type JsonRequest = <T>(path: string, init?: RequestInit) => Promise<T>;
+
+export function biometricCalls(request: JsonRequest) {
+  return {
+    /**
+     * Re-authenticate a verified user by matching a live selfie 1:1 against
+     * their KYC enrollment reference. Publishable-safe. Uniform 404
+     * `not_enrolled` — a missing entity, a business entity and no template
+     * all answer the same, so nothing can be probed.
+     */
+    async authenticate(body: BiometricAuthRequest): Promise<BiometricAuthResponse> {
+      return request<BiometricAuthResponse>('/biometric/authenticate', {
+        method: 'POST',
+        body: JSON.stringify(body),
+      });
+    },
+
+    /** Whether a user is enrolled for face re-auth (whether to OFFER it). */
+    async getBiometricStatus(externalUserId: string): Promise<BiometricStatusResponse> {
+      return request<BiometricStatusResponse>(
+        `/biometric/status/${encodeURIComponent(externalUserId)}`,
+      );
+    },
+  };
+}

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

@@ -0,0 +1,41 @@
+// ---------------------------------------------------------------------------
+// Biometric re-authentication wire shapes — a mirror of the web SDK's
+// services/api.ts (keep the two in lockstep). Publishable-safe: the verdict,
+// a confidence, and a single-use proof token. No PII.
+// ---------------------------------------------------------------------------
+
+/** What the SDK asserts about the liveness run that produced the selfie. */
+export interface BiometricLivenessClaim {
+  mode: 'gestures' | 'flash' | 'both';
+  passed: boolean;
+}
+
+/** Request body for `POST /api/kyc/biometric/authenticate`. */
+export interface BiometricAuthRequest {
+  /** The org's user reference (Entity.externalUserId) being re-authenticated. */
+  externalUserId: string;
+  /** A mediaId from `upload(file, 'selfie')` — the live selfie. */
+  selfie: string;
+  liveness?: BiometricLivenessClaim;
+}
+
+/**
+ * Response from `POST /api/kyc/biometric/authenticate`. `token` is present
+ * only on `authenticated` — redeem it from your backend with a secret key at
+ * `/biometric/verify-proof`.
+ */
+export interface BiometricAuthResponse {
+  authenticated: boolean;
+  status: 'authenticated' | 'no_match' | 'liveness_failed';
+  confidence: number | null;
+  live: boolean;
+  attemptId: string;
+  token?: string;
+}
+
+/** Response from `GET /api/kyc/biometric/status/:externalUserId`. */
+export interface BiometricStatusResponse {
+  enrolled: boolean;
+  enrolledAt?: string;
+  lastAuthenticatedAt?: string | null;
+}

package/src/services/api-types.ts

@@ -23,7 +23,9 @@ export type MediaUploadType =
   // The two kinds that accept a PDF — a proof of address is usually a
   // downloaded statement, and company paperwork is almost always a scan.
   | 'proof_of_address'
-  | 'business_document';
+  | 'business_document'
+  // Address Intelligence door / premises photo (image only).
+  | 'address_photo';
 
 /**
  * A file to upload, in React Native's multipart shape. `uri` points at a
@@ -47,9 +49,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 +91,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 +136,88 @@ 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;
+  /** Whether the platform has a forward-search backend. Gates the whole
+   *  address-search step; absent means no search screen, never an error. */
+  addressSearch?: boolean;
+  /** Which backend: 'autocomplete' (Places, as-you-type) or 'basic'
+   *  (explicit submit). Absent when addressSearch is false. */
+  addressSearchMode?: 'autocomplete' | 'basic';
+  /**
+   * The framed Google-map picker page (OUR hosted /embed/map + a signed APP
+   * grant), for a WebView. Absent when the platform holds no Maps key — the
+   * built-in OSM picker is the fallback every map failure degrades to.
+   */
+  mapsFrameUrl?: string | null;
+}
+
+// ── Address search / reverse geocoding ──────────────────────────────────────
+//
+// Every one of these may fail, and every failure degrades to "place the pin by
+// hand" — never to a blocked flow. Shapes mirror the web SDK's services/api.ts.
+
+/** The pin's address broken down — what the details sheet displays as rows. */
+export interface AddressParts {
+  street?: string | null;
+  area?: string | null;
+  city?: string | null;
+  state?: string | null;
+  postcode?: string | null;
+  /**
+   * ISO-2 of the pin's OWN country, from the geocoder. On the address scope
+   * the declared country follows it (lib/country-adoption.ts); it is never a
+   * row in the sheet, which shows the country the flow declared.
+   */
+  country?: string | null;
+}
+
+export interface AddressReverseResult {
+  line: string | null;
+  road: string | null;
+  parts?: AddressParts | null;
+}
+
+/** One candidate from the basic (explicit-submit) forward search. */
+export interface AddressSearchHit {
+  label: string;
+  lat: number;
+  lng: number;
+  houseNumber: string | null;
+  road: string | null;
+  /** ISO-2 of the hit's own country (the declaration derives from it). */
+  country?: string | null;
+}
+
+/** One Places autocomplete suggestion. */
+export interface PlaceSuggestion {
+  placeId: string;
+  mainText: string;
+  secondaryText: string;
+}
+
+/** A picked suggestion, resolved to coordinates + structured pieces. */
+export interface ResolvedPlace {
+  lat: number;
+  lng: number;
+  houseNumber: string | null;
+  road: string | null;
+  formatted: string | null;
+  area?: string | null;
+  city?: string | null;
+  state?: string | null;
+  postcode?: string | null;
+  /**
+   * ISO-2 of the picked address's own country — the declaration derives from
+   * it on the address scope (a pick is the applicant's own statement).
+   */
+  country?: string | null;
 }
 
 /**
@@ -141,6 +250,28 @@ 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;
+  /**
+   * The address-search availability flags, when the resolution route carries
+   * them.
+   *
+   * A `workflowId` mount skips `/config` entirely, so these are the only route
+   * by which such a mount could learn a search backend exists. The server does
+   * not serve them here yet (only `/config` and the hosted bootstrap do), which
+   * is why they degrade to "no search screen" rather than an error.
+   */
+  addressSearch?: boolean;
+  addressSearchMode?: 'autocomplete' | 'basic';
+  /** The framed Google-map picker page, when the route carries one (see
+   *  SdkConfigResponse.mapsFrameUrl). */
+  mapsFrameUrl?: string | null;
   /** KYB only: the mapped applicant workflow, when configured and resolvable. */
   applicantWorkflow?: ApplicantWorkflowPayload | null;
 }
@@ -157,8 +288,125 @@ 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 }[];
+}
+
+export * from './api-types-biometric';