@flonkid/kyc 1.8.1 → 1.9.0

package/README.md

@@ -124,9 +124,16 @@ widget.destroy();
 ```typescript
 import { FlonkKYCServer } from '@flonkid/kyc/server';
 
-const flonk = new FlonkKYCServer({ secretKey: 'sk_live_...' });
+const flonk = new FlonkKYCServer({
+  secretKey: 'sk_live_...',
+  // Transient failures (429 / 5xx / network) are retried with jittered
+  // exponential backoff. GETs always retry; writes retry only when idempotent.
+  maxRetries: 2,   // default; set 0 to disable
+});
 
-// Create session
+// Create session — idempotent: a retry (same key) returns the original session,
+// never a duplicate. A key is auto-generated per call; pass `idempotencyKey` to
+// make a specific create idempotent across process restarts.
 const session = await flonk.createSession({
   clientMetadata: { email: 'user@example.com', userId: 'user_123' },
   expiryMinutes: 30,
@@ -162,6 +169,105 @@ switch (event.type) {
 }
 ```
 
+### Signature formats & replay protection
+
+Flonk sends **two** signature headers, both HMAC-SHA256 with your webhook
+secret; `constructEvent` verifies whichever you pass. Both prove authenticity +
+integrity — the only difference is replay protection:
+
+| Header | Format | Replay-protected? |
+|--------|--------|-------------------|
+| `X-Signature` | `t=<unix>, v1=<hex>` | ✅ Timestamp is signed; requests outside the skew window (default 300s) are rejected. |
+| `X-Signature-256` | `sha256=<hex>` | ❌ No timestamp — a captured request stays valid (close the gap with event-id dedup, below). |
+
+Both are fully valid signatures; prefer `X-Signature` when you want replay
+protection at the signature layer. Verification is constant-time.
+
+Since delivery is **at-least-once** (Flonk retries on non-200), also dedupe by
+`event.id` so a retry is processed once. Do this in your own store — a unique
+DB index, or Redis `SET id 1 NX EX <ttl>` — exactly as you would for Stripe:
+
+```typescript
+app.post('/webhooks/flonk', async (req, res) => {
+  const event = flonk.webhooks.constructEvent(req.rawBody, req.headers['x-signature'], secret);
+
+  // Idempotency: SET NX returns null if the key already existed → it's a retry.
+  const fresh = await redis.set(`whk:${event.id}`, '1', 'PX', 6 * 60_000, 'NX');
+  if (fresh === null) return res.status(200).end(); // already handled
+
+  await process(event);
+  res.status(200).end();
+});
+```
+
+## Content Security Policy & CORS
+
+The widget runs in an iframe on `widget.flonk.id` and loads a small branded
+loader script from the API. If your site sends a `Content-Security-Policy`
+header, allow our origins:
+
+```
+Content-Security-Policy:
+  frame-src   https://widget.flonk.id;
+  script-src  https://widget.flonk.id https://api.flonk.id;
+  connect-src https://api.flonk.id https://widget.flonk.id;
+  img-src     https://widget.flonk.id data:;
+```
+
+- `frame-src` — the widget iframe (`widget.flonk.id`).
+- `script-src` — `widget.js` (`widget.flonk.id`) and the server-hosted loader
+  (`api.flonk.id/v1/public/loader.js`). If the loader script is blocked, the SDK
+  **falls back to its bundled loader** — it still works, just without
+  dashboard-driven branding/fixes.
+- `connect-src` — session/token/design-token fetches.
+
+You do **not** need any CORS or `Cross-Origin-Resource-Policy` configuration on
+your side. Our public assets (`loader.js`, `loader-config`, `design-tokens`)
+already send `Cross-Origin-Resource-Policy: cross-origin`, and the API handles
+CORS for the SDK's `fetch`/`POST` calls.
+
+### Debugging blocked resources
+
+Every degradation is observable — no silent failures. Pass `onDiagnostic`, or
+flip the global debug flag to mirror events to the console:
+
+```typescript
+const kyc = new FlonkKYC({
+  onDiagnostic: (e) => console.log(`[flonk:${e.code}] ${e.message}`, e.detail),
+});
+
+// Or, without code — anywhere before the widget opens:
+window.__FLONK_DEBUG__ = true;          // SDK + widget.js both honor this
+// <script ... data-debug>                also enables it for widget.js
+```
+
+Codes you may see when something is blocked or degraded:
+
+| Code | Meaning |
+|------|---------|
+| `LOADER_SCRIPT_BLOCKED` | Server loader script failed to load (CSP `script-src`, CORP, offline). Bundled loader used. |
+| `LOADER_FALLBACK_BUNDLED` | Server loader wasn't ready at show time; bundled loader used. |
+| `PREWARM_SKIPPED` | Prewarm disabled (`prewarm: 'none'`) or no DOM (SSR). |
+| `READY_TIMEOUT_REVEAL` | No `READY` from the iframe within 4s; revealed on safety timeout (check `frame-src`). |
+| `IFRAME_FRESH` | A fresh widget iframe was built. |
+
+Console output is silent unless `onDiagnostic` is set or `__FLONK_DEBUG__` is
+truthy — zero noise in production by default.
+
+## Versioning
+
+Three versions, deliberately separate:
+
+- **Package version** (npm) — changes every release.
+- **SDK↔iframe wire protocol** — the widget iframe and SDK deploy independently,
+  so the wire is additive-only; a `PROTOCOL_VERSION_MISMATCH` diagnostic surfaces
+  a stale-cached peer. Details: [`CONTRACT.md`](./CONTRACT.md).
+- **REST API version** — date-pinned, sent as the `Flonk-Version` header on every
+  server request. The API is additive-only within a version; a breaking change
+  would mint a new date and serve the old shape to SDKs pinned to the old one.
+  Override with `new FlonkKYCServer({ apiVersion: '2026-06-01' })`; the server
+  echoes the resolved version back in the `Flonk-Version` response header.
+
 ## Links
 
 - [Full Documentation](https://docs.flonk.id)

package/dist/index.cjs

@@ -4,14 +4,31 @@ var react = require('react');
 var jsxRuntime = require('react/jsx-runtime');
 
 // src/shared/constants.ts
-var SDK_VERSION = "1.8.1";
+var SDK_VERSION = "1.9.0";
 var DEFAULT_WIDGET_URL = "https://widget.flonk.id";
 var DEFAULT_API_BASE = "https://api.flonk.id/v1";
+var API_VERSION = "2026-06-01";
+var PROTOCOL_VERSION = 1;
 var WIDGET_EVENTS = {
   READY: "KYC_WIDGET_READY",
   COMPLETE: "KYC_COMPLETE",
   CANCEL: "KYC_CANCEL",
-  ERROR: "KYC_ERROR"
+  ERROR: "KYC_ERROR",
+  CONFIG: "KYC_WIDGET_CONFIG"
+};
+var WIDGET_PARAMS = {
+  PROTOCOL_VERSION: "pv",
+  SESSION_ID: "sessionId",
+  EMBED_TOKEN: "embedToken",
+  TOKEN: "token",
+  PUBLISHABLE_KEY: "publishableKey",
+  CLIENT_ID: "clientId",
+  CLIENT_METADATA: "clientMetadata",
+  DESIGN_TOKENS: "designTokens",
+  ALLOW_MANUAL_UPLOAD: "allowManualUpload",
+  LANG: "lang",
+  OVERLAY_COLOR: "overlayColor",
+  MODE: "mode"
 };
 
 // src/shared/errors.ts
@@ -199,24 +216,6 @@ async function fetchSessionFromServer(serverUrl, clientMetadata, requestHeaders)
   sessionCreateInflight.set(key, promise);
   return promise;
 }
