@flonkid/kyc 1.6.0 → 1.7.0

package/README.md

@@ -1,169 +1,175 @@
-# @flonkid/kyc
-
-Official SDK for [Flonk](https://flonk.id) identity verification.
-
-- **Dashboard**: [dashboard.flonk.id](https://dashboard.flonk.id)
-- **Docs**: [docs.flonk.id](https://docs.flonk.id)
-
-## Install
-
-```bash
-npm install @flonkid/kyc
-```
-
-| Import | Use |
-|--------|-----|
-| `@flonkid/kyc` | Browser — widget + React component |
-| `@flonkid/kyc/server` | Node.js — sessions API + webhook verification |
-
-## Keys
-
-You'll find two keys in **Dashboard → Project Settings → API Keys**:
-
-| Key | Prefix | Where to use | Purpose |
-|-----|--------|--------------|---------|
-| **Publishable key** | `pk_live_*` / `pk_sandbox_*` | Frontend (browser) | Loads your project branding (logo, colors) instantly |
-| **Secret key** | `sk_live_*` / `sk_sandbox_*` | Backend only | Creates sessions, authenticates API calls |
-
-> **Never expose your secret key in client-side code.**
-
-## React Component (recommended)
-
-### Option A: SDK handles session creation
-
-```tsx
-import { FlonkKYCWidget } from '@flonkid/kyc';
-
-<FlonkKYCWidget
-  publishableKey="pk_live_..."
-  serverUrl="/api/kyc/create-session"
-  clientMetadata={{ email: 'user@example.com', userId: 'user_123' }}
-  lang="de"
-  onSuccess={(result) => console.log('Verified:', result)}
-  onError={(error) => console.error(error)}
-  onCancel={() => console.log('Cancelled')}
-/>
-
-// With authenticated backend
-<FlonkKYCWidget
-  publishableKey="pk_live_..."
-  serverUrl="/api/kyc/create-session"
-  requestHeaders={{ Authorization: `Bearer ${token}` }}
-  ...
-/>
-```
-
-### Option B: You control session creation
-
-```tsx
-import { FlonkKYCWidget } from '@flonkid/kyc';
-
-// 1. Create session on your backend first
-const { sessionId, embedToken } = await fetch('/api/kyc/create-session', {
-  method: 'POST',
-  body: JSON.stringify({ email: user.email }),
-}).then(r => r.json());
-
-// 2. Pass credentials to widget
-<FlonkKYCWidget
-  sessionId={sessionId}
-  embedToken={embedToken}
-  lang="de"
-  onSuccess={(result) => console.log('Verified:', result)}
-  onError={(error) => console.error(error)}
-  onCancel={() => console.log('Cancelled')}
-/>
-```
-
-### Props
-
-| Prop | Type | Description |
-|------|------|-------------|
-| `publishableKey` | `string` | Your `pk_live_*` key — enables instant branded loader |
-| `serverUrl` | `string` | Your backend endpoint — SDK auto-creates session |
-| `sessionId` | `string` | Pre-created session ID (Option B) |
-| `embedToken` | `string` | JWT token from your backend (Option B) |
-| `requestHeaders` | `Record<string, string>` | Extra headers for serverUrl (e.g. JWT auth) |
-| `clientMetadata` | `Record<string, unknown>` | Custom data passed to session |
-| `lang` | `'en' \| 'de' \| 'uk'` | Widget language |
-| `onSuccess` | `(result) => void` | Verification completed |
-| `onError` | `(error) => void` | Error occurred |
-| `onCancel` | `() => void` | User closed widget |
-| `onReady` | `() => void` | Widget loaded |
-| `autoOpen` | `boolean` | Open on mount (default: `true`) |
-
-## Imperative API (non-React)
-
-```typescript
-import { FlonkKYC } from '@flonkid/kyc';
-
-const kyc = new FlonkKYC();
-
-const widget = await kyc.init({
-  publishableKey: 'pk_live_...',
-  serverUrl: '/api/kyc/create-session',
-  clientMetadata: { email: 'user@example.com' },
-  lang: 'de',
-  onSuccess: (result) => console.log('Verified:', result),
-  onError: (error) => console.error(error),
-  onCancel: () => console.log('Cancelled'),
-});
-
-// Cleanup
-widget.destroy();
-```
-
-## Server — Node.js
-
-```typescript
-import { FlonkKYCServer } from '@flonkid/kyc/server';
-
-const flonk = new FlonkKYCServer({ secretKey: 'sk_live_...' });
-
-// Create session
-const session = await flonk.createSession({
-  clientMetadata: { email: 'user@example.com', userId: 'user_123' },
-  expiryMinutes: 30,
-  language: 'de',
-});
-// → { id, embedToken, status, expiresAt, widgetUrl, qrCodeUrl }
-
-// Verify webhook
-const event = flonk.webhooks.constructEvent(rawBody, signature, secret);
-```
-
-## Webhook Events
-
-| Event | Description |
-|-------|-------------|
-| `verification.completed` | AI verification finished |
-| `verification.status_changed` | Admin changed status (approved/rejected) |
-| `verification.updated` | Admin edited verification data |
-
-```typescript
-const event = flonk.webhooks.constructEvent(rawBody, signature, secret);
-
-switch (event.type) {
-  case 'verification.completed':
-    console.log('Extracted:', event.data.object.extracted_data);
-    break;
-  case 'verification.status_changed':
-    console.log('New status:', event.data.object.status);
-    break;
-  case 'verification.updated':
-    console.log('Updated by:', event.data.object.updated_by);
-    break;
-}
-```
-
-## Links
-
-- [Full Documentation](https://docs.flonk.id)
-- [Integration Guide](https://docs.flonk.id/docs/integration-frontend-backend)
-- [Webhook Guide](https://docs.flonk.id/docs/webhooks)
-- [Dashboard](https://dashboard.flonk.id)
-
-## License
-
-Proprietary. Copyright (c) 2026 Flonk. All rights reserved.
-See [Terms of Service](https://flonk.id/terms) for usage terms.
+# @flonkid/kyc
+
+Official SDK for [Flonk](https://flonk.id) identity verification.
+
+- **Dashboard**: [dashboard.flonk.id](https://dashboard.flonk.id)
+- **Docs**: [docs.flonk.id](https://docs.flonk.id)
+
+## Install
+
+```bash
+npm install @flonkid/kyc
+```
+
+| Import | Use |
+|--------|-----|
+| `@flonkid/kyc` | Browser — widget + React component |
+| `@flonkid/kyc/server` | Node.js — sessions API + webhook verification |
+
+## Keys
+
+You'll find two keys in **Dashboard → Project Settings → API Keys**:
+
+| Key | Prefix | Where to use | Purpose |
+|-----|--------|--------------|---------|
+| **Publishable key** | `pk_live_*` / `pk_sandbox_*` | Frontend (browser) | Loads your project branding (logo, colors) instantly |
+| **Secret key** | `sk_live_*` / `sk_sandbox_*` | Backend only | Creates sessions, authenticates API calls |
+
+> **Never expose your secret key in client-side code.**
+
+## React Component (recommended)
+
+### Option A: SDK handles session creation
+
+```tsx
+import { FlonkKYCWidget } from '@flonkid/kyc';
+
+<FlonkKYCWidget
+  publishableKey="pk_live_..."
+  serverUrl="/api/kyc/create-session"
+  clientMetadata={{ email: 'user@example.com', userId: 'user_123' }}
+  lang="de"
+  onSuccess={(result) => console.log('Verified:', result)}
+  onError={(error) => console.error(error)}
+  onCancel={() => console.log('Cancelled')}
+/>
+
+// With authenticated backend
+<FlonkKYCWidget
+  publishableKey="pk_live_..."
+  serverUrl="/api/kyc/create-session"
+  requestHeaders={{ Authorization: `Bearer ${token}` }}
+  ...
+/>
+```
+
+### Option B: You control session creation
+
+```tsx
+import { FlonkKYCWidget } from '@flonkid/kyc';
+
+// 1. Create session on your backend first
+const { sessionId, embedToken } = await fetch('/api/kyc/create-session', {
+  method: 'POST',
+  body: JSON.stringify({ email: user.email }),
+}).then(r => r.json());
+
+// 2. Pass credentials to widget
+<FlonkKYCWidget
+  publishableKey="pk_live_..."  // optional — instant branded loader (see note)
+  sessionId={sessionId}
+  embedToken={embedToken}
+  lang="de"
+  onSuccess={(result) => console.log('Verified:', result)}
+  onError={(error) => console.error(error)}
+  onCancel={() => console.log('Cancelled')}
+/>
+```
+
+> `publishableKey` enables the instant branded loader in **both** flows. With it,
+> the brand color is resolved straight from the key (in parallel with session
+> setup) and painted on the first frame; without it, branding is resolved from
+> the session and the loader shows the default color until that request returns.
+
+### Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `publishableKey` | `string` | Your `pk_live_*` key — enables instant branded loader |
+| `serverUrl` | `string` | Your backend endpoint — SDK auto-creates session |
+| `sessionId` | `string` | Pre-created session ID (Option B) |
+| `embedToken` | `string` | JWT token from your backend (Option B) |
+| `requestHeaders` | `Record<string, string>` | Extra headers for serverUrl (e.g. JWT auth) |
+| `clientMetadata` | `Record<string, unknown>` | Custom data passed to session |
+| `lang` | `'en' \| 'de' \| 'uk'` | Widget language |
+| `onSuccess` | `(result) => void` | Verification completed |
+| `onError` | `(error) => void` | Error occurred |
+| `onCancel` | `() => void` | User closed widget |
+| `onReady` | `() => void` | Widget loaded |
+| `autoOpen` | `boolean` | Open on mount (default: `true`) |
+
+## Imperative API (non-React)
+
+```typescript
+import { FlonkKYC } from '@flonkid/kyc';
+
+const kyc = new FlonkKYC();
+
+const widget = await kyc.init({
+  publishableKey: 'pk_live_...',
+  serverUrl: '/api/kyc/create-session',
+  clientMetadata: { email: 'user@example.com' },
+  lang: 'de',
+  onSuccess: (result) => console.log('Verified:', result),
+  onError: (error) => console.error(error),
+  onCancel: () => console.log('Cancelled'),
+});
+
+// Cleanup
+widget.destroy();
+```
+
+## Server — Node.js
+
+```typescript
+import { FlonkKYCServer } from '@flonkid/kyc/server';
+
+const flonk = new FlonkKYCServer({ secretKey: 'sk_live_...' });
+
+// Create session
+const session = await flonk.createSession({
+  clientMetadata: { email: 'user@example.com', userId: 'user_123' },
+  expiryMinutes: 30,
+  language: 'de',
+});
+// → { id, embedToken, status, expiresAt, widgetUrl, qrCodeUrl }
+
+// Verify webhook
+const event = flonk.webhooks.constructEvent(rawBody, signature, secret);
+```
+
+## Webhook Events
+
+| Event | Description |
+|-------|-------------|
+| `verification.completed` | AI verification finished |
+| `verification.status_changed` | Admin changed status (approved/rejected) |
+| `verification.updated` | Admin edited verification data |
+
+```typescript
+const event = flonk.webhooks.constructEvent(rawBody, signature, secret);
+
+switch (event.type) {
+  case 'verification.completed':
+    console.log('Extracted:', event.data.object.extracted_data);
+    break;
+  case 'verification.status_changed':
+    console.log('New status:', event.data.object.status);
+    break;
+  case 'verification.updated':
+    console.log('Updated by:', event.data.object.updated_by);
+    break;
+}
+```
+
+## Links
+
+- [Full Documentation](https://docs.flonk.id)
+- [Integration Guide](https://docs.flonk.id/docs/integration-frontend-backend)
+- [Webhook Guide](https://docs.flonk.id/docs/webhooks)
+- [Dashboard](https://dashboard.flonk.id)
+
+## License
+
+Proprietary. Copyright (c) 2026 Flonk. All rights reserved.
+See [Terms of Service](https://flonk.id/terms) for usage terms.