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

package/src/ui/components/screens.tsx

@@ -0,0 +1,283 @@
+/**
+ * Presentational step screens for the Phase 1 verification flow.
+ * Plain RN components (no reanimated yet) — kept simple and theme-driven.
+ */
+import {
+    ActivityIndicator,
+    Image,
+    Pressable,
+    ScrollView,
+    StyleSheet,
+    Text,
+    View,
+} from "react-native";
+
+import type { MessageKey, Translate } from "../../i18n";
+import type { CaptureAsset, DocumentType } from "../../types";
+
+export interface Theme {
+    primary: string;
+    background: string;
+    foreground: string;
+}
+
+const DOC_LABEL_KEYS: Record<DocumentType, MessageKey> = {
+    id_card: "documentType.idCard",
+    passport: "documentType.passport",
+    drivers_license: "documentType.driversLicense",
+    voters_card: "documentType.votersCard",
+    residence_permit: "documentType.residencePermit",
+};
+
+function docLabel(type: DocumentType, t: Translate): string {
+    return t(DOC_LABEL_KEYS[type]);
+}
+
+function PrimaryButton({
+    label,
+    onPress,
+    theme,
+}: {
+    label: string;
+    onPress: () => void;
+    theme: Theme;
+}) {
+    return (
+        <Pressable style={[styles.btn, { backgroundColor: theme.primary }]} onPress={onPress}>
+            <Text style={styles.btnText}>{label}</Text>
+        </Pressable>
+    );
+}
+
+export function IntroScreen({
+    orgName,
+    onNext,
+    theme,
+    t,
+}: {
+    orgName?: string;
+    onNext: () => void;
+    theme: Theme;
+    t: Translate;
+}) {
+    return (
+        <View style={styles.screen}>
+            <Text style={[styles.h1, { color: theme.foreground }]}>{t("intro.title")}</Text>
+            <Text style={styles.body}>
+                {orgName ? `${t("intro.orgUsesKwikID", { orgName })} ` : ""}
+                {t("intro.bodyMobile")}
+            </Text>
+            <View style={styles.spacer} />
+            <PrimaryButton label={t("intro.getStarted")} onPress={onNext} theme={theme} />
+        </View>
+    );
+}
+
+export function DocumentTypeScreen({
+    allowed,
+    onSelect,
+    theme,
+    t,
+}: {
+    allowed: DocumentType[];
+    onSelect: (doc: DocumentType) => void;
+    theme: Theme;
+    t: Translate;
+}) {
+    return (
+        <ScrollView contentContainerStyle={styles.screen}>
+            <Text style={[styles.h1, { color: theme.foreground }]}>
+                {t("documentType.chooseTitle")}
+            </Text>
+            {allowed.map((doc) => (
+                <Pressable
+                    key={doc}
+                    style={styles.docRow}
+                    onPress={() => onSelect(doc)}
+                    accessibilityRole="button"
+                >
+                    <Text style={[styles.docLabel, { color: theme.foreground }]}>
+                        {docLabel(doc, t)}
+                    </Text>
+                    <Text style={[styles.chevron, { color: theme.primary }]}>›</Text>
+                </Pressable>
+            ))}
+        </ScrollView>
+    );
+}
+
+const PREPARE_COPY_KEYS: Record<
+    "front" | "back" | "selfie",
+    { title: MessageKey; body: MessageKey }
+> = {
+    front: { title: "prepareFront.titleMobile", body: "prepareFront.bodyMobile" },
+    back: { title: "prepareBack.titleMobile", body: "prepareBack.bodyMobile" },
+    selfie: { title: "prepareSelfie.titleMobile", body: "prepareSelfie.bodyMobile" },
+};
+
+export function PrepareScreen({
+    kind,
+    onNext,
+    theme,
+    t,
+}: {
+    kind: "front" | "back" | "selfie";
+    onNext: () => void;
+    theme: Theme;
+    t: Translate;
+}) {
+    const copy = PREPARE_COPY_KEYS[kind];
+    return (
+        <View style={styles.screen}>
+            <Text style={[styles.h1, { color: theme.foreground }]}>{t(copy.title)}</Text>
+            <Text style={styles.body}>{t(copy.body)}</Text>
+            <View style={styles.spacer} />
+            <PrimaryButton label={t("common.imReady")} onPress={onNext} theme={theme} />
+        </View>
+    );
+}
+
+export function ConfirmScreen({
+    asset,
+    onConfirm,
+    onRetake,
+    theme,
+    t,
+}: {
+    asset: CaptureAsset;
+    onConfirm: () => void;
+    onRetake: () => void;
+    theme: Theme;
+    t: Translate;
+}) {
+    return (
+        <View style={styles.screen}>
+            <Text style={[styles.h1, { color: theme.foreground }]}>
+                {t("confirm.looksGoodTitle")}
+            </Text>
+            <Image source={{ uri: asset.uri }} style={styles.preview} resizeMode="contain" />
+            <View style={styles.spacer} />
+            <PrimaryButton label={t("confirm.useThisPhoto")} onPress={onConfirm} theme={theme} />
+            <Pressable style={styles.linkBtn} onPress={onRetake}>
+                <Text style={[styles.linkText, { color: theme.primary }]}>
+                    {t("common.retake")}
+                </Text>
+            </Pressable>
+        </View>
+    );
+}
+
+export function ProcessingScreen({
+    progress,
+    stage,
+    theme,
+    t,
+}: {
+    progress: number;
+    stage: string | null;
+    theme: Theme;
+    t: Translate;
+}) {
+    const label =
+        stage === "submitting"
+            ? t("processing.submitting")
+            : stage === "document_front"
+              ? t("processing.uploadingFront")
+              : stage === "document_back"
+                ? t("processing.uploadingBack")
+                : stage === "selfie"
+                  ? t("processing.uploadingSelfie")
+                  : t("processing.working");
+    return (
+        <View style={styles.center}>
+            <ActivityIndicator size="large" color={theme.primary} />
+            <Text style={[styles.body, { marginTop: 16 }]}>{label}</Text>
+            <View style={styles.progressTrack}>
+                <View
+                    style={[
+                        styles.progressFill,
+                        { width: `${progress}%`, backgroundColor: theme.primary },
+                    ]}
+                />
+            </View>
+        </View>
+    );
+}
+
+export function ResultScreen({
+    success,
+    message,
+    onDone,
+    theme,
+    t,
+}: {
+    success: boolean;
+    message: string;
+    onDone: () => void;
+    theme: Theme;
+    t: Translate;
+}) {
+    return (
+        <View style={styles.center}>
+            <View
+                style={[styles.resultBadge, { backgroundColor: success ? "#16a34a" : "#dc2626" }]}
+            >
+                <Text style={styles.resultIcon}>{success ? "✓" : "!"}</Text>
+            </View>
+            <Text
+                style={[styles.h1, { color: theme.foreground, textAlign: "center", marginTop: 16 }]}
+            >
+                {t(success ? "result.submittedShort" : "result.somethingWrong")}
+            </Text>
+            <Text style={[styles.body, { textAlign: "center" }]}>{message}</Text>
+            <View style={styles.spacer} />
+            <PrimaryButton label={t("common.done")} onPress={onDone} theme={theme} />
+        </View>
+    );
+}
+
+const styles = StyleSheet.create({
+    screen: { flex: 1, padding: 24 },
+    center: { flex: 1, padding: 24, alignItems: "center", justifyContent: "center" },
+    h1: { fontSize: 22, fontWeight: "700", marginBottom: 12 },
+    body: { fontSize: 15, lineHeight: 22, color: "#4b5563" },
+    spacer: { flex: 1, minHeight: 24 },
+    btn: { borderRadius: 12, paddingVertical: 16, alignItems: "center" },
+    btnText: { color: "#fff", fontSize: 16, fontWeight: "600" },
+    linkBtn: { paddingVertical: 14, alignItems: "center" },
+    linkText: { fontSize: 15, fontWeight: "600" },
+    docRow: {
+        flexDirection: "row",
+        alignItems: "center",
+        justifyContent: "space-between",
+        paddingVertical: 18,
+        borderBottomWidth: 1,
+        borderBottomColor: "#eee",
+    },
+    docLabel: { fontSize: 16, fontWeight: "500" },
+    chevron: { fontSize: 24, fontWeight: "300" },
+    preview: {
+        flex: 1,
+        width: "100%",
+        marginVertical: 16,
+        borderRadius: 12,
+        backgroundColor: "#f3f4f6",
+    },
+    progressTrack: {
+        width: "80%",
+        height: 6,
+        borderRadius: 3,
+        backgroundColor: "#e5e7eb",
+        marginTop: 20,
+        overflow: "hidden",
+    },
+    progressFill: { height: 6, borderRadius: 3 },
+    resultBadge: {
+        width: 64,
+        height: 64,
+        borderRadius: 32,
+        alignItems: "center",
+        justifyContent: "center",
+    },
+    resultIcon: { color: "#fff", fontSize: 32, fontWeight: "700" },
+});

