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

package/src/screens/liveness/ShutterFlash.tsx

@@ -0,0 +1,25 @@
+import React, { useEffect, useRef } from 'react';
+import { Animated, Easing } from 'react-native';
+import { StyleAbsFill } from './constants';
+
+// The shutter: a white flash over the camera circle as the still is taken,
+// fading out over the beat the ring takes to close and go green. Mirrors the
+// web SDK's animate-capture-flash (600ms ease-out). Core Animated on the
+// native driver — opacity only — is the same recipe LightingBanner uses.
+export function ShutterFlash() {
+  const opacity = useRef(new Animated.Value(0.85)).current;
+  useEffect(() => {
+    Animated.timing(opacity, {
+      toValue: 0,
+      duration: 600,
+      easing: Easing.out(Easing.cubic),
+      useNativeDriver: true,
+    }).start();
+  }, [opacity]);
+  return (
+    <Animated.View
+      pointerEvents="none"
+      style={[StyleAbsFill, { backgroundColor: '#FFFFFF', opacity }]}
+    />
+  );
+}

package/src/screens/liveness/index.ts

@@ -3,6 +3,10 @@ export { StyleAbsFill, FRESH_FACE_TIMEOUT_MS, INSTRUCTION_HEIGHT } from './const
 export { LightingBanner } from './LightingBanner';
 export { resolveGuidance } from './resolveGuidance';
 export { ProgressDots } from './ProgressDots';
+export { CaptureRing } from './CaptureRing';
+export { ShutterFlash } from './ShutterFlash';
 export { SelfiePreview } from './SelfiePreview';
 export { useSelfieUpload } from './useSelfieUpload';
 export { LivenessComplete, LivenessFailed } from './LivenessOutcome';
+export { LivenessCamera } from './LivenessCamera';
+export { LivenessHandover, useSelfieAutoAdvance } from './LivenessHandover';

package/src/screens/liveness/useSelfieUpload.ts

