vesant-sdk 1.6.6 → 2.0.0-dev.03b7c82

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-2utj53GK.js';
+import { R as RiskLevel, P as PaginationParams } from '../types-QUCWam16.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;
@@ -45,6 +46,7 @@ interface KycRequest {
     callback_url: string;
     redirect_url?: string;
     declined_reason?: string;
+    declined_code?: KycDeclinedCode;
     accepted_reason?: string;
     other_reason?: string;
     warnings?: Record<string, Record<string, string>>;
@@ -117,6 +119,71 @@ interface UpdateKycAlertRequest {
     alert_type?: KycAlertType;
     status?: KycAlertStatus;
 }
+/**
+ * Threshold-gated trigger for transaction events.
+ *
+ * - `enabled=false` + umbrella `transaction=false` → event blocked.
+ * - `enabled=true`, `threshold=0` (or null/omitted) → every event of this
+ *   type triggers Re-Use KYC, regardless of amount.
+ * - `enabled=true`, `threshold>0` → only amounts `>= threshold` trigger.
+ * - `enabled=false` + umbrella `transaction=true` → triggers on any
+ *   amount; the threshold is ignored when the specific rule is disabled.
+ */
+interface ReuseKycThresholdTrigger {
+    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 ReuseKycFrequencyTrigger {
+    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 Re-Use KYC for a tenant. */
+interface ReuseKycTriggers {
+    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;
+    /**
+     * Legacy umbrella flag. When true and a specific transaction rule is
+     * not configured, any transaction triggers Re-Use KYC.
+     */
+    transaction: boolean;
+    deposit: ReuseKycThresholdTrigger;
+    withdrawal: ReuseKycThresholdTrigger;
+    large_bet_placement: ReuseKycThresholdTrigger;
+    high_frequency_betting: ReuseKycFrequencyTrigger;
+    account_balance_transfer: boolean;
+}
+/**
+ * Reactions taken when a customer exhausts the Re-Use KYC 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 ReuseKycReactions {
+    /** 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 +192,8 @@ interface KycPreferences {
     is_face_verification_required: boolean;
     is_address_verification_required: boolean;
     is_age_verification_required: boolean;
+    /** Master switch for the Re-Use KYC feature. */
+    is_reuse_kyc_enabled?: boolean;
     min_age: number;
     max_age: number;
     required_document_count: number;
@@ -132,6 +201,10 @@ interface KycPreferences {
     high_risk_score: number;
     medium_risk_score: number;
     supported_document_types: SupportedDocumentType[];
+    /** Per-event triggers for Re-Use KYC. */
+    reuse_kyc_triggers?: ReuseKycTriggers;
+    /** Retry / reaction policy for Re-Use KYC. */
+    reuse_kyc_reactions?: ReuseKycReactions;
     created_at: string;
     updated_at: string;
 }
@@ -141,6 +214,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 +222,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<ReuseKycTriggers>;
+    /** Partial update — only the keys present here are changed. */
+    reuse_kyc_reactions?: Partial<ReuseKycReactions>;
 }
 interface Name {
     first_name?: string;
@@ -223,27 +301,72 @@ 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;
 }
+/**
+ * Trigger events that can request Re-Use KYC.
+ *
+ * Account-sensitive: any sensitive change to the account profile.
+ * Transaction events: covered by the per-event threshold rules in
+ * `ReuseKycTriggers` (`deposit`, `withdrawal`, `large_bet_placement`) or
+ * the umbrella `transaction` flag.
+ *
+ * The legacy `"login"` and `"transactions"` strings are accepted for
+ * backwards compatibility with older SDK clients that didn't have the
+ * fine-grained event enum.
+ */
+type ReuseKycEvent = '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'
+/** Legacy umbrella string accepted by the server. */
+ | 'transactions';
 interface CreateReuseKycSessionRequest {
     /** 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' */
+    /**
+     * The triggering event. Preferred over `path`. When both are sent, the
+     * server uses `event` and silently ignores `path`.
+     */
+    event?: ReuseKycEvent;
+    /**
+     * 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;
+    /**
+     * Legacy path field — `"login"` or `"transactions"`. Use `event`
+     * instead. Kept for older SDK clients.
+     * @deprecated Send `event` instead.
+     */
     path?: string;
+    /**
+     * 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) */
     callback_url?: string;
 }
 interface SubmitReuseKycSessionRequest {
-    /** Reuse KYC session token generated from createReUseKycSession endpoint */
+    /** Reuse KYC session token generated from createReuseKycSession */
     token: string;
     /** Base64 encoded face image or selfie for verification */
     proof: string;
@@ -251,22 +374,90 @@ interface SubmitReuseKycSessionRequest {
     reference?: 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;
 }
+/** Device class detected by the SDK (purely client-side — server doesn't care). */
+type ReuseKycDeviceType = 'mobile' | 'desktop';
 interface CreateReuseKycSessionResponse {
-    /** Generated reuse KYC session token, valid X minutes */
-    token: string;
-    /** reuse KYC session reference */
+    /** Reuse KYC session reference (echo of the request reference) */
     reference: string;
-    /** re-use-kyc required for the action or not */
+    /** Generated reuse KYC session token, valid 10 minutes */
+    token: string;
+    /**
+     * Empty string when Re-Use KYC 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 ReuseKycReactionResult {
+    /** 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;
+    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 Re-Use KYC
+ * submission completes (also returned synchronously from
+ * `submitReuseKycSession`).
+ */
+interface ReuseKycCallback {
+    event: 'reuse_kyc';
+    reference: string;
+    resource_id: string;
+    status: KycStatus;
+    declined_reason?: string;
+    warnings?: Record<string, Record<string, string>>;
+    data: ReuseKycReactionResult;
+}
+/**
+ * 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 Re-Use KYC. */
+    is_submitted: boolean;
 }
 interface CheckKycStatusRequest {
     /** User ID to check KYC status for */
@@ -290,6 +481,7 @@ interface CheckKycStatusResponse {
     face_verified: boolean;
     age_verified: boolean;
     declined_reason?: string;
+    declined_code?: KycDeclinedCode;
     other_reason?: string;
     accepted_reason?: string;
     warnings?: Record<string, Record<string, string>>;
@@ -461,44 +653,75 @@ 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 Re-Use KYC session.
      *
-     * @param request - Request containing the reference, customer_id, optional redirect URL, and callback URL (receives POST requests)
+     * 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 - Reference, customer_id, event, amount (for threshold events), optional URLs.
      */
     createReuseKycSession(request: CreateReuseKycSessionRequest): Promise<CreateReuseKycSessionResponse>;
     /**
-     * Submit a reuse KYC session for validate a user with existing KYC verification
+     * Submit a real-time face capture for an active Re-Use KYC 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 `createReuseKycSession` 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 `createReuseKycSession`, plus the base64 selfie.
      */
-    submitReuseKycSession(request: SubmitReuseKycSessionRequest): Promise<CheckKycStatusResponse>;
+    submitReuseKycSession(request: SubmitReuseKycSessionRequest): Promise<ReuseKycCallback>;
     /**
-     * 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 Re-Use KYC session by its forward
+     * reference. Useful for desktop pollers waiting on the mobile handoff.
+     *
+     * @param reference - The reference used when the session was created.
+     */
+    getReuseKycSessionStatus(reference: string): Promise<ReuseKycCallback>;
+    /**
+     * 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 `createReuseKycSession`.
+     */
+    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 +1042,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 CreateReuseKycSessionRequest, type CreateReuseKycSessionResponse, CustomerProfile, ProfileFilters as CustomerProfileFilters, ProfileListResponse as CustomerProfileListResponse, type DocumentType, type DocumentVerificationRequest, type DocumentVerificationResponse, 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, type ReuseKycCallback, type ReuseKycDeviceType, type ReuseKycEvent, type ReuseKycFrequencyTrigger, type ReuseKycReactionResult, type ReuseKycReactions, type ReuseKycThresholdTrigger, type ReuseKycTriggers, 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 };

package/dist/kyc/index.js

@@ -216,7 +216,7 @@ function createConsoleLogger() {
 }
 
 // src/core/version.ts
-var SDK_VERSION = "1.6.6";
+var SDK_VERSION = "2.0.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,84 @@ var KycClient = class extends BaseClient {
     });
   }
   /**
-   * Create a reuse KYC session for validate a user with existing KYC verification
+   * Create a Re-Use KYC 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", {
+    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 Re-Use KYC 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 `createReuseKycSession` 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 `createReuseKycSession`, plus the base64 selfie.
    */
   async submitReuseKycSession(request) {
-    return this.requestWithRetry("/api/v1/kyc/face/submit", {
+    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)
-   * **/
+   * Look up the current state of a Re-Use KYC session by its forward
+   * reference. Useful for desktop pollers waiting on the mobile handoff.
+   *
+   * @param reference - The reference used when the session was created.
+   */
   async getReuseKycSessionStatus(reference) {
     return this.requestWithRetry(`/api/v1/kyc/face/verify/${encodeURIComponent(reference)}`, {
       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 `createReuseKycSession`.
+   */
+  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 +1062,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 +1176,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