@flonkid/kyc 1.8.1 → 1.9.0

package/dist/index.d.cts

@@ -2,9 +2,32 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
 
 type DocumentType = 'passport' | 'id_card' | 'driver_license';
 type WidgetLanguage = 'en' | 'de' | 'uk';
+type FlonkDiagnosticLevel = 'info' | 'warn' | 'error';
+/**
+ * Known diagnostic codes emitted when the SDK degrades or branches. The union
+ * is open (`| string`) so new codes don't break consumers' exhaustiveness.
+ */
+type FlonkDiagnosticCode = 'LOADER_FALLBACK_BUNDLED' | 'LOADER_SCRIPT_BLOCKED' | 'PREWARM_SKIPPED' | 'IFRAME_REUSE' | 'IFRAME_FRESH' | 'PROTOCOL_VERSION_MISMATCH' | 'READY_TIMEOUT_REVEAL' | (string & {});
+/**
+ * A structured diagnostic surfaced via `onDiagnostic` (and console when
+ * `window.__FLONK_DEBUG__` is set). Never contains tokens or PII.
+ */
+interface FlonkDiagnostic {
+    code: FlonkDiagnosticCode;
+    level: FlonkDiagnosticLevel;
+    message: string;
+    detail?: Record<string, unknown>;
+}
 interface FlonkKYCOptions {
     widgetUrl?: string;
     apiBase?: string;
+    /**
+     * Observe SDK degradations/branches (loader fallback, blocked script, prewarm
+     * skipped, ready-timeout reveal, …). Errors thrown here are swallowed — they
+     * can never break the SDK. Console output for the same events is gated behind
+     * `window.__FLONK_DEBUG__ = true` so there's no noise by default.
+     */
+    onDiagnostic?: (event: FlonkDiagnostic) => void;
 }
 interface WidgetInitConfig {
     serverUrl?: string;
@@ -79,11 +102,57 @@ interface VerificationResult {
     [key: string]: unknown;
 }
 
+/**
+ * Self-prewarming for the KYC widget.
+ *
+ * Warms the connection and assets to our widget origin BEFORE the user clicks
+ * "Start", so the loader (and ultimately the widget) appears with little or no
+ * wait. All work is scheduled at idle / after the host page's `load`, so it
+ * never competes with the host page's own critical resources.
+ *
+ * Levels (`prewarm`):
+ *   - 'connect' (default): preconnect + idle prefetch of the loader/branding
+ *     assets and the widget document. Cheap; warms DNS/TLS + caches.
+ *   - 'intent': warm when the user signals intent (hover / focus / the trigger
+ *     scrolls into view). Best for widgets on general pages — no cost for
+ *     visitors who never engage.
+ *   - 'eager': also pre-mount a hidden iframe at idle so the full widget bundle
+ *     loads in the background. Best for dedicated, high-click-through KYC pages.
+ *   - 'none': do nothing.
+ *
+ * Never throws; SSR-safe (no-ops when there's no document). Sessions are NEVER
+ * pre-created here — only static assets are warmed.
+ */
+type PrewarmLevel = 'connect' | 'intent' | 'eager' | 'none';
+
 declare class FlonkKYC {
-    static readonly version = "1.8.1";
+    static readonly version = "1.9.0";
     private readonly widgetUrl;
     private readonly apiBase;
+    private disposeDiagnostics;
     constructor(options?: FlonkKYCOptions);
+    /** Unregister this instance's `onDiagnostic` handler. */
+    dispose(): void;
+    /**
+     * 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?: {
+        publishableKey?: string;
+        sessionId?: string;
+        widgetUrl?: string;
+        apiBase?: string;
+        level?: PrewarmLevel;
+        trigger?: Element | null;
+    }): () => void;
     /**
      * 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.
@@ -153,6 +222,22 @@ declare class FlonkKYC {
     private openWidget;
 }
 
+/**
+ * Tiny observability sink. The SDK emits a structured diagnostic at every
+ * degradation/branch point (loader fallback, blocked script, prewarm skipped,
+ * ready-timeout reveal, …) so integrators — and we — can see WHY the SDK did
+ * what it did, instead of guessing from a silent fallback.
+ *
+ * Module-level by necessity: several emit points (prewarm, the server-loader
+ * script load) run outside any FlonkKYC instance (static / constructor). The
+ * FlonkKYC constructor registers its `onDiagnostic` here; `window.__FLONK_DEBUG__`
+ * additionally mirrors events to the console. Zero-cost when nothing is
+ * registered and the debug flag is unset.
+ */
+type DiagnosticHandler = (event: FlonkDiagnostic) => void;
+/** Register a diagnostic handler. Returns an unsubscribe. De-dupes by reference. */
+declare function addDiagnosticHandler(handler: DiagnosticHandler): () => void;
+
 interface FlonkKYCProps extends FlonkKYCOptions {
     publishableKey?: string;
     serverUrl?: string;
@@ -196,13 +281,52 @@ interface FlonkKYCBrandingPreloaderProps {
  */
 declare function FlonkKYCBrandingPreloader({ publishableKey, sessionId, apiBase, }: FlonkKYCBrandingPreloaderProps): null;
 
+/**
+ * Stable, machine-branchable error codes returned by the API in the `code`
+ * field of an error body. Open union (`| (string & {})`) so new codes don't
+ * break consumers — branch on the ones you handle, fall through on the rest.
+ */
+type FlonkErrorCode = 'authentication_error' | 'invalid_publishable_key' | 'session_not_found' | 'session_expired' | 'session_invalid_state' | 'rate_limited' | 'validation_error' | 'api_error' | (string & {});
 declare class FlonkError extends Error {
-    readonly code: string;
+    readonly code: FlonkErrorCode;
     readonly statusCode?: number | undefined;
-    constructor(message: string, code: string, statusCode?: number | undefined);
+    constructor(message: string, code: FlonkErrorCode, statusCode?: number | undefined);
 }
 declare class FlonkValidationError extends FlonkError {
     constructor(message: string);
 }
 
-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 };
+declare const SDK_VERSION = "1.9.0";
+/**
+ * REST API version this SDK is built against (date-pinned, separate from the
+ * package version). Sent as the `Flonk-Version` header so a future breaking API
+ * change can be served the old shape to old SDKs and the new shape to new ones.
+ * The API is additive-only within a version; a breaking change mints a new date.
+ */
+declare const API_VERSION = "2026-06-01";
+declare const PROTOCOL_VERSION = 1;
+/** postMessage `type` values exchanged between the SDK and the iframe. */
+declare const WIDGET_EVENTS: {
+    readonly READY: "KYC_WIDGET_READY";
+    readonly COMPLETE: "KYC_COMPLETE";
+    readonly CANCEL: "KYC_CANCEL";
+    readonly ERROR: "KYC_ERROR";
+    readonly CONFIG: "KYC_WIDGET_CONFIG";
+};
+/** Canonical iframe URL param keys the SDK stamps onto the widget src. */
+declare const WIDGET_PARAMS: {
+    readonly PROTOCOL_VERSION: "pv";
+    readonly SESSION_ID: "sessionId";
+    readonly EMBED_TOKEN: "embedToken";
+    readonly TOKEN: "token";
+    readonly PUBLISHABLE_KEY: "publishableKey";
+    readonly CLIENT_ID: "clientId";
+    readonly CLIENT_METADATA: "clientMetadata";
+    readonly DESIGN_TOKENS: "designTokens";
+    readonly ALLOW_MANUAL_UPLOAD: "allowManualUpload";
+    readonly LANG: "lang";
+    readonly OVERLAY_COLOR: "overlayColor";
+    readonly MODE: "mode";
+};
+
+export { API_VERSION, type DocumentType, type EmbedInstance, type FlonkDiagnostic, type FlonkDiagnosticCode, type FlonkDiagnosticLevel, FlonkError, type FlonkErrorCode, FlonkKYC, FlonkKYCBrandingPreloader, type FlonkKYCBrandingPreloaderProps, type FlonkKYCOptions, type FlonkKYCProps, FlonkKYCWidget, FlonkValidationError, PROTOCOL_VERSION, type PreviewColors, SDK_VERSION, type VerificationResult, WIDGET_EVENTS, WIDGET_PARAMS, type WidgetEmbedConfig, type WidgetInitConfig, type WidgetInstance, type WidgetLanguage, type WidgetPreviewConfig, addDiagnosticHandler };

package/dist/index.d.ts

@@ -2,9 +2,32 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
 
 type DocumentType = 'passport' | 'id_card' | 'driver_license';
 type WidgetLanguage = 'en' | 'de' | 'uk';
+type FlonkDiagnosticLevel = 'info' | 'warn' | 'error';
+/**
+ * Known diagnostic codes emitted when the SDK degrades or branches. The union
+ * is open (`| string`) so new codes don't break consumers' exhaustiveness.
+ */
+type FlonkDiagnosticCode = 'LOADER_FALLBACK_BUNDLED' | 'LOADER_SCRIPT_BLOCKED' | 'PREWARM_SKIPPED' | 'IFRAME_REUSE' | 'IFRAME_FRESH' | 'PROTOCOL_VERSION_MISMATCH' | 'READY_TIMEOUT_REVEAL' | (string & {});
+/**
+ * A structured diagnostic surfaced via `onDiagnostic` (and console when
+ * `window.__FLONK_DEBUG__` is set). Never contains tokens or PII.
+ */
+interface FlonkDiagnostic {
+    code: FlonkDiagnosticCode;
+    level: FlonkDiagnosticLevel;
+    message: string;
+    detail?: Record<string, unknown>;
+}
 interface FlonkKYCOptions {
     widgetUrl?: string;
     apiBase?: string;
+    /**
+     * Observe SDK degradations/branches (loader fallback, blocked script, prewarm
+     * skipped, ready-timeout reveal, …). Errors thrown here are swallowed — they
+     * can never break the SDK. Console output for the same events is gated behind
+     * `window.__FLONK_DEBUG__ = true` so there's no noise by default.
+     */
+    onDiagnostic?: (event: FlonkDiagnostic) => void;
 }
 interface WidgetInitConfig {
     serverUrl?: string;
@@ -79,11 +102,57 @@ interface VerificationResult {
     [key: string]: unknown;
 }
 
+/**
+ * Self-prewarming for the KYC widget.
+ *
+ * Warms the connection and assets to our widget origin BEFORE the user clicks
+ * "Start", so the loader (and ultimately the widget) appears with little or no
+ * wait. All work is scheduled at idle / after the host page's `load`, so it
+ * never competes with the host page's own critical resources.
+ *
+ * Levels (`prewarm`):
+ *   - 'connect' (default): preconnect + idle prefetch of the loader/branding
+ *     assets and the widget document. Cheap; warms DNS/TLS + caches.
+ *   - 'intent': warm when the user signals intent (hover / focus / the trigger
+ *     scrolls into view). Best for widgets on general pages — no cost for
+ *     visitors who never engage.
+ *   - 'eager': also pre-mount a hidden iframe at idle so the full widget bundle
+ *     loads in the background. Best for dedicated, high-click-through KYC pages.
+ *   - 'none': do nothing.
+ *
+ * Never throws; SSR-safe (no-ops when there's no document). Sessions are NEVER
+ * pre-created here — only static assets are warmed.
+ */
+type PrewarmLevel = 'connect' | 'intent' | 'eager' | 'none';
+
 declare class FlonkKYC {
-    static readonly version = "1.8.1";
+    static readonly version = "1.9.0";
     private readonly widgetUrl;
     private readonly apiBase;
+    private disposeDiagnostics;
     constructor(options?: FlonkKYCOptions);
+    /** Unregister this instance's `onDiagnostic` handler. */
+    dispose(): void;
+    /**
+     * 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?: {
+        publishableKey?: string;
+        sessionId?: string;
+        widgetUrl?: string;
+        apiBase?: string;
+        level?: PrewarmLevel;
+        trigger?: Element | null;
+    }): () => void;
     /**
      * 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.
@@ -153,6 +222,22 @@ declare class FlonkKYC {
     private openWidget;
 }
 
+/**
+ * Tiny observability sink. The SDK emits a structured diagnostic at every
+ * degradation/branch point (loader fallback, blocked script, prewarm skipped,
+ * ready-timeout reveal, …) so integrators — and we — can see WHY the SDK did
+ * what it did, instead of guessing from a silent fallback.
+ *
+ * Module-level by necessity: several emit points (prewarm, the server-loader
+ * script load) run outside any FlonkKYC instance (static / constructor). The
+ * FlonkKYC constructor registers its `onDiagnostic` here; `window.__FLONK_DEBUG__`
+ * additionally mirrors events to the console. Zero-cost when nothing is
+ * registered and the debug flag is unset.
+ */
+type DiagnosticHandler = (event: FlonkDiagnostic) => void;
+/** Register a diagnostic handler. Returns an unsubscribe. De-dupes by reference. */
+declare function addDiagnosticHandler(handler: DiagnosticHandler): () => void;
+
 interface FlonkKYCProps extends FlonkKYCOptions {
     publishableKey?: string;
     serverUrl?: string;
@@ -196,13 +281,52 @@ interface FlonkKYCBrandingPreloaderProps {
  */
 declare function FlonkKYCBrandingPreloader({ publishableKey, sessionId, apiBase, }: FlonkKYCBrandingPreloaderProps): null;
 
+/**
+ * Stable, machine-branchable error codes returned by the API in the `code`
+ * field of an error body. Open union (`| (string & {})`) so new codes don't
+ * break consumers — branch on the ones you handle, fall through on the rest.
+ */
+type FlonkErrorCode = 'authentication_error' | 'invalid_publishable_key' | 'session_not_found' | 'session_expired' | 'session_invalid_state' | 'rate_limited' | 'validation_error' | 'api_error' | (string & {});
 declare class FlonkError extends Error {
-    readonly code: string;
+    readonly code: FlonkErrorCode;
     readonly statusCode?: number | undefined;
-    constructor(message: string, code: string, statusCode?: number | undefined);
+    constructor(message: string, code: FlonkErrorCode, statusCode?: number | undefined);
 }
 declare class FlonkValidationError extends FlonkError {
     constructor(message: string);
 }
 
-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 };
+declare const SDK_VERSION = "1.9.0";
+/**
+ * REST API version this SDK is built against (date-pinned, separate from the
+ * package version). Sent as the `Flonk-Version` header so a future breaking API
+ * change can be served the old shape to old SDKs and the new shape to new ones.
+ * The API is additive-only within a version; a breaking change mints a new date.
+ */
+declare const API_VERSION = "2026-06-01";
+declare const PROTOCOL_VERSION = 1;
+/** postMessage `type` values exchanged between the SDK and the iframe. */
+declare const WIDGET_EVENTS: {
+    readonly READY: "KYC_WIDGET_READY";
+    readonly COMPLETE: "KYC_COMPLETE";
+    readonly CANCEL: "KYC_CANCEL";
+    readonly ERROR: "KYC_ERROR";
+    readonly CONFIG: "KYC_WIDGET_CONFIG";
+};
+/** Canonical iframe URL param keys the SDK stamps onto the widget src. */
+declare const WIDGET_PARAMS: {
+    readonly PROTOCOL_VERSION: "pv";
+    readonly SESSION_ID: "sessionId";
+    readonly EMBED_TOKEN: "embedToken";
+    readonly TOKEN: "token";
+    readonly PUBLISHABLE_KEY: "publishableKey";
+    readonly CLIENT_ID: "clientId";
+    readonly CLIENT_METADATA: "clientMetadata";
+    readonly DESIGN_TOKENS: "designTokens";
+    readonly ALLOW_MANUAL_UPLOAD: "allowManualUpload";
+    readonly LANG: "lang";
+    readonly OVERLAY_COLOR: "overlayColor";
+    readonly MODE: "mode";
+};
+
+export { API_VERSION, type DocumentType, type EmbedInstance, type FlonkDiagnostic, type FlonkDiagnosticCode, type FlonkDiagnosticLevel, FlonkError, type FlonkErrorCode, FlonkKYC, FlonkKYCBrandingPreloader, type FlonkKYCBrandingPreloaderProps, type FlonkKYCOptions, type FlonkKYCProps, FlonkKYCWidget, FlonkValidationError, PROTOCOL_VERSION, type PreviewColors, SDK_VERSION, type VerificationResult, WIDGET_EVENTS, WIDGET_PARAMS, type WidgetEmbedConfig, type WidgetInitConfig, type WidgetInstance, type WidgetLanguage, type WidgetPreviewConfig, addDiagnosticHandler };