@flonkid/kyc 1.7.0 → 1.8.0

package/dist/index.d.cts

@@ -80,10 +80,28 @@ interface VerificationResult {
 }
 
 declare class FlonkKYC {
-    static readonly version = "1.7.0";
+    static readonly version = "1.8.0";
     private readonly widgetUrl;
     private readonly apiBase;
     constructor(options?: FlonkKYCOptions);
+    /**
+     * Warm the project's branding (colors) ahead of time so the widget paints the
+     * brand color on the first frame, with no branding round-trip at click time.
+     *
+     * Call it early — on page mount, route enter, or hover of the "verify" button
+     * — well before `init()`. The result is cached (module-level, 5-min TTL) and
+     * every subsequent `init()`/`open()` for the same key reads from it. Safe to
+     * call repeatedly; concurrent calls dedupe. Never throws.
+     *
+     * @example
+     * // in a layout effect, long before the user clicks "Verify"
+     * FlonkKYC.preloadBranding({ publishableKey: 'pk_live_...' });
+     */
+    static preloadBranding(opts: {
+        publishableKey?: string;
+        sessionId?: string;
+        apiBase?: string;
+    }): Promise<void>;
     /**
      * Open the KYC verification widget.
      *
@@ -160,6 +178,23 @@ interface FlonkKYCProps extends FlonkKYCOptions {
     autoOpen?: boolean;
 }
 declare function FlonkKYCWidget({ widgetUrl, apiBase, autoOpen, publishableKey, serverUrl, sessionId, embedToken, clientMetadata, lang, overlayColor, allowManualUpload, requestHeaders, onSuccess, onError, onCancel, onReady, }: FlonkKYCProps): react_jsx_runtime.JSX.Element;
+interface FlonkKYCBrandingPreloaderProps {
+    publishableKey?: string;
+    sessionId?: string;
+    apiBase?: string;
+}
+/**
+ * Invisible helper that warms the project's branding cache on mount, so the
+ * widget paints the brand color on the first frame when the user later opens it.
+ *
+ * Mount it high in the tree (e.g. an authenticated layout) so branding is ready
+ * long before the user reaches the verification screen. Renders nothing.
+ *
+ * @example
+ * // app/(authed)/layout.tsx
+ * <FlonkKYCBrandingPreloader publishableKey={process.env.NEXT_PUBLIC_FLONK_PK} />
+ */
+declare function FlonkKYCBrandingPreloader({ publishableKey, sessionId, apiBase, }: FlonkKYCBrandingPreloaderProps): null;
 
 declare class FlonkError extends Error {
     readonly code: string;
@@ -170,4 +205,4 @@ declare class FlonkValidationError extends FlonkError {
     constructor(message: string);
 }
 
-export { type DocumentType, type EmbedInstance, FlonkError, FlonkKYC, type FlonkKYCOptions, type FlonkKYCProps, FlonkKYCWidget, FlonkValidationError, type PreviewColors, type VerificationResult, type WidgetEmbedConfig, type WidgetInitConfig, type WidgetInstance, type WidgetLanguage, type WidgetPreviewConfig };
+export { type DocumentType, type EmbedInstance, FlonkError, FlonkKYC, FlonkKYCBrandingPreloader, type FlonkKYCBrandingPreloaderProps, type FlonkKYCOptions, type FlonkKYCProps, FlonkKYCWidget, FlonkValidationError, type PreviewColors, type VerificationResult, type WidgetEmbedConfig, type WidgetInitConfig, type WidgetInstance, type WidgetLanguage, type WidgetPreviewConfig };

package/dist/index.d.ts

@@ -80,10 +80,28 @@ interface VerificationResult {
 }
 
 declare class FlonkKYC {
-    static readonly version = "1.7.0";
+    static readonly version = "1.8.0";
     private readonly widgetUrl;
     private readonly apiBase;
     constructor(options?: FlonkKYCOptions);
+    /**
+     * Warm the project's branding (colors) ahead of time so the widget paints the
+     * brand color on the first frame, with no branding round-trip at click time.
+     *
+     * Call it early — on page mount, route enter, or hover of the "verify" button
+     * — well before `init()`. The result is cached (module-level, 5-min TTL) and
+     * every subsequent `init()`/`open()` for the same key reads from it. Safe to
+     * call repeatedly; concurrent calls dedupe. Never throws.
+     *
+     * @example
+     * // in a layout effect, long before the user clicks "Verify"
+     * FlonkKYC.preloadBranding({ publishableKey: 'pk_live_...' });
+     */
+    static preloadBranding(opts: {
+        publishableKey?: string;
+        sessionId?: string;
+        apiBase?: string;
+    }): Promise<void>;
     /**
      * Open the KYC verification widget.
      *
@@ -160,6 +178,23 @@ interface FlonkKYCProps extends FlonkKYCOptions {
     autoOpen?: boolean;
 }
 declare function FlonkKYCWidget({ widgetUrl, apiBase, autoOpen, publishableKey, serverUrl, sessionId, embedToken, clientMetadata, lang, overlayColor, allowManualUpload, requestHeaders, onSuccess, onError, onCancel, onReady, }: FlonkKYCProps): react_jsx_runtime.JSX.Element;
+interface FlonkKYCBrandingPreloaderProps {
+    publishableKey?: string;
+    sessionId?: string;
+    apiBase?: string;
+}
+/**
+ * Invisible helper that warms the project's branding cache on mount, so the
+ * widget paints the brand color on the first frame when the user later opens it.
+ *
+ * Mount it high in the tree (e.g. an authenticated layout) so branding is ready
+ * long before the user reaches the verification screen. Renders nothing.
+ *
+ * @example
+ * // app/(authed)/layout.tsx
+ * <FlonkKYCBrandingPreloader publishableKey={process.env.NEXT_PUBLIC_FLONK_PK} />
+ */
+declare function FlonkKYCBrandingPreloader({ publishableKey, sessionId, apiBase, }: FlonkKYCBrandingPreloaderProps): null;
 
 declare class FlonkError extends Error {
     readonly code: string;
@@ -170,4 +205,4 @@ declare class FlonkValidationError extends FlonkError {
     constructor(message: string);
 }
 
-export { type DocumentType, type EmbedInstance, FlonkError, FlonkKYC, type FlonkKYCOptions, type FlonkKYCProps, FlonkKYCWidget, FlonkValidationError, type PreviewColors, type VerificationResult, type WidgetEmbedConfig, type WidgetInitConfig, type WidgetInstance, type WidgetLanguage, type WidgetPreviewConfig };
+export { type DocumentType, type EmbedInstance, FlonkError, FlonkKYC, FlonkKYCBrandingPreloader, type FlonkKYCBrandingPreloaderProps, type FlonkKYCOptions, type FlonkKYCProps, FlonkKYCWidget, FlonkValidationError, type PreviewColors, type VerificationResult, type WidgetEmbedConfig, type WidgetInitConfig, type WidgetInstance, type WidgetLanguage, type WidgetPreviewConfig };

package/dist/index.js

@@ -2,7 +2,7 @@ import { useRef, useMemo, useEffect } from 'react';
 import { jsx } from 'react/jsx-runtime';
 
 // src/shared/constants.ts
-var SDK_VERSION = "1.7.0";
+var SDK_VERSION = "1.8.0";
 var DEFAULT_WIDGET_URL = "https://widget.flonk.id";
 var DEFAULT_API_BASE = "https://api.flonk.id/v1";
 var WIDGET_EVENTS = {
@@ -104,21 +104,43 @@ async function fetchWidgetToken(pk, apiBase) {
   }
   return res.json();
 }
-async function fetchDesignTokens(apiBase, opts) {
+var BRANDING_CACHE_TTL_MS = 5 * 60 * 1e3;
+var brandingCache = /* @__PURE__ */ new Map();
+function brandingCacheKey(opts) {
+  if (opts.pk) return `pk:${opts.pk}`;
+  if (opts.sessionId) return `sid:${opts.sessionId}`;
+  if (opts.clientId) return `cid:${opts.clientId}`;
+  return null;
+}
+async function requestDesignTokens(apiBase, opts) {
   const params = [];
   if (opts.sessionId) params.push(`sessionId=${encodeURIComponent(opts.sessionId)}`);
   else if (opts.clientId) params.push(`clientId=${encodeURIComponent(opts.clientId)}`);
   const url = `${apiBase}/public/design-tokens${params.length ? "?" + params.join("&") : ""}`;
-  try {
-    const res = await fetchWithTimeout(
-      url,
-      { headers: opts.pk ? { "x-kyc-pk": opts.pk } : {}, credentials: "omit" },
-      8e3
-    );
-    return res.ok ? res.json() : null;
-  } catch {
-    return null;
+  const res = await fetchWithTimeout(
+    url,
+    { headers: opts.pk ? { "x-kyc-pk": opts.pk } : {}, credentials: "omit" },
+    8e3
+  );
+  return res.ok ? res.json() : null;
+}
+async function fetchDesignTokens(apiBase, opts) {
+  const key = brandingCacheKey(opts);
+  if (!key) return null;
+  const now = Date.now();
+  const cached = brandingCache.get(key);
+  if (cached && cached.expiresAt > now) {
+    return cached.promise;
   }
+  const promise = requestDesignTokens(apiBase, opts).catch(() => null);
+  brandingCache.set(key, { promise, expiresAt: now + BRANDING_CACHE_TTL_MS });
+  promise.then((tokens) => {
+    if (tokens == null) brandingCache.delete(key);
+  });
+  return promise;
+}
+function preloadDesignTokens(apiBase, opts) {
+  return fetchDesignTokens(apiBase, opts);
 }
 function validateServerUrl(url) {
   if (url.startsWith("/")) return;
@@ -703,6 +725,26 @@ var FlonkKYC = class {
     this.widgetUrl = (options.widgetUrl || DEFAULT_WIDGET_URL).replace(/\/$/, "");
     this.apiBase = (options.apiBase || DEFAULT_API_BASE).replace(/\/$/, "");
   }
+  /**
+   * Warm the project's branding (colors) ahead of time so the widget paints the
+   * brand color on the first frame, with no branding round-trip at click time.
+   *
+   * Call it early — on page mount, route enter, or hover of the "verify" button
+   * — well before `init()`. The result is cached (module-level, 5-min TTL) and
+   * every subsequent `init()`/`open()` for the same key reads from it. Safe to
+   * call repeatedly; concurrent calls dedupe. Never throws.
+   *
+   * @example
+   * // in a layout effect, long before the user clicks "Verify"
+   * FlonkKYC.preloadBranding({ publishableKey: 'pk_live_...' });
+   */
+  static preloadBranding(opts) {
+    const apiBase = (opts.apiBase || DEFAULT_API_BASE).replace(/\/$/, "");
+    return preloadDesignTokens(apiBase, {
+      pk: opts.publishableKey,
+      sessionId: opts.sessionId
+    }).then(() => void 0);
+  }
   // ── Public API ───────────────────────────────────────
   /**
    * Open the KYC verification widget.
@@ -1075,6 +1117,10 @@ function FlonkKYCWidget({
   const callbacksRef = useRef({ onSuccess, onError, onCancel, onReady });
   callbacksRef.current = { onSuccess, onError, onCancel, onReady };
   const sdk = useMemo(() => new FlonkKYC({ widgetUrl, apiBase }), [widgetUrl, apiBase]);
+  useEffect(() => {
+    if (!publishableKey && !sessionId) return;
+    void FlonkKYC.preloadBranding({ publishableKey, sessionId, apiBase });
+  }, [publishableKey, sessionId, apiBase]);
   const generationRef = useRef(0);
   useEffect(() => {
     if (!autoOpen) return;
@@ -1117,7 +1163,17 @@ function FlonkKYCWidget({
   }, [sdk, publishableKey, serverUrl, sessionId, embedToken, lang, overlayColor, allowManualUpload, autoOpen]);
   return /* @__PURE__ */ jsx("div", { ref: mountRef });
 }
+function FlonkKYCBrandingPreloader({
+  publishableKey,
+  sessionId,
+  apiBase
+}) {
+  useEffect(() => {
+    void FlonkKYC.preloadBranding({ publishableKey, sessionId, apiBase });
+  }, [publishableKey, sessionId, apiBase]);
+  return null;
+}
 
-export { FlonkError, FlonkKYC, FlonkKYCWidget, FlonkValidationError };
+export { FlonkError, FlonkKYC, FlonkKYCBrandingPreloader, FlonkKYCWidget, FlonkValidationError };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map