@kwik-id/sdk-react-native 0.0.0-stage → 0.1.0-alpha.0

package/src/lib/kwik-id-rn-sdk.ts

@@ -0,0 +1,160 @@
+/**
+ * Headless orchestrator for the RN SDK.
+ *
+ * Wraps SessionManager + ApiClient + EventEmitter so the UI (and advanced
+ * integrators) drive a single object. No camera/UI concerns live here.
+ */
+import { ApiClient, type StatusResponse } from "../api/api-client";
+import { SessionManager } from "../crypto/session-manager";
+import type {
+    CaptureAsset,
+    CaptureType,
+    DocumentType,
+    KwikIdConfig,
+    KwikIdEventHandler,
+    KwikIdEventName,
+    LivenessResult,
+    QualityResult,
+    SessionInfo,
+} from "../types";
+import { assertSupportedRuntime } from "./device-detector";
+import { EventEmitter } from "./event-emitter";
+
+export interface KwikIdRNSDKOptions extends KwikIdConfig {
+    /** Skip the Expo Go runtime guard (tests only). */
+    skipRuntimeCheck?: boolean;
+}
+
+export class KwikIdRNSDK {
+    private readonly events = new EventEmitter();
+    private readonly sessionManager: SessionManager;
+    private readonly api: ApiClient;
+    private readonly options: KwikIdRNSDKOptions;
+    private sessionInfo: SessionInfo | null = null;
+    private initialized = false;
+
+    constructor(options: KwikIdRNSDKOptions) {
+        this.options = options;
+        this.sessionManager = new SessionManager();
+        this.api = new ApiClient(this.sessionManager, {
+            baseUrl: options.baseUrl,
+            timeout: options.timeout,
+            debug: options.debug,
+        });
+    }
+
+    /** Validate the runtime + session token. Returns the org/session config. */
+    async initialize(): Promise<SessionInfo> {
+        if (!this.options.skipRuntimeCheck) {
+            assertSupportedRuntime();
+        }
+        try {
+            this.sessionInfo = await this.api.validateSession(this.options.clientSecret);
+            this.initialized = true;
+            const session = this.sessionManager.getSession();
+            if (session) this.events.emit("session:created", session);
+            this.events.emit("ready", undefined);
+            return this.sessionInfo;
+        } catch (error) {
+            this.events.emit("error", {
+                code: "INIT_FAILED",
+                message: (error as Error).message,
+                recoverable: false,
+            });
+            throw error;
+        }
+    }
+
+    /** Redeem a desktop→mobile handoff code, swapping in the mobile session token. */
+    async redeemHandoff(code: string): Promise<void> {
+        try {
+            const { sessionToken } = await this.api.redeemHandoff(code);
+            this.sessionInfo = await this.api.validateSession(sessionToken);
+            this.initialized = true;
+            const session = this.sessionManager.getSession();
+            this.events.emit("handoff:redeemed", { jobId: session?.jobId ?? "" });
+        } catch (error) {
+            this.events.emit("handoff:error", { error: error as Error });
+            throw error;
+        }
+    }
+
+    async uploadCapture(
+        type: CaptureType,
+        asset: CaptureAsset,
+        onProgress?: (progress: number) => void
+    ): Promise<{ uploadId: string }> {
+        this.assertReady();
+        this.events.emit("upload:starting", { type });
+        try {
+            const res = await this.api.uploadCapture(type, asset, (p) => {
+                this.events.emit("upload:progress", { type, progress: p });
+                onProgress?.(p);
+            });
+            this.events.emit("upload:complete", { type, uploadId: res.uploadId });
+            return { uploadId: res.uploadId };
+        } catch (error) {
+            const retryable =
+                typeof (error as { isRetryable?: () => boolean }).isRetryable === "function"
+                    ? (error as { isRetryable: () => boolean }).isRetryable()
+                    : false;
+            this.events.emit("upload:failed", { type, error: error as Error, retryable });
+            throw error;
+        }
+    }
+
+    async submit(
+        documentType: DocumentType,
+        analysis?: { quality?: QualityResult; liveness?: LivenessResult }
+    ): Promise<{ jobId: string }> {
+        this.assertReady();
+        this.events.emit("verification:submitting", undefined);
+        try {
+            const res = await this.api.submitVerification(documentType, {
+                qualityScores: analysis?.quality,
+                livenessResult: analysis?.liveness,
+            });
+            const jobId = res.jobId ?? this.sessionManager.getSession()?.jobId ?? "";
+            this.events.emit("verification:submitted", { jobId });
+            return { jobId };
+        } catch (error) {
+            this.events.emit("verification:failed", { error: error as Error });
+            throw error;
+        }
+    }
+
+    getStatus(): Promise<StatusResponse> {
+        this.assertReady();
+        return this.api.getStatus();
+    }
+
+    getSessionInfo(): SessionInfo | null {
+        return this.sessionInfo;
+    }
+
+    /** True when the session token is within ~2 min of expiry. */
+    needsRefresh(): boolean {
+        return this.sessionManager.needsRefresh();
+    }
+
+    on<E extends KwikIdEventName>(event: E, handler: KwikIdEventHandler<E>): () => void {
+        return this.events.on(event, handler);
+    }
+
+    reset(): void {
+        this.sessionManager.clearSession();
+        this.sessionInfo = null;
+        this.initialized = false;
+    }
+
+    destroy(): void {
+        this.reset();
+        this.events.removeAllListeners();
+    }
+
+    private assertReady(): void {
+        if (!this.initialized) {
+            throw new Error("KwikIdRNSDK not initialized — call initialize() first");
+        }
+    }
+}

