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

package/src/screens/usePoaAttach.ts

@@ -0,0 +1,121 @@
+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 { loadDocumentPicker } from '../services/documentPicker';
+
+// ---------------------------------------------------------------------------
+// Getting a proof-of-address document off the device.
+//
+// One drop zone, like the web SDK — tapping it asks WHERE the document is
+// coming from. Photographing a bill on the table and choosing a downloaded PDF
+// are still different pickers, but they're a choice made after the user has
+// committed to uploading, rather than two competing buttons that make the step
+// look like it wants two files.
+// ---------------------------------------------------------------------------
+
+/** What the picker handed back, so the screen can preview it. */
+export interface PoaPick {
+  uri: string;
+  mimeType: string | undefined;
+  name: string;
+}
+
+type UploadFn = (pick: PoaPick) => Promise<void>;
+
+export function usePoaAttach(
+  upload: UploadFn,
+  setError: (message: string) => void,
+): {
+  pick: () => void;
+  sheetOpen: boolean;
+  closeSheet: () => void;
+  choosePhoto: () => Promise<void>;
+  takePhoto: () => Promise<void>;
+  chooseFile: () => Promise<void>;
+} {
+  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;
+    },
+    [setError],
+  );
+
+  const takePhoto = useCallback(async () => {
+    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) return;
+    if (tooLarge(asset.fileSize)) return;
+    await upload({
+      uri: asset.uri,
+      mimeType: asset.mimeType ?? 'image/jpeg',
+      name: asset.fileName ?? 'proof-of-address.jpg',
+    });
+  }, [setError, tooLarge, upload]);
+
+  const choosePhoto = useCallback(async () => {
+    const result = await ImagePicker.launchImageLibraryAsync({
+      mediaTypes: ['images'],
+      quality: 1,
+    });
+    const asset = result.canceled ? undefined : result.assets[0];
+    if (!asset) return;
+    if (tooLarge(asset.fileSize)) return;
+    await upload({
+      uri: asset.uri,
+      mimeType: asset.mimeType ?? 'image/jpeg',
+      name: asset.fileName ?? 'proof-of-address.jpg',
+    });
+  }, [tooLarge, upload]);
+
+  const chooseFile = useCallback(async () => {
+    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 photo (JPEG, PNG or WebP) or a PDF.');
+      return;
+    }
+    if (tooLarge(asset.size)) return;
+    await upload({
+      uri: asset.uri,
+      mimeType: asset.mimeType,
+      name: asset.name ?? 'proof-of-address',
+    });
+  }, [setError, tooLarge, upload]);
+
+  // The "where is it?" question is the SDK's own sheet now, not
+  // ActionSheetIOS / Alert — both were stock OS dialogs dropped into the
+  // middle of a branded flow (and the Android alert didn't even read as a
+  // chooser). The hook only owns the STATE; the screen renders the
+  // MediaSourceSheet, because a hook can't render.
+  const [sheetOpen, setSheetOpen] = useState(false);
+  const pick = useCallback(() => setSheetOpen(true), []);
+  const closeSheet = useCallback(() => setSheetOpen(false), []);
+
+  return { pick, sheetOpen, closeSheet, choosePhoto, takePhoto, chooseFile };
+}

package/src/services/api-types.ts

