@flonkid/kyc 1.4.0

package/dist/server.d.ts

@@ -0,0 +1,127 @@
+type SessionStatus = 'pending' | 'connected' | 'processing' | 'completed' | 'failed' | 'expired';
+type DocumentType = 'passport' | 'id_card' | 'driver_license';
+type WidgetLanguage = 'en' | 'de' | 'uk';
+interface FlonkKYCServerOptions {
+    secretKey: string;
+    apiBase?: string;
+    timeout?: number;
+}
+interface CreateSessionParams {
+    clientMetadata?: Record<string, unknown>;
+    /** 1–60, default: 5 */
+    expiryMinutes?: number;
+    language?: WidgetLanguage;
+    serverMetadata?: Record<string, unknown>;
+}
+interface Session {
+    id: string;
+    status: SessionStatus;
+    expiresAt: string;
+    clientMetadata?: Record<string, unknown>;
+    widgetUrl: string;
+    qrCodeUrl: string;
+    createdAt: string;
+    projectId: string;
+    allowManualUpload: boolean;
+    embedToken?: string;
+    reused?: boolean;
+    testMode?: boolean;
+}
+interface SessionDetails extends Session {
+    lastActivity?: string;
+    serverMetadata?: Record<string, unknown>;
+    updatedAt: string;
+}
+interface UpdateSessionParams {
+    clientMetadata?: Record<string, unknown>;
+    serverMetadata?: Record<string, unknown>;
+}
+interface WebhookEvent {
+    id: string;
+    type: 'verification.completed' | 'verification.status_changed' | 'verification.updated';
+    created: number;
+    livemode: boolean;
+    data: {
+        object: {
+            id: string;
+            client_id?: string;
+            client_metadata?: Record<string, unknown>;
+            status: string;
+            confidence?: number;
+            document_type: string;
+            extracted_data: {
+                full_name?: string;
+                first_name?: string;
+                last_name?: string;
+                date_of_birth?: string;
+                nationality?: string;
+                sex?: string;
+                [key: string]: unknown;
+            };
+            created_at: string;
+            updated_at?: string;
+            updated_by?: string;
+            test_mode?: boolean;
+            poa_verification?: {
+                status: string;
+                confidence_score: number | null;
+            };
+            previous_status?: string;
+            rejection_reason?: string;
+            reviewed_by?: string;
+        };
+    };
+}
+interface WebhookVerifyOptions {
+    /** Max clock skew in seconds. Default: 300 */
+    maxSkewSeconds?: number;
+}
+
+declare class Webhooks {
+    /**
+     * Verify X-Signature-256 header: "sha256=<hex>"
+     */
+    verifySignature(payload: string, signature: string, secret: string): WebhookEvent;
+    /**
+     * Verify Stripe-like header: "t=<unix>, v1=<hex>"
+     */
+    verifyTimestampSignature(payload: string, header: string, secret: string, options?: WebhookVerifyOptions): WebhookEvent;
+    /**
+     * Auto-detect signature format and verify.
+     */
+    constructEvent(payload: string, signature: string, secret: string): WebhookEvent;
+    private parsePayload;
+    private parseHeader;
+    private safeEqual;
+}
+
+declare class FlonkKYCServer {
+    static readonly version = "1.4.0";
+    private readonly http;
+    readonly webhooks: Webhooks;
+    constructor(options: FlonkKYCServerOptions);
+    createSession(params?: CreateSessionParams): Promise<Session>;
+    getSession(sessionId: string): Promise<SessionDetails>;
+    updateSession(sessionId: string, params: UpdateSessionParams): Promise<SessionDetails>;
+}
+
+declare class FlonkError extends Error {
+    readonly code: string;
+    readonly statusCode?: number | undefined;
+    constructor(message: string, code: string, statusCode?: number | undefined);
+}
+declare class FlonkAPIError extends FlonkError {
+    readonly body?: unknown | undefined;
+    constructor(message: string, statusCode: number, body?: unknown | undefined);
+}
+declare class FlonkAuthenticationError extends FlonkError {
+    constructor(message?: string);
+}
+declare class FlonkValidationError extends FlonkError {
+    constructor(message: string);
+}
+declare class FlonkWebhookSignatureError extends FlonkError {
+    constructor(message?: string);
+}
+
+export { type CreateSessionParams, type DocumentType, FlonkAPIError, FlonkAuthenticationError, FlonkError, FlonkKYCServer, type FlonkKYCServerOptions, FlonkValidationError, FlonkWebhookSignatureError, type Session, type SessionDetails, type SessionStatus, type UpdateSessionParams, type WebhookEvent, type WebhookVerifyOptions, Webhooks, type WidgetLanguage };