-async function fetchPublicSession(apiBase, sessionId, embedToken) {
-  const res = await fetchWithTimeout(`${apiBase}/public/session/${sessionId}`, {
-    headers: {
-      "Content-Type": "application/json",
-      "Authorization": `Bearer ${embedToken}`
-    }
-  });
-  if (!res.ok) {
-    let message = `Failed to fetch session (${res.status})`;
-    try {
-      const b = await res.json();
-      message = b.error || b.message || message;
-    } catch {
-    }
-    throw new Error(message);
-  }
-  return res.json();
-}
 async function exchangeSessionForToken(apiBase, sessionId) {
   const res = await fetchWithTimeout(`${apiBase}/public/session/${sessionId}/token`, {
     method: "POST",
@@ -247,10 +246,14 @@ function createIframe(src) {
       top: "0",
       left: "0",
       zIndex: "9999",
-      background: "transparent",
-      backgroundColor: "transparent",
+      // Hidden until reveal so the loader overlay doesn't show the iframe's own
+      // loading state through its translucent backdrop (double loader). Reveal
+      // is gated on READY-OR-a-timeout (see index.ts), so a missing READY can't
+      // leave it permanently hidden — that timeout is what removed the deadlock.
       opacity: "0",
       visibility: "hidden",
+      background: "transparent",
+      backgroundColor: "transparent",
       borderRadius: d ? "0" : "",
       boxShadow: d ? "none" : "",
       colorScheme: "normal"
@@ -285,15 +288,15 @@ function adjustZIndex(loader, iframe) {
 function transitionLoaderToIframe(loader, iframe, onDone) {
   const d = isDesktop();
   const dur = d ? 300 : 500;
-  setStyles(iframe, { opacity: "0", visibility: "hidden" });
   const card = loader.querySelector("div");
   if (card) {
     setStyles(card, {
+      transition: "transform 300ms ease-out, opacity 300ms ease-out",
       transform: d ? "translateY(-10px) scale(0.98)" : "translateY(-15px) scale(0.96)",
       opacity: "0"
     });
   }
-  loader.style.opacity = "0";
+  setStyles(loader, { transition: "opacity 300ms ease-out", opacity: "0" });
   setTimeout(() => {
     onDone();
     setStyles(iframe, {
@@ -304,6 +307,160 @@ function transitionLoaderToIframe(loader, iframe, onDone) {
   }, dur);
 }
 
+// src/browser/diagnostics.ts
+var handlers = /* @__PURE__ */ new Set();
+function addDiagnosticHandler(handler) {
+  handlers.add(handler);
+  return () => {
+    handlers.delete(handler);
+  };
+}
+function debugEnabled() {
+  try {
+    return Boolean(globalThis.__FLONK_DEBUG__);
+  } catch {
+    return false;
+  }
+}
+function emitDiagnostic(code, level, message, detail) {
+  const event = { code, level, message, detail };
+  if (debugEnabled()) {
+    try {
+      const fn = level === "error" ? console.error : level === "warn" ? console.warn : console.log;
+      fn(`[flonk:${code}] ${message}`, detail ?? "");
+    } catch {
+    }
+  }
+  for (const handler of handlers) {
+    try {
+      handler(event);
+    } catch {
+    }
+  }
+}
+
+// src/browser/prewarm.ts
+var noop = () => {
+};
+function originOf(url) {
+  try {
+    return new URL(url).origin;
+  } catch {
+    return url.replace(/\/+$/, "");
+  }
+}
+function addLinkHint(doc, rel, href, attrs) {
+  try {
+    const existing = doc.querySelector(`link[rel="${rel}"][href="${href}"]`);
+    if (existing) return;
+    const link = doc.createElement("link");
+    link.rel = rel;
+    link.href = href;
+    if (attrs) for (const k of Object.keys(attrs)) link.setAttribute(k, attrs[k]);
+    (doc.head || doc.documentElement).appendChild(link);
+  } catch {
+  }
+}
+function preconnect(widgetUrl, doc = document) {
+  const origin = originOf(widgetUrl);
+  addLinkHint(doc, "preconnect", origin, { crossorigin: "" });
+  addLinkHint(doc, "dns-prefetch", origin);
+}
+function defaultScheduleIdle(fn) {
+  if (typeof window === "undefined") {
+    fn();
+    return;
+  }
+  const w = window;
+  const run = () => {
+    if (typeof w.requestIdleCallback === "function") {
+      w.requestIdleCallback(fn, { timeout: 2e3 });
+    } else {
+      setTimeout(fn, 200);
+    }
+  };
+  if (document.readyState === "complete") run();
+  else window.addEventListener("load", run, { once: true });
+}
+function prewarm(options) {
+  const level = options.level ?? "connect";
+  const doc = options.doc ?? (typeof document !== "undefined" ? document : void 0);
+  if (level === "none" || !doc) {
+    emitDiagnostic("PREWARM_SKIPPED", "info", `Prewarm skipped (level=${level}${doc ? "" : ", no document"}).`);
+    return noop;
+  }
+  const scheduleIdle = options.scheduleIdle ?? defaultScheduleIdle;
+  const origin = originOf(options.widgetUrl);
+  preconnect(options.widgetUrl, doc);
+  const warmAssets = () => {
+    if (options.apiBase) {
+      const q = options.publishableKey ? `pk=${encodeURIComponent(options.publishableKey)}` : options.sessionId ? `sessionId=${encodeURIComponent(options.sessionId)}` : "";
+      addLinkHint(doc, "prefetch", `${options.apiBase}/v1/public/design-tokens${q ? `?${q}` : ""}`);
+    }
+    addLinkHint(doc, "prefetch", `${origin}/`, { as: "document" });
+  };
+  if (level === "intent") {
+    return attachIntent(doc, options.trigger ?? null, () => {
+      warmAssets();
+      mountHiddenIframe(doc, origin);
+    });
+  }
+  scheduleIdle(() => {
+    warmAssets();
+    if (level === "eager") mountHiddenIframe(doc, origin);
+  });
+  return noop;
+}
+function attachIntent(doc, trigger, warm) {
+  let fired = false;
+  const fire = () => {
+    if (fired) return;
+    fired = true;
+    cleanup();
+    warm();
+  };
+  const events = [
+    ["mouseenter", fire],
+    ["focusin", fire],
+    ["touchstart", fire]
+  ];
+  let io = null;
+  const cleanup = () => {
+    if (trigger) for (const [type, fn] of events) trigger.removeEventListener(type, fn);
+    if (io) {
+      io.disconnect();
+      io = null;
+    }
+  };
+  if (trigger) {
+    for (const [type, fn] of events) trigger.addEventListener(type, fn, { passive: true });
+    const w = doc.defaultView || (typeof window !== "undefined" ? window : void 0);
+    if (w && typeof w.IntersectionObserver === "function") {
+      const observer = new w.IntersectionObserver((entries) => {
+        if (entries.some((e) => e.isIntersecting)) fire();
+      });
+      observer.observe(trigger);
+      io = observer;
+    }
+  } else {
+    defaultScheduleIdle(fire);
+  }
+  return cleanup;
+}
+function mountHiddenIframe(doc, origin) {
+  try {
+    if (doc.querySelector("iframe[data-flonk-prewarm]")) return;
+    const iframe = doc.createElement("iframe");
+    iframe.src = `${origin}/?prewarm=1`;
+    iframe.setAttribute("data-flonk-prewarm", "1");
+    iframe.setAttribute("aria-hidden", "true");
+    iframe.tabIndex = -1;
+    iframe.style.cssText = "position:absolute;width:1px;height:1px;left:-9999px;top:-9999px;border:0;opacity:0;pointer-events:none";
+    (doc.body || doc.documentElement).appendChild(iframe);
+  } catch {
+  }
+}
+
 // src/browser/loader.ts
 var LOADER_I18N = {
   en: { title: "Initializing...", subtitle: "Loading KYC widget", errorTitle: "Something went wrong", close: "Close" },
@@ -553,8 +710,81 @@ var Loader = class {
     this.cleanup = null;
   }
 };
+function isServerLoaderReady() {
+  return typeof window !== "undefined" && !!window.FlonkWidgetLoader?.show;
+}
+var serverScriptRequested = false;
+function loadServerLoaderScript(apiBase, pk, sessionId) {
+  if (typeof document === "undefined" || serverScriptRequested || isServerLoaderReady()) return;
+  serverScriptRequested = true;
+  try {
+    const q = pk ? `?publishableKey=${encodeURIComponent(pk)}` : sessionId ? `?sessionId=${encodeURIComponent(sessionId)}` : "";
+    const s = document.createElement("script");
+    s.src = `${apiBase}/public/loader.js${q}`;
+    s.async = true;
+    s.onerror = () => {
+      serverScriptRequested = false;
+      emitDiagnostic(
+        "LOADER_SCRIPT_BLOCKED",
+        "warn",
+        `Failed to load the server loader (${s.src}). Likely a CSP script-src or CORP block \u2014 allow the API origin in script-src. Falling back to the bundled loader.`,
+        { src: s.src }
+      );
+    };
+    (document.head || document.documentElement).appendChild(s);
+  } catch {
+  }
+}
+var ServerLoader = class {
+  constructor() {
+    this.overlay = null;
+  }
+  show(primaryColor, lang) {
+    this.overlay = window.FlonkWidgetLoader.show({ primaryColor, lang });
+    return this.overlay;
+  }
+  get element() {
+    return this.overlay;
+  }
+  updateColor(primaryColor) {
+    this.overlay?.updateColor?.(primaryColor);
+  }
+  showError(message, lang) {
+    this.overlay?.showError?.(message, lang);
+  }
+  fadeOut() {
+    this.overlay?.fadeOut?.();
+  }
+  destroy() {
+    try {
+      this.overlay?.remove();
+    } catch {
+    }
+    this.overlay = null;
+  }
+};
+function makeLoader() {
+  if (isServerLoaderReady()) return new ServerLoader();
+  emitDiagnostic(
+    "LOADER_FALLBACK_BUNDLED",
+    "info",
+    "Server loader not ready at show time \u2014 using the bundled loader."
+  );
+  return new Loader();
+}
 
 // src/browser/message-handler.ts
+function checkProtocol(data) {
+  const remote = data.protocolVersion;
+  if (typeof remote === "number" && remote !== PROTOCOL_VERSION) {
+    emitDiagnostic(
+      "PROTOCOL_VERSION_MISMATCH",
+      "warn",
+      `SDK speaks protocol ${PROTOCOL_VERSION}, iframe speaks ${remote}. Additive-compatible, but check for a stale-cached widget if behavior is off.`,
+      { sdk: PROTOCOL_VERSION, iframe: remote }
+    );
+  }
+}
 var MessageHandler = class {
   constructor(iframeSrc, iframe, callbacks) {
     this.iframeSrc = iframeSrc;
@@ -587,6 +817,7 @@ var MessageHandler = class {
         this.completionHandled = true;
         this.callbacks.onError?.(data.error || "Unknown error");
       } else if (type === WIDGET_EVENTS.READY) {
+        checkProtocol(data);
         this.callbacks.onReady?.();
       }
     };
@@ -738,14 +969,55 @@ async function showLoaderWithEarlyColor(tokensPromise, lang) {
     new Promise((resolve) => setTimeout(() => resolve(null), EARLY_COLOR_BUDGET_MS))
   ]);
   const primaryColor = primaryFrom(earlyTokens);
-  const loader = new Loader();
+  const loader = makeLoader();
   loader.show(primaryColor, lang);
   return { loader, primaryColor };
 }
 var FlonkKYC = class {
   constructor(options = {}) {
+    this.disposeDiagnostics = null;
     this.widgetUrl = (options.widgetUrl || DEFAULT_WIDGET_URL).replace(/\/$/, "");
     this.apiBase = (options.apiBase || DEFAULT_API_BASE).replace(/\/$/, "");
+    if (options.onDiagnostic) this.disposeDiagnostics = addDiagnosticHandler(options.onDiagnostic);
+    if (typeof document !== "undefined") {
+      try {
+        preconnect(this.widgetUrl);
+      } catch {
+      }
+      try {
+        loadServerLoaderScript(this.apiBase);
+      } catch {
+      }
+    }
+  }
+  /** Unregister this instance's `onDiagnostic` handler. */
+  dispose() {
+    this.disposeDiagnostics?.();
+    this.disposeDiagnostics = null;
+  }
+  /**
+   * Prewarm the widget ahead of the user's click — preconnect + idle prefetch
+   * of branding/assets, and (with `level:'eager'`) a hidden background iframe so
+   * the full bundle is loaded before the click. Call on page mount / route
+   * enter. Returns a cleanup (removes `intent` listeners). Never pre-creates a
+   * session. SSR-safe.
+   *
+   * @example
+   * FlonkKYC.prewarm({ publishableKey: 'pk_live_…', level: 'eager' });
+   * // or, warm only when the user shows intent:
+   * FlonkKYC.prewarm({ publishableKey: 'pk_live_…', level: 'intent', trigger: btn });
+   */
+  static prewarm(opts = {}) {
+    if (typeof document === "undefined") return () => {
+    };
+    return prewarm({
+      widgetUrl: (opts.widgetUrl || DEFAULT_WIDGET_URL).replace(/\/$/, ""),
+      apiBase: (opts.apiBase || DEFAULT_API_BASE).replace(/\/$/, ""),
+      publishableKey: opts.publishableKey,
+      sessionId: opts.sessionId,
+      level: opts.level,
+      trigger: opts.trigger ?? null
+    });
   }
   /**
    * Warm the project's branding (colors) ahead of time so the widget paints the
@@ -896,20 +1168,7 @@ var FlonkKYC = class {
       const finalTokens = designTokens ?? await fetchDesignTokens(this.apiBase, { sessionId });
       const finalColor = primaryFrom(finalTokens);
       if (finalColor !== primaryColor) loader.updateColor(finalColor);
-      const sessionData = await fetchPublicSession(this.apiBase, sessionId, embedToken);
-      const session = {
-        id: sessionData.id,
-        allowManualUpload: sessionData.allowManualUpload ?? config.allowManualUpload ?? true,
-        clientMetadata: sessionData.clientMetadata || config.clientMetadata,
-        qrCodeUrl: sessionData.qrCodeUrl,
-        testMode: sessionData.testMode || false,
-        poaEnabled: sessionData.poaEnabled || false,
-        poaRequired: sessionData.poaRequired || false,
-        mlAutoCaptureEnabled: sessionData.mlAutoCaptureEnabled || false,
-        mlCropEnabled: sessionData.mlCropEnabled ?? true,
-        mlVerifyEnabled: sessionData.mlVerifyEnabled || false
-      };
-      return this.buildWidget(embedToken, session, config, loader, finalTokens);
+      return this.buildWidget(embedToken, sessionId, config, loader, finalTokens);
     } catch (err) {
       const msg = err.message || "Failed to create session";
       loader.showError(msg, config.lang);
@@ -923,32 +1182,12 @@ var FlonkKYC = class {
   async initWithEmbedToken(config) {
     const pk = config.publishableKey;
     const designTokensPromise = pk ? fetchDesignTokens(this.apiBase, { pk }) : fetchDesignTokens(this.apiBase, { sessionId: config.sessionId });
-    const sessionPromise = fetchPublicSession(
-      this.apiBase,
-      config.sessionId,
-      config.embedToken
-    );
     const { loader, primaryColor } = await showLoaderWithEarlyColor(designTokensPromise, config.lang);
     try {
-      const [sessionData, designTokens] = await Promise.all([
-        sessionPromise,
-        designTokensPromise
-      ]);
+      const designTokens = await designTokensPromise;
       const finalColor = primaryFrom(designTokens);
       if (finalColor !== primaryColor) loader.updateColor(finalColor);
-      const session = {
-        id: sessionData.id,
-        allowManualUpload: sessionData.allowManualUpload ?? config.allowManualUpload ?? true,
-        clientMetadata: sessionData.clientMetadata || config.clientMetadata,
-        qrCodeUrl: sessionData.qrCodeUrl,
-        testMode: sessionData.testMode || false,
-        poaEnabled: sessionData.poaEnabled || false,
-        poaRequired: sessionData.poaRequired || false,
-        mlAutoCaptureEnabled: sessionData.mlAutoCaptureEnabled || false,
-        mlCropEnabled: sessionData.mlCropEnabled ?? true,
-        mlVerifyEnabled: sessionData.mlVerifyEnabled || false
-      };
-      return this.buildWidget(config.embedToken, session, config, loader, designTokens);
+      return this.buildWidget(config.embedToken, config.sessionId, config, loader, designTokens);
     } catch (err) {
       const msg = err.message || "Failed to initialize verification";
       loader.showError(msg, config.lang);
@@ -974,7 +1213,7 @@ var FlonkKYC = class {
         exchangePromise,
         designTokensPromise
       ]);
-      return this.buildWidget(embedToken, session, config, loader, designTokens);
+      return this.buildWidget(embedToken, config.sessionId || session.id, config, loader, designTokens);
     } catch (err) {
       const msg = err.message || "Failed to initialize verification";
       loader.showError(msg, config.lang);
@@ -1021,32 +1260,21 @@ var FlonkKYC = class {
     }
   }
   // ── Core widget builder ──────────────────────────────
-  buildWidget(token, session, config, loader, designTokens) {
+  buildWidget(token, sessionId, config, loader, designTokens) {
     const params = {
       mode: "embedded",
-      sessionId: config.sessionId || session.id,
-      token,
-      allowManualUpload: String(session.allowManualUpload !== false)
+      sessionId,
+      token
     };
-    if (session.testMode) params.testMode = "true";
-    if (session.poaEnabled) params.poaEnabled = "true";
-    if (session.poaRequired) params.poaRequired = "true";
-    if (session.mlAutoCaptureEnabled) params.mlAutoCaptureEnabled = "true";
-    if (session.mlCropEnabled !== false) params.mlCropEnabled = "true";
-    if (session.mlVerifyEnabled) params.mlVerifyEnabled = "true";
-    if (session.vaultReuseEnabled) params.vaultReuseEnabled = "true";
-    if (session.vaultReuseChallenge) params.vaultReuseChallenge = session.vaultReuseChallenge;
-    if (session.faceAutoCapture) params.faceAutoCapture = JSON.stringify(session.faceAutoCapture);
-    if (session.project) params.project = JSON.stringify(session.project);
-    params.policyReady = "1";
+    if (config.allowManualUpload !== void 0) {
+      params.allowManualUpload = String(config.allowManualUpload !== false);
+    }
     if (designTokens?.colors) {
       params.designTokens = JSON.stringify(designTokens);
     }
     if (config.embedToken) params.embedToken = config.embedToken;
-    if (session.qrCodeUrl) params.qrCodeUrl = session.qrCodeUrl;
-    const clientMetadata = session.clientMetadata || config.clientMetadata;
-    if (clientMetadata) {
-      params.clientMetadata = JSON.stringify(clientMetadata);
+    if (config.clientMetadata) {
+      params.clientMetadata = JSON.stringify(config.clientMetadata);
     }
     if (config.lang) params.lang = config.lang;
     if (config.overlayColor) params.overlayColor = config.overlayColor;
@@ -1068,12 +1296,14 @@ var FlonkKYC = class {
     const filtered = Object.fromEntries(
       Object.entries(params).filter(([, v]) => v != null)
     );
+    filtered[WIDGET_PARAMS.PROTOCOL_VERSION] = String(PROTOCOL_VERSION);
     const search = new URLSearchParams(filtered);
     const src = `${this.widgetUrl}/?${search.toString()}`;
     const iframe = createIframe(src);
+    emitDiagnostic("IFRAME_FRESH", "info", "Built a fresh widget iframe");
     const mountTarget = opts.mount || document.body;
     const loader = opts.loader ?? (() => {
-      const l = new Loader();
+      const l = makeLoader();
       l.show(opts.primaryColor, opts.lang);
       return l;
     })();
@@ -1109,11 +1339,18 @@ var FlonkKYC = class {
       onReady: opts.onReady
     });
     handler.listen();
-    handler.onReadyOnce(() => {
-      if (loader.element) {
-        transitionLoaderToIframe(loader.element, iframe, () => loader.destroy());
-      }
-    });
+    let revealed = false;
+    const revealOnce = () => {
+      if (revealed) return;
+      revealed = true;
+      clearTimeout(revealTimer);
+      if (loader.element) transitionLoaderToIframe(loader.element, iframe, () => loader.destroy());
+    };
+    const revealTimer = setTimeout(() => {
+      emitDiagnostic("READY_TIMEOUT_REVEAL", "warn", "Widget did not signal READY in time; revealing anyway");
+      revealOnce();
+    }, 4e3);
+    handler.onReadyOnce(revealOnce);
     return {
       iframe,
       destroy: cleanupAll
@@ -1201,10 +1438,16 @@ function FlonkKYCBrandingPreloader({
   return null;
 }
 
+exports.API_VERSION = API_VERSION;
 exports.FlonkError = FlonkError;
 exports.FlonkKYC = FlonkKYC;
 exports.FlonkKYCBrandingPreloader = FlonkKYCBrandingPreloader;
 exports.FlonkKYCWidget = FlonkKYCWidget;
 exports.FlonkValidationError = FlonkValidationError;
+exports.PROTOCOL_VERSION = PROTOCOL_VERSION;
+exports.SDK_VERSION = SDK_VERSION;
+exports.WIDGET_EVENTS = WIDGET_EVENTS;
+exports.WIDGET_PARAMS = WIDGET_PARAMS;
+exports.addDiagnosticHandler = addDiagnosticHandler;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map