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

package/lib/typescript/module/ui/components/screens.d.ts

@@ -0,0 +1,46 @@
+import type { Translate } from "../../i18n/index.js";
+import type { CaptureAsset, DocumentType } from "../../types/index.js";
+export interface Theme {
+    primary: string;
+    background: string;
+    foreground: string;
+}
+export declare function IntroScreen({ orgName, onNext, theme, t, }: {
+    orgName?: string;
+    onNext: () => void;
+    theme: Theme;
+    t: Translate;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function DocumentTypeScreen({ allowed, onSelect, theme, t, }: {
+    allowed: DocumentType[];
+    onSelect: (doc: DocumentType) => void;
+    theme: Theme;
+    t: Translate;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function PrepareScreen({ kind, onNext, theme, t, }: {
+    kind: "front" | "back" | "selfie";
+    onNext: () => void;
+    theme: Theme;
+    t: Translate;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function ConfirmScreen({ asset, onConfirm, onRetake, theme, t, }: {
+    asset: CaptureAsset;
+    onConfirm: () => void;
+    onRetake: () => void;
+    theme: Theme;
+    t: Translate;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function ProcessingScreen({ progress, stage, theme, t, }: {
+    progress: number;
+    stage: string | null;
+    theme: Theme;
+    t: Translate;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function ResultScreen({ success, message, onDone, theme, t, }: {
+    success: boolean;
+    message: string;
+    onDone: () => void;
+    theme: Theme;
+    t: Translate;
+}): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=screens.d.ts.map

package/lib/typescript/module/ui/components/screens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"screens.d.ts","sourceRoot":"","sources":["../../../../../src/ui/components/screens.tsx"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAc,SAAS,EAAE,MAAM,qBAAY,CAAC;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,sBAAa,CAAC;AAE9D,MAAM,WAAW,KAAK;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACtB;AA8BD,wBAAgB,WAAW,CAAC,EACxB,OAAO,EACP,MAAM,EACN,KAAK,EACL,CAAC,GACJ,EAAE;IACC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,KAAK,EAAE,KAAK,CAAC;IACb,CAAC,EAAE,SAAS,CAAC;CAChB,2CAYA;AAED,wBAAgB,kBAAkB,CAAC,EAC/B,OAAO,EACP,QAAQ,EACR,KAAK,EACL,CAAC,GACJ,EAAE;IACC,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,QAAQ,EAAE,CAAC,GAAG,EAAE,YAAY,KAAK,IAAI,CAAC;IACtC,KAAK,EAAE,KAAK,CAAC;IACb,CAAC,EAAE,SAAS,CAAC;CAChB,2CAqBA;AAWD,wBAAgB,aAAa,CAAC,EAC1B,IAAI,EACJ,MAAM,EACN,KAAK,EACL,CAAC,GACJ,EAAE;IACC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC;IAClC,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,KAAK,EAAE,KAAK,CAAC;IACb,CAAC,EAAE,SAAS,CAAC;CAChB,2CAUA;AAED,wBAAgB,aAAa,CAAC,EAC1B,KAAK,EACL,SAAS,EACT,QAAQ,EACR,KAAK,EACL,CAAC,GACJ,EAAE;IACC,KAAK,EAAE,YAAY,CAAC;IACpB,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB,KAAK,EAAE,KAAK,CAAC;IACb,CAAC,EAAE,SAAS,CAAC;CAChB,2CAgBA;AAED,wBAAgB,gBAAgB,CAAC,EAC7B,QAAQ,EACR,KAAK,EACL,KAAK,EACL,CAAC,GACJ,EAAE;IACC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,KAAK,EAAE,KAAK,CAAC;IACb,CAAC,EAAE,SAAS,CAAC;CAChB,2CAyBA;AAED,wBAAgB,YAAY,CAAC,EACzB,OAAO,EACP,OAAO,EACP,MAAM,EACN,KAAK,EACL,CAAC,GACJ,EAAE;IACC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,KAAK,EAAE,KAAK,CAAC;IACb,CAAC,EAAE,SAAS,CAAC;CAChB,2CAkBA"}

package/lib/typescript/module/ui/context/kwik-id-provider.d.ts

@@ -0,0 +1,19 @@
+import { KwikIdRNSDK } from "../../lib/kwik-id-rn-sdk.js";
+import type { DocumentType, KwikIdConfig, KwikIdTheme, LivenessMode, SessionInfo } from "../../types/index.js";
+export interface KwikIDContextValue {
+    sdk: KwikIdRNSDK;
+    sessionInfo: SessionInfo | null;
+    orgName?: string;
+    allowedDocumentTypes: DocumentType[];
+    livenessMode: LivenessMode;
+    theme: KwikIdTheme;
+}
+export interface KwikIDProviderProps {
+    config: KwikIdConfig;
+    /** Initialize the session immediately on mount (default true). */
+    autoInitialize?: boolean;
+    children: React.ReactNode;
+}
+export declare function KwikIDProvider({ config, autoInitialize, children }: KwikIDProviderProps): import("react").FunctionComponentElement<import("react").ProviderProps<KwikIDContextValue | null>>;
+export declare function useKwikID(): KwikIDContextValue;
+//# sourceMappingURL=kwik-id-provider.d.ts.map

package/lib/typescript/module/ui/context/kwik-id-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kwik-id-provider.d.ts","sourceRoot":"","sources":["../../../../../src/ui/context/kwik-id-provider.tsx"],"names":[],"mappings":"AAOA,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA0B,CAAC;AACvD,OAAO,KAAK,EACR,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,WAAW,EACd,MAAM,sBAAa,CAAC;AAErB,MAAM,WAAW,kBAAkB;IAC/B,GAAG,EAAE,WAAW,CAAC;IACjB,WAAW,EAAE,WAAW,GAAG,IAAI,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oBAAoB,EAAE,YAAY,EAAE,CAAC;IACrC,YAAY,EAAE,YAAY,CAAC;IAC3B,KAAK,EAAE,WAAW,CAAC;CACtB;AAID,MAAM,WAAW,mBAAmB;IAChC,MAAM,EAAE,YAAY,CAAC;IACrB,kEAAkE;IAClE,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC7B;AAED,wBAAgB,cAAc,CAAC,EAAE,MAAM,EAAE,cAAqB,EAAE,QAAQ,EAAE,EAAE,mBAAmB,sGA6B9F;AAED,wBAAgB,SAAS,IAAI,kBAAkB,CAM9C"}

package/lib/typescript/module/ui/hooks/use-kwik-verification.d.ts

@@ -0,0 +1,29 @@
+import type { DocumentType, KwikIdTheme, LivenessMode, Locale, VerificationOutcome } from "../../types/index.js";
+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;
+}
+export declare function useKwikVerification(options: UseKwikVerificationOptions): UseKwikVerification;
+//# sourceMappingURL=use-kwik-verification.d.ts.map

package/lib/typescript/module/ui/hooks/use-kwik-verification.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-kwik-verification.d.ts","sourceRoot":"","sources":["../../../../../src/ui/hooks/use-kwik-verification.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACR,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,MAAM,EACN,mBAAmB,EACtB,MAAM,sBAAa,CAAC;AAGrB,MAAM,WAAW,0BAA0B;IACvC,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,aAAa,CAAC,EAAE,YAAY,EAAE,CAAC;IAC/B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;CACnD;AAED,MAAM,WAAW,mBAAmB;IAChC,sEAAsE;IACtE,KAAK,EAAE,MAAM,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAC1C,0EAA0E;IAC1E,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;IAChB,sEAAsE;IACtE,KAAK,EAAE,KAAK,CAAC,EAAE,CAAC;CACnB;AAQD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,0BAA0B,GAAG,mBAAmB,CAyE5F"}

package/lib/typescript/module/ui/index.d.ts

@@ -0,0 +1,7 @@
+export { KwikIDVerificationModal } from "./components/KwikIDVerificationModal.js";
+export type { KwikIDVerificationModalProps } from "./components/KwikIDVerificationModal.js";
+export { useKwikVerification } from "./hooks/use-kwik-verification.js";
+export type { UseKwikVerification, UseKwikVerificationOptions, } from "./hooks/use-kwik-verification.js";
+export { KwikIDProvider, useKwikID } from "./context/kwik-id-provider.js";
+export type { KwikIDProviderProps, KwikIDContextValue } from "./context/kwik-id-provider.js";
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/module/ui/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/ui/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,yCAAsC,CAAC;AAC/E,YAAY,EAAE,4BAA4B,EAAE,MAAM,yCAAsC,CAAC;AACzF,OAAO,EAAE,mBAAmB,EAAE,MAAM,kCAA+B,CAAC;AACpE,YAAY,EACR,mBAAmB,EACnB,0BAA0B,GAC7B,MAAM,kCAA+B,CAAC;AACvC,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,+BAA4B,CAAC;AACvE,YAAY,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,+BAA4B,CAAC"}

package/package.json

@@ -1,6 +1,124 @@
 {
   "name": "@kwik-id/sdk-react-native",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0-alpha.0",
+  "description": "KwikId on-device KYC + liveness SDK for React Native / Expo",
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "Kwik Nkap Technologies",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kwik-nkap/kwik-id.git",
+    "directory": "libs/sdk-react-native"
+  },
+  "homepage": "https://github.com/kwik-nkap/kwik-id/tree/main/libs/sdk-react-native#readme",
+  "bugs": {
+    "url": "https://github.com/kwik-nkap/kwik-id/issues"
+  },
+  "main": "./lib/commonjs/index.js",
+  "module": "./lib/module/index.js",
+  "types": "./lib/typescript/commonjs/index.d.ts",
+  "react-native": "./src/index.ts",
+  "source": "./src/index.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "source": "./src/index.ts",
+      "react-native": "./src/index.ts",
+      "import": {
+        "types": "./lib/typescript/module/index.d.ts",
+        "default": "./lib/module/index.js"
+      },
+      "require": {
+        "types": "./lib/typescript/commonjs/index.d.ts",
+        "default": "./lib/commonjs/index.js"
+      }
+    },
+    "./app.plugin.js": "./app.plugin.js"
+  },
+  "files": [
+    "src",
+    "lib",
+    "app.plugin.js",
+    "!**/__tests__",
+    "!**/*.test.*",
+    "!**/__mocks__",
+    "!**/__compat__*",
+    "!**/*.tsbuildinfo"
+  ],
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "exclude": "**/{__tests__,__mocks__,__compat__}/**",
+    "targets": [
+      [
+        "commonjs",
+        {
+          "esm": true
+        }
+      ],
+      [
+        "module",
+        {
+          "esm": true
+        }
+      ],
+      [
+        "typescript",
+        {
+          "project": "tsconfig.lib.json"
+        }
+      ]
+    ]
+  },
+  "nx": {
+    "name": "sdk-react-native"
+  },
+  "peerDependencies": {
+    "expo": ">=53.0.0 <54.0.0",
+    "expo-constants": "~17.1.0",
+    "expo-device": "~7.1.0",
+    "expo-file-system": "~18.1.0",
+    "expo-image-manipulator": "~13.1.0",
+    "expo-localization": "~16.1.0",
+    "react": ">=19.0.0",
+    "react-native": ">=0.79.0",
+    "react-native-reanimated": ">=3.10.0 <4.0.0",
+    "react-native-vision-camera": ">=4.6.0 <5.0.0",
+    "react-native-vision-camera-face-detector": ">=1.8.0 <2.0.0",
+    "react-native-worklets-core": ">=1.3.0 <2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react-native-reanimated": {
+      "optional": true
+    },
+    "react-native-vision-camera-face-detector": {
+      "optional": true
+    },
+    "react-native-worklets-core": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "expo": "~53.0.0",
+    "expo-constants": "~17.1.0",
+    "expo-device": "~7.1.0",
+    "expo-file-system": "~18.1.0",
+    "expo-image-manipulator": "~13.1.0",
+    "expo-localization": "~16.1.0",
+    "react": "19.0.0",
+    "react-native": "0.79.5",
+    "react-native-builder-bob": "^0.43.0",
+    "react-native-reanimated": "~3.17.0",
+    "react-native-vision-camera": "^4.6.0",
+    "react-native-vision-camera-face-detector": "^1.8.0",
+    "react-native-worklets-core": "^1.6.0",
+    "@kwik-id/types": "0.0.1",
+    "@kwik-id/sdk-core": "0.0.1"
+  },
+  "scripts": {
+    "build": "bob build",
+    "typecheck": "tsc --noEmit -p tsconfig.lib.json",
+    "test": "jest",
+    "publish:alpha": "bob build && pnpm publish --tag alpha --access public",
+    "publish:latest": "bob build && pnpm publish --access public"
+  }
 }

package/src/api/api-client.ts

@@ -0,0 +1,319 @@
+/**
+ * RN API client for the KwikId SDK gateway (`/sdk/v1/*`).
+ *
+ * Ported from @kwik-id/sdk-core: the JSON `request()` (fetch + AbortController) is
+ * unchanged; the XMLHttpRequest upload is replaced with an injectable multipart
+ * uploader (expo-file-system by default). `liveness_frame` has no server endpoint
+ * and is rejected.
+ */
+import { SessionManager } from "../crypto/session-manager";
+import type {
+    CaptureAsset,
+    CaptureType,
+    DocumentType,
+    LivenessResult,
+    QualityResult,
+    SessionInfo,
+    VerificationResult,
+} from "../types";
+import { ApiError } from "./api-error";
+import { type Uploader, uploadMultipart } from "./upload";
+
+export const DEFAULT_BASE_URL = "https://api.identity.kwiknkap.com";
+
+export interface ApiClientConfig {
+    baseUrl: string;
+    timeout?: number;
+    debug?: boolean;
+    /** Custom fetch implementation (for testing). */
+    fetch?: typeof fetch;
+    /** Custom multipart uploader (for testing). */
+    uploader?: Uploader;
+}
+
+export interface UploadResponse {
+    uploadId: string;
+    status: string;
+}
+
+export interface SubmitResponse {
+    success: boolean;
+    message?: string;
+    jobId?: string;
+}
+
+export interface StatusResponse {
+    jobId: string;
+    status: "queued" | "processing" | "completed" | "failed" | "verified" | "rejected";
+    progress?: number;
+    processingStep?: string;
+    errorCode?: string;
+    errorMessage?: string;
+    errorDetails?: {
+        document: string;
+        errorCode: string;
+        errorMessage: string;
+    };
+}
+
+export interface HandoffValidateResponse {
+    valid: boolean;
+    orgName?: string;
+    orgLogoUrl?: string;
+    expiresAt?: string;
+    error?: string;
+}
+
+export interface HandoffRedeemResponse {
+    sessionToken: string;
+    jobId: string;
+    expiresAt: string;
+}
+
+const CAPTURE_PATH: Record<CaptureType, string | null> = {
+    document_front: "front",
+    document_back: "back",
+    selfie: "selfie",
+    liveness_frame: null, // no server endpoint — liveness evidence rides in /submit
+};
+
+export class ApiClient {
+    private config: ApiClientConfig;
+    private sessionManager: SessionManager;
+    private uploader: Uploader;
+
+    constructor(sessionManager: SessionManager, config?: Partial<ApiClientConfig>) {
+        this.config = {
+            baseUrl: DEFAULT_BASE_URL,
+            timeout: 30000,
+            debug: false,
+            ...config,
+        };
+        this.sessionManager = sessionManager;
+        this.uploader = config?.uploader ?? uploadMultipart;
+    }
+
+    async validateSession(clientSecret: string): Promise<SessionInfo> {
+        await this.sessionManager.initializeFromClientSecret(clientSecret);
+        const response = await this.request<SessionInfo>("GET", "/sdk/v1/session");
+        this.sessionManager.updateSession({ expiresAt: new Date(response.expiresAt) });
+        return response;
+    }
+
+    async uploadCapture(
+        type: CaptureType,
+        asset: CaptureAsset,
+        onProgress?: (progress: number) => void
+    ): Promise<UploadResponse> {
+        const path = CAPTURE_PATH[type];
+        if (!path) {
+            throw new Error(`Unsupported capture type for upload: ${type}`);
+        }
+
+        const url = `${this.config.baseUrl}/sdk/v1/upload/${path}`;
+        const headers = this.sessionManager.getRequestHeaders();
+        return this.uploader({
+            url,
+            asset,
+            headers,
+            onProgress,
+            timeoutMs: this.config.timeout,
+        });
+    }
+
+    async submitVerification(
+        documentType: DocumentType,
+        clientAnalysis?: { qualityScores?: QualityResult; livenessResult?: LivenessResult }
+    ): Promise<SubmitResponse> {
+        const payload = await this.sessionManager.createSecurePayload({
+            documentType,
+            clientAnalysis,
+            submittedAt: Date.now(),
+        });
+        return this.request<SubmitResponse>("POST", "/sdk/v1/submit", payload);
+    }
+
+    async getStatus(): Promise<StatusResponse> {
+        return this.request<StatusResponse>("GET", "/sdk/v1/status");
+    }
+
+    async getResult(): Promise<VerificationResult> {
+        return this.request<VerificationResult>("GET", "/sdk/v1/result");
+    }
+
+    async pollForResult(
+        options: {
+            maxAttempts?: number;
+            intervalMs?: number;
+            onProgress?: (status: StatusResponse) => void;
+        } = {}
+    ): Promise<VerificationResult> {
+        const { maxAttempts = 60, intervalMs = 2000, onProgress } = options;
+        let attempts = 0;
+
+        while (attempts < maxAttempts) {
+            const status = await this.getStatus();
+            onProgress?.(status);
+
+            if (status.status === "verified") {
+                return this.getResult();
+            }
+
+            if (status.status === "rejected") {
+                const result = await this.getResult();
+                const contextualError = status.errorDetails
+                    ? `${status.errorDetails.document === "front" ? "Front" : "Back"} document: ${status.errorDetails.errorMessage}`
+                    : undefined;
+                return {
+                    ...result,
+                    status: "rejected",
+                    errorDetails: status.errorDetails,
+                    rejectionReasons: [
+                        contextualError || status.errorMessage || "Verification rejected",
+                    ],
+                };
+            }
+
+            if (status.status === "failed") {
+                // A failed job may have no result record, so fall back to a minimal one.
+                const result = await this.getResult().catch(
+                    (): VerificationResult => ({
+                        jobId: status.jobId,
+                        status: "rejected",
+                        overallScore: 0,
+                        scores: {
+                            documentQuality: 0,
+                            documentAuthenticity: 0,
+                            faceMatch: 0,
+                            liveness: 0,
+                        },
+                        timestamps: { submitted: "" },
+                        referenceId: "",
+                    })
+                );
+                return {
+                    ...result,
+                    // VerificationResult has no "failed" status (it mirrors sdk-core).
+                    status: "rejected",
+                    errorDetails: status.errorDetails,
+                    rejectionReasons: [
+                        status.errorDetails?.errorMessage ||
+                            status.errorMessage ||
+                            "Verification failed",
+                    ],
+                };
+            }
+
+            attempts++;
+            await this.delay(intervalMs);
+        }
+
+        throw new Error("Verification timeout");
+    }
+
+    // ---- Handoff (mobile redeemer) ----
+
+    async validateHandoff(code: string): Promise<HandoffValidateResponse> {
+        const url = `${this.config.baseUrl}/sdk/v1/handoff/${encodeURIComponent(code)}`;
+        const fetchFn = this.config.fetch || fetch;
+        const response = await fetchFn(url);
+        if (!response.ok) {
+            return { valid: false, error: `Validation failed: ${response.status}` };
+        }
+        return (await response.json()) as HandoffValidateResponse;
+    }
+
+    async redeemHandoff(code: string): Promise<HandoffRedeemResponse> {
+        const url = `${this.config.baseUrl}/sdk/v1/handoff/${encodeURIComponent(code)}/redeem`;
+        const fetchFn = this.config.fetch || fetch;
+        const response = await fetchFn(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+        });
+        if (!response.ok) {
+            const error = (await response.json().catch(() => ({}))) as Record<string, string>;
+            throw new ApiError(
+                error.message || `Redeem failed: ${response.status}`,
+                response.status
+            );
+        }
+        return (await response.json()) as HandoffRedeemResponse;
+    }
+
+    async reportHandoffStatus(code: string, status: "completed" | "abandoned"): Promise<void> {
+        await this.request<{ success: boolean }>(
+            "POST",
+            `/sdk/v1/handoff/${encodeURIComponent(code)}/status`,
+            { status }
+        );
+    }
+
+    getBaseUrl(): string {
+        return this.config.baseUrl;
+    }
+
+    private async request<T>(
+        method: "GET" | "POST" | "PUT" | "DELETE",
+        path: string,
+        body?: unknown
+    ): Promise<T> {
+        const url = `${this.config.baseUrl}${path}`;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+
+        try {
+            const headers: Record<string, string> = {
+                "Content-Type": "application/json",
+                ...this.sessionManager.getRequestHeaders(),
+            };
+            const fetchFn = this.config.fetch || fetch;
+
+            const response = await fetchFn(url, {
+                method,
+                headers,
+                body: body ? JSON.stringify(body) : undefined,
+                signal: controller.signal,
+            });
+
+            clearTimeout(timeoutId);
+
+            if (!response.ok) {
+                throw await this.parseErrorResponse(response);
+            }
+
+            const data = await response.json();
+            if (this.config.debug) {
+                console.log(`[KwikID API] ${method} ${path}`, { body, response: data });
+            }
+            return data as T;
+        } catch (error) {
+            clearTimeout(timeoutId);
+            if (error instanceof Error && error.name === "AbortError") {
+                throw new Error("Request timeout");
+            }
+            throw error;
+        }
+    }
+
+    private async parseErrorResponse(response: Response): Promise<Error> {
+        try {
+            const data = (await response.json()) as {
+                message?: string;
+                code?: string;
+                details?: unknown;
+            };
+            return new ApiError(
+                data.message || `API error: ${response.status}`,
+                response.status,
+                data.code,
+                data.details
+            );
+        } catch {
+            return new ApiError(`API error: ${response.status}`, response.status);
+        }
+    }
+
+    private delay(ms: number): Promise<void> {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}

package/src/api/api-error.ts

@@ -0,0 +1,28 @@
+/**
+ * API error (ported verbatim from @kwik-id/sdk-core).
+ */
+export class ApiError extends Error {
+    public readonly statusCode: number;
+    public readonly code?: string;
+    public readonly details?: unknown;
+
+    constructor(message: string, statusCode: number, code?: string, details?: unknown) {
+        super(message);
+        this.name = "ApiError";
+        this.statusCode = statusCode;
+        this.code = code;
+        this.details = details;
+    }
+
+    isRetryable(): boolean {
+        return this.statusCode >= 500 || this.statusCode === 429;
+    }
+
+    isAuthError(): boolean {
+        return this.statusCode === 401 || this.statusCode === 403;
+    }
+
+    isValidationError(): boolean {
+        return this.statusCode === 400 || this.statusCode === 422;
+    }
+}

package/src/api/index.ts

@@ -0,0 +1,12 @@
+export { ApiClient, DEFAULT_BASE_URL } from "./api-client";
+export type {
+    ApiClientConfig,
+    UploadResponse,
+    SubmitResponse,
+    StatusResponse,
+    HandoffValidateResponse,
+    HandoffRedeemResponse,
+} from "./api-client";
+export { ApiError } from "./api-error";
+export { uploadMultipart } from "./upload";
+export type { Uploader, UploadResult } from "./upload";