@flonkid/kyc 1.6.1 → 1.8.0

package/dist/index.d.ts

@@ -12,9 +12,15 @@ interface WidgetInitConfig {
      * Your project's publishable key (`pk_live_*` or `pk_sandbox_*`).
      * Found in Dashboard → Project Settings → API Keys.
      *
-     * When used with `serverUrl`, enables instant branded loading screen
-     * by fetching design tokens in parallel with session creation.
-     * Recommended for the best user experience.
+     * Enables an instant branded loading screen: the brand color is resolved
+     * directly from the key (a Redis-cached read) in parallel with session
+     * setup, so the loader paints your color on first frame instead of waiting
+     * on the session. Works with both flows:
+     *   - `serverUrl` (your backend creates the session), and
+     *   - `sessionId` + `embedToken` (you pass a pre-created session).
+     *
+     * Without it, branding is resolved from the session and the loader shows
+     * the default color until that request returns. Recommended for the best UX.
      */
     publishableKey?: string;
     sessionId?: string;
@@ -74,18 +80,38 @@ interface VerificationResult {
 }
 
 declare class FlonkKYC {
-    static readonly version = "1.6.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.
      *
-     * Flows (pick one):
-     *  1. `{ serverUrl, publishableKey }` — auto-create session via your backend (recommended).
-     *     `publishableKey` enables instant branded loader (~200-500ms faster).
-     *  2. `{ sessionId, embedToken }` — server-to-server with pre-created session
-     *  3. `{ publishableKey }` — client-side only (legacy)
+     * Flows (pick one; add `publishableKey` to any for an instant branded loader):
+     *  1. `{ serverUrl }` — SDK auto-creates the session via your backend (recommended).
+     *  2. `{ sessionId, embedToken }` — you created the session; pass its credentials.
+     *  3. `{ sessionId }` — **deprecated**: exchanges the sessionId for an embedToken
+     *     via an extra round-trip. Prefer flow 2 by returning `embedToken` from your
+     *     backend alongside `sessionId`.
+     *  4. `{ publishableKey }` — client-only; SDK mints a short-lived widget token.
      */
     init(config: WidgetInitConfig): Promise<WidgetInstance>;
     /**
@@ -110,6 +136,10 @@ declare class FlonkKYC {
     private initWithEmbedToken;
     /**
      * Flow 3: sessionId only — exchange for embedToken, then init.
+     *
+     * @deprecated Prefer flow 2 (`sessionId` + `embedToken`). Return the
+     * `embedToken` from your backend together with the `sessionId` to skip this
+     * extra token-exchange round-trip.
      */
     private initWithSession;
     /**
@@ -148,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;
@@ -158,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 };