@koraidv/react 1.7.10 → 1.8.0

package/dist/index.d.mts

@@ -55,6 +55,16 @@ interface VerificationState {
     completedChallenges: number;
     isLoading: boolean;
     error: KoraError | null;
+    /**
+     * Transient feedback message for the last liveness challenge that
+     * the backend rejected. Set by submitChallenge when the server
+     * returns passed:false; LivenessScreen renders it inline so the
+     * user knows WHY their attempt failed (the v1.7.x behavior was to
+     * silently re-arm the same challenge — confusing). Cleared the
+     * moment the user moves to the next challenge or the same one
+     * passes on retry.
+     */
+    lastChallengeError: string | null;
 }
 /**
  * useKoraIDV hook return value
@@ -67,7 +77,7 @@ interface UseKoraIDVReturn {
     /**
      * Start a new verification
      */
-    startVerification: (externalId: string, tier?: string) => Promise<void>;
+    startVerification: (externalId: string, tier?: string, expectedFirstName?: string, expectedLastName?: string) => Promise<void>;
     /**
      * Resume an existing verification
      */
@@ -142,6 +152,28 @@ interface VerificationFlowProps {
     externalId: string;
     tier?: 'basic' | 'standard' | 'enhanced';
     documentTypes?: DocumentType[];
+    /**
+     * Optional name-match inputs. When set, the backend compares the
+     * OCR'd names on the document against these values and surfaces a
+     * real `scores.nameMatch` percentage on the verification result —
+     * the ResultScreen's "Name Match" row shows real PASS/FAIL instead
+     * of the always-0% / always-FAIL it shows when these aren't passed.
+     *
+     * Wire from your user record at mount time, e.g.
+     *   `<VerificationFlow expectedFirstName={user.firstName} ... />`
+     *
+     * Mirrors iOS's
+     * `KoraIDV.startVerification(expectedFirstName:expectedLastName:)`.
+     */
+    expectedFirstName?: string;
+    expectedLastName?: string;
+    /**
+     * Whether to render Visual Guide illustrations above the capture +
+     * liveness viewfinders (default true). Set false for a plain text-
+     * only flow. Matches the same flag iOS exposes via `showVisualGuides`
+     * on Configuration; Android has had it since v1.3.0.
+     */
+    showVisualGuides?: boolean;
     onComplete?: (verification: Verification) => void;
     onError?: (error: KoraError) => void;
     onCancel?: () => void;
@@ -151,7 +183,7 @@ interface VerificationFlowProps {
 /**
  * Complete verification flow component
  */
-declare function VerificationFlow({ externalId, tier, documentTypes, onComplete, onError, onCancel, className, style, }: VerificationFlowProps): react_jsx_runtime.JSX.Element;
+declare function VerificationFlow({ externalId, tier, documentTypes, expectedFirstName, expectedLastName, showVisualGuides, onComplete, onError, onCancel, className, style, }: VerificationFlowProps): react_jsx_runtime.JSX.Element;
 
 interface ConsentScreenProps {
     onAccept: () => void;
@@ -187,14 +219,18 @@ interface DocumentCaptureScreenProps {
     onQualityCheck?: (imageData: Blob) => Promise<DocumentQualityResponse>;
     onCapture: (imageData: Blob) => Promise<boolean>;
     onCancel: () => void;
+    /** Render Visual Guide illustration above the capture area (v1.8.0). */
+    showVisualGuides?: boolean;
 }
-declare function DocumentCaptureScreen({ side, documentType, requiresBack, onQualityCheck, onCapture, onCancel, }: DocumentCaptureScreenProps): react_jsx_runtime.JSX.Element;
+declare function DocumentCaptureScreen({ side, documentType, requiresBack, onQualityCheck, onCapture, onCancel, showVisualGuides, }: DocumentCaptureScreenProps): react_jsx_runtime.JSX.Element;
 
 interface SelfieCaptureScreenProps {
     onCapture: (imageData: Blob) => Promise<boolean>;
     onCancel: () => void;
+    /** Render Visual Guide above the selfie viewfinder (v1.8.0). */
+    showVisualGuides?: boolean;
 }
-declare function SelfieCaptureScreen({ onCapture, onCancel }: SelfieCaptureScreenProps): react_jsx_runtime.JSX.Element;
+declare function SelfieCaptureScreen({ onCapture, onCancel, showVisualGuides }: SelfieCaptureScreenProps): react_jsx_runtime.JSX.Element;
 
 interface LivenessScreenProps {
     session: LivenessSession | null;
@@ -204,6 +240,16 @@ interface LivenessScreenProps {
     onStart: () => Promise<void>;
     onComplete: () => Promise<any>;
     onCancel: () => void;
+    /**
+     * Inline retake feedback for the LAST attempt the backend rejected.
+     * Surfaced in the prompt card during the 'preparing' phase of the
+     * next attempt so the user knows what went wrong before they try
+     * again. Cleared by the hook when a challenge passes or a new
+     * challenge starts.
+     */
+    lastChallengeError?: string | null;
+    /** Render per-challenge VisualGuide above the instruction (v1.8.0). */
+    showVisualGuides?: boolean;
 }
 /**
  * Web liveness screen with a real front-facing camera.
@@ -236,7 +282,7 @@ interface LivenessScreenProps {
  * themselves against a countdown. Today's ship is "real camera, real
  * frames, server decides," which is the parity floor.
  */
-declare function LivenessScreen({ session, currentChallenge, completedChallenges, onChallengeComplete, onStart, onComplete, onCancel, }: LivenessScreenProps): react_jsx_runtime.JSX.Element;
+declare function LivenessScreen({ session, currentChallenge, completedChallenges, onChallengeComplete, onStart, onComplete, onCancel, lastChallengeError, showVisualGuides, }: LivenessScreenProps): react_jsx_runtime.JSX.Element;
 
 type ResultPageMode = 'detailed' | 'simplified';
 interface ResultScreenProps {
@@ -323,8 +369,26 @@ interface ProcessingStep {
     status: 'done' | 'active' | 'pending';
 }
 interface ProcessingScreenProps {
-    steps: ProcessingStep[];
+    /**
+     * Optional explicit steps. When provided, the screen renders them as-
+     * is (the v1.7.x behavior — kept for backwards compat with any caller
+     * passing a custom array).
+     */
+    steps?: ProcessingStep[];
+    /**
+     * When true (and `steps` is omitted), the screen auto-advances
+     * through a default 3-step sequence on a timer — the user sees
+     * "Document analyzed → Checking face match → Finalizing results"
+     * progress visually instead of a static screen. Each step transition
+     * is ~1.4s so the full sequence completes in ~4s, long enough to
+     * read but short enough that the typical sub-second backend
+     * `/complete` resolution still shows visible motion. Pre-v1.8.0 the
+     * labels were hardcoded with "Checking face match" pinned as
+     * 'active' regardless of actual progress — looked frozen on any
+     * processing window over ~500ms.
+     */
+    autoAdvance?: boolean;
 }
-declare function ProcessingScreen({ steps }: ProcessingScreenProps): react_jsx_runtime.JSX.Element;
+declare function ProcessingScreen({ steps, autoAdvance }: ProcessingScreenProps): react_jsx_runtime.JSX.Element;
 
 export { ConsentScreen, type CountryInfo, CountrySelectionScreen, DocumentCaptureScreen, DocumentSelectionScreen, ErrorScreen, type KoraIDVContextValue, KoraIDVProvider, LivenessScreen, ProcessingScreen, QrHandoffScreen, ResultScreen, ScoreCard, ScoreMetricRow, SelfieCaptureScreen, StepProgressBar, VerificationFlow, type VerificationFlowProps, useKoraIDV };

package/dist/index.d.ts

@@ -55,6 +55,16 @@ interface VerificationState {
     completedChallenges: number;
     isLoading: boolean;
     error: KoraError | null;
+    /**
+     * Transient feedback message for the last liveness challenge that
+     * the backend rejected. Set by submitChallenge when the server
+     * returns passed:false; LivenessScreen renders it inline so the
+     * user knows WHY their attempt failed (the v1.7.x behavior was to
+     * silently re-arm the same challenge — confusing). Cleared the
+     * moment the user moves to the next challenge or the same one
+     * passes on retry.
+     */
+    lastChallengeError: string | null;
 }
 /**
  * useKoraIDV hook return value
@@ -67,7 +77,7 @@ interface UseKoraIDVReturn {
     /**
      * Start a new verification
      */
-    startVerification: (externalId: string, tier?: string) => Promise<void>;
+    startVerification: (externalId: string, tier?: string, expectedFirstName?: string, expectedLastName?: string) => Promise<void>;
     /**
      * Resume an existing verification
      */
@@ -142,6 +152,28 @@ interface VerificationFlowProps {
     externalId: string;
     tier?: 'basic' | 'standard' | 'enhanced';
     documentTypes?: DocumentType[];
+    /**
+     * Optional name-match inputs. When set, the backend compares the
+     * OCR'd names on the document against these values and surfaces a
+     * real `scores.nameMatch` percentage on the verification result —
+     * the ResultScreen's "Name Match" row shows real PASS/FAIL instead
+     * of the always-0% / always-FAIL it shows when these aren't passed.
+     *
+     * Wire from your user record at mount time, e.g.
+     *   `<VerificationFlow expectedFirstName={user.firstName} ... />`
+     *
+     * Mirrors iOS's
+     * `KoraIDV.startVerification(expectedFirstName:expectedLastName:)`.
+     */
+    expectedFirstName?: string;
+    expectedLastName?: string;
+    /**
+     * Whether to render Visual Guide illustrations above the capture +
+     * liveness viewfinders (default true). Set false for a plain text-
+     * only flow. Matches the same flag iOS exposes via `showVisualGuides`
+     * on Configuration; Android has had it since v1.3.0.
+     */
+    showVisualGuides?: boolean;
     onComplete?: (verification: Verification) => void;
     onError?: (error: KoraError) => void;
     onCancel?: () => void;
@@ -151,7 +183,7 @@ interface VerificationFlowProps {
 /**
  * Complete verification flow component
  */
-declare function VerificationFlow({ externalId, tier, documentTypes, onComplete, onError, onCancel, className, style, }: VerificationFlowProps): react_jsx_runtime.JSX.Element;
+declare function VerificationFlow({ externalId, tier, documentTypes, expectedFirstName, expectedLastName, showVisualGuides, onComplete, onError, onCancel, className, style, }: VerificationFlowProps): react_jsx_runtime.JSX.Element;
 
 interface ConsentScreenProps {
     onAccept: () => void;
@@ -187,14 +219,18 @@ interface DocumentCaptureScreenProps {
     onQualityCheck?: (imageData: Blob) => Promise<DocumentQualityResponse>;
     onCapture: (imageData: Blob) => Promise<boolean>;
     onCancel: () => void;
+    /** Render Visual Guide illustration above the capture area (v1.8.0). */
+    showVisualGuides?: boolean;
 }
-declare function DocumentCaptureScreen({ side, documentType, requiresBack, onQualityCheck, onCapture, onCancel, }: DocumentCaptureScreenProps): react_jsx_runtime.JSX.Element;
+declare function DocumentCaptureScreen({ side, documentType, requiresBack, onQualityCheck, onCapture, onCancel, showVisualGuides, }: DocumentCaptureScreenProps): react_jsx_runtime.JSX.Element;
 
 interface SelfieCaptureScreenProps {
     onCapture: (imageData: Blob) => Promise<boolean>;
     onCancel: () => void;
+    /** Render Visual Guide above the selfie viewfinder (v1.8.0). */
+    showVisualGuides?: boolean;
 }
-declare function SelfieCaptureScreen({ onCapture, onCancel }: SelfieCaptureScreenProps): react_jsx_runtime.JSX.Element;
+declare function SelfieCaptureScreen({ onCapture, onCancel, showVisualGuides }: SelfieCaptureScreenProps): react_jsx_runtime.JSX.Element;
 
 interface LivenessScreenProps {
     session: LivenessSession | null;
@@ -204,6 +240,16 @@ interface LivenessScreenProps {
     onStart: () => Promise<void>;
     onComplete: () => Promise<any>;
     onCancel: () => void;
+    /**
+     * Inline retake feedback for the LAST attempt the backend rejected.
+     * Surfaced in the prompt card during the 'preparing' phase of the
+     * next attempt so the user knows what went wrong before they try
+     * again. Cleared by the hook when a challenge passes or a new
+     * challenge starts.
+     */
+    lastChallengeError?: string | null;
+    /** Render per-challenge VisualGuide above the instruction (v1.8.0). */
+    showVisualGuides?: boolean;
 }
 /**
  * Web liveness screen with a real front-facing camera.
@@ -236,7 +282,7 @@ interface LivenessScreenProps {
  * themselves against a countdown. Today's ship is "real camera, real
  * frames, server decides," which is the parity floor.
  */
-declare function LivenessScreen({ session, currentChallenge, completedChallenges, onChallengeComplete, onStart, onComplete, onCancel, }: LivenessScreenProps): react_jsx_runtime.JSX.Element;
+declare function LivenessScreen({ session, currentChallenge, completedChallenges, onChallengeComplete, onStart, onComplete, onCancel, lastChallengeError, showVisualGuides, }: LivenessScreenProps): react_jsx_runtime.JSX.Element;
 
 type ResultPageMode = 'detailed' | 'simplified';
 interface ResultScreenProps {
@@ -323,8 +369,26 @@ interface ProcessingStep {
     status: 'done' | 'active' | 'pending';
 }
 interface ProcessingScreenProps {
-    steps: ProcessingStep[];
+    /**
+     * Optional explicit steps. When provided, the screen renders them as-
+     * is (the v1.7.x behavior — kept for backwards compat with any caller
+     * passing a custom array).
+     */
+    steps?: ProcessingStep[];
+    /**
+     * When true (and `steps` is omitted), the screen auto-advances
+     * through a default 3-step sequence on a timer — the user sees
+     * "Document analyzed → Checking face match → Finalizing results"
+     * progress visually instead of a static screen. Each step transition
+     * is ~1.4s so the full sequence completes in ~4s, long enough to
+     * read but short enough that the typical sub-second backend
+     * `/complete` resolution still shows visible motion. Pre-v1.8.0 the
+     * labels were hardcoded with "Checking face match" pinned as
+     * 'active' regardless of actual progress — looked frozen on any
+     * processing window over ~500ms.
+     */
+    autoAdvance?: boolean;
 }
-declare function ProcessingScreen({ steps }: ProcessingScreenProps): react_jsx_runtime.JSX.Element;
+declare function ProcessingScreen({ steps, autoAdvance }: ProcessingScreenProps): react_jsx_runtime.JSX.Element;
 
 export { ConsentScreen, type CountryInfo, CountrySelectionScreen, DocumentCaptureScreen, DocumentSelectionScreen, ErrorScreen, type KoraIDVContextValue, KoraIDVProvider, LivenessScreen, ProcessingScreen, QrHandoffScreen, ResultScreen, ScoreCard, ScoreMetricRow, SelfieCaptureScreen, StepProgressBar, VerificationFlow, type VerificationFlowProps, useKoraIDV };