@@ -0,0 +1,164 @@
+// ---------------------------------------------------------------------------
+// The HTTP contract: every request and response shape the SDK exchanges with
+// the server.
+//
+// Split from api.ts (200-line rule) so the client and the contract can be read
+// separately — and so a module that only needs a type does not pull in the
+// fetch/blob machinery. The server is the source of truth for all of it; these
+// are declarations, never validation.
+// ---------------------------------------------------------------------------
+
+// The /verify request is large enough to live on its own; re-exported so this
+// module remains the single view of the contract.
+export type * from './api-verify-types';
+
+/** Media kinds the SDK can upload — document/selfie photos plus best-effort videos. */
+export type MediaUploadType =
+  | 'document_front'
+  | 'document_back'
+  | 'selfie'
+  | 'document_front_video'
+  | 'document_back_video'
+  | 'liveness_video'
+  // 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';
+
+/**
+ * A file to upload, in React Native's multipart shape. `uri` points at a
+ * local file (camera capture / gallery pick); `name`/`type` populate the
+ * multipart part's filename + Content-Type.
+ */
+export interface UploadFile {
+  uri: string;
+  name?: string;
+  /** Raw mime type (codec params are stripped before sending). */
+  type?: string;
+}
+
+export interface UploadResponse {
+  mediaId: string;
+}
+
+export interface KeyPersonInvite {
+  keyPersonId: string;
+  name: string;
+  inviteUrl: string;
+}
+
+export interface VerifyResponse {
+  verificationId: string;
+  status: 'pending';
+  /**
+   * KYB with applicant verification: the KeyPerson row the applicant's OWN
+   * identity check must link back to, via `metadata.userId` on a second,
+   * ordinary individual submission.
+   */
+  applicantKeyPersonId?: string;
+  /** Per-person hosted-KYC links to hand to the people the applicant listed. */
+  keyPeopleInvites?: KeyPersonInvite[];
+}
+
+/**
+ * Minimal, publishable-safe status from `GET /api/kyc/status/:id` — no PII,
+ * scores, or result data; only the lifecycle state and an org-safe reason.
+ */
+export interface VerificationStatusResponse {
+  verificationId: string;
+  status: 'pending' | 'verified' | 'failed' | 'not_found' | 'error';
+  reason?: string | null;
+  reasonCode?: string | null;
+  createdAt: string;
+  completedAt?: string;
+}
+
+export interface SdkConfigIdType {
+  country: string;
+  idType: string;
+  /**
+   * Whether this document carries a readable eMRTD chip. Catalogue-driven
+   * server-side and intrinsic to the ID (not org-gated), so it is the
+   * authoritative answer to "should the chip step be offered".
+   */
+  supportsNfc?: boolean;
+  /**
+   * Display metadata the server sends per pair. Load-bearing for Global
+   * Documents: the SDK's curated table only covers the five gov-DB countries,
+   * so for any of the other ~235 these fields ARE the definition. Dropping
+   * them (as this type used to) left those countries with an empty ID list.
+   */
+  label?: string;
+  requiresDocumentCapture?: boolean;
+  scanSides?: string;
+  features: {
+    documentVerification: boolean;
+    livenessCheck: boolean;
+    govDbCheck: boolean;
+  };
+}
+
+/** Org branding configured server-side, returned with the SDK config. */
+export interface SdkConfigBranding {
+  logo?: string;
+  companyName?: string;
+  primaryColor?: string;
+}
+
+export interface SdkConfigResponse {
+  environment: 'DEVELOPMENT' | 'SANDBOX' | 'PRODUCTION';
+  idTypes: SdkConfigIdType[];
+  branding?: SdkConfigBranding;
+}
+
+/**
+ * The template half of a resolved workflow — exactly the keys a published flow
+ * may set. Loosely typed on purpose: the server is the contract, and an unknown
+ * key added there must not make an older SDK fail to parse. `mergeWorkflowConfig`
+ * only reads the keys it knows.
+ */
+export type WorkflowConfigPayload = Record<string, unknown>;
+
+/**
+ * A KYB workflow's mapped APPLICANT workflow (business.applicant.workflowId),
+ * resolved server-side: the individual workflow whose capture template
+ * overlays the applicant's own KYC leg, and whose id is stamped on that
+ * submission.
+ */
+export interface ApplicantWorkflowPayload {
+  id: string;
+  name: string;
+  version: number;
+  config: WorkflowConfigPayload;
+}
+
+/** Response from `GET /api/kyc/workflows/:workflowId` — one round trip hydrates
+ *  the SDK, so `/config` is skipped entirely. */
+export interface WorkflowResolutionResponse {
+  workflow: { id: string; name: string; version: number };
+  config: WorkflowConfigPayload;
+  environment: 'DEVELOPMENT' | 'SANDBOX' | 'PRODUCTION';
+  /** Org allowlist + per-ID feature flags (same shape as /config). */
+  idTypes: SdkConfigIdType[];
+  branding?: SdkConfigBranding;
+  /** KYB only: the mapped applicant workflow, when configured and resolvable. */
+  applicantWorkflow?: ApplicantWorkflowPayload | null;
+}
+
+export interface ContactSendResponse {
+  challengeId: string;
+  expiresAt: string;
+  deliveryChannel: string;
+}
+
+export interface ContactCheckResponse {
+  verified: boolean;
+  /** Single-use proof submitted with /verify as `contact.emailToken`/`phoneToken`. */
+  token: string;
+}
+
+export interface HealthResponse {
+  status: string;
+}
+
+// The mime types the server accepts (must mirror the server's upload allowlist).

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

