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

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
@@ -142,6 +144,80 @@ export interface SdkConfigResponse {
    * 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;
 }
 
 /**
@@ -182,6 +258,20 @@ export interface WorkflowResolutionResponse {
    * 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;
 }
@@ -318,3 +408,5 @@ export interface BusinessSearchResponse {
 export interface BusinessRegionsResponse {
   regions: { code: string; name: string }[];
 }
+
+export * from './api-types-biometric';

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

@@ -45,9 +45,46 @@ export interface VerifyRequest {
     documentBackVideo?: string;
     livenessVideo?: string;
     proofOfAddress?: string;
+    /** Address Intelligence door photo (individual flows only). */
+    addressPhoto?: string;
   };
   /** Which kind of document the user said they uploaded as proof of address. */
   proofOfAddressType?: string;
+  /**
+   * Address Intelligence: the map pin the applicant dropped (+ the optional
+   * one-shot device fix taken at Continue). The server corroborates it; the
+   * SDK only collects. Sent only when the step ran and a pin was confirmed.
+   */
+  address?: {
+    lat: number;
+    lng: number;
+    accuracy?: number;
+    /**
+     * The line the applicant CONFIRMED (a search pick, or a reverse geocode
+     * they accepted). The server prefers it for the composed address over its
+     * own derivation, whose OSM coverage drops whole streets in our markets.
+     */
+    label?: string;
+    directions?: string;
+    propertyName?: string;
+    propertyNumber?: string;
+    /** A street the applicant typed because no map source knew it. */
+    street?: string;
+    /** The edit-details claims: unit + area/region corrections. */
+    unit?: string;
+    neighbourhood?: string;
+    city?: string;
+    state?: string;
+    postcode?: string;
+    /** Street View entrance frame — coordinates only; the server fetches the
+     *  image with its own key. Never written by this SDK (no panorama on
+     *  mobile), but a session begun on a hosted page can carry one. */
+    streetView?: { panoId: string; heading: number; pitch: number; fov: number };
+    deviceLat?: number;
+    deviceLng?: number;
+    deviceAccuracy?: number;
+    capturedAt?: 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

package/src/services/api.ts

@@ -1,5 +1,7 @@
 import { SDK_VERSION } from './deviceMetadata';
 import type {
+  AddressReverseResult,
+  AddressSearchHit,
   BusinessRegionsResponse,
   BusinessSearchResponse,
   BusinessSelectResponse,
@@ -8,6 +10,8 @@ import type {
   ContactSendResponse,
   HealthResponse,
   MediaUploadType,
+  PlaceSuggestion,
+  ResolvedPlace,
   SdkConfigResponse,
   SessionStartResponse,
   SessionSummaryResponse,
@@ -18,6 +22,7 @@ import type {
   VerifyResponse,
   WorkflowResolutionResponse,
 } from './api-types';
+import { biometricCalls } from './api-biometric';
 
 // 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.
@@ -70,9 +75,14 @@ function uriToBlob(uri: string, mimeType: string): Promise<Blob> {
     xhr.onload = () => {
       const blob = xhr.response as Blob | null;
       if (blob) {
-        // Ensure the part carries the right content-type even if the platform
-        // didn't infer one from the URI.
-        resolve(blob.type ? blob : blob.slice(0, blob.size, mimeType));
+        // ALWAYS re-type the part, never only when the platform inferred
+        // nothing. Its guess comes from the URI's extension and describes the
+        // file we PICKED, not the one we are sending: an iPhone gallery photo
+        // arrives as HEIC, gets transcoded to JPEG on the way here, and the
+        // part still went out labelled image/heic — which the server refuses,
+        // so most camera-roll uploads failed with a message that blamed the
+        // document. `mimeType` is the normalised type the bytes actually are.
+        resolve(blob.type === mimeType ? blob : blob.slice(0, blob.size, mimeType));
       } else {
         reject(new Error(`Could not read file at ${uri}`));
       }
@@ -157,6 +167,8 @@ export function createKYCApi(baseUrl: string, apiKey: string) {
   }
 
   return {
+    ...biometricCalls(request),
+
     /**
      * Single multipart upload: the local file is POSTed to our server, which
      * stores it and returns the `mediaId` referenced later by /verify.
@@ -279,6 +291,10 @@ export function createKYCApi(baseUrl: string, apiKey: string) {
       workflowId?: string;
       /** Persistent device id — the anonymous-mount resume fallback. */
       deviceRef?: string;
+      /** The same device block the submission sends, so the dashboard's
+       *  in-progress row shows the device and SDK from the moment the SDK
+       *  loads rather than after the applicant finishes (2026-09-08). */
+      device?: Record<string, unknown>;
     }): Promise<SessionStartResponse> {
       return request<SessionStartResponse>('/session/start', {
         method: 'POST',
@@ -354,6 +370,120 @@ export function createKYCApi(baseUrl: string, apiKey: string) {
       });
     },
 
+    /**
+     * Forward address search for the address step's search box.
+     *
+     * EXPLICIT SUBMIT ONLY — never call this per keystroke. The server's map
+     * source forbids autocomplete, and the request budget has to be spent on
+     * the query the person actually meant rather than on every prefix of it.
+     */
+    async addressSearch(
+      query: string,
+      country?: string | null,
+    ): Promise<{ results: AddressSearchHit[] }> {
+      const qs = new URLSearchParams({ q: query });
+      if (country) qs.set('country', country);
+      return request<{ results: AddressSearchHit[] }>(`/address/search?${qs.toString()}`);
+    },
+
+    /**
+     * The framed Street View entrance, as an image SOURCE the review card can
+     * hand straight to <Image>.
+     *
+     * The browser key never reaches this SDK (the framed page holds it), so
+     * the picture comes through the server, which does. Returned as a URL plus
+     * the auth header rather than fetched bytes: React Native's Image carries
+     * headers itself, which keeps Blob, FileReader and base64 out of a path
+     * that only has to draw a thumbnail. Mirrors the web SDK's
+     * addressStreetViewPreview, which returns a Blob because a browser <img>
+     * cannot send an Authorization header.
+     */
+    /**
+     * The pinned location as a PICTURE, for the review card.
+     *
+     * A confirmation screen wants a photograph of the place, not a second
+     * instrument: a live map there invites a drag that goes nowhere and
+     * carries the vendor's own controls over the SDK's chrome. Same shape as
+     * the Street View source above, and the same reason for it: the key lives
+     * on the server. lib/authed-image fetches it with the header — an <Image>
+     * given `source.headers` drops them on Android.
+     */
+    staticMapSource(view: {
+      lat: number;
+      lng: number;
+      zoom?: number;
+      width?: number;
+      height?: number;
+    }): { uri: string; headers: Record<string, string> } {
+      const qs = new URLSearchParams({
+        lat: String(view.lat),
+        lng: String(view.lng),
+        zoom: String(view.zoom ?? 16),
+        width: String(Math.round(view.width ?? 640)),
+        height: String(Math.round(view.height ?? 360)),
+      });
+      return { uri: `${base}/address/static-map?${qs.toString()}`, headers };
+    },
+
+    streetViewPreviewSource(frame: {
+      panoId: string;
+      heading: number;
+      pitch: number;
+      fov: number;
+    }): { uri: string; headers: Record<string, string> } {
+      const qs = new URLSearchParams({
+        panoId: frame.panoId,
+        heading: String(frame.heading),
+        pitch: String(frame.pitch),
+        fov: String(frame.fov),
+      });
+      return {
+        uri: `${base}/address/street-view-preview?${qs.toString()}`,
+        headers,
+      };
+    },
+
+    /** The street line for a pin, for the summary card after a locate or a
+     *  drag. Display only — it never decides anything. */
+    async addressReverse(lat: number, lng: number): Promise<AddressReverseResult> {
+      const qs = new URLSearchParams({ lat: String(lat), lng: String(lng) });
+      return request<AddressReverseResult>(`/address/reverse?${qs.toString()}`);
+    },
+
+    /**
+     * Places-backed as-you-type suggestions.
+     *
+     * `session` is ONE token per typing session: it is the billing unit, so
+     * Google bills per session rather than per keystroke. Mint it when the
+     * search screen opens, reuse it for every keystroke, and mint a fresh one
+     * after a details call — that call closes the session.
+     */
+    async addressAutocomplete(
+      query: string,
+      session: string,
+      country?: string | null,
+      near?: { lat: number; lng: number } | null,
+    ): Promise<{ suggestions: PlaceSuggestion[] }> {
+      const qs = new URLSearchParams({ q: query, session });
+      if (country) qs.set('country', country);
+      // The device fix, a RANKING bias so nearby streets come first: without
+      // it "Awolowo Road" in Calabar ranks against every Awolowo Road in the
+      // country. Mirrors the web SDK's api.addressAutocomplete.
+      if (near) {
+        qs.set('lat', String(near.lat));
+        qs.set('lng', String(near.lng));
+      }
+      return request<{ suggestions: PlaceSuggestion[] }>(`/address/autocomplete?${qs.toString()}`);
+    },
+
+    /** Resolve a picked suggestion to coordinates + structured pieces. */
+    async addressPlace(placeId: string, session: string): Promise<{ place: ResolvedPlace }> {
+      const qs = new URLSearchParams({ session });
+      return request<{ place: ResolvedPlace }>(
+        `/address/place/${encodeURIComponent(placeId)}?${qs.toString()}`,
+      );
+    },
+
     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.5.0';
+export const SDK_VERSION = '2.6.0';
 
 export interface ReactNativeDeviceMetadata {
   sdkType: 'react-native';