@flonkid/kyc 1.4.2 → 1.5.1

package/README.md

@@ -11,45 +11,66 @@ Official SDK for [Flonk](https://flonk.id) identity verification.
 npm install @flonkid/kyc
 ```
 
-## Browser — Imperative
+| Import | Use |
+|--------|-----|
+| `@flonkid/kyc` | Browser — widget + React component |
+| `@flonkid/kyc/server` | Node.js — sessions API + webhook verification |
 
-```typescript
-import { FlonkKYC } from '@flonkid/kyc';
+## React Component (recommended)
 
-const kyc = new FlonkKYC();
-const widget = await kyc.init({
-  publishableKey: 'pk_live_...',
-  onSuccess: (result) => console.log('Verified:', result),
-  onError: (err) => console.error(err),
-});
+### Option A: SDK handles session creation
 
-// Later: widget.destroy()
+```tsx
+import { FlonkKYCWidget } from '@flonkid/kyc';
+
+<FlonkKYCWidget
+  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
+  serverUrl="/api/kyc/create-session"
+  requestHeaders={{ Authorization: `Bearer ${token}` }}
+  ...
+/>
 ```
 
-## Browser — React Component
+### Option B: You control session creation
 
 ```tsx
 import { FlonkKYCWidget } from '@flonkid/kyc';
 
-function App() {
-  return (
-    <FlonkKYCWidget
-      publishableKey="pk_live_..."
-      onSuccess={(result) => console.log('Verified:', result)}
-      onError={(err) => console.error(err)}
-    />
-  );
-}
+// 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` | Client-side key (`pk_live_*` or `pk_sandbox_*`) |
-| `serverUrl` | `string` | Your backend endpoint for session creation |
-| `sessionId` | `string` | Pre-created session ID |
-| `embedToken` | `string` | JWT token from server-to-server flow |
+| `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 |
@@ -57,6 +78,26 @@ function App() {
 | `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({
+  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
@@ -65,11 +106,14 @@ import { FlonkKYCServer } from '@flonkid/kyc/server';
 const flonk = new FlonkKYCServer({ secretKey: 'sk_live_...' });
 
 // Create session
-const session = await flonk.sessions.create({
-  clientMetadata: { userId: 'user_123' },
+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 signature
+// Verify webhook
 const event = flonk.webhooks.constructEvent(rawBody, signature, secret);
 ```
 
@@ -78,7 +122,7 @@ const event = flonk.webhooks.constructEvent(rawBody, signature, secret);
 | Event | Description |
 |-------|-------------|
 | `verification.completed` | AI verification finished |
-| `verification.status_changed` | Admin changed status |
+| `verification.status_changed` | Admin changed status (approved/rejected) |
 | `verification.updated` | Admin edited verification data |
 
 ```typescript
@@ -86,13 +130,13 @@ const event = flonk.webhooks.constructEvent(rawBody, signature, secret);
 
 switch (event.type) {
   case 'verification.completed':
-    // Automated decision
+    console.log('Extracted:', event.data.object.extracted_data);
     break;
   case 'verification.status_changed':
-    // Admin approved/rejected
+    console.log('New status:', event.data.object.status);
     break;
   case 'verification.updated':
-    // Admin edited extracted data
+    console.log('Updated by:', event.data.object.updated_by);
     break;
 }
 ```
@@ -100,9 +144,9 @@ switch (event.type) {
 ## Links
 
 - [Full Documentation](https://docs.flonk.id)
-- [Dashboard](https://dashboard.flonk.id)
+- [Integration Guide](https://docs.flonk.id/docs/integration-frontend-backend)
 - [Webhook Guide](https://docs.flonk.id/docs/webhooks)
-- [API Reference](https://docs.flonk.id/docs/api-verification)
+- [Dashboard](https://dashboard.flonk.id)
 
 ## License
 

package/dist/index.cjs

@@ -4,7 +4,7 @@ var react = require('react');
 var jsxRuntime = require('react/jsx-runtime');
 
 // src/shared/constants.ts
-var SDK_VERSION = "1.4.0";
+var SDK_VERSION = "1.5.1";
 var DEFAULT_WIDGET_URL = "https://widget.flonk.id";
 var DEFAULT_API_BASE = "https://api.flonk.id/v1";
 var WIDGET_EVENTS = {
@@ -121,11 +121,12 @@ function validateServerUrl(url) {
     throw new Error(`Invalid serverUrl: ${url}`);
   }
 }
-async function fetchSessionFromServer(serverUrl, clientMetadata) {
+async function fetchSessionFromServer(serverUrl, clientMetadata, requestHeaders) {
   validateServerUrl(serverUrl);
   const res = await fetch(serverUrl, {
     method: "POST",
-    headers: { "Content-Type": "application/json" },
+    headers: { "Content-Type": "application/json", ...requestHeaders },
+    credentials: "include",
     body: JSON.stringify({ clientMetadata })
   });
   if (!res.ok) {
@@ -769,18 +770,23 @@ var FlonkKYC = class {
   /**
    * Flow 1: serverUrl — POST to client's backend, get sessionId + embedToken.
    */
+  /**
+   * POST to serverUrl to get sessionId + embedToken, then same path as embed token flow.
+   * No loader here — avoids wrong brand color before design tokens exist; initWithEmbedToken
+   * fetches tokens first, then shows loader with project primary color.
+   */
   async initWithServerUrl(config) {
-    const loader = new Loader();
-    loader.show("#15BA68", config.lang);
     try {
       const { sessionId, embedToken } = await fetchSessionFromServer(
         config.serverUrl,
-        config.clientMetadata
+        config.clientMetadata,
+        config.requestHeaders
       );
-      loader.destroy();
       return this.initWithEmbedToken({ ...config, sessionId, embedToken });
     } catch (err) {
       const msg = err.message || "Failed to create session";
+      const loader = new Loader();
+      loader.show("#15BA68", config.lang);
       loader.showError(msg, config.lang);
       config.onError?.(msg);
       throw err;
@@ -984,6 +990,7 @@ function FlonkKYCWidget({
   lang,
   overlayColor,
   allowManualUpload,
+  requestHeaders,
   onSuccess,
   onError,
   onCancel,
@@ -1007,6 +1014,7 @@ function FlonkKYCWidget({
       lang,
       overlayColor,
       allowManualUpload,
+      requestHeaders,
       mount: mountRef.current || void 0,
       onSuccess: (r) => callbacksRef.current.onSuccess?.(r),
       onError: (e) => callbacksRef.current.onError?.(e),