@@ -0,0 +1,99 @@
+// ---------------------------------------------------------------------------
+// The /verify request.
+//
+// Split from api-types.ts (200-line rule) because it is the largest and most
+// consequential shape in the contract: every optional block on it corresponds
+// to a step the flow may or may not have run, and sending one the flow did not
+// collect is a claim we cannot support.
+// ---------------------------------------------------------------------------
+
+export interface VerifyRequest {
+  country: string;
+  idType: string;
+  idNumber?: string;
+  /** The org's user reference → Entity.externalUserId at the seam (not matched). */
+  userId?: string;
+  userData?: {
+    firstName?: string;
+    lastName?: string;
+    dateOfBirth?: string;
+  };
+  mediaIds: {
+    documentFront?: string;
+    documentBack?: string;
+    selfie?: string;
+    documentFrontVideo?: string;
+    documentBackVideo?: string;
+    livenessVideo?: string;
+    proofOfAddress?: string;
+  };
+  /** Which kind of document the user said they uploaded as proof of address. */
+  proofOfAddressType?: string;
+  /**
+   * Business (KYB) registry details. Its presence is what makes this a business
+   * submission — and the server REQUIRES a published KYB workflow for one, so
+   * this never appears without a `workflowId`.
+   */
+  business?: {
+    registrationNumber: string;
+    registrationName?: string;
+    product?: string;
+    /**
+     * Contact email for key-people verification — the server emails this
+     * address the invite links when the workflow's `keyPeople.invite.channel`
+     * is 'email' and a role needs full KYC. Sent only when non-empty.
+     */
+    contactEmail?: string;
+    /** Company profile (the collectCompanyInfo fields) — echoed on the org's
+     *  webhook and address-matched against the registry. */
+    address?: string;
+    email?: string;
+    phone?: string;
+    website?: string;
+    /** Uploaded supporting documents (honoured only when the workflow's
+     *  `business.documents` block configures them). */
+    documents?: Array<{ type: string; mediaId: string }>;
+    /** Applicant-declared directors & owners (≤20; `email` drives auto-sent
+     *  invites; honoured only when the workflow sets `keyPeople.collect`). */
+    keyPeople?: Array<{
+      name: string;
+      role: string;
+      email?: string;
+      /** The person's ISO-2 country — drives their verification link's country. */
+      country?: string;
+      ownershipPct?: number;
+      /** This entry IS the applicant (picked on the applicant-role step) —
+       *  the server merges it with the applicant row: one person, one KYC,
+       *  one screening, no invite. */
+      isApplicant?: boolean;
+    }>;
+    /** The applicant's declared role (+ optional name — the server backfills it
+     *  from their verified KYC when absent). */
+    applicant?: { role: string; name?: string };
+  };
+  /**
+   * eMRTD chip data, base64. The server runs PASSIVE AUTHENTICATION on it —
+   * hashing DG1 against the signed security object and verifying the document
+   * 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 };
+  /** The workflow that drove this flow — attributes the submission to it. */
+  workflowId?: string;
+  /**
+   * Single-use proofs from the contact-verification steps. The server drops an
+   * invalid or expired proof; a workflow that REQUIRES one 422s without it.
+   */
+  contact?: { emailToken?: string; phoneToken?: string };
+  /**
+   * Compliance answers, validated server-side against the PUBLISHED
+   * questionnaire definition. Sent without a workflow they are discarded —
+   * there is no definition to trust them against.
+   */
+  questionnaire?: Record<string, string | number | boolean | string[]>;
+  metadata: {
+    requestId: string;
+    device?: Record<string, unknown>;
+    [key: string]: unknown;
+  };
+}

package/src/services/api.ts

@@ -1,4 +1,21 @@
 import { SDK_VERSION } from './deviceMetadata';
+import type {
+  ContactCheckResponse,
+  ContactSendResponse,
+  HealthResponse,
+  MediaUploadType,
+  SdkConfigResponse,
+  UploadFile,
+  UploadResponse,
+  VerificationStatusResponse,
+  VerifyRequest,
+  VerifyResponse,
+  WorkflowResolutionResponse,
+} from './api-types';
+
+// The HTTP contract lives in ./api-types and is re-exported here, so importers
+// keep a single entry point for both the client and the shapes it exchanges.
+export * from './api-types';
 
 // ---------------------------------------------------------------------------
 // HTTP client — talks to the only endpoints the SDK calls (upload / verify /