package/dist/server.js

@@ -0,0 +1,184 @@
+import * as crypto from 'crypto';
+
+// src/shared/constants.ts
+var SDK_VERSION = "1.4.0";
+var DEFAULT_API_BASE = "https://api.flonk.id/v1";
+
+// src/shared/errors.ts
+var FlonkError = class extends Error {
+  constructor(message, code, statusCode) {
+    super(message);
+    this.code = code;
+    this.statusCode = statusCode;
+    this.name = "FlonkError";
+  }
+};
+var FlonkAPIError = class extends FlonkError {
+  constructor(message, statusCode, body) {
+    super(message, "api_error", statusCode);
+    this.body = body;
+    this.name = "FlonkAPIError";
+  }
+};
+var FlonkAuthenticationError = class extends FlonkError {
+  constructor(message = "Invalid or missing secret key") {
+    super(message, "authentication_error", 401);
+    this.name = "FlonkAuthenticationError";
+  }
+};
+var FlonkValidationError = class extends FlonkError {
+  constructor(message) {
+    super(message, "validation_error", 400);
+    this.name = "FlonkValidationError";
+  }
+};
+var FlonkWebhookSignatureError = class extends FlonkError {
+  constructor(message = "Invalid webhook signature") {
+    super(message, "webhook_signature_error");
+    this.name = "FlonkWebhookSignatureError";
+  }
+};
+
+// src/server/http-client.ts
+var HttpClient = class {
+  constructor(baseUrl, secretKey, timeout = 3e4) {
+    this.baseUrl = baseUrl;
+    this.secretKey = secretKey;
+    this.timeout = timeout;
+  }
+  async get(path) {
+    return this.request("GET", path);
+  }
+  async post(path, body) {
+    return this.request("POST", path, body);
+  }
+  async patch(path, body) {
+    return this.request("PATCH", path, body);
+  }
+  async request(method, path, body) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const res = await fetch(`${this.baseUrl}${path}`, {
+        method,
+        headers: {
+          "Authorization": `Bearer ${this.secretKey}`,
+          "Content-Type": "application/json",
+          "User-Agent": `flonk-kyc-node/${SDK_VERSION}`
+        },
+        body: body ? JSON.stringify(body) : void 0,
+        signal: controller.signal
+      });
+      const json = await res.json().catch(() => null);
+      if (!res.ok) {
+        if (res.status === 401) throw new FlonkAuthenticationError();
+        throw new FlonkAPIError(
+          json?.message || `Request failed: ${res.status}`,
+          res.status,
+          json
+        );
+      }
+      return json;
+    } catch (err) {
+      if (err instanceof FlonkAPIError || err instanceof FlonkAuthenticationError) throw err;
+      throw new FlonkAPIError(err.message, 0);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+};
+var Webhooks = class {
+  /**
+   * Verify X-Signature-256 header: "sha256=<hex>"
+   */
+  verifySignature(payload, signature, secret) {
+    const expected = "sha256=" + crypto.createHmac("sha256", secret).update(payload).digest("hex");
+    if (!this.safeEqual(signature, expected)) {
+      throw new FlonkWebhookSignatureError();
+    }
+    return this.parsePayload(payload);
+  }
+  /**
+   * Verify Stripe-like header: "t=<unix>, v1=<hex>"
+   */
+  verifyTimestampSignature(payload, header, secret, options) {
+    const maxSkew = options?.maxSkewSeconds ?? 300;
+    const parts = this.parseHeader(header);
+    const ts = Number(parts["t"]);
+    const v1 = parts["v1"];
+    if (!ts || !v1) {
+      throw new FlonkWebhookSignatureError("Missing timestamp or signature");
+    }
+    if (Math.abs(Math.floor(Date.now() / 1e3) - ts) > maxSkew) {
+      throw new FlonkWebhookSignatureError(`Timestamp skew exceeds ${maxSkew}s`);
+    }
+    const expected = crypto.createHmac("sha256", secret).update(`${ts}.${payload}`).digest("hex");
+    if (!this.safeEqual(v1, expected)) {
+      throw new FlonkWebhookSignatureError();
+    }
+    return this.parsePayload(payload);
+  }
+  /**
+   * Auto-detect signature format and verify.
+   */
+  constructEvent(payload, signature, secret) {
+    if (signature.startsWith("sha256=")) {
+      return this.verifySignature(payload, signature, secret);
+    }
+    if (signature.includes("t=") && signature.includes("v1=")) {
+      return this.verifyTimestampSignature(payload, signature, secret);
+    }
+    throw new FlonkWebhookSignatureError("Unrecognized signature format");
+  }
+  parsePayload(payload) {
+    try {
+      return JSON.parse(payload);
+    } catch {
+      throw new FlonkWebhookSignatureError("Malformed JSON payload");
+    }
+  }
+  parseHeader(header) {
+    const result = {};
+    for (const part of header.split(",")) {
+      const [k, v] = part.trim().split("=");
+      if (k && v) result[k] = v;
+    }
+    return result;
+  }
+  safeEqual(a, b) {
+    if (a.length !== b.length) return false;
+    return crypto.timingSafeEqual(Buffer.from(a), Buffer.from(b));
+  }
+};
+
+// src/server/index.ts
+var SK_PATTERN = /^sk_(live|sandbox|test_sandbox|test_live)_[A-Za-z0-9]{16,}$/;
+var FlonkKYCServer = class {
+  constructor(options) {
+    this.webhooks = new Webhooks();
+    if (!options.secretKey) throw new FlonkAuthenticationError("secretKey is required");
+    if (!SK_PATTERN.test(options.secretKey)) {
+      throw new FlonkAuthenticationError("Invalid secret key format. Expected: sk_live_*, sk_sandbox_*, sk_test_sandbox_*, sk_test_live_*");
+    }
+    const base = (options.apiBase || DEFAULT_API_BASE).replace(/\/$/, "");
+    this.http = new HttpClient(base, options.secretKey, options.timeout);
+  }
+  static {
+    this.version = SDK_VERSION;
+  }
+  async createSession(params) {
+    return this.http.post("/sessions", params ?? {});
+  }
+  async getSession(sessionId) {
+    if (!sessionId) throw new FlonkValidationError("sessionId is required");
+    return this.http.get(`/sessions/${sessionId}`);
+  }
+  async updateSession(sessionId, params) {
+    if (!sessionId) throw new FlonkValidationError("sessionId is required");
+    return this.http.patch(`/sessions/${sessionId}`, params);
+  }
+};
+
+export { FlonkAPIError, FlonkAuthenticationError, FlonkError, FlonkKYCServer, FlonkValidationError, FlonkWebhookSignatureError, Webhooks };
+//# sourceMappingURL=server.js.map
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/shared/constants.ts","../src/shared/errors.ts","../src/server/http-client.ts","../src/server/webhooks.ts","../src/server/index.ts"],"names":[],"mappings":"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","file":"server.js","sourcesContent":["export const SDK_VERSION = '1.4.0';\r\nexport const DEFAULT_WIDGET_URL = 'https://widget.flonk.id';\r\nexport const DEFAULT_API_BASE = 'https://api.flonk.id/v1';\r\n\r\nexport const WIDGET_EVENTS = {\r\n  READY: 'KYC_WIDGET_READY',\r\n  COMPLETE: 'KYC_COMPLETE',\r\n  CANCEL: 'KYC_CANCEL',\r\n  ERROR: 'KYC_ERROR',\r\n} as const;\r\n","export class FlonkError extends Error {\r\n  constructor(\r\n    message: string,\r\n    public readonly code: string,\r\n    public readonly statusCode?: number,\r\n  ) {\r\n    super(message);\r\n    this.name = 'FlonkError';\r\n  }\r\n}\r\n\r\nexport class FlonkAPIError extends FlonkError {\r\n  constructor(\r\n    message: string,\r\n    statusCode: number,\r\n    public readonly body?: unknown,\r\n  ) {\r\n    super(message, 'api_error', statusCode);\r\n    this.name = 'FlonkAPIError';\r\n  }\r\n}\r\n\r\nexport class FlonkAuthenticationError extends FlonkError {\r\n  constructor(message = 'Invalid or missing secret key') {\r\n    super(message, 'authentication_error', 401);\r\n    this.name = 'FlonkAuthenticationError';\r\n  }\r\n}\r\n\r\nexport class FlonkValidationError extends FlonkError {\r\n  constructor(message: string) {\r\n    super(message, 'validation_error', 400);\r\n    this.name = 'FlonkValidationError';\r\n  }\r\n}\r\n\r\nexport class FlonkWebhookSignatureError extends FlonkError {\r\n  constructor(message = 'Invalid webhook signature') {\r\n    super(message, 'webhook_signature_error');\r\n    this.name = 'FlonkWebhookSignatureError';\r\n  }\r\n}\r\n","import { SDK_VERSION } from '../shared/constants';\r\nimport { FlonkAPIError, FlonkAuthenticationError } from '../shared/errors';\r\n\r\nexport class HttpClient {\r\n  constructor(\r\n    private readonly baseUrl: string,\r\n    private readonly secretKey: string,\r\n    private readonly timeout = 30_000,\r\n  ) {}\r\n\r\n  async get<T>(path: string): Promise<T> {\r\n    return this.request<T>('GET', path);\r\n  }\r\n\r\n  async post<T>(path: string, body?: unknown): Promise<T> {\r\n    return this.request<T>('POST', path, body);\r\n  }\r\n\r\n  async patch<T>(path: string, body?: unknown): Promise<T> {\r\n    return this.request<T>('PATCH', path, body);\r\n  }\r\n\r\n  private async request<T>(method: string, path: string, body?: unknown): Promise<T> {\r\n    const controller = new AbortController();\r\n    const timer = setTimeout(() => controller.abort(), this.timeout);\r\n\r\n    try {\r\n      const res = await fetch(`${this.baseUrl}${path}`, {\r\n        method,\r\n        headers: {\r\n          'Authorization': `Bearer ${this.secretKey}`,\r\n          'Content-Type': 'application/json',\r\n          'User-Agent': `flonk-kyc-node/${SDK_VERSION}`,\r\n        },\r\n        body: body ? JSON.stringify(body) : undefined,\r\n        signal: controller.signal,\r\n      });\r\n\r\n      const json = await res.json().catch(() => null);\r\n\r\n      if (!res.ok) {\r\n        if (res.status === 401) throw new FlonkAuthenticationError();\r\n        throw new FlonkAPIError(\r\n          json?.message || `Request failed: ${res.status}`,\r\n          res.status,\r\n          json,\r\n        );\r\n      }\r\n\r\n      return json as T;\r\n    } catch (err) {\r\n      if (err instanceof FlonkAPIError || err instanceof FlonkAuthenticationError) throw err;\r\n      throw new FlonkAPIError((err as Error).message, 0);\r\n    } finally {\r\n      clearTimeout(timer);\r\n    }\r\n  }\r\n}\r\n","import * as crypto from 'crypto';\r\nimport { FlonkWebhookSignatureError } from '../shared/errors';\r\nimport type { WebhookEvent, WebhookVerifyOptions } from '../shared/types';\r\n\r\nexport class Webhooks {\r\n  /**\r\n   * Verify X-Signature-256 header: \"sha256=<hex>\"\r\n   */\r\n  verifySignature(payload: string, signature: string, secret: string): WebhookEvent {\r\n    const expected =\r\n      'sha256=' + crypto.createHmac('sha256', secret).update(payload).digest('hex');\r\n\r\n    if (!this.safeEqual(signature, expected)) {\r\n      throw new FlonkWebhookSignatureError();\r\n    }\r\n\r\n    return this.parsePayload(payload);\r\n  }\r\n\r\n  /**\r\n   * Verify Stripe-like header: \"t=<unix>, v1=<hex>\"\r\n   */\r\n  verifyTimestampSignature(\r\n    payload: string,\r\n    header: string,\r\n    secret: string,\r\n    options?: WebhookVerifyOptions,\r\n  ): WebhookEvent {\r\n    const maxSkew = options?.maxSkewSeconds ?? 300;\r\n    const parts = this.parseHeader(header);\r\n    const ts = Number(parts['t']);\r\n    const v1 = parts['v1'];\r\n\r\n    if (!ts || !v1) {\r\n      throw new FlonkWebhookSignatureError('Missing timestamp or signature');\r\n    }\r\n\r\n    if (Math.abs(Math.floor(Date.now() / 1000) - ts) > maxSkew) {\r\n      throw new FlonkWebhookSignatureError(`Timestamp skew exceeds ${maxSkew}s`);\r\n    }\r\n\r\n    const expected = crypto\r\n      .createHmac('sha256', secret)\r\n      .update(`${ts}.${payload}`)\r\n      .digest('hex');\r\n\r\n    if (!this.safeEqual(v1, expected)) {\r\n      throw new FlonkWebhookSignatureError();\r\n    }\r\n\r\n    return this.parsePayload(payload);\r\n  }\r\n\r\n  /**\r\n   * Auto-detect signature format and verify.\r\n   */\r\n  constructEvent(payload: string, signature: string, secret: string): WebhookEvent {\r\n    if (signature.startsWith('sha256=')) {\r\n      return this.verifySignature(payload, signature, secret);\r\n    }\r\n    if (signature.includes('t=') && signature.includes('v1=')) {\r\n      return this.verifyTimestampSignature(payload, signature, secret);\r\n    }\r\n    throw new FlonkWebhookSignatureError('Unrecognized signature format');\r\n  }\r\n\r\n  private parsePayload(payload: string): WebhookEvent {\r\n    try {\r\n      return JSON.parse(payload) as WebhookEvent;\r\n    } catch {\r\n      throw new FlonkWebhookSignatureError('Malformed JSON payload');\r\n    }\r\n  }\r\n\r\n  private parseHeader(header: string): Record<string, string> {\r\n    const result: Record<string, string> = {};\r\n    for (const part of header.split(',')) {\r\n      const [k, v] = part.trim().split('=');\r\n      if (k && v) result[k] = v;\r\n    }\r\n    return result;\r\n  }\r\n\r\n  private safeEqual(a: string, b: string): boolean {\r\n    if (a.length !== b.length) return false;\r\n    return crypto.timingSafeEqual(Buffer.from(a), Buffer.from(b));\r\n  }\r\n}\r\n","import { SDK_VERSION, DEFAULT_API_BASE } from '../shared/constants';\r\nimport { FlonkAuthenticationError, FlonkValidationError } from '../shared/errors';\r\nimport type {\r\n  FlonkKYCServerOptions,\r\n  CreateSessionParams,\r\n  Session,\r\n  SessionDetails,\r\n  UpdateSessionParams,\r\n} from '../shared/types';\r\nimport { HttpClient } from './http-client';\r\nimport { Webhooks } from './webhooks';\r\n\r\nconst SK_PATTERN = /^sk_(live|sandbox|test_sandbox|test_live)_[A-Za-z0-9]{16,}$/;\r\n\r\nexport class FlonkKYCServer {\r\n  static readonly version = SDK_VERSION;\r\n\r\n  private readonly http: HttpClient;\r\n  public readonly webhooks = new Webhooks();\r\n\r\n  constructor(options: FlonkKYCServerOptions) {\r\n    if (!options.secretKey) throw new FlonkAuthenticationError('secretKey is required');\r\n    if (!SK_PATTERN.test(options.secretKey)) {\r\n      throw new FlonkAuthenticationError('Invalid secret key format. Expected: sk_live_*, sk_sandbox_*, sk_test_sandbox_*, sk_test_live_*');\r\n    }\r\n\r\n    const base = (options.apiBase || DEFAULT_API_BASE).replace(/\\/$/, '');\r\n    this.http = new HttpClient(base, options.secretKey, options.timeout);\r\n  }\r\n\r\n  async createSession(params?: CreateSessionParams): Promise<Session> {\r\n    return this.http.post<Session>('/sessions', params ?? {});\r\n  }\r\n\r\n  async getSession(sessionId: string): Promise<SessionDetails> {\r\n    if (!sessionId) throw new FlonkValidationError('sessionId is required');\r\n    return this.http.get<SessionDetails>(`/sessions/${sessionId}`);\r\n  }\r\n\r\n  async updateSession(sessionId: string, params: UpdateSessionParams): Promise<SessionDetails> {\r\n    if (!sessionId) throw new FlonkValidationError('sessionId is required');\r\n    return this.http.patch<SessionDetails>(`/sessions/${sessionId}`, params);\r\n  }\r\n}\r\n"]}