@@ -44,12 +44,29 @@ export function useSelfieUpload(): SelfieUpload {
   const config = useKycConfig();
   const api = useKyc((s) => s.api);
   const setMediaId = useKyc((s) => s.setMediaId);
+  const setSelfiePreview = useKyc((s) => s.setSelfiePreview);
+  // The store-side progress report. The liveness step may hand over before
+  // the upload lands (the biometric scopes hide the review), so the submitted
+  // step waits on THIS rather than on this hook's local state.
+  const setSelfieUpload = useKyc((s) => s.setSelfieUpload);
+  const storedPreview = useKyc((s) => s.selfiePreviewUri);
+  const storedSelfieId = useKyc((s) => s.mediaIds.selfie);
 
-  const [selfieUri, setSelfieUri] = useState<string | null>(null);
+  // Hydrated from the STORE so leaving the step and returning lands on the
+  // review screen with the same selfie, exactly as document captures do. The
+  // setter writes through, keeping the store the source of truth.
+  const [selfieUri, setSelfieUriState] = useState<string | null>(storedPreview);
+  const setSelfieUri = useCallback(
+    (uri: string | null) => {
+      setSelfieUriState(uri);
+      setSelfiePreview(uri);
+    },
+    [setSelfiePreview],
+  );
   const [uploading, setUploading] = useState(false);
   const [retryInfo, setRetryInfo] = useState<{ attempt: number; total: number } | null>(null);
   const [uploadError, setUploadError] = useState<string | null>(null);
-  const selfieIdRef = useRef<string | null>(null);
+  const selfieIdRef = useRef<string | null>(storedSelfieId ?? null);
   const videoPathRef = useRef<string | null>(null);
 
   const uploadSelfieAndVideo = useCallback(
@@ -57,6 +74,7 @@ export function useSelfieUpload(): SelfieUpload {
       setUploading(true);
       setUploadError(null);
       setRetryInfo(null);
+      setSelfieUpload({ status: 'uploading', message: null });
       const onRetry = (attempt: number, total: number) => setRetryInfo({ attempt, total });
       try {
         const selfieId = await withRetry(
@@ -81,16 +99,18 @@ export function useSelfieUpload(): SelfieUpload {
         }
         setRetryInfo(null);
         setUploading(false);
+        setSelfieUpload({ status: 'done', message: null });
       } catch (err) {
         setRetryInfo(null);
         setUploading(false);
         const kycError = mapToKycError(err, 'upload');
         setUploadError(kycError.message);
+        setSelfieUpload({ status: 'failed', message: kycError.message });
         toast.show({ variant: 'error', title: 'Upload failed', message: kycError.message });
         safeReportError(config.onError, kycError);
       }
     },
-    [api, setMediaId, config.onError, toast],
+    [api, setMediaId, setSelfieUpload, config.onError, toast],
   );
 
   return {

package/src/screens/nfc/NfcScanIllustration.tsx

@@ -1,6 +1,6 @@
 import React, { useEffect, useRef, useState } from 'react';
 import { AccessibilityInfo, Animated, Easing, View } from 'react-native';
-import Svg, { Circle, Defs, G, Path, RadialGradient, Rect, Stop } from 'react-native-svg';
+import Svg, { Circle, G, Path, Rect } from 'react-native-svg';
 
 import { useTheme } from '../../components/runtime';
 
@@ -112,22 +112,6 @@ export function NfcScanIllustration(): React.ReactElement {
     // Same footprint as the web: full width up to 384 (`max-w-sm`), 320:240.
     <View style={{ width: '100%', maxWidth: 384, aspectRatio: 320 / 240, alignSelf: 'center' }}>
       <Svg width="100%" height="100%" viewBox="0 0 320 240">
-        <Defs>
-          {/* The field falls off with distance — the reason the document has
-              to be held CLOSE, said as a gradient instead of a caption. */}
-          <RadialGradient
-            id="kyc-nfc-field"
-            cx={COUPLING.x}
-            cy={COUPLING.y}
-            r={90}
-            gradientUnits="userSpaceOnUse"
-          >
-            <Stop offset="0" stopColor={colors.primary} stopOpacity={0.18} />
-            <Stop offset="0.55" stopColor={colors.primary} stopOpacity={0.06} />
-            <Stop offset="1" stopColor={colors.primary} stopOpacity={0} />
-          </RadialGradient>
-        </Defs>
-
         {/* ── The document, tucked BEHIND the phone: portrait, chip, MRZ. ── */}
         <G rotation={7} origin="212, 112">
           <Rect
@@ -224,7 +208,12 @@ export function NfcScanIllustration(): React.ReactElement {
         </G>
 
         {/* ── The field, over both objects. ── */}
-        <Circle cx={COUPLING.x} cy={COUPLING.y} r={90} fill="url(#kyc-nfc-field)" />
+        {/* The field falls off with distance — the reason the document has to
+            be held CLOSE. Flat concentric steps (no gradients in the flow,
+            house rule 2026-08-29). */}
+        <Circle cx={COUPLING.x} cy={COUPLING.y} r={90} fill={colors.primary} fillOpacity={0.04} />
+        <Circle cx={COUPLING.x} cy={COUPLING.y} r={56} fill={colors.primary} fillOpacity={0.07} />
+        <Circle cx={COUPLING.x} cy={COUPLING.y} r={28} fill={colors.primary} fillOpacity={0.12} />
         <Circle cx={COUPLING.x} cy={COUPLING.y} r={4.5} fill={colors.primary} />
         {WAVES.map((w, i) => (
           <AnimatedPath

package/src/screens/useAddressPhotoAttach.ts

@@ -0,0 +1,77 @@
+import { useCallback, useState } from 'react';
+import * as ImagePicker from 'expo-image-picker';
+
+import { isAcceptedAddressPhotoMimeType } from '../config/addressCollection';
+import { IMAGE_MAX_BYTES } from '../config/uploadLimits';
+
+// ---------------------------------------------------------------------------
+// Getting the door photo off the device — the address step's slim sibling of
+// usePoaAttach. Camera or photo library only: the door photo is a PICTURE of a
+// place, so there is no PDF/file case, and each pick closes the source sheet
+// before the picker opens.
+// ---------------------------------------------------------------------------
+
+/** What the picker handed back, so the screen can preview it. */
+export interface AddressPhotoPick {
+  uri: string;
+  mimeType: string | undefined;
+  name: string;
+}
+
+type UploadFn = (pick: AddressPhotoPick) => Promise<void>;
+
+export function useAddressPhotoAttach(
+  upload: UploadFn,
+  setError: (message: string) => void,
+): {
+  pick: () => void;
+  sheetOpen: boolean;
+  closeSheet: () => void;
+  choosePhoto: () => Promise<void>;
+  takePhoto: () => Promise<void>;
+} {
+  const [sheetOpen, setSheetOpen] = useState(false);
+  const pick = useCallback(() => setSheetOpen(true), []);
+  const closeSheet = useCallback(() => setSheetOpen(false), []);
+
+  const accept = useCallback(
+    async (asset: ImagePicker.ImagePickerAsset | undefined, fallbackName: string) => {
+      if (!asset) return;
+      if (typeof asset.fileSize === 'number' && asset.fileSize > IMAGE_MAX_BYTES) {
+        setError('Photo is too large (max 5 MB).');
+        return;
+      }
+      const mimeType = asset.mimeType ?? 'image/jpeg';
+      // The picker's media filter is advisory on some platforms, so what came
+      // back is re-checked rather than trusted.
+      if (!isAcceptedAddressPhotoMimeType(mimeType)) {
+        setError('Please choose a photo (JPEG, PNG or WebP).');
+        return;
+      }
+      await upload({ uri: asset.uri, mimeType, name: asset.fileName ?? fallbackName });
+    },
+    [setError, upload],
+  );
+
+  const takePhoto = useCallback(async () => {
+    setSheetOpen(false);
+    const permission = await ImagePicker.requestCameraPermissionsAsync();
+    if (!permission.granted) {
+      setError('Camera access is needed to photograph the entrance.');
+      return;
+    }
+    const result = await ImagePicker.launchCameraAsync({ mediaTypes: ['images'], quality: 1 });
+    await accept(result.canceled ? undefined : result.assets[0], 'address-photo.jpg');
+  }, [accept, setError]);
+
+  const choosePhoto = useCallback(async () => {
+    setSheetOpen(false);
+    const result = await ImagePicker.launchImageLibraryAsync({
+      mediaTypes: ['images'],
+      quality: 1,
+    });
+    await accept(result.canceled ? undefined : result.assets[0], 'address-photo.jpg');
+  }, [accept]);
+
+  return { pick, sheetOpen, closeSheet, choosePhoto, takePhoto };
+}

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-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
@@ -41,6 +43,34 @@ export interface UploadResponse {
   mediaId: string;
 }
 
+/** Which side of a document a capture check is about. */
+export type DocumentCaptureSide = 'front' | 'back';
+
+/**
+ * Ask whether an uploaded document photo will be readable, using the same
+ * detectors the server later decides the verification with.
+ */
+export interface DocumentCaptureCheckRequest {
+  mediaId: string;
+  side: DocumentCaptureSide;
+  country: string;
+  idType: string;
+  /** The workflow the submission will carry, when it carries one. */
+  workflowId?: string;
+  /** The attempt session from /session/start, when the flow has one. */
+  sessionId?: string;
+}
+
+/**
+ * `false` = looked and found nothing (ask for a retake); `true` = fine;
+ * `null` = not applicable, or the server could not look (treat as fine).
+ */
+export interface DocumentCaptureCheckResponse {
+  side: DocumentCaptureSide;
+  face: boolean | null;
+  barcode: boolean | null;
+}
+
 export interface KeyPersonInvite {
   keyPersonId: string;
   name: string;
@@ -142,6 +172,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 +286,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;
 }

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