vesant-sdk 1.6.6 → 1.7.0-dev.254dc8c

package/dist/kyc/index.mjs

@@ -214,7 +214,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() {
@@ -601,23 +601,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) {
@@ -628,40 +624,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
    *
@@ -1020,8 +1064,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, {
@@ -1133,6 +1178,19 @@ var KycClient = class extends BaseClient {
   // ============================================================================
 };
 
-export { KycClient };
+// 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"
+};
+
+export { KYC_DECLINED_DESCRIPTIONS, KycClient };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map