package/src/ui/context/kwik-id-provider.tsx

@@ -0,0 +1,72 @@
+/**
+ * KwikIDProvider / useKwikID — optional context for advanced integrations that want
+ * to share a single SDK instance + theme across custom screens. The imperative
+ * `useKwikVerification` hook does NOT require this provider.
+ */
+import { createContext, createElement, useContext, useEffect, useMemo, useState } from "react";
+
+import { KwikIdRNSDK } from "../../lib/kwik-id-rn-sdk";
+import type {
+    DocumentType,
+    KwikIdConfig,
+    KwikIdTheme,
+    LivenessMode,
+    SessionInfo,
+} from "../../types";
+
+export interface KwikIDContextValue {
+    sdk: KwikIdRNSDK;
+    sessionInfo: SessionInfo | null;
+    orgName?: string;
+    allowedDocumentTypes: DocumentType[];
+    livenessMode: LivenessMode;
+    theme: KwikIdTheme;
+}
+
+const KwikIDContext = createContext<KwikIDContextValue | null>(null);
+
+export interface KwikIDProviderProps {
+    config: KwikIdConfig;
+    /** Initialize the session immediately on mount (default true). */
+    autoInitialize?: boolean;
+    children: React.ReactNode;
+}
+
+export function KwikIDProvider({ config, autoInitialize = true, children }: KwikIDProviderProps) {
+    const sdk = useMemo(() => new KwikIdRNSDK(config), [config]);
+    const [sessionInfo, setSessionInfo] = useState<SessionInfo | null>(null);
+
+    useEffect(() => {
+        if (!autoInitialize) return;
+        let active = true;
+        sdk.initialize()
+            .then((info) => active && setSessionInfo(info))
+            .catch(() => undefined);
+        return () => {
+            active = false;
+            sdk.destroy();
+        };
+    }, [sdk, autoInitialize]);
+
+    const value = useMemo<KwikIDContextValue>(
+        () => ({
+            sdk,
+            sessionInfo,
+            orgName: sessionInfo?.orgName,
+            allowedDocumentTypes: sessionInfo?.config.documentTypes ?? [],
+            livenessMode: config.livenessMode ?? sessionInfo?.config.livenessMode ?? "passive",
+            theme: config.theme ?? {},
+        }),
+        [sdk, sessionInfo, config.livenessMode, config.theme]
+    );
+
+    return createElement(KwikIDContext.Provider, { value }, children);
+}
+
+export function useKwikID(): KwikIDContextValue {
+    const ctx = useContext(KwikIDContext);
+    if (!ctx) {
+        throw new Error("useKwikID must be used within a <KwikIDProvider>");
+    }
+    return ctx;
+}

