@flonkid/kyc 1.8.1 → 1.9.0

package/dist/index.js

@@ -2,14 +2,31 @@ import { useRef, useMemo, useEffect } from 'react';
 import { jsx } from '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
@@ -197,24 +214,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",
@@ -245,10 +244,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"
@@ -283,15 +286,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, {
@@ -302,6 +305,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" },
@@ -551,8 +708,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;
@@ -585,6 +815,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?.();
       }
     };
@@ -736,14 +967,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
@@ -894,20 +1166,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);
@@ -921,32 +1180,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);
@@ -972,7 +1211,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);
@@ -1019,32 +1258,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;
@@ -1066,12 +1294,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;
     })();
@@ -1107,11 +1337,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
@@ -1199,6 +1436,6 @@ function FlonkKYCBrandingPreloader({
   return null;
 }
 
-export { FlonkError, FlonkKYC, FlonkKYCBrandingPreloader, FlonkKYCWidget, FlonkValidationError };
+export { API_VERSION, FlonkError, FlonkKYC, FlonkKYCBrandingPreloader, FlonkKYCWidget, FlonkValidationError, PROTOCOL_VERSION, SDK_VERSION, WIDGET_EVENTS, WIDGET_PARAMS, addDiagnosticHandler };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map