vesant-sdk 1.6.6 → 1.7.0-dev.117915b

package/dist/kyc/index.d.ts

@@ -1,6 +1,6 @@
-import { R as RiskLevel, P as PaginationParams } from '../types-B4Ezqo7V.js';
-import { e as ProfileFilters, f as ProfileListResponse, C as CustomerProfile, d as CreateProfileRequest } from '../types-X5Md_dD_.js';
-import { B as BaseClient } from '../client-ePzhQKp9.js';
+import { P as ProfileFilters, b as ProfileListResponse, C as CustomerProfile, a as CreateProfileRequest } from '../types-UGyDl1fd.js';
+import { c as Reason, R as RiskLevel, P as PaginationParams } from '../types-CBQRNL-l.js';
+import { B as BaseClient } from '../client-BolQlL5e.js';
 
 /**
  * TypeScript type definitions for Vesant KYC Service API
@@ -12,12 +12,13 @@ import { B as BaseClient } from '../client-ePzhQKp9.js';
  */
 
 type KycStatus = 'pending' | 'accepted' | 'declined' | 'review.pending' | 'unknown';
+type KycDeclinedCode = 'KYC_DOCUMENT_EXPIRED' | 'KYC_DOCUMENT_INVALID' | 'KYC_FACE_MISMATCH' | 'KYC_AGE_REQUIREMENT' | 'KYC_DUPLICATE_IDENTITY' | 'KYC_ADDRESS_MISMATCH' | 'KYC_NAME_MISMATCH' | 'KYC_PROVIDER_REJECTED' | 'KYC_DECLINED';
+declare const KYC_DECLINED_DESCRIPTIONS: Record<KycDeclinedCode, string>;
 type KycAlertStatus = 'pending' | 'in_progress' | 'resolved' | 'closed' | 'escalated';
 type KycAlertType = 'kyc' | 'fraud';
 type DocumentType = 'id_card' | 'driving_license' | 'passport';
 type ProofType = 'document' | 'document_two' | 'face' | 'address' | 'additional_document';
 type SupportedDocumentType = 'id_card' | 'passport' | 'driving_license';