package/src/ui/hooks/use-kwik-verification.ts

@@ -0,0 +1,121 @@
+/**
+ * useKwikVerification — imperative entry point (RN analog of the web
+ * `openKwikVerification`). Render `<kyc.Modal />` once, then `await kyc.start()`.
+ */
+import { createElement, useCallback, useMemo, useRef, useSyncExternalStore } from "react";
+
+import type {
+    DocumentType,
+    KwikIdTheme,
+    LivenessMode,
+    Locale,
+    VerificationOutcome,
+} from "../../types";
+import { KwikIDVerificationModal } from "../components/KwikIDVerificationModal";
+
+export interface UseKwikVerificationOptions {
+    clientSecret: string;
+    baseUrl?: string;
+    appName?: string;
+    theme?: KwikIdTheme;
+    locale?: Locale;
+    /**
+     * @deprecated Not yet supported: accepted for forward compatibility but ignored.
+     * Phase 1 is capture-only; on-device liveness (and this option) lands in Phase 2.
+     */
+    livenessMode?: LivenessMode;
+    documentTypes?: DocumentType[];
+    skipRuntimeCheck?: boolean;
+    onSubmitted?: (data: { jobId: string }) => void;
+}
+
+export interface UseKwikVerification {
+    /** Open the flow; resolves when the user reaches a terminal state. */
+    start: () => Promise<VerificationOutcome>;
+    /** Programmatically dismiss (resolves a pending start() as cancelled). */
+    cancel: () => void;
+    isOpen: boolean;
+    /** Render this once in your tree; the verification UI mounts here. */
+    Modal: React.FC;
+}
+
+interface Store {
+    open: boolean;
+    resolve: ((o: VerificationOutcome) => void) | null;
+    listeners: Set<() => void>;
+}
+
+export function useKwikVerification(options: UseKwikVerificationOptions): UseKwikVerification {
+    const storeRef = useRef<Store>(undefined as unknown as Store);
+    if (!storeRef.current) {
+        storeRef.current = { open: false, resolve: null, listeners: new Set() };
+    }
+    const store = storeRef.current;
+
+    const optionsRef = useRef(options);
+    optionsRef.current = options;
+
+    const subscribe = useCallback(
+        (cb: () => void) => {
+            store.listeners.add(cb);
+            return () => store.listeners.delete(cb);
+        },
+        [store]
+    );
+    const getSnapshot = useCallback(() => store.open, [store]);
+
+    const setOpen = useCallback(
+        (v: boolean) => {
+            store.open = v;
+            store.listeners.forEach((l) => l());
+        },
+        [store]
+    );
+
+    const start = useCallback(
+        () =>
+            new Promise<VerificationOutcome>((resolve) => {
+                store.resolve = resolve;
+                setOpen(true);
+            }),
+        [store, setOpen]
+    );
+
+    const finish = useCallback(
+        (outcome: VerificationOutcome) => {
+            setOpen(false);
+            const resolve = store.resolve;
+            store.resolve = null;
+            resolve?.(outcome);
+        },
+        [store, setOpen]
+    );
+
+    const cancel = useCallback(() => finish({ status: "cancelled" }), [finish]);
+
+    const isOpen = useSyncExternalStore(subscribe, getSnapshot);
+
+    const Modal = useMemo<React.FC>(() => {
+        const KwikModal: React.FC = () => {
+            const open = useSyncExternalStore(subscribe, getSnapshot);
+            const o = optionsRef.current;
+            return createElement(KwikIDVerificationModal, {
+                visible: open,
+                clientSecret: o.clientSecret,
+                baseUrl: o.baseUrl,
+                appName: o.appName,
+                theme: o.theme,
+                locale: o.locale,
+                documentTypes: o.documentTypes,
+                skipRuntimeCheck: o.skipRuntimeCheck,
+                onSubmitted: o.onSubmitted,
+                onComplete: finish,
+                onClose: () => undefined,
+            });
+        };
+        KwikModal.displayName = "KwikIDModal";
+        return KwikModal;
+    }, [subscribe, getSnapshot, finish]);
+
+    return { start, cancel, isOpen, Modal };
+}

package/src/ui/index.ts

@@ -0,0 +1,9 @@
+export { KwikIDVerificationModal } from "./components/KwikIDVerificationModal";
+export type { KwikIDVerificationModalProps } from "./components/KwikIDVerificationModal";
+export { useKwikVerification } from "./hooks/use-kwik-verification";
+export type {
+    UseKwikVerification,
+    UseKwikVerificationOptions,
+} from "./hooks/use-kwik-verification";
+export { KwikIDProvider, useKwikID } from "./context/kwik-id-provider";
+export type { KwikIDProviderProps, KwikIDContextValue } from "./context/kwik-id-provider";