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

package/src/ui/components/KwikIDVerificationModal.tsx

@@ -0,0 +1,450 @@
+/**
+ * KwikIDVerificationModal — the full Phase 1 verification flow.
+ *
+ * Owns a KwikIdRNSDK, drives the verification-machine reducer, renders the step
+ * screens + camera capture, runs upload/submit on the processing step, and reports
+ * a terminal VerificationOutcome via onComplete.
+ *
+ * Phase 1 = capture-only (manual selfie, no on-device liveness). The `liveness`
+ * step is a plain front-camera capture; Phase 2 replaces it with align + challenges.
+ */
+import { useCallback, useEffect, useMemo, useReducer, useRef, useState } from "react";
+
+import { ActivityIndicator, Modal, Pressable, StyleSheet, Text, View } from "react-native";
+
+import { ApiError } from "../../api/api-error";
+import { CameraView } from "../../camera/camera-view";
+import { compressCapture } from "../../camera/photo-capture";
+import { type Translate, createTranslator, getDeviceLocale } from "../../i18n";
+import { KwikIdRNSDK } from "../../lib/kwik-id-rn-sdk";
+import {
+    type MachineEvent,
+    type MachineState,
+    getStepProgress,
+    initialState,
+    reducer,
+} from "../../lib/verification-machine";
+import type {
+    CaptureType,
+    DocumentType,
+    KwikIdTheme,
+    Locale,
+    SessionInfo,
+    VerificationOutcome,
+} from "../../types";
+import {
+    ConfirmScreen,
+    DocumentTypeScreen,
+    IntroScreen,
+    PrepareScreen,
+    ProcessingScreen,
+    ResultScreen,
+    type Theme,
+} from "./screens";
+
+export interface KwikIDVerificationModalProps {
+    visible: boolean;
+    clientSecret: string;
+    baseUrl?: string;
+    appName?: string;
+    theme?: KwikIdTheme;
+    /** UI language; defaults to the device language ('fr' for French, else 'en'). */
+    locale?: Locale;
+    /** Restrict the selectable document types (intersected with the session config). */
+    documentTypes?: DocumentType[];
+    /** Skip the Expo Go runtime guard (tests only). */
+    skipRuntimeCheck?: boolean;
+    onSubmitted?: (data: { jobId: string }) => void;
+    onComplete: (outcome: VerificationOutcome) => void;
+    onClose?: () => void;
+}
+
+const DEFAULT_DOCS: DocumentType[] = ["passport", "id_card", "drivers_license"];
+
+// Phase 1 has no handoff, so the reducer's options arg is unused — adapt to useReducer's 2-arg shape.
+const machineReducer = (state: MachineState, event: MachineEvent): MachineState =>
+    reducer(state, event);
+
+function resolveTheme(theme?: KwikIdTheme): Theme {
+    return {
+        primary: theme?.primary ?? "#1E3A8A",
+        background: theme?.background ?? "#ffffff",
+        foreground: theme?.foreground ?? "#111111",
+    };
+}
+
+export function KwikIDVerificationModal(props: KwikIDVerificationModalProps) {
+    const { visible, clientSecret, baseUrl, appName, documentTypes, skipRuntimeCheck } = props;
+    const theme = useMemo(() => resolveTheme(props.theme), [props.theme]);
+    const t = useMemo(() => createTranslator(props.locale ?? getDeviceLocale()), [props.locale]);
+
+    const sdk = useMemo(
+        () =>
+            new KwikIdRNSDK({
+                clientSecret,
+                baseUrl,
+                appName,
+                skipRuntimeCheck,
+            }),
+        [clientSecret, baseUrl, appName, skipRuntimeCheck]
+    );
+
+    const [state, dispatch] = useReducer(machineReducer, undefined, initialState);
+    const [sessionInfo, setSessionInfo] = useState<SessionInfo | null>(null);
+    const [initializing, setInitializing] = useState(false);
+    const startedRef = useRef(false);
+    const submittingRef = useRef(false);
+
+    const { step, context } = state;
+
+    // Initialize the SDK when the modal opens.
+    useEffect(() => {
+        if (!visible || startedRef.current) return;
+        startedRef.current = true;
+        setInitializing(true);
+        sdk.initialize()
+            .then((info) => setSessionInfo(info))
+            .catch((error: unknown) => {
+                dispatch({ t: "FAILED", error: describeError(error, t) });
+            })
+            .finally(() => setInitializing(false));
+    }, [visible, sdk]);
+
+    // Reset internal state when the modal closes, so the next open starts a fresh run
+    // (the useKwikVerification host keeps this component mounted between runs).
+    useEffect(() => {
+        if (!visible) {
+            startedRef.current = false;
+            submittingRef.current = false;
+            dispatch({ t: "RESET" });
+            setSessionInfo(null);
+        }
+    }, [visible]);
+
+    const allowedDocs = useMemo(() => {
+        const fromSession = sessionInfo?.config.documentTypes?.length
+            ? sessionInfo.config.documentTypes
+            : DEFAULT_DOCS;
+        return documentTypes?.length
+            ? fromSession.filter((d) => documentTypes.includes(d))
+            : fromSession;
+    }, [sessionInfo, documentTypes]);
+
+    // Upload + submit when entering the processing step.
+    useEffect(() => {
+        if (step !== "processing" || submittingRef.current) return;
+        submittingRef.current = true;
+
+        (async () => {
+            try {
+                const upload = async (
+                    type: CaptureType,
+                    asset?: {
+                        uri: string;
+                        name: string;
+                        type: string;
+                        width: number;
+                        height: number;
+                    }
+                ) => {
+                    if (!asset) return;
+                    dispatch({
+                        t: "PROGRESS",
+                        stage:
+                            type === "document_front"
+                                ? "document_front"
+                                : type === "document_back"
+                                  ? "document_back"
+                                  : "selfie",
+                        value: 0,
+                    });
+                    await sdk.uploadCapture(type, asset, (p) =>
+                        dispatch({
+                            t: "PROGRESS",
+                            stage:
+                                type === "document_front"
+                                    ? "document_front"
+                                    : type === "document_back"
+                                      ? "document_back"
+                                      : "selfie",
+                            value: p,
+                        })
+                    );
+                };
+
+                await upload("document_front", context.front);
+                await upload("document_back", context.back);
+                await upload("selfie", context.selfie);
+
+                dispatch({ t: "PROGRESS", stage: "submitting", value: 80 });
+                const { jobId } = await sdk.submit(context.documentType!, {
+                    liveness: context.livenessResult,
+                });
+                props.onSubmitted?.({ jobId });
+                dispatch({ t: "SUBMITTED", jobId });
+            } catch (error) {
+                dispatch({ t: "FAILED", error: describeError(error, t) });
+            }
+        })();
+    }, [step]);
+
+    // Report the terminal outcome (after the user taps Done on the result screen).
+    const finish = useCallback(() => {
+        const outcome = context.outcome ?? { status: "cancelled" as const };
+        sdk.destroy();
+        props.onComplete(outcome);
+    }, [context.outcome, sdk, props]);
+
+    const handleClose = useCallback(() => {
+        if (step === "processing") return; // don't allow closing mid-submit
+        sdk.destroy();
+        props.onClose?.();
+        props.onComplete({ status: "cancelled" });
+    }, [step, sdk, props]);
+
+    const onCaptured = useCallback(
+        async (type: CaptureType, raw: { path: string; width?: number; height?: number }) => {
+            // Errors propagate to CameraView, which shows them and lets the user retry.
+            const asset = await compressCapture(type, raw, Date.now());
+            if (type === "document_front") dispatch({ t: "CAPTURED", slot: "front", asset });
+            else if (type === "document_back") dispatch({ t: "CAPTURED", slot: "back", asset });
+            // No on-device liveness yet (Phase 2), so no liveness result is claimed.
+            else dispatch({ t: "LIVENESS_DONE", selfie: asset });
+        },
+        []
+    );
+
+    const canGoBack =
+        !["intro", "processing", "result", "liveness"].includes(step) && step !== "document-type";
+    const showProgress = !["intro", "processing", "result"].includes(step);
+
+    return (
+        <Modal
+            visible={visible}
+            animationType="slide"
+            onRequestClose={handleClose}
+            statusBarTranslucent
+        >
+            <View style={[styles.container, { backgroundColor: theme.background }]}>
+                {/* Header */}
+                <View style={styles.header}>
+                    <Pressable
+                        style={styles.headerBtn}
+                        onPress={canGoBack ? () => dispatch({ t: "BACK" }) : undefined}
+                        hitSlop={8}
+                    >
+                        {canGoBack ? (
+                            <Text style={[styles.headerIcon, { color: theme.foreground }]}>‹</Text>
+                        ) : null}
+                    </Pressable>
+                    <Text
+                        style={[styles.headerTitle, { color: theme.foreground }]}
+                        numberOfLines={1}
+                    >
+                        {appName ?? sessionInfo?.orgName ?? t("common.identityVerification")}
+                    </Text>
+                    <Pressable
+                        style={styles.headerBtn}
+                        onPress={step === "processing" ? undefined : handleClose}
+                        hitSlop={8}
+                    >
+                        {step !== "processing" ? (
+                            <Text style={[styles.headerIcon, { color: theme.foreground }]}>✕</Text>
+                        ) : null}
+                    </Pressable>
+                </View>
+                {showProgress ? (
+                    <View style={styles.progressTrack}>
+                        <View
+                            style={[
+                                styles.progressFill,
+                                {
+                                    width: `${getStepProgress(state)}%`,
+                                    backgroundColor: theme.primary,
+                                },
+                            ]}
+                        />
+                    </View>
+                ) : null}
+
+                {/* Body */}
+                <View style={styles.body}>
+                    {initializing && step === "intro" ? (
+                        <View style={styles.center}>
+                            <ActivityIndicator size="large" color={theme.primary} />
+                        </View>
+                    ) : null}
+
+                    {step === "intro" && !initializing && (
+                        <IntroScreen
+                            orgName={sessionInfo?.orgName}
+                            onNext={() => dispatch({ t: "NEXT" })}
+                            theme={theme}
+                            t={t}
+                        />
+                    )}
+
+                    {step === "document-type" && (
+                        <DocumentTypeScreen
+                            allowed={allowedDocs}
+                            onSelect={(doc) => dispatch({ t: "SELECT_DOC", doc })}
+                            theme={theme}
+                            t={t}
+                        />
+                    )}
+
+                    {step === "prepare-front" && (
+                        <PrepareScreen
+                            kind="front"
+                            onNext={() => dispatch({ t: "NEXT" })}
+                            theme={theme}
+                            t={t}
+                        />
+                    )}
+                    {step === "prepare-back" && (
+                        <PrepareScreen
+                            kind="back"
+                            onNext={() => dispatch({ t: "NEXT" })}
+                            theme={theme}
+                            t={t}
+                        />
+                    )}
+                    {step === "prepare-selfie" && (
+                        <PrepareScreen
+                            kind="selfie"
+                            onNext={() => dispatch({ t: "NEXT" })}
+                            theme={theme}
+                            t={t}
+                        />
+                    )}
+
+                    {step === "camera-front" && (
+                        <CameraView
+                            facing="back"
+                            active={visible}
+                            primaryColor={theme.primary}
+                            captureErrorText={t("camera.captureFailedMobile")}
+                            permissionTitle={t("camera.permissionTitleMobile")}
+                            permissionBody={t("camera.permissionBodyMobile")}
+                            openSettingsLabel={t("camera.openSettingsMobile")}
+                            captureLabel={t("common.capturePhoto")}
+                            instruction={t("camera.instructionFrontMobile")}
+                            onCapture={(raw) => onCaptured("document_front", raw)}
+                        />
+                    )}
+                    {step === "camera-back" && (
+                        <CameraView
+                            facing="back"
+                            active={visible}
+                            primaryColor={theme.primary}
+                            captureErrorText={t("camera.captureFailedMobile")}
+                            permissionTitle={t("camera.permissionTitleMobile")}
+                            permissionBody={t("camera.permissionBodyMobile")}
+                            openSettingsLabel={t("camera.openSettingsMobile")}
+                            captureLabel={t("common.capturePhoto")}
+                            instruction={t("camera.instructionBackMobile")}
+                            onCapture={(raw) => onCaptured("document_back", raw)}
+                        />
+                    )}
+                    {step === "liveness" && (
+                        <CameraView
+                            facing="front"
+                            active={visible}
+                            primaryColor={theme.primary}
+                            captureErrorText={t("camera.captureFailedMobile")}
+                            permissionTitle={t("camera.permissionTitleMobile")}
+                            permissionBody={t("camera.permissionBodyMobile")}
+                            openSettingsLabel={t("camera.openSettingsMobile")}
+                            captureLabel={t("common.capturePhoto")}
+                            instruction={t("camera.instructionSelfieMobile")}
+                            onCapture={(raw) => onCaptured("selfie", raw)}
+                        />
+                    )}
+
+                    {step === "confirm-front" && context.front && (
+                        <ConfirmScreen
+                            asset={context.front}
+                            onConfirm={() => dispatch({ t: "NEXT" })}
+                            onRetake={() => dispatch({ t: "RETAKE", slot: "front" })}
+                            theme={theme}
+                            t={t}
+                        />
+                    )}
+                    {step === "confirm-back" && context.back && (
+                        <ConfirmScreen
+                            asset={context.back}
+                            onConfirm={() => dispatch({ t: "NEXT" })}
+                            onRetake={() => dispatch({ t: "RETAKE", slot: "back" })}
+                            theme={theme}
+                            t={t}
+                        />
+                    )}
+                    {step === "confirm-selfie" && context.selfie && (
+                        <ConfirmScreen
+                            asset={context.selfie}
+                            onConfirm={() => dispatch({ t: "NEXT" })}
+                            onRetake={() => dispatch({ t: "RETAKE", slot: "selfie" })}
+                            theme={theme}
+                            t={t}
+                        />
+                    )}
+
+                    {step === "processing" && (
+                        <ProcessingScreen
+                            progress={context.uploadProgress}
+                            stage={context.uploadStage}
+                            theme={theme}
+                            t={t}
+                        />
+                    )}
+
+                    {step === "result" && (
+                        <ResultScreen
+                            success={context.outcome?.status === "submitted"}
+                            message={
+                                context.outcome?.status === "submitted"
+                                    ? t("result.submittedMessageMobile")
+                                    : (context.error ?? t("result.couldNotComplete"))
+                            }
+                            onDone={finish}
+                            theme={theme}
+                            t={t}
+                        />
+                    )}
+                </View>
+            </View>
+        </Modal>
+    );
+}
+
+function describeError(error: unknown, t: Translate): string {
+    if (error instanceof ApiError && error.isAuthError()) {
+        return t("errors.sessionExpiredShort");
+    }
+    return error instanceof Error ? error.message : t("errors.unexpected");
+}
+
+const styles = StyleSheet.create({
+    container: { flex: 1 },
+    header: {
+        flexDirection: "row",
+        alignItems: "center",
+        justifyContent: "space-between",
+        paddingHorizontal: 12,
+        paddingTop: 52,
+        paddingBottom: 8,
+    },
+    headerBtn: { width: 40, height: 40, alignItems: "center", justifyContent: "center" },
+    headerIcon: { fontSize: 24, fontWeight: "500" },
+    headerTitle: { flex: 1, textAlign: "center", fontSize: 16, fontWeight: "600" },
+    progressTrack: {
+        height: 3,
+        backgroundColor: "#e5e7eb",
+        marginHorizontal: 12,
+        borderRadius: 2,
+        overflow: "hidden",
+    },
+    progressFill: { height: 3 },
+    body: { flex: 1 },
+    center: { flex: 1, alignItems: "center", justifyContent: "center" },
+});