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

package/README.md

@@ -0,0 +1,311 @@
+# @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.
+
+## Installation
+
+```bash
+npm install @kwik-id/sdk-react
+# or
+pnpm add @kwik-id/sdk-react
+# or
+yarn add @kwik-id/sdk-react
+```
+
+**Peer dependencies:** `react >= 18`, `react-dom >= 18`, `framer-motion >= 10`, `lucide-react >= 0.300`
+
+## 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:
+
+```ts
+// Backend (Express, Next.js API route, etc.)
+import { KwikIDNode } from "@kwik-id/sdk-node";
+
+const kwikId = new KwikIDNode({ apiKey: process.env.KWIKID_API_KEY! });
+
+app.post("/api/create-session", async (req, res) => {
+    const session = await kwikId.createSession({
+        referenceId: req.user.id,
+        userName: req.user.name,
+    });
+    res.json({ clientSecret: session.token });
+});
+```
+
+### 2. Use the KwikID component in your frontend
+
+```tsx
+import { KwikID } from "@kwik-id/sdk-react";
+
+function VerificationPage() {
+    const [clientSecret, setClientSecret] = useState<string | null>(null);
+
+    useEffect(() => {
+        fetch("/api/create-session", { method: "POST" })
+            .then((res) => res.json())
+            .then((data) => setClientSecret(data.clientSecret));
+    }, []);
+
+    if (!clientSecret) return <div>Loading...</div>;
+
+    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);
+                },
+            }}
+        />
+    );
+}
+```
+
+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.
+
+## Configuration
+
+### `KwikIDConfig`
+
+| 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                                                                                               |
+
+### `KwikIDTheme`
+
+```ts
+{
+  primary?: string;    // Primary brand color (hex, e.g. "#2563EB")
+  accent?: string;     // Accent color (hex)
+  background?: string; // Background color (hex)
+  foreground?: string; // Foreground/text color (hex)
+}
+```
+
+## Components
+
+### `<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.
+
+```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";
+
+function App() {
+    return (
+        <KwikIDProvider config={{ clientSecret, appName: "My App" }} clientSecret={clientSecret}>
+            <CustomVerificationFlow />
+        </KwikIDProvider>
+    );
+}
+
+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";
+```
+
+### Cross-Device Handoff
+
+Let desktop users continue verification on their phone:
+
+```tsx
+import { HandoffChoiceView, HandoffQRView, useHandoff } from "@kwik-id/sdk-react";
+```
+
+## 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,
+});
+```
+
+### `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();
+```
+
+## Utilities
+
+```tsx
+import {
+    // Check image sharpness
+    UploadManager, // Manage file uploads
+    // Compress images before upload
+    analyzeImageQuality,
+    // Check image brightness
+    checkBlur,
+    // Analyze image quality from a frame
+    checkLuminance,
+    compressImage,
+} from "@kwik-id/sdk-react";
+```
+
+## TypeScript
+
+All types are exported for full TypeScript support:
+
+```tsx
+import type {
+    AlignmentResult,
+    DetectedFace,
+    DocumentData,
+    KYCFormData,
+    KwikIdConfig,
+    KwikIdTheme,
+    PassiveLivenessResult,
+    QualityResult,
+    SDKState,
+    SDKStatus,
+    SelfieData,
+    VerificationResult,
+} from "@kwik-id/sdk-react";
+```
+
+## Supported Document Types
+
+- National ID Card
+- Passport
+- Driver's License
+- Voter's Card
+
+## Browser Support
+
+- Chrome 80+
+- Firefox 78+
+- Safari 14+
+- Edge 80+
+
+Camera access requires HTTPS in production (except `localhost` for development).
+
+## License
+
+MIT