@flonkid/kyc 1.8.2 → 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.2";
+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
@@ -229,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"
@@ -267,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, {
@@ -286,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" },
@@ -535,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;
@@ -569,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?.();
       }
     };
@@ -720,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
@@ -1006,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;
     })();
@@ -1047,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
@@ -1139,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