@flonkid/kyc 1.9.2 → 1.9.3

package/dist/core.d.ts

@@ -0,0 +1,294 @@
+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;
+    /**
+     * Your project's publishable key (`pk_live_*` or `pk_sandbox_*`).
+     * Found in Dashboard → Project Settings → API Keys.
+     *
+     * 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;
+    embedToken?: string;
+    /**
+     * URL the desktop→mobile QR code points to. Needed for the mobile-transfer
+     * QR to render. In the `serverUrl` flow, return it from your endpoint
+     * alongside `sessionId`/`embedToken` (it's the `qrCodeUrl` from `createSession`);
+     * in the `sessionId` + `embedToken` flow, pass it here.
+     */
+    qrCodeUrl?: string;
+    clientMetadata?: Record<string, unknown>;
+    lang?: WidgetLanguage;
+    overlayColor?: string;
+    allowManualUpload?: boolean;
+    mount?: HTMLElement;
+    /**
+     * Extra headers sent with the `serverUrl` POST request.
+     * Use this to pass Authorization tokens (e.g. JWT) when your
+     * backend requires authentication.
+     *
+     * @example { Authorization: 'Bearer <jwt>' }
+     */
+    requestHeaders?: Record<string, string>;
+    onSuccess?: (result: VerificationResult) => void;
+    onError?: (error: string) => void;
+    onCancel?: () => void;
+    onReady?: () => void;
+}
+interface WidgetPreviewConfig {
+    colors?: PreviewColors;
+    documentType?: DocumentType;
+    lang?: WidgetLanguage;
+    overlayColor?: string;
+    onSuccess?: (result: VerificationResult) => void;
+    onError?: (error: string) => void;
+    onCancel?: () => void;
+}
+interface WidgetEmbedConfig {
+    container: string | HTMLElement;
+    colors?: PreviewColors;
+    device?: 'mobile' | 'desktop';
+    scale?: number;
+    documentType?: DocumentType;
+    lang?: WidgetLanguage;
+}
+interface WidgetInstance {
+    iframe: HTMLIFrameElement;
+    destroy: () => void;
+}
+interface EmbedInstance extends WidgetInstance {
+    setColors: (colors: Partial<PreviewColors>) => void;
+    setDevice: (device: 'mobile' | 'desktop') => void;
+    getColors: () => PreviewColors;
+}
+interface PreviewColors {
+    primaryColor?: string;
+    secondaryColor?: string;
+}
+interface VerificationResult {
+    sessionId?: string;
+    status?: string;
+    [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.9.3";
+    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.
+     *
+     * 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; 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>;
+    /**
+     * Preview mode — no API calls, mock data.
+     */
+    preview(config?: WidgetPreviewConfig): WidgetInstance;
+    /**
+     * Embed inline preview in a container (for dashboards).
+     */
+    embed(config: WidgetEmbedConfig): EmbedInstance;
+    /**
+     * Flow 1: serverUrl — POST to client's backend, get sessionId + embedToken.
+     *
+     * When `publishableKey` is provided, design tokens are fetched in parallel
+     * with the session creation request. This shows the branded loader ~200-500ms
+     * faster because we don't have to wait for the session to be created first.
+     */
+    private initWithServerUrl;
+    /**
+     * Flow 2: sessionId + embedToken — fetch session data, open widget.
+     */
+    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;
+    /**
+     * Flow 4: publishableKey — fetch widget token, open widget.
+     */
+    private initWithPublishableKey;
+    private buildWidget;
+    /**
+     * Core: create iframe, attach listeners, return WidgetInstance.
+     */
+    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;
+
+/**
+ * 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: FlonkErrorCode;
+    readonly statusCode?: number | undefined;
+    constructor(message: string, code: FlonkErrorCode, statusCode?: number | undefined);
+}
+declare class FlonkValidationError extends FlonkError {
+    constructor(message: string);
+}
+
+declare const SDK_VERSION = "1.9.3";
+/**
+ * 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, type FlonkKYCOptions, 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/core.js

@@ -0,0 +1,3 @@
+export { API_VERSION, FlonkError, FlonkKYC, FlonkValidationError, PROTOCOL_VERSION, SDK_VERSION, WIDGET_EVENTS, WIDGET_PARAMS, addDiagnosticHandler } from './chunk-EEHIUYDR.js';
+//# sourceMappingURL=core.js.map
+//# sourceMappingURL=core.js.map

package/dist/core.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"core.js"}

package/dist/index.cjs

@@ -4,7 +4,7 @@ var react = require('react');
 var jsxRuntime = require('react/jsx-runtime');
 
 // src/shared/constants.ts
-var SDK_VERSION = "1.9.2";
+var SDK_VERSION = "1.9.3";
 var DEFAULT_WIDGET_URL = "https://widget.flonk.id";
 var DEFAULT_API_BASE = "https://api.flonk.id/v1";
 var API_VERSION = "2026-06-01";