@@ -80,107 +97,9 @@ async function handleResponse<T>(res: Response): Promise<T> {
   return data as T;
 }
 
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-/** Media kinds the SDK can upload — document/selfie photos plus best-effort videos. */
-export type MediaUploadType =
-  | 'document_front'
-  | 'document_back'
-  | 'selfie'
-  | 'document_front_video'
-  | 'document_back_video'
-  | 'liveness_video';
-
-/**
- * A file to upload, in React Native's multipart shape. `uri` points at a
- * local file (camera capture / gallery pick); `name`/`type` populate the
- * multipart part's filename + Content-Type.
- */
-export interface UploadFile {
-  uri: string;
-  name?: string;
-  /** Raw mime type (codec params are stripped before sending). */
-  type?: string;
-}
-
-export interface UploadResponse {
-  mediaId: string;
-}
-
-export interface VerifyRequest {
-  country: string;
-  idType: string;
-  idNumber?: string;
-  userData?: {
-    firstName?: string;
-    lastName?: string;
-    dateOfBirth?: string;
-  };
-  mediaIds: {
-    documentFront?: string;
-    documentBack?: string;
-    selfie?: string;
-    documentFrontVideo?: string;
-    documentBackVideo?: string;
-    livenessVideo?: string;
-  };
-  metadata: {
-    requestId: string;
-    device?: Record<string, unknown>;
-    [key: string]: unknown;
-  };
-}
-
-export interface VerifyResponse {
-  verificationId: string;
-  status: 'pending';
-}
-
-/**
- * Minimal, publishable-safe status from `GET /api/kyc/status/:id` — no PII,
- * scores, or result data; only the lifecycle state and an org-safe reason.
- */
-export interface VerificationStatusResponse {
-  verificationId: string;
-  status: 'pending' | 'verified' | 'failed' | 'not_found' | 'error';
-  reason?: string | null;
-  reasonCode?: string | null;
-  createdAt: string;
-  completedAt?: string;
-}
-
-export interface SdkConfigIdType {
-  country: string;
-  idType: string;
-  features: {
-    documentVerification: boolean;
-    livenessCheck: boolean;
-    govDbCheck: boolean;
-  };
-}
-
-/** Org branding configured server-side, returned with the SDK config. */
-export interface SdkConfigBranding {
-  logo?: string;
-  companyName?: string;
-  primaryColor?: string;
-}
-
-export interface SdkConfigResponse {
-  environment: 'DEVELOPMENT' | 'SANDBOX' | 'PRODUCTION';
-  idTypes: SdkConfigIdType[];
-  branding?: SdkConfigBranding;
-}
-
-export interface HealthResponse {
-  status: string;
-}
-
-// The mime types the server accepts (must mirror the server's upload allowlist).
 const IMAGE_MIME_TYPES = ['image/jpeg', 'image/png', 'image/webp'] as const;
 const VIDEO_MIME_TYPES = ['video/webm', 'video/mp4'] as const;
