@flonkid/kyc 1.4.1 → 1.5.0

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

@@ -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) {
@@ -775,7 +776,8 @@ var FlonkKYC = class {
     try {
       const { sessionId, embedToken } = await fetchSessionFromServer(
         config.serverUrl,
-        config.clientMetadata
+        config.clientMetadata,
+        config.requestHeaders
       );
       loader.destroy();
       return this.initWithEmbedToken({ ...config, sessionId, embedToken });
@@ -984,6 +986,7 @@ function FlonkKYCWidget({
   lang,
   overlayColor,
   allowManualUpload,
+  requestHeaders,
   onSuccess,
   onError,
   onCancel,
@@ -991,50 +994,45 @@ function FlonkKYCWidget({
 }) {
   const mountRef = react.useRef(null);
   const widgetRef = react.useRef(null);
-  const destroyedRef = react.useRef(false);
-  const initPromiseRef = react.useRef(null);
   const callbacksRef = react.useRef({ onSuccess, onError, onCancel, onReady });
   callbacksRef.current = { onSuccess, onError, onCancel, onReady };
   const sdk = react.useMemo(() => new FlonkKYC({ widgetUrl, apiBase }), [widgetUrl, apiBase]);
+  const generationRef = react.useRef(0);
   react.useEffect(() => {
     if (!autoOpen) return;
-    const prev = initPromiseRef.current;
-    destroyedRef.current = false;
-    const run = async () => {
-      if (prev) await prev.catch(() => {
-      });
-      if (destroyedRef.current) return;
-      const config = {
-        publishableKey,
-        serverUrl,
-        sessionId,
-        embedToken,
-        clientMetadata,
-        lang,
-        overlayColor,
-        allowManualUpload,
-        mount: mountRef.current || void 0,
-        onSuccess: (r) => callbacksRef.current.onSuccess?.(r),
-        onError: (e) => callbacksRef.current.onError?.(e),
-        onCancel: () => callbacksRef.current.onCancel?.(),
-        onReady: () => callbacksRef.current.onReady?.()
-      };
-      try {
-        const instance = await sdk.init(config);
-        if (destroyedRef.current) {
+    const thisGeneration = ++generationRef.current;
+    const config = {
+      publishableKey,
+      serverUrl,
+      sessionId,
+      embedToken,
+      clientMetadata,
+      lang,
+      overlayColor,
+      allowManualUpload,
+      requestHeaders,
+      mount: mountRef.current || void 0,
+      onSuccess: (r) => callbacksRef.current.onSuccess?.(r),
+      onError: (e) => callbacksRef.current.onError?.(e),
+      onCancel: () => callbacksRef.current.onCancel?.(),
+      onReady: () => callbacksRef.current.onReady?.()
+    };
+    const timer = setTimeout(() => {
+      if (generationRef.current !== thisGeneration) return;
+      sdk.init(config).then((instance) => {
+        if (generationRef.current !== thisGeneration) {
           instance.destroy();
         } else {
           widgetRef.current = instance;
         }
-      } catch (err) {
-        if (!destroyedRef.current) {
+      }).catch((err) => {
+        if (generationRef.current === thisGeneration) {
           callbacksRef.current.onError?.(err.message);
         }
-      }
-    };
-    initPromiseRef.current = run();
+      });
+    }, 0);
     return () => {
-      destroyedRef.current = true;
+      clearTimeout(timer);
       widgetRef.current?.destroy();
       widgetRef.current = null;
     };