-type KycTriggerEvent = 'onboarding' | 'first_withdrawal' | 'first_purchase' | 'manual' | 'withdrawal' | 'purchase';
 interface KycRequest {
     id: string;
     reference: string;
@@ -44,10 +45,30 @@ interface KycRequest {
     is_age_verification_required: boolean;
     callback_url: string;
     redirect_url?: string;
+    /** Structured decline reasons. Present when status is `declined`. */
+    declined_reasons?: Reason[];
+    /** Structured, non-blocking warnings. */
+    warning_reasons?: Reason[];
+    /** @deprecated Use {@link declined_reasons}. Comma-joined message text. */
     declined_reason?: string;
+    /** @deprecated Use the `code` on {@link declined_reasons}. */
+    declined_code?: KycDeclinedCode;
     accepted_reason?: string;
     other_reason?: string;
+    /** @deprecated Use {@link warning_reasons}. */
     warnings?: Record<string, Record<string, string>>;
+    /**
+     * Tenant app should block onboarding/the action when true. Set when a
+     * failed verification matches a per-event KYC alert rule with the `block`
+     * reaction; sticky once set (a later non-blocking update won't clear it).
+     */
+    block: boolean;
+    /**
+     * Names the configured verification that triggered the block (e.g.
+     * `document_verification`, `face_verification`, `address_verification`,
+     * `age_verification`). Empty when {@link block} is false.
+     */
+    block_reason?: string;
     proofs?: Proof[];
     alerts?: KycAlert[];
     risk_profile?: KycCustomerProfile;
@@ -117,6 +138,65 @@ interface UpdateKycAlertRequest {
     alert_type?: KycAlertType;
     status?: KycAlertStatus;
 }
+/**
+ * Threshold-gated trigger for transaction events. Each rule is
+ * self-contained — there is no umbrella flag.
+ *
+ * - `enabled=false` → event blocked.
+ * - `enabled=true`, `threshold=0` (or null/omitted) → every event of this
+ *   type triggers Event-Based Face Verification, regardless of amount.
+ * - `enabled=true`, `threshold>0` → only amounts `>= threshold` trigger.
+ */
+interface EventBasedFaceVerificationThresholdTrigger {
+    enabled: boolean;
+    /** USD threshold; 0 / null / omitted means "any amount". */
+    threshold: number;
+}
+/**
+ * Rate-of-occurrence trigger (used by `high_frequency_betting`). The
+ * tenant tells the server how many events have happened over how many
+ * minutes via the request body (`event_count`, `event_window_minutes`);
+ * the server triggers when `event_count >= count` AND
+ * `event_window_minutes <= window_minutes`. Either bound of 0 means
+ * "don't enforce that bound".
+ */
+interface EventBasedFaceVerificationFrequencyTrigger {
+    enabled: boolean;
+    /** Minimum number of events; 0 / null / omitted means "any count". */
+    count: number;
+    /** Maximum lookback window in minutes; 0 / null / omitted means "any window". */
+    window_minutes: number;
+}
+/** Events that can trigger Event-Based Face Verification for a tenant. */
+interface EventBasedFaceVerificationTriggers {
+    login: boolean;
+    password_change: boolean;
+    name_change: boolean;
+    phone_number_change: boolean;
+    two_factor_auth_change: boolean;
+    new_device_or_location: boolean;
+    device_fingerprint_change: boolean;
+    payment_method_change: boolean;
+    deposit: EventBasedFaceVerificationThresholdTrigger;
+    withdrawal: EventBasedFaceVerificationThresholdTrigger;
+    large_bet_placement: EventBasedFaceVerificationThresholdTrigger;
+    high_frequency_betting: EventBasedFaceVerificationFrequencyTrigger;
+    account_balance_transfer: boolean;
+}
+/**
+ * Reactions taken when a customer exhausts the Event-Based Face Verification retry limit.
+ * `trigger_alert` is enforced by the server (creates a KYC alert);
+ * `enforce_logout` and `freeze_account` are forwarded to the tenant app
+ * via the callback `data` field for it to enforce.
+ */
+interface EventBasedFaceVerificationReactions {
+    /** Retries after the first attempt; total submissions = this + 1. */
+    max_retry_attempts: number;
+    trigger_alert: boolean;
+    enforce_logout: boolean;
+    freeze_account: boolean;
+    freeze_duration_minutes: number;
+}
 interface KycPreferences {
     id: string;
     tenant_id: string;
@@ -125,6 +205,8 @@ interface KycPreferences {
     is_face_verification_required: boolean;
     is_address_verification_required: boolean;
     is_age_verification_required: boolean;
+    /** Master switch for the Event-Based Face Verification feature. */
+    is_reuse_kyc_enabled?: boolean;
     min_age: number;
     max_age: number;
     required_document_count: number;
@@ -132,6 +214,10 @@ interface KycPreferences {
     high_risk_score: number;
     medium_risk_score: number;
     supported_document_types: SupportedDocumentType[];
+    /** Per-event triggers for Event-Based Face Verification. */
+    reuse_kyc_triggers?: EventBasedFaceVerificationTriggers;
+    /** Retry / reaction policy for Event-Based Face Verification. */
+    reuse_kyc_reactions?: EventBasedFaceVerificationReactions;
     created_at: string;
     updated_at: string;
 }
@@ -141,6 +227,7 @@ interface UpdateKycPreferencesRequest {
     is_face_verification_required?: boolean;
     is_address_verification_required?: boolean;
     is_age_verification_required?: boolean;
+    is_reuse_kyc_enabled?: boolean;
     min_age?: number;
     max_age?: number;
     required_document_count?: number;
@@ -148,6 +235,10 @@ interface UpdateKycPreferencesRequest {
     high_risk_score?: number;
     medium_risk_score?: number;
     supported_document_types?: SupportedDocumentType[];
+    /** Partial update — only the events present here are changed. */
+    reuse_kyc_triggers?: Partial<EventBasedFaceVerificationTriggers>;
+    /** Partial update — only the keys present here are changed. */
+    reuse_kyc_reactions?: Partial<EventBasedFaceVerificationReactions>;
 }
 interface Name {
     first_name?: string;
@@ -223,50 +314,175 @@ interface UpdateKycStatusRequest {
 interface RequestKycSubmitLinkRequest {
     /** User ID to generate KYC submission link for */
     user_id: string;
-    /** URL to redirect user after KYC submission */
-    redirect_url: string;
-    /** URL to receive callback notifications via POST request when KYC status changes */
-    callback_url: string;
-    /** Event that triggered the KYC request */
-    trigger_event: KycTriggerEvent;
+    /** URL to redirect user after KYC submission (optional) */
+    redirect_url?: string;
+    /** URL to receive callback notifications via POST request when KYC status changes (optional) */
+    callback_url?: string;
+    /** Event that triggered the KYC request (e.g. "onboarding", "login", "transaction") */
+    trigger_event?: string;
 }
-interface CreateReuseKycSessionRequest {
+/**
+ * Trigger events that can request Event-Based Face Verification.
+ *
+ * Account-sensitive: any sensitive change to the account profile.
+ * Transaction events: covered by the per-event rules in
+ * `EventBasedFaceVerificationTriggers` (`deposit`, `withdrawal`, `large_bet_placement`,
+ * `high_frequency_betting`, `account_balance_transfer`).
+ */
+type EventBasedFaceVerificationEvent = 'login' | 'password_change' | 'name_change' | 'phone_number_change' | 'two_factor_auth_change' | 'new_device_or_location' | 'device_fingerprint_change' | 'payment_method_change' | 'deposit' | 'withdrawal' | 'large_bet_placement' | 'high_frequency_betting' | 'account_balance_transfer';
+interface CreateEventBasedFaceVerificationSessionRequest {
     /** Unique reference for the KYC session (e.g., customer ID or transaction ID) */
     reference: string;
-    /** customer ID to associate with the KYC session */
+    /** Customer ID to associate with the KYC session */
     customer_id: string;
-    /** where the re-use-kyc using 'login' | 'transactions' */
-    path?: string;
+    /**
+     * The triggering event. One of the `EventBasedFaceVerificationEvent` union members.
+     * Required — when empty, the server falls through to the unknown-event
+     * passthrough and allows the request silently.
+     */
+    event: EventBasedFaceVerificationEvent;
+    /**
+     * USD amount associated with the event. Required for threshold-gated
+     * events (`deposit`, `withdrawal`, `large_bet_placement`); ignored for
+     * everything else. Missing/zero with a non-zero threshold blocks the
+     * session.
+     */
+    amount?: number;
+    /**
+     * Number of qualifying events the customer has performed in the
+     * window described by `event_window_minutes`. Required for
+     * frequency-gated events (`high_frequency_betting`); ignored for
+     * everything else.
+     */
+    event_count?: number;
+    /**
+     * Lookback window (in minutes) the tenant counted `event_count` over.
+     * Required for frequency-gated events alongside `event_count`. A
+     * window larger than the tenant's configured `window_minutes`
+     * implies a slower rate than "high frequency" and blocks the session.
+     */
+    event_window_minutes?: number;
     /** URL to redirect user after validate the facial submission (optional) */
     redirect_url?: string;
-    /** URL to receive callback notifications via POST request when reuse KYC status changes (optional) */
+    /** URL to receive callback notifications via POST request when Event-Based Face Verification status changes (optional) */
     callback_url?: string;
 }
-interface SubmitReuseKycSessionRequest {
-    /** Reuse KYC session token generated from createReUseKycSession endpoint */
+interface SubmitEventBasedFaceVerificationSessionRequest {
+    /** Event-Based Face Verification session token generated from createEventBasedFaceVerificationSession */
     token: string;
     /** Base64 encoded face image or selfie for verification */
     proof: string;
     /** Unique reference for the KYC session (e.g., customer ID or transaction ID) */
     reference?: string;
+    /**
+     * Optional capture telemetry (JSON string): the face-detection
+     * bounding-box samples recorded in the moments before capture. Attached
+     * automatically by `FaceCaptureModal` when in-modal detection is active;
+     * omit when building a custom capture UI without detection. Stored
+     * verbatim server-side for audit/review — a weak presence signal, not
+     * certified anti-spoofing.
+     */
+    liveness_artifact?: string;
 }
 interface RequestKycSubmitLinkResponse {
-    /** Whether KYC is required for this user */
-    kyc_required: boolean;
-    /** Whether the user can skip KYC */
-    can_skip: boolean;
     /** Generated KYC submission redirect URL */
-    link?: string;
+    link: string;
     /** KYC request ID */
-    kyc_id?: string;
+    kyc_id: string;
 }
-interface CreateReuseKycSessionResponse {
-    /** Generated reuse KYC session token, valid X minutes */
-    token: string;
-    /** reuse KYC session reference */
+/** Device class detected by the SDK (purely client-side — server doesn't care). */
+type EventBasedFaceVerificationDeviceType = 'mobile' | 'desktop';
+interface CreateEventBasedFaceVerificationSessionResponse {
+    /** Event-Based Face Verification session reference (echo of the request reference) */
     reference: string;
-    /** re-use-kyc required for the action or not */
+    /** Generated Event-Based Face Verification session token, valid 10 minutes */
+    token: string;
+    /**
+     * Empty string when Event-Based Face Verification is required. When `is_required` is
+     * false, this contains the human-readable reason (e.g. feature
+     * disabled, threshold not met, customer has no prior KYC).
+     */
+    reason: string;
+    /** Whether the caller must complete the face capture before proceeding */
     is_required: boolean;
+    /**
+     * Public HTTPS handoff URL the SDK encodes into a QR code on desktop.
+     * The mobile device scans it, lands on the tenant frontend's
+     * /reuse-kyc-submit page, and completes the face capture there. Empty
+     * when the server has no `BASE_URL_FRONTEND` configured — the SDK
+     * falls back to building its own URL in that case.
+     */
+    link: string;
+    /** Failed face-capture attempts so far on this session. 0 on a fresh session. */
+    attempts: number;
+    /**
+     * Total submissions permitted before reactions fire
+     * (`reuse_kyc_reactions.max_retry_attempts + 1`).
+     */
+    max_attempts: number;
+}
+/**
+ * Reaction outcome returned on every face-submit callback. Tenant apps
+ * use this to decide whether to allow another retry, end the session,
+ * or freeze the account. Reaction flags are only populated when
+ * `retry_limit_exceeded` is true.
+ */
+interface EventBasedFaceVerificationReactionResult {
+    /** Submissions the customer still has before the retry limit fires. */
+    retries_remaining: number;
+    /** True once the latest failed attempt exhausts the retry policy. */
+    retry_limit_exceeded: boolean;
+    trigger_alert: boolean;
+    enforce_logout: boolean;
+    freeze_account: boolean;
+    /** Tenant app should block the action/account when true. */
+    block: boolean;
+    freeze_duration_minutes: number;
+    /** Set when an alert was raised on the dashboard. */
+    alert_id?: string;
+}
+/**
+ * Shape of the webhook body POSTed to `callback_url` after a Event-Based Face Verification
+ * submission completes (also returned synchronously from
+ * `submitEventBasedFaceVerificationSession`).
+ */
+interface EventBasedFaceVerificationCallback {
+    event: 'reuse_kyc';
+    reference: string;
+    resource_id: string;
+    status: KycStatus;
+    /**
+     * True when the tenant app should block the action/account. Mirrors the
+     * `block` reaction on {@link data} at the top level of the callback so
+     * consumers can branch without inspecting `data`. Omitted when false.
+     */
+    block?: boolean;
+    /** Names the event/verification that triggered the block. Omitted when not blocked. */
+    block_reason?: string;
+    /** Structured decline reasons. */
+    declined_reasons?: Reason[];
+    /** @deprecated Use {@link declined_reasons}. */
+    declined_reason?: string;
+    /** @deprecated Use structured reasons. */
+    warnings?: Record<string, Record<string, string>>;
+    data: EventBasedFaceVerificationReactionResult;
+}
+/**
+ * Server-side handoff session backed by Redis (TTL: 15 minutes). Shared
+ * with the normal KYC mobile/desktop handoff. Desktop clients poll this
+ * to detect when a mobile device has attached to the same token via QR.
+ */
+interface KycHandoffSession {
+    document: string;
+    document_backside: string;
+    document_two: string;
+    document_two_backside: string;
+    address: string;
+    face: string;
+    /** True after a mobile device hits PUT /api/v1/kyc/session/connect. */
+    mobile_connected: boolean;
+    /** True after the (normal-KYC) document submission completes; unused for Event-Based Face Verification. */
+    is_submitted: boolean;
 }
 interface CheckKycStatusRequest {
     /** User ID to check KYC status for */
@@ -289,9 +505,17 @@ interface CheckKycStatusResponse {
     address_verified: boolean;
     face_verified: boolean;
     age_verified: boolean;
+    /** Structured decline reasons. Present when status is `declined`. */
+    declined_reasons?: Reason[];
+    /** Structured, non-blocking warnings. */
+    warning_reasons?: Reason[];
+    /** @deprecated Use {@link declined_reasons}. */
     declined_reason?: string;
+    /** @deprecated Use the `code` on {@link declined_reasons}. */
+    declined_code?: KycDeclinedCode;
     other_reason?: string;
     accepted_reason?: string;
+    /** @deprecated Use {@link warning_reasons}. */
     warnings?: Record<string, Record<string, string>>;
     required_document_count: number;
     supported_document_types?: SupportedDocumentType[];
@@ -461,44 +685,79 @@ declare class KycClient extends BaseClient {
      *
      * Generates a link that the user can visit to submit their KYC documents.
      *
-     * @param request - Request containing the user ID, redirect URL, callback URL, and trigger event
-     * @returns Response containing kyc_required, can_skip, and optionally the redirect link and KYC ID
+     * @param request - Request containing the user ID, optional redirect URL, and optional callback URL (receives POST requests)
+     * @returns Response containing the redirect link and KYC ID
      *
      * @example
      * ```typescript
      * const result = await client.requestKycSubmitLink({
      *   user_id: "user_123",
-     *   redirect_url: "https://merchant.com/kyc-complete",
-     *   callback_url: "https://merchant.com/api/kyc-webhook",
-     *   trigger_event: "onboarding"
+     *   redirect_url: "https://merchant.com/kyc-complete", // optional
+     *   callback_url: "https://merchant.com/api/kyc-webhook" // optional - receives POST requests on status change
      * });
      *
-     * if (result.kyc_required && result.link) {
-     *   console.log(`Redirect user to: ${result.link}`);
-     * } else if (result.can_skip) {
-     *   console.log("KYC not required, user can proceed");
-     * }
+     * console.log(`Redirect user to: ${result.link}`);
+     * console.log(`KYC ID: ${result.kyc_id}`);
      * ```
      */
     requestKycSubmitLink(request: RequestKycSubmitLinkRequest): Promise<RequestKycSubmitLinkResponse>;
     /**
-     * Create a reuse KYC session for validate a user with existing KYC verification
+     * Create a Event-Based Face Verification session.
+     *
+     * Inspect the response before showing UI:
+     * - `is_required === false` → skip face capture; `reason` explains why.
+     * - `device_type === 'desktop'` → render `qr_payload` as a QR; the
+     *   mobile device picks up the session via the connect endpoint.
+     * - `device_type === 'mobile'` → open the face capture modal directly.
      *
-     * @param request - Request containing the reference, customer_id, optional redirect URL, and callback URL (receives POST requests)
+     * @param request - Reference, customer_id, event, amount (for threshold events), optional URLs.
      */
-    createReuseKycSession(request: CreateReuseKycSessionRequest): Promise<CreateReuseKycSessionResponse>;
+    createEventBasedFaceVerificationSession(request: CreateEventBasedFaceVerificationSessionRequest): Promise<CreateEventBasedFaceVerificationSessionResponse>;
     /**
-     * Submit a reuse KYC session for validate a user with existing KYC verification
+     * Submit a real-time face capture for an active Event-Based Face Verification session.
      *
-     * @param request - Request containing the reference, token and proof (receives POST requests)
+     * **Mobile-only.** The server rejects desktop User-Agents with HTTP
+     * 400 (`face capture must be completed on a mobile device`). Use the
+     * QR handoff from `createEventBasedFaceVerificationSession` for desktop callers.
+     *
+     * The `data` field on the response carries `retries_remaining`,
+     * `retry_limit_exceeded`, and the reaction flags (`enforce_logout`,
+     * `freeze_account`, etc.) so the tenant app can act on a final failure.
+     *
+     * @param request - Token from `createEventBasedFaceVerificationSession`, plus the base64 selfie.
      */
-    submitReuseKycSession(request: SubmitReuseKycSessionRequest): Promise<CheckKycStatusResponse>;
+    submitEventBasedFaceVerificationSession(request: SubmitEventBasedFaceVerificationSessionRequest): Promise<EventBasedFaceVerificationCallback>;
     /**
-     * Check reuse KYC session status for a reference
-     * @param reference - The unique reference used for the reuse KYC session (e.g., customer ID or transaction ID)
-     * @returns Response with kyc_status and message (reason)
-     * **/
-    getReuseKycSessionStatus(reference: string): Promise<CheckKycStatusResponse>;
+     * Look up the current state of a Event-Based Face Verification session by its
+     * session token. Useful for desktop pollers waiting on the mobile handoff.
+     *
+     * The lookup is scoped by the unguessable, server-issued session token (not
+     * the enumerable forward reference): the endpoint is public/unauthenticated,
+     * and scoping by the token is what prevents cross-tenant status reads.
+     *
+     * @param token - The session token returned by `createEventBasedFaceVerificationSession`.
+     */
+    getEventBasedFaceVerificationSessionStatus(token: string): Promise<EventBasedFaceVerificationCallback>;
+    /**
+     * Fetch the Redis-backed handoff session for a token. Same backing
+     * store as normal KYC (`kyc:session:<token>`, 15-minute TTL). Desktop
+     * callers poll `mobile_connected` to detect when a mobile device has
+     * scanned the QR and attached.
+     *
+     * @param token - The session token returned by `createEventBasedFaceVerificationSession`.
+     */
+    getHandoffSession(token: string): Promise<KycHandoffSession>;
+    /**
+     * Attach a mobile device to a desktop-initiated session. The mobile
+     * client calls this after scanning the QR code. The desktop poller
+     * sees `mobile_connected: true` on the next `getHandoffSession`.
+     *
+     * @param token - The session token transferred via the QR payload.
+     * @param isDisconnect - Pass true to release the session (default false).
+     */
+    connectMobileSession(token: string, isDisconnect?: boolean): Promise<{
+        mobile_connected: boolean;
+    }>;
     /**
      * Check KYC status for a user
      *
@@ -819,4 +1078,4 @@ declare class KycClient extends BaseClient {
     createCustomerProfile(profile: CreateProfileRequest): Promise<CustomerProfile>;
 }
 
-export { type CheckKycStatusRequest, type CheckKycStatusResponse, CreateProfileRequest as CreateCustomerProfileRequest, type CreateReuseKycSessionRequest, type CreateReuseKycSessionResponse, CustomerProfile, ProfileFilters as CustomerProfileFilters, ProfileListResponse as CustomerProfileListResponse, type DocumentType, type DocumentVerificationRequest, type DocumentVerificationResponse, type FaceProof, type KycAlert, type KycAlertFilters, type KycAlertListResponse, type KycAlertStatus, type KycAlertType, KycClient, type KycClientConfig, type KycCustomerProfile, type KycOverview, type KycPagination, type KycPreferences, type KycRequest, type KycRequestFilters, type KycRequestListResponse, type KycStatus, type KycTriggerEvent, type Name, PaginationParams, type Proof, type ProofDownloadURL, type ProofType, type RequestAdditionalDocumentsRequest, type RequestKycSubmitLinkRequest, type RequestKycSubmitLinkResponse, RiskLevel, type SubmitReuseKycSessionRequest, type SubmittedDocument, type SupportedDocumentType, type UpdateKycAlertRequest, type UpdateKycPreferencesRequest, type UpdateKycStatusRequest, type UseKycAlertsOptions, type UseKycAlertsResult, type UseKycOverviewOptions, type UseKycOverviewResult, type UseKycPreferencesResult, type UseKycRequestsOptions, type UseKycRequestsResult, type UseKycSubmissionOptions, type UseKycSubmissionResult };
+export { type CheckKycStatusRequest, type CheckKycStatusResponse, CreateProfileRequest as CreateCustomerProfileRequest, type CreateEventBasedFaceVerificationSessionRequest, type CreateEventBasedFaceVerificationSessionResponse, CustomerProfile, ProfileFilters as CustomerProfileFilters, ProfileListResponse as CustomerProfileListResponse, type DocumentType, type DocumentVerificationRequest, type DocumentVerificationResponse, type EventBasedFaceVerificationCallback, type EventBasedFaceVerificationDeviceType, type EventBasedFaceVerificationEvent, type EventBasedFaceVerificationFrequencyTrigger, type EventBasedFaceVerificationReactionResult, type EventBasedFaceVerificationReactions, type EventBasedFaceVerificationThresholdTrigger, type EventBasedFaceVerificationTriggers, type FaceProof, KYC_DECLINED_DESCRIPTIONS, type KycAlert, type KycAlertFilters, type KycAlertListResponse, type KycAlertStatus, type KycAlertType, KycClient, type KycClientConfig, type KycCustomerProfile, type KycDeclinedCode, type KycHandoffSession, type KycOverview, type KycPagination, type KycPreferences, type KycRequest, type KycRequestFilters, type KycRequestListResponse, type KycStatus, type Name, PaginationParams, type Proof, type ProofDownloadURL, type ProofType, type RequestAdditionalDocumentsRequest, type RequestKycSubmitLinkRequest, type RequestKycSubmitLinkResponse, RiskLevel, type SubmitEventBasedFaceVerificationSessionRequest, type SubmittedDocument, type SupportedDocumentType, type UpdateKycAlertRequest, type UpdateKycPreferencesRequest, type UpdateKycStatusRequest, type UseKycAlertsOptions, type UseKycAlertsResult, type UseKycOverviewOptions, type UseKycOverviewResult, type UseKycPreferencesResult, type UseKycRequestsOptions, type UseKycRequestsResult, type UseKycSubmissionOptions, type UseKycSubmissionResult };

package/dist/kyc/index.js

@@ -216,7 +216,7 @@ function createConsoleLogger() {
 }
 
 // src/core/version.ts
-var SDK_VERSION = "1.6.6";
+var SDK_VERSION = "1.7.0";
 
 // src/shared/browser-utils.ts
 function generateUUID() {
@@ -603,23 +603,19 @@ var KycClient = class extends BaseClient {
    *
    * Generates a link that the user can visit to submit their KYC documents.
    *
-   * @param request - Request containing the user ID, redirect URL, callback URL, and trigger event
-   * @returns Response containing kyc_required, can_skip, and optionally the redirect link and KYC ID
+   * @param request - Request containing the user ID, optional redirect URL, and optional callback URL (receives POST requests)
+   * @returns Response containing the redirect link and KYC ID
    *
    * @example
    * ```typescript
    * const result = await client.requestKycSubmitLink({
    *   user_id: "user_123",
-   *   redirect_url: "https://merchant.com/kyc-complete",
-   *   callback_url: "https://merchant.com/api/kyc-webhook",
-   *   trigger_event: "onboarding"
+   *   redirect_url: "https://merchant.com/kyc-complete", // optional
+   *   callback_url: "https://merchant.com/api/kyc-webhook" // optional - receives POST requests on status change
    * });
    *
-   * if (result.kyc_required && result.link) {
-   *   console.log(`Redirect user to: ${result.link}`);
-   * } else if (result.can_skip) {
-   *   console.log("KYC not required, user can proceed");
-   * }
+   * console.log(`Redirect user to: ${result.link}`);
+   * console.log(`KYC ID: ${result.kyc_id}`);
    * ```
    */
   async requestKycSubmitLink(request) {
@@ -630,40 +626,88 @@ var KycClient = class extends BaseClient {
     });
   }
   /**
-   * Create a reuse KYC session for validate a user with existing KYC verification
+   * Create a Event-Based Face Verification session.
+   *
+   * Inspect the response before showing UI:
+   * - `is_required === false` → skip face capture; `reason` explains why.
+   * - `device_type === 'desktop'` → render `qr_payload` as a QR; the
+   *   mobile device picks up the session via the connect endpoint.
+   * - `device_type === 'mobile'` → open the face capture modal directly.
    *
-   * @param request - Request containing the reference, customer_id, optional redirect URL, and callback URL (receives POST requests)
+   * @param request - Reference, customer_id, event, amount (for threshold events), optional URLs.
    */
-  async createReuseKycSession(request) {
-    return this.requestWithRetry("/api/v1/kyc/face/session", {
+  async createEventBasedFaceVerificationSession(request) {
+    return this.request("/api/v1/kyc/face/session", {
       method: "POST",
       body: JSON.stringify(request),
       headers: this.getUserHeaders()
     });
   }
   /**
-   * Submit a reuse KYC session for validate a user with existing KYC verification
+   * Submit a real-time face capture for an active Event-Based Face Verification session.
+   *
+   * **Mobile-only.** The server rejects desktop User-Agents with HTTP
+   * 400 (`face capture must be completed on a mobile device`). Use the
+   * QR handoff from `createEventBasedFaceVerificationSession` for desktop callers.
    *
-   * @param request - Request containing the reference, token and proof (receives POST requests)
+   * The `data` field on the response carries `retries_remaining`,
+   * `retry_limit_exceeded`, and the reaction flags (`enforce_logout`,
+   * `freeze_account`, etc.) so the tenant app can act on a final failure.
+   *
+   * @param request - Token from `createEventBasedFaceVerificationSession`, plus the base64 selfie.
    */
-  async submitReuseKycSession(request) {
-    return this.requestWithRetry("/api/v1/kyc/face/submit", {
+  async submitEventBasedFaceVerificationSession(request) {
+    return this.request("/api/v1/kyc/face/submit", {
       method: "POST",
       body: JSON.stringify(request),
       headers: this.getUserHeaders()
     });
   }
   /**
-   * Check reuse KYC session status for a reference
-   * @param reference - The unique reference used for the reuse KYC session (e.g., customer ID or transaction ID)
-   * @returns Response with kyc_status and message (reason)
-   * **/
-  async getReuseKycSessionStatus(reference) {
-    return this.requestWithRetry(`/api/v1/kyc/face/verify/${encodeURIComponent(reference)}`, {
+   * Look up the current state of a Event-Based Face Verification session by its
+   * session token. Useful for desktop pollers waiting on the mobile handoff.
+   *
+   * The lookup is scoped by the unguessable, server-issued session token (not
+   * the enumerable forward reference): the endpoint is public/unauthenticated,
+   * and scoping by the token is what prevents cross-tenant status reads.
+   *
+   * @param token - The session token returned by `createEventBasedFaceVerificationSession`.
+   */
+  async getEventBasedFaceVerificationSessionStatus(token) {
+    return this.requestWithRetry(`/api/v1/kyc/face/verify/${encodeURIComponent(token)}`, {
       method: "GET",
       headers: this.getUserHeaders()
     });
   }
+  /**
+   * Fetch the Redis-backed handoff session for a token. Same backing
+   * store as normal KYC (`kyc:session:<token>`, 15-minute TTL). Desktop
+   * callers poll `mobile_connected` to detect when a mobile device has
+   * scanned the QR and attached.
+   *
+   * @param token - The session token returned by `createEventBasedFaceVerificationSession`.
+   */
+  async getHandoffSession(token) {
+    return this.request(
+      `/api/v1/kyc/session${this.buildQueryString({ token })}`,
+      { headers: this.getUserHeaders() }
+    );
+  }
+  /**
+   * Attach a mobile device to a desktop-initiated session. The mobile
+   * client calls this after scanning the QR code. The desktop poller
+   * sees `mobile_connected: true` on the next `getHandoffSession`.
+   *
+   * @param token - The session token transferred via the QR payload.
+   * @param isDisconnect - Pass true to release the session (default false).
+   */
+  async connectMobileSession(token, isDisconnect = false) {
+    return this.request("/api/v1/kyc/session/connect", {
+      method: "PUT",
+      body: JSON.stringify({ token, is_disconnect: isDisconnect }),
+      headers: this.getUserHeaders()
+    });
+  }
   /**
    * Check KYC status for a user
    *
@@ -1022,8 +1066,9 @@ var KycClient = class extends BaseClient {
    */
   async riskProfileRequest(path, options = {}) {
     if (!this.riskProfileBaseURL) {
-      throw new Error(
-        "Risk Profile Service URL not configured. Please provide riskProfileBaseURL in KycClientConfig."
+      throw new ValidationError(
+        "Risk Profile Service URL not configured. Please provide riskProfileBaseURL in KycClientConfig.",
+        ["riskProfileBaseURL"]
       );
     }
     return this.request(path, {
@@ -1135,6 +1180,20 @@ var KycClient = class extends BaseClient {
   // ============================================================================
 };
 
+// src/kyc/types.ts
+var KYC_DECLINED_DESCRIPTIONS = {
+  KYC_DOCUMENT_EXPIRED: "The submitted document has expired",
+  KYC_DOCUMENT_INVALID: "The submitted document could not be verified",
+  KYC_FACE_MISMATCH: "Face verification did not match the identity document",
+  KYC_AGE_REQUIREMENT: "Age requirement not met",
+  KYC_DUPLICATE_IDENTITY: "This identity has already been verified under another account",
+  KYC_ADDRESS_MISMATCH: "Address verification failed",
+  KYC_NAME_MISMATCH: "Name on document does not match the registered name",
+  KYC_PROVIDER_REJECTED: "Identity verification was rejected by the verification provider",
+  KYC_DECLINED: "Identity verification was declined"
+};
+
+exports.KYC_DECLINED_DESCRIPTIONS = KYC_DECLINED_DESCRIPTIONS;
 exports.KycClient = KycClient;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map