+const POA_MIME_TYPES = ['image/jpeg', 'image/png', 'image/webp', 'application/pdf'] as const;
 
 const MIME_EXTENSIONS: Record<string, string> = {
   'image/jpeg': 'jpg',
@@ -188,6 +107,7 @@ const MIME_EXTENSIONS: Record<string, string> = {
   'image/webp': 'webp',
   'video/webm': 'webm',
   'video/mp4': 'mp4',
+  'application/pdf': 'pdf',
 };
 
 /**
@@ -199,7 +119,12 @@ const MIME_EXTENSIONS: Record<string, string> = {
 function normalizeMimeType(rawType: string | undefined, type: MediaUploadType): string {
   const base = (rawType?.split(';')[0] ?? '').trim().toLowerCase();
   const isVideo = type.endsWith('_video');
-  const allowed: readonly string[] = isVideo ? VIDEO_MIME_TYPES : IMAGE_MIME_TYPES;
+  const isPoa = type === 'proof_of_address' || type === 'business_document';
+  const allowed: readonly string[] = isVideo
+    ? VIDEO_MIME_TYPES
+    : isPoa
+      ? POA_MIME_TYPES
+      : IMAGE_MIME_TYPES;
   if (allowed.includes(base)) return base;
   return isVideo ? 'video/mp4' : 'image/jpeg';
 }
@@ -277,8 +202,52 @@ export function createKYCApi(baseUrl: string, apiKey: string) {
       return request<VerificationStatusResponse>(`/status/${verificationId}`);
     },
 
-    async config(): Promise<SdkConfigResponse> {
-      return request<SdkConfigResponse>('/config');
+    /**
+     * Send a contact-verification OTP. Non-production environments never
+     * deliver a real message — the code is all zeros of `codeLength`, so an
+     * integrator can automate the flow for free.
+     */
+    async contactSend(body: {
+      channel: 'email' | 'phone';
+      destination: string;
+      /** ISO-2 default country for national phone formats (the flow's country). */
+      country?: string;
+      /** Phone delivery channel preference (default sms). */
+      via?: 'sms' | 'whatsapp';
+      /** Org-configured code length (server clamps 4–8). */
+      codeLength?: number;
+      /** Org-configured attempt budget (server clamps 1–5). */
+      maxAttempts?: number;
+    }): Promise<ContactSendResponse> {
+      return request<ContactSendResponse>('/contact/send', {
+        method: 'POST',
+        body: JSON.stringify(body),
+      });
+    },
+
+    /** Check a typed code. The returned `token` is a single-use proof that
+     *  rides the /verify submission. */
+    async contactCheck(body: { challengeId: string; code: string }): Promise<ContactCheckResponse> {
+      return request<ContactCheckResponse>('/contact/check', {
+        method: 'POST',
+        body: JSON.stringify(body),
+      });
+    },
+
+    async config(signal?: AbortSignal): Promise<SdkConfigResponse> {
+      return request<SdkConfigResponse>('/config', signal ? { signal } : {});
+    },
+
+    /**
+     * Resolve a published workflow. Returns the flow's config plus the org's
+     * ID-type allowlist and branding, so a `workflowId` mount needs no
+     * subsequent `/config` call.
+     */
+    async workflow(workflowId: string, signal?: AbortSignal): Promise<WorkflowResolutionResponse> {
+      return request<WorkflowResolutionResponse>(
+        `/workflows/${encodeURIComponent(workflowId)}`,
+        signal ? { signal } : {},
+      );
     },
 
     async health(): Promise<HealthResponse> {
@@ -289,3 +258,4 @@ export function createKYCApi(baseUrl: string, apiKey: string) {
 }
 
 export type KYCApi = ReturnType<typeof createKYCApi>;
+

package/src/services/cardCrop.ts

@@ -12,36 +12,51 @@ export interface CropRect {
   height: number;
 }
 
-const VIEW_AR = 3 / 4; // viewfinder box width ÷ height
+/** Legacy framed-viewfinder aspect — only correct when capture runs in the 3:4 box. */
+export const FRAMED_VIEW_AR = 3 / 4;
 const GUIDE_WIDTH_FRACTION = 0.88; // card width as a fraction of the box (overlay GW/VB_W)
 
 /**
- * Given the photo's pixel size and the guide `aspect` (width ÷ height), return
- * the card-guide crop rect in photo pixels:
- *   1. the cover-fit 3:4 box shows a centred 3:4 slice of the photo,
+ * Given the photo's pixel size, the guide `aspect` (width ÷ height), and the
+ * aspect of the box the preview ACTUALLY rendered in, return the card-guide
+ * crop rect in photo pixels:
+ *   1. the cover-fit box shows a centred `viewAr` slice of the photo,
  *   2. the guide is centred in that slice (88% wide, `aspect` ratio).
+ *
+ * `viewAr` is a parameter because assuming it was the bug: this math was
+ * written for the framed 3:4 viewfinder, and capture then moved to a
+ * FULL-SCREEN modal (~9:19.5) without the constant following. A cover-fit
+ * 3:4 slice of the photo is far wider than the slice a full-screen preview
+ * shows, so every review image came back ~1.6× wider than what the user had
+ * framed. The caller passes the MEASURED box aspect, so the crop and the
+ * preview agree by construction.
  */
-export function cardCropRect(imageW: number, imageH: number, aspect: number): CropRect {
+export function cardCropRect(
+  imageW: number,
+  imageH: number,
+  aspect: number,
+  viewAr: number = FRAMED_VIEW_AR,
+): CropRect {
   const photoAR = imageW / imageH;
   let visW: number;
   let visH: number;
   let offX: number;
   let offY: number;
-  if (photoAR > VIEW_AR) {
+  if (photoAR > viewAr) {
     visH = imageH;
-    visW = imageH * VIEW_AR;
+    visW = imageH * viewAr;
     offX = (imageW - visW) / 2;
     offY = 0;
   } else {
     visW = imageW;
-    visH = imageW / VIEW_AR;
+    visH = imageW / viewAr;
     offX = 0;
     offY = (imageH - visH) / 2;
   }
   const leftFraction = (1 - GUIDE_WIDTH_FRACTION) / 2;
   // card height ÷ box height = (cardWidthFrac · boxWidth / aspect) / boxHeight,
-  // and boxWidth ÷ boxHeight = VIEW_AR.
-  const heightFraction = (GUIDE_WIDTH_FRACTION * VIEW_AR) / aspect;
+  // and boxWidth ÷ boxHeight = viewAr.
+  const heightFraction = (GUIDE_WIDTH_FRACTION * viewAr) / aspect;
   const topFraction = (1 - heightFraction) / 2;
   return {
     originX: offX + leftFraction * visW,