package/dist/types.d.ts

@@ -0,0 +1,153 @@
+type SessionStatus = 'pending' | 'connected' | 'processing' | 'completed' | 'failed' | 'expired';
+type DocumentType = 'passport' | 'id_card' | 'driver_license';
+type WidgetLanguage = 'en' | 'de' | 'uk';
+interface FlonkKYCOptions {
+    widgetUrl?: string;
+    apiBase?: string;
+}
+interface WidgetInitConfig {
+    serverUrl?: string;
+    publishableKey?: string;
+    sessionId?: string;
+    embedToken?: string;
+    clientMetadata?: Record<string, unknown>;
+    lang?: WidgetLanguage;
+    overlayColor?: string;
+    allowManualUpload?: boolean;
+    mount?: HTMLElement;
+    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;
+}
+interface FlonkKYCServerOptions {
+    secretKey: string;
+    apiBase?: string;
+    timeout?: number;
+}
+interface CreateSessionParams {
+    clientMetadata?: Record<string, unknown>;
+    /** 1–60, default: 5 */
+    expiryMinutes?: number;
+    language?: WidgetLanguage;
+    serverMetadata?: Record<string, unknown>;
+}
+interface Session {
+    id: string;
+    status: SessionStatus;
+    expiresAt: string;
+    clientMetadata?: Record<string, unknown>;
+    widgetUrl: string;
+    qrCodeUrl: string;
+    createdAt: string;
+    projectId: string;
+    allowManualUpload: boolean;
+    embedToken?: string;
+    reused?: boolean;
+    testMode?: boolean;
+}
+interface SessionDetails extends Session {
+    lastActivity?: string;
+    serverMetadata?: Record<string, unknown>;
+    updatedAt: string;
+}
+interface UpdateSessionParams {
+    clientMetadata?: Record<string, unknown>;
+    serverMetadata?: Record<string, unknown>;
+}
+interface WebhookEvent {
+    id: string;
+    type: 'verification.completed' | 'verification.status_changed' | 'verification.updated';
+    created: number;
+    livemode: boolean;
+    data: {
+        object: {
+            id: string;
+            client_id?: string;
+            client_metadata?: Record<string, unknown>;
+            status: string;
+            confidence?: number;
+            document_type: string;
+            extracted_data: {
+                full_name?: string;
+                first_name?: string;
+                last_name?: string;
+                date_of_birth?: string;
+                nationality?: string;
+                sex?: string;
+                [key: string]: unknown;
+            };
+            created_at: string;
+            updated_at?: string;
+            updated_by?: string;
+            test_mode?: boolean;
+            poa_verification?: {
+                status: string;
+                confidence_score: number | null;
+            };
+            previous_status?: string;
+            rejection_reason?: string;
+            reviewed_by?: string;
+        };
+    };
+}
+interface WebhookVerifyOptions {
+    /** Max clock skew in seconds. Default: 300 */
+    maxSkewSeconds?: number;
+}
+
+declare class FlonkError extends Error {
+    readonly code: string;
+    readonly statusCode?: number | undefined;
+    constructor(message: string, code: string, statusCode?: number | undefined);
+}
+declare class FlonkAPIError extends FlonkError {
+    readonly body?: unknown | undefined;
+    constructor(message: string, statusCode: number, body?: unknown | undefined);
+}
+declare class FlonkAuthenticationError extends FlonkError {
+    constructor(message?: string);
+}
+declare class FlonkValidationError extends FlonkError {
+    constructor(message: string);
+}
+declare class FlonkWebhookSignatureError extends FlonkError {
+    constructor(message?: string);
+}
+
+export { type CreateSessionParams, type DocumentType, type EmbedInstance, FlonkAPIError, FlonkAuthenticationError, FlonkError, type FlonkKYCOptions, type FlonkKYCServerOptions, FlonkValidationError, FlonkWebhookSignatureError, type PreviewColors, type Session, type SessionDetails, type SessionStatus, type UpdateSessionParams, type VerificationResult, type WebhookEvent, type WebhookVerifyOptions, type WidgetEmbedConfig, type WidgetInitConfig, type WidgetInstance, type WidgetLanguage, type WidgetPreviewConfig };

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@flonkid/kyc",
+  "version": "1.4.0",
+  "description": "Official Flonk KYC SDK — identity verification for any application",
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "Flonk.id — Dmytrii Popovych (dimon1936)",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
+      "require": { "types": "./dist/index.d.ts", "default": "./dist/index.cjs" }
+    },
+    "./server": {
+      "import": { "types": "./dist/server.d.ts", "default": "./dist/server.js" },
+      "require": { "types": "./dist/server.d.ts", "default": "./dist/server.cjs" }
+    },
+    "./types": {
+      "import": { "types": "./dist/types.d.ts" },
+      "require": { "types": "./dist/types.d.ts" }
+    }
+  },
+  "files": ["dist"],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": { "optional": true }
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.2",
+    "@types/node": "^22.10.1",
+    "@types/react": "^19.0.0",
+    "react": "^19.0.0"
+  },
+  "engines": { "node": ">=18.0.0" },
+  "keywords": ["kyc", "identity-verification", "flonk", "sdk", "widget"]
+}