@kwik-id/sdk-react 0.1.0-alpha.3 → 0.1.0-alpha.7

package/README.md

@@ -1,6 +1,6 @@
 # @kwik-id/sdk-react
 
-React SDK for [KwikID](https://kwik-id.com) identity verification. Drop-in components and hooks for adding KYC verification to your React application.
+SDK for [KwikID](https://identity.kwiknkap.com) identity verification. Adds a complete KYC verification flow to any web application with a single function call.
 
 ## Installation
 
@@ -12,15 +12,13 @@ pnpm add @kwik-id/sdk-react
 yarn add @kwik-id/sdk-react
 ```
 
-**Peer dependencies:** `react >= 18`, `react-dom >= 18`, `framer-motion >= 10`, `lucide-react >= 0.300`
+**Peer dependencies:** `react >= 18`, `react-dom >= 18`, `framer-motion >= 10`, `lucide-react >= 0.300`, `lottie-react >= 2.4`
 
 ## Quick Start
 
-The fastest way to add verification is the `<KwikID>` component — a complete, pre-built verification flow.
-
 ### 1. Create a session on your backend
 
-Use [`@kwik-id/sdk-node`](https://www.npmjs.com/package/@kwik-id/sdk-node) to create a session server-side:
+> **Security:** Sessions must be created server-side. Your API key must never be exposed to the browser. Use [`@kwik-id/sdk-node`](https://www.npmjs.com/package/@kwik-id/sdk-node) or a direct API call from your backend to get a short-lived `clientSecret` (session token) to pass to the frontend.
 
 ```ts
 // Backend (Express, Next.js API route, etc.)
@@ -37,63 +35,68 @@ app.post("/api/create-session", async (req, res) => {
 });
 ```
 
-### 2. Use the KwikID component in your frontend
+### 2. Open the verification modal
 
-```tsx
-import { KwikID } from "@kwik-id/sdk-react";
+Call `openKwikVerification()` from any button click or event handler. It injects the modal at `document.body` — zero layout impact on your page — and returns a Promise that resolves when the user finishes or exits.
 
-function VerificationPage() {
-    const [clientSecret, setClientSecret] = useState<string | null>(null);
+```ts
+import { openKwikVerification } from "@kwik-id/sdk-react";
 
-    useEffect(() => {
-        fetch("/api/create-session", { method: "POST" })
-            .then((res) => res.json())
-            .then((data) => setClientSecret(data.clientSecret));
-    }, []);
+// Works in React, Vue, Angular, or plain JavaScript
+async function handleVerifyClick() {
+    const { clientSecret } = await fetch("/api/create-session", { method: "POST" }).then((r) =>
+        r.json()
+    );
 
-    if (!clientSecret) return <div>Loading...</div>;
+    const { status, jobId } = await openKwikVerification({
+        clientSecret,
+        appName: "My App",
+        theme: { primary: "#2563EB", accent: "#FBBF24" },
+        onSubmitted: ({ jobId }) => {
+            // Fires while modal is still open — save the jobId immediately.
+            // The actual verification result (pass/fail) arrives later via webhook.
+            console.log("Submitted for review, jobId:", jobId);
+        },
+    });
 
-    return (
-        <KwikID
-            config={{
-                clientSecret,
-                appName: "My App",
-                theme: { primary: "#2563EB", accent: "#FBBF24" },
-                onSubmitted: ({ jobId }) => {
-                    // Fires immediately when documents are uploaded and background
-                    // processing begins. Save the jobId to track status via webhooks.
-                    console.log("Submitted for review, jobId:", jobId);
-                },
-                onComplete: (data) => {
-                    // Fires when the user dismisses the result screen (clicks "Done").
-                    // Use this to redirect or clean up.
-                    console.log("User dismissed verification modal", data);
-                },
-                onError: (error) => {
-                    console.error("Verification error:", error);
-                },
-            }}
-        />
-    );
+    if (status === "submitted") {
+        // Modal closed. Documents are with the backend.
+        // Listen for the result via your webhook endpoint.
+        showMessage("We'll notify you once your identity is verified.");
+    } else if (status === "cancelled") {
+        // User closed the modal before submitting.
+    } else if (status === "error") {
+        // Upload or submission failed.
+    }
 }
 ```
 
-That's it — the component handles the full flow: document selection, camera capture, quality checks, face detection, liveness, and submission. The modal opens automatically when the component renders.
+That's it — the modal handles the full flow: document selection, camera capture, quality checks, liveness, and submission.
+
+> **Note:** `status === "submitted"` means documents were received by the backend and processing has started — **not** that the verification passed. The pass/fail result arrives asynchronously via [webhooks](#webhooks).
 
 ## Configuration
 
-### `KwikIDConfig`
+### `OpenVerificationOptions`
+
+| Option         | Type                  | Required | Description                                                                                       |
+| -------------- | --------------------- | -------- | ------------------------------------------------------------------------------------------------- |
+| `clientSecret` | `string`              | Yes      | Session token from your backend                                                                   |
+| `appName`      | `string`              | No       | App name shown in the modal header (falls back to org name)                                       |
+| `baseUrl`      | `string`              | No       | API base URL (defaults to production)                                                             |
+| `theme`        | `KwikIDTheme`         | No       | Custom theme colors                                                                               |
+| `showLogo`     | `boolean`             | No       | Show org logo in header (default: `true`)                                                         |
+| `onSubmitted`  | `({ jobId }) => void` | No       | Called while the modal is still open, immediately when documents are uploaded. Save `jobId` here. |
+
+### `VerificationOutcome`
+
+Resolved value of the Promise returned by `openKwikVerification()`:
 
-| Prop           | Type                     | Required | Description                                                                                                    |
-| -------------- | ------------------------ | -------- | -------------------------------------------------------------------------------------------------------------- |
-| `clientSecret` | `string`                 | Yes      | Session token from your backend                                                                                |
-| `appName`      | `string`                 | No       | App name shown in the header (falls back to org name)                                                          |
-| `baseUrl`      | `string`                 | No       | API base URL (defaults to production)                                                                          |
-| `theme`        | `KwikIDTheme`            | No       | Custom theme colors                                                                                            |
-| `showLogo`     | `boolean`                | No       | Show org logo in header (default: `true`)                                                                      |
-| `onSubmitted`  | `({ jobId }) => void`    | No       | Called immediately when documents are uploaded and background processing begins. Use this to save the `jobId`. |
-| `onComplete`   | `(data) => void`         | No       | Called when the user dismisses the result screen (clicks "Done")                                               |
-| `onError`      | `(error: Error) => void` | No       | Called on errors                                                                                               |
+| Field    | Type                                    | Description                                          |
+| -------- | --------------------------------------- | ---------------------------------------------------- |
+| `status` | `"submitted" \| "cancelled" \| "error"` | What happened when the modal closed                  |
+| `jobId`  | `string`                                | Present on `"submitted"` — use to track via webhooks |
+| `error`  | `Error`                                 | Present on `"cancelled"` and `"error"`               |
 
 ### `KwikIDTheme`
 
@@ -106,159 +109,57 @@ That's it — the component handles the full flow: document selection, camera ca
 }
 ```
 
-## Components
+## React Component (alternative)
 
-### `<KwikID>` — Drop-in Verification
-
-The all-in-one component. Renders a complete verification flow with document selection, camera capture, quality feedback, liveness detection, and submission.
+If you prefer a declarative React approach, `<KwikID>` is available. It renders the same modal as `openKwikVerification()` — mount it conditionally, unmount it to close.
 
 ```tsx
-<KwikID config={{ clientSecret, appName: "My App" }} />
-```
-
-### `<KYCModalFlow>` — Modal Verification
-
-Renders the verification flow inside a modal dialog with step indicators.
-
-```tsx
-import { KYCModalFlow } from "@kwik-id/sdk-react";
-```
-
-### `<KwikIDProvider>` — Context Provider
-
-For custom integrations, wrap your components with the provider to access SDK state via hooks.
-
-```tsx
-import { KwikIDProvider, useKwikID } from "@kwik-id/sdk-react";
+import { KwikID } from "@kwik-id/sdk-react";
 
-function App() {
-    return (
-        <KwikIDProvider config={{ clientSecret, appName: "My App" }} clientSecret={clientSecret}>
-            <CustomVerificationFlow />
-        </KwikIDProvider>
+{
+    showVerification && (
+        <KwikID
+            config={{
+                clientSecret,
+                appName: "My App",
+                onSubmitted: ({ jobId }) => saveJobId(jobId),
+                onComplete: () => setShowVerification(false),
+                onError: () => setShowVerification(false),
+            }}
+        />
     );
 }
-
-function CustomVerificationFlow() {
-    const {
-        sdk,
-        isSDKReady,
-        qualityResult,
-        detectedFace,
-        analyzeQuality,
-        detectFace,
-        submitVerification,
-    } = useKwikID();
-
-    // Build your own UI using SDK state and actions
-}
 ```
 
-### Individual Steps
-
-Build custom flows by composing individual step components:
-
-```tsx
-import {
-    CameraCapture,
-    ConsentStep,
-    DocumentTypeSelection,
-    IntroStep,
-    PhotoConfirmation,
-    PrepareIDBack,
-    PrepareIDFront,
-    PrepareSelfie,
-    SelfieConfirmation,
-} from "@kwik-id/sdk-react";
-```
+### `<KwikIDProvider>` — Context Provider
 
-### Cross-Device Handoff
+Wraps your components to provide SDK state and actions via the `useKwikID()` hook. Used internally by both `openKwikVerification()` and `<KwikID>`.
 
-Let desktop users continue verification on their phone:
+> **Note:** Building a fully custom verification flow with this provider (custom camera UI, custom step sequencing, cross-device handoff) requires significant implementation work. Detailed documentation for custom integrations is coming.
 
-```tsx
-import { HandoffChoiceView, HandoffQRView, useHandoff } from "@kwik-id/sdk-react";
-```
+`useKwikID()` returns: `isSDKReady`, `orgName`, `orgLogoUrl`, `qualityResult`, `detectedFace`, `alignmentResult`, `livenessResult`, `analyzeQuality(video)`, `detectFace(video)`, `checkAlignment()`, `runPassiveLiveness()`, `submitVerification(docType)`, `uploadFile(type, file)`.
 
 ## Hooks
 
-For advanced custom integrations, use hooks directly:
-
-### `useKwikId(config)`
-
-Core hook that manages the full SDK lifecycle.
-
-```tsx
-const { sdk, state, status, submit, captures, events } = useKwikId({
-    clientSecret,
-    baseUrl: "https://api.kwik-id.com",
-});
-```
-
-### `useCamera(options)`
-
-Camera access and frame capture.
-
-```tsx
-const { videoRef, stream, start, stop, capture } = useCamera({
-    facingMode: "environment",
-    width: 1280,
-    height: 720,
-});
-```
+The following hooks are exported. They are used internally by the built-in components and are available for custom integrations. Hooks marked **requires provider** must be used inside `<KwikIDProvider>`.
 
-### `useQuality(options)`
-
-Real-time image quality analysis.
-
-```tsx
-const { analyze, result, isAcceptable } = useQuality({
-    minBrightness: 0.3,
-    maxBrightness: 0.9,
-});
-```
-
-### `useFaceDetection(options)`
-
-Face detection and alignment feedback.
-
-```tsx
-const { detect, face, alignment, isAligned } = useFaceDetection();
-```
-
-### `useLiveness(options)`
-
-Passive and active liveness detection.
-
-```tsx
-const { check, result, isLive } = useLiveness();
-```
-
-### `useVerification(options)`
-
-Full verification workflow state machine.
-
-```tsx
-const { step, next, back, submit, isComplete } = useVerification({
-    clientSecret,
-    onComplete: (data) => console.log("Done", data),
-});
-```
-
-### `useHandoff()`
-
-Cross-device handoff (QR code transfer from desktop to mobile).
-
-```tsx
-const { startHandoff, handoffState, handoffUrl } = useHandoff();
-```
+| Hook                        | Requires provider | Description                                          |
+| --------------------------- | ----------------- | ---------------------------------------------------- |
+| `useKwikID()`               | Yes               | Full SDK state and actions (camera, capture, submit) |
+| `useCamera(options)`        | No                | Camera access and frame capture                      |
+| `useQuality(options)`       | No                | Real-time image quality analysis                     |
+| `useFaceDetection(options)` | No                | Face detection and alignment                         |
+| `useLiveness(options)`      | No                | Passive liveness detection                           |
+| `useVerification(options)`  | Yes               | Verification step state machine                      |
+| `useHandoff()`              | Yes               | Cross-device QR handoff                              |
 
 ## Utilities
 
 ```tsx
 import {
     // Check image sharpness
-    UploadManager, // Manage file uploads
+    UploadManager,
+    // Manage file uploads
     // Compress images before upload
     analyzeImageQuality,
     // Check image brightness

package/dist/hooks/kwik-id-context.d.ts

@@ -1,5 +1,5 @@
 import { AlignmentResult, DetectedFace, KwikIdSDK, PassiveLivenessResult, QualityResult } from '../../../sdk-core/src/index.ts';
-import { KwikIDConfig } from '../../../types/src/index.ts';
+import { KwikIDConfig } from '../../../types/src';
 /**
  * Extended context value that includes SDK functionality
  */

package/dist/index.d.ts

@@ -5,6 +5,8 @@
  *
  * @packageDocumentation
  */
+export { openKwikVerification } from './open-kwik-verification';
+export type { OpenVerificationOptions, VerificationOutcome } from './open-kwik-verification';
 export { KwikIDProvider, KwikIDContext, useKwikID } from './hooks/kwik-id-context';
 export { KwikIdProvider, useKwikIdContext } from './context/kwik-id-context';
 export type { KwikIdProviderProps, KwikIdContextState, KwikIdContextActions, KwikIdContextValue, } from './context/kwik-id-context';
@@ -35,5 +37,5 @@ export { compressImage } from './utils/image-compression';
 export { analyzeImageQuality, checkLuminance, checkBlur, getImageDataFromVideo, getImageDataFromFile, type ImageQualityResult, type QualityCheckResult, } from './utils/image-quality';
 export { UploadManager } from './utils/upload-manager';
 export type { KwikIdConfig, KwikIdTheme, QualityResult, QualityGuidance, DetectedFace, BoundingBox, FacePose, AlignmentResult, AlignmentGuidance, PassiveLivenessResult, Challenge, ChallengeType, ChallengeResult, VerificationResult, SDKState, SDKStatus, } from '../../sdk-core/src/index.ts';
-export type { KwikIDConfig, KwikIDTheme, KYCFormData, ConsentData, DocumentData, SelfieData, } from '../../types/src/index.ts';
+export type { KwikIDConfig, KwikIDTheme, KYCFormData, ConsentData, DocumentData, SelfieData, } from '../../types/src';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAGnF,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAC7E,YAAY,EACR,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,kBAAkB,GACrB,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EACH,SAAS,EACT,SAAS,EACT,UAAU,EACV,gBAAgB,EAChB,WAAW,EACX,eAAe,GAClB,MAAM,SAAS,CAAC;AACjB,YAAY,EACR,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,uBAAuB,EACvB,sBAAsB,EACtB,kBAAkB,EAClB,iBAAiB,EACjB,sBAAsB,EACtB,qBAAqB,EACrB,gBAAgB,GACnB,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,YAAY,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAGxD,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,KAAK,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACpE,OAAO,EAAE,gBAAgB,IAAI,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACrF,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAGtD,OAAO,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAC;AACpE,OAAO,EAAE,qBAAqB,EAAE,MAAM,8CAA8C,CAAC;AACrF,OAAO,EAAE,SAAS,EAAE,MAAM,iCAAiC,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,yCAAyC,CAAC;AAC5E,OAAO,EAAE,cAAc,EAAE,MAAM,uCAAuC,CAAC;AACvE,OAAO,EAAE,aAAa,EAAE,MAAM,sCAAsC,CAAC;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAC;AACpE,OAAO,EAAE,kBAAkB,EAAE,MAAM,0CAA0C,CAAC;AAG9E,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAGxE,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EACH,mBAAmB,EACnB,cAAc,EACd,SAAS,EACT,qBAAqB,EACrB,oBAAoB,EACpB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,GAC1B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAOvD,YAAY,EACR,YAAY,EACZ,WAAW,EACX,aAAa,EACb,eAAe,EACf,YAAY,EACZ,WAAW,EACX,QAAQ,EACR,eAAe,EACf,iBAAiB,EACjB,qBAAqB,EACrB,SAAS,EACT,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,QAAQ,EACR,SAAS,GACZ,MAAM,mBAAmB,CAAC;AAG3B,YAAY,EACR,YAAY,EACZ,WAAW,EACX,WAAW,EACX,WAAW,EACX,YAAY,EACZ,UAAU,GACb,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}