package/src/lib/verification-machine.ts

@@ -0,0 +1,273 @@
+/**
+ * Pure reducer for the RN verification flow.
+ *
+ * Adapted from the web SDK's KYCModalFlow SubStep machine. No React / no native
+ * dependency, so it is fully unit-testable. The selfie branch folds the web's
+ * `camera-selfie` into a single `liveness` step (align → passive/active → capture).
+ */
+import type {
+    CaptureAsset,
+    CaptureSlot,
+    CaptureType,
+    DocumentType,
+    LivenessResult,
+    VerificationOutcome,
+    VerificationSubStep,
+} from "../types";
+
+export interface MachineContext {
+    documentType: DocumentType | null;
+    front?: CaptureAsset;
+    back?: CaptureAsset;
+    selfie?: CaptureAsset;
+    livenessResult?: LivenessResult;
+    /** 0..100 upload/submit progress shown on the processing screen. */
+    uploadProgress: number;
+    uploadStage: CaptureType | "submitting" | null;
+    outcome?: VerificationOutcome;
+    error?: string;
+}
+
+export interface MachineState {
+    step: VerificationSubStep;
+    context: MachineContext;
+}
+
+export interface MachineOptions {
+    /** When launched as the mobile redeemer of a desktop handoff. */
+    hasHandoffCode?: boolean;
+}
+
+export type MachineEvent =
+    | { t: "NEXT" }
+    | { t: "BACK" }
+    | { t: "SELECT_DOC"; doc: DocumentType }
+    | { t: "CAPTURED"; slot: CaptureSlot; asset: CaptureAsset }
+    | { t: "RETAKE"; slot: CaptureSlot }
+    | { t: "HANDOFF_REDEEMED" }
+    /** `result` is omitted until on-device liveness ships (Phase 2). */
+    | { t: "LIVENESS_DONE"; result?: LivenessResult; selfie: CaptureAsset }
+    | { t: "PROGRESS"; stage: MachineContext["uploadStage"]; value: number }
+    | { t: "SUBMITTED"; jobId: string }
+    | { t: "CANCEL" }
+    | { t: "FAILED"; error: string }
+    /** Back to a fresh intro, e.g. when the modal closes so the next run starts clean. */
+    | { t: "RESET" };
+
+export function needsBackImage(doc: DocumentType | null): boolean {
+    return doc === "id_card" || doc === "drivers_license" || doc === "voters_card";
+}
+
+export function initialState(): MachineState {
+    return {
+        step: "intro",
+        context: {
+            documentType: null,
+            uploadProgress: 0,
+            uploadStage: null,
+        },
+    };
+}
+
+/** Steps that contribute to the progress bar, in order (mirrors web getProgress). */
+function progressSteps(ctx: MachineContext): VerificationSubStep[] {
+    const steps: VerificationSubStep[] = [
+        "document-type",
+        "prepare-front",
+        "camera-front",
+        "confirm-front",
+    ];
+    if (needsBackImage(ctx.documentType)) {
+        steps.push("prepare-back", "camera-back", "confirm-back");
+    }
+    steps.push("prepare-selfie", "liveness", "confirm-selfie");
+    return steps;
+}
+
+/** Progress-bar percentage (0..100) for the current step. */
+export function getStepProgress(state: MachineState): number {
+    const hidden: VerificationSubStep[] = ["intro", "handoff-redeem", "processing", "result"];
+    if (hidden.includes(state.step)) return 0;
+    const steps = progressSteps(state.context);
+    const idx = steps.indexOf(state.step);
+    if (idx < 0) return 0;
+    return ((idx + 1) / steps.length) * 100;
+}
+
+/**
+ * Upload/submit progress banding (matches web performVerification):
+ * front 0–30, back 30–45, selfie 45–70 (or 30–55 without back), submit 80, done 100.
+ */
+export function computeUploadProgress(
+    stage: MachineContext["uploadStage"],
+    pct: number,
+    hasBack: boolean
+): number {
+    switch (stage) {
+        case "document_front":
+            return Math.round(pct * 0.3);
+        case "document_back":
+            return 30 + Math.round(pct * 0.15);
+        case "selfie": {
+            const base = hasBack ? 45 : 30;
+            return base + Math.round(pct * 0.25);
+        }
+        case "submitting":
+            return Math.max(80, Math.round(pct));
+        default:
+            return 0;
+    }
+}
+
+const FORWARD_TAP: Partial<Record<VerificationSubStep, VerificationSubStep>> = {
+    "prepare-front": "camera-front",
+    "prepare-back": "camera-back",
+    "prepare-selfie": "liveness",
+    // 'confirm-front' is resolved dynamically (needs back?) in the reducer.
+    "confirm-back": "prepare-selfie",
+    "confirm-selfie": "processing",
+};
+
+const BACK_FLOW: Partial<Record<VerificationSubStep, VerificationSubStep>> = {
+    "document-type": "intro",
+    "prepare-front": "document-type",
+    "camera-front": "prepare-front",
+    "confirm-front": "camera-front",
+    "prepare-back": "confirm-front",
+    "camera-back": "prepare-back",
+    "confirm-back": "camera-back",
+    "confirm-selfie": "prepare-selfie",
+};
+
+export function reducer(
+    state: MachineState,
+    event: MachineEvent,
+    options: MachineOptions = {}
+): MachineState {
+    const { step, context } = state;
+
+    switch (event.t) {
+        case "NEXT": {
+            if (step === "intro") {
+                return {
+                    ...state,
+                    step: options.hasHandoffCode ? "handoff-redeem" : "document-type",
+                };
+            }
+            if (step === "confirm-front") {
+                return {
+                    ...state,
+                    step: needsBackImage(context.documentType) ? "prepare-back" : "prepare-selfie",
+                };
+            }
+            const next = FORWARD_TAP[step];
+            return next ? { ...state, step: next } : state;
+        }
+
+        case "BACK": {
+            // Terminal / non-reversible steps.
+            if (step === "processing" || step === "result" || step === "liveness") return state;
+            if (step === "prepare-selfie") {
+                return {
+                    ...state,
+                    step: needsBackImage(context.documentType) ? "confirm-back" : "confirm-front",
+                };
+            }
+            const prev = BACK_FLOW[step];
+            return prev ? { ...state, step: prev } : state;
+        }
+
+        case "SELECT_DOC": {
+            if (step !== "document-type") return state;
+            return {
+                step: "prepare-front",
+                context: { ...context, documentType: event.doc },
+            };
+        }
+
+        case "HANDOFF_REDEEMED": {
+            if (step !== "handoff-redeem") return state;
+            return { ...state, step: "document-type" };
+        }
+
+        case "CAPTURED": {
+            const ctx = { ...context, [event.slot]: event.asset };
+            if (event.slot === "front" && step === "camera-front") {
+                return { step: "confirm-front", context: ctx };
+            }
+            if (event.slot === "back" && step === "camera-back") {
+                return { step: "confirm-back", context: ctx };
+            }
+            return { ...state, context: ctx };
+        }
+
+        case "RETAKE": {
+            if (event.slot === "front") {
+                return { step: "camera-front", context: { ...context, front: undefined } };
+            }
+            if (event.slot === "back") {
+                return { step: "camera-back", context: { ...context, back: undefined } };
+            }
+            return {
+                step: "liveness",
+                context: { ...context, selfie: undefined, livenessResult: undefined },
+            };
+        }
+
+        case "LIVENESS_DONE": {
+            if (step !== "liveness") return state;
+            return {
+                step: "confirm-selfie",
+                context: { ...context, selfie: event.selfie, livenessResult: event.result },
+            };
+        }
+
+        case "PROGRESS": {
+            const hasBack = !!context.back;
+            return {
+                ...state,
+                context: {
+                    ...context,
+                    uploadStage: event.stage,
+                    uploadProgress: computeUploadProgress(event.stage, event.value, hasBack),
+                },
+            };
+        }
+
+        case "SUBMITTED": {
+            return {
+                step: "result",
+                context: {
+                    ...context,
+                    uploadProgress: 100,
+                    uploadStage: null,
+                    outcome: { status: "submitted", jobId: event.jobId },
+                },
+            };
+        }
+
+        case "FAILED": {
+            return {
+                step: "result",
+                context: {
+                    ...context,
+                    error: event.error,
+                    outcome: { status: "error", error: new Error(event.error) },
+                },
+            };
+        }
+
+        case "CANCEL": {
+            return {
+                ...state,
+                context: { ...context, outcome: { status: "cancelled" } },
+            };
+        }
+
+        case "RESET":
+            return initialState();
+
+        default:
+            return state;
+    }
+}

package/src/types/events.ts

@@ -0,0 +1,75 @@
+/**
+ * Event vocabulary for @kwik-id/sdk-react-native.
+ *
+ * Mirrors the portable subset of the web SDK's KwikIdEvents — DOM/Blob/MediaStream
+ * payloads are replaced with RN-native equivalents (CaptureAsset, FaceSignals).
+ */
+import type {
+    CaptureAsset,
+    CaptureType,
+    Challenge,
+    ChallengeResult,
+    FaceSignals,
+    LivenessMode,
+    LivenessResult,
+    PassiveLivenessResult,
+    Session,
+    VerificationResult,
+} from "./index";
+
+export interface KwikIdEvents {
+    // Session
+    "session:created": Session;
+    "session:expired": { sessionId: string };
+    "session:refreshed": Session;
+
+    // Camera
+    "camera:ready": void;
+    "camera:error": { error: Error; recoverable: boolean };
+    "camera:permission_denied": { canAskAgain: boolean };
+
+    // Face / alignment
+    "face:detected": FaceSignals;
+    "face:lost": void;
+    "face:aligned": void;
+    "face:misaligned": { reason: string };
+
+    // Liveness
+    "liveness:starting": { mode: LivenessMode };
+    "liveness:challenge": Challenge;
+    "liveness:challenge_result": ChallengeResult;
+    "liveness:passive_result": PassiveLivenessResult;
+    "liveness:complete": LivenessResult;
+    "liveness:failed": { reason: string };
+
+    // Capture
+    "capture:starting": { type: CaptureType };
+    "capture:complete": { type: CaptureType; asset: CaptureAsset };
+    "capture:failed": { type: CaptureType; error: Error };
+
+    // Upload
+    "upload:starting": { type: CaptureType };
+    "upload:progress": { type: CaptureType; progress: number };
+    "upload:complete": { type: CaptureType; uploadId: string };
+    "upload:failed": { type: CaptureType; error: Error; retryable: boolean };
+
+    // Verification
+    "verification:submitting": void;
+    "verification:submitted": { jobId: string };
+    "verification:processing": { jobId: string; progress?: number };
+    "verification:complete": VerificationResult;
+    "verification:failed": { error: Error; jobId?: string };
+
+    // Handoff (mobile is the redeemer)
+    "handoff:redeemed": { jobId: string };
+    "handoff:error": { error: Error };
+
+    // General
+    ready: void;
+    error: { code: string; message: string; recoverable: boolean };
+    destroy: void;
+}
+
+export type KwikIdEventName = keyof KwikIdEvents;
+
+export type KwikIdEventHandler<T extends KwikIdEventName> = (data: KwikIdEvents[T]) => void;