vesant-sdk 1.7.2-dev.617dd44 → 1.7.2-dev.9ef17db

package/dist/kyc/index.mjs

@@ -662,19 +662,27 @@ var KycClient = class extends BaseClient {
    *
    * Generates a link that the user can visit to submit their KYC documents.
    *
+   * Pass the `trigger_event` that matches the user action so the tenant's
+   * trigger preferences decide whether verification is required; inspect
+   * `kyc_required` and `reason` on the response before redirecting.
+   *
    * Optionally pass the customer's registered identity data as
    * `customer_data` (same shape as the geolocation `customer_data` block).
    * It seeds the customer's risk profile so document verification can
    * cross-check the submitted document against trusted reference data;
    * fields never overwrite data already on the profile.
    *
-   * @param request - Request containing the user ID, optional redirect URL, optional callback URL (receives POST requests), and optional customer identity data
-   * @returns Response containing the redirect link and KYC ID
+   * The call is made once and is not retried: each request creates a new
+   * KYC record and link, so a retry after a timeout would leave duplicates.
+   *
+   * @param request - Request containing the user ID, trigger event, optional redirect URL, optional callback URL (receives POST requests), and optional customer identity data
+   * @returns Response containing the redirect link, KYC ID, `kyc_required`, `can_skip` and `reason`
    *
    * @example
    * ```typescript
    * const result = await client.requestKycSubmitLink({
    *   user_id: "user_123",
+   *   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
    *   customer_data: { // optional - seeds the risk profile for document cross-checks
@@ -687,25 +695,25 @@ var KycClient = class extends BaseClient {
    *   }
    * });
    *
+   * if (!result.kyc_required) return proceed();
    * console.log(`Redirect user to: ${result.link}`);
    * console.log(`KYC ID: ${result.kyc_id}`);
    * ```
    */
   async requestKycSubmitLink(request, requestOptions) {
-    return this.requestWithRetry("/api/v1/kyc/request", {
+    return this.request("/api/v1/kyc/request", {
       method: "POST",
       body: JSON.stringify(request),
       headers: this.getUserHeaders()
-    }, void 0, void 0, requestOptions);
+    }, void 0, requestOptions);
   }
   /**
    * 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.
+   * - `is_required === false` → skip face verification; `reason` explains why.
+   * - `verification_url` present → embed the hosted journey and poll status.
+   * - `verification_url` absent → use the local camera / QR fallback.
    *
    * @param request - Reference, customer_id, event, amount (for threshold events), optional URLs.
    */
@@ -719,9 +727,9 @@ var KycClient = class extends BaseClient {
   /**
    * 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.
+   * Works from any device: the platform does not inspect the User-Agent.
+   * `FaceCaptureModal` decides between direct capture and the QR handoff
+   * on the client; custom UIs may submit from desktop or mobile alike.
    *
    * The `data` field on the response carries `retries_remaining`,
    * `retry_limit_exceeded`, and the reaction flags (`enforce_logout`,
@@ -752,11 +760,28 @@ var KycClient = class extends BaseClient {
       headers: this.getUserHeaders()
     });
   }
+  /**
+   * Mint a fresh hosted verification journey for the next attempt on an
+   * active session whose previous hosted-journey attempt was declined.
+   * Only valid while the session is active and attempts remain; the
+   * response carries the new `verification_url` to embed. Used internally
+   * by `FaceCaptureModal`'s Try Again flow in hosted-journey mode.
+   *
+   * @param token - The session token returned by `createEventBasedFaceVerificationSession`.
+   */
+  async retryEventBasedFaceVerificationJourney(token) {
+    return this.request("/api/v1/kyc/face/onsite/journey", {
+      method: "POST",
+      body: JSON.stringify({ token }),
+      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.
+   * store as normal KYC (`kyc:session:<token>`, 15-minute TTL). The
+   * Event-Based Face Verification database session still expires after
+   * 10 minutes. 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`.
    */
@@ -785,25 +810,30 @@ var KycClient = class extends BaseClient {
    * Check KYC status for a user
    *
    * Returns the current KYC status:
-   * - "complete" → KYC verified, show "Continue to Login"
-   * - "processing" → Under review, show "Continue to Login"
-   * - "failed" / "declined" → Show error + retry option
-   * - "pending" / "in_progress" → Keep polling
+   * - "accepted" / "review.pending" → verified (limited access while under review)
+   * - "pending" → documents submitted, verification running: keep polling
+   * - "awaiting_kyc" → nothing submitted yet; check `link_expired` before
+   *   re-surfacing or re-requesting the link. Never treat as in progress.
+   * - "declined" → show `additional_data.declined_reasons` (fallback
+   *   `declined_reason`) with a retry option
    *
-   * @param request - Request containing user_id and token
-   * @returns Response with kyc_status and message (reason)
+   * @param request - Request containing user_id and kyc_id
+   * @returns Response with status, verification flags and, once terminal, the full record in `additional_data`
    *
    * @example
    * ```typescript
    * const result = await client.checkKycStatus({
    *   user_id: "user_123",
-   *   token: "auth_token_xyz"
+   *   kyc_id: "550e8400-e29b-41d4-a716-446655440000"
    * });
    *
-   * if (result.kyc_status === 'complete') {
-   *   // Show "Continue to Login"
-   * } else if (result.kyc_status === 'failed' || result.kyc_status === 'declined') {
+   * if (result.status === 'accepted' || result.status === 'review.pending') {
+   *   // Grant access
+   * } else if (result.status === 'declined') {
+   *   const reasons = result.additional_data?.declined_reasons;
    *   // Show error + retry option
+   * } else if (result.status === 'awaiting_kyc') {
+   *   // Prompt to verify; request a new link when result.link_expired is true
    * } else {
    *   // Keep polling
    * }
@@ -825,7 +855,9 @@ var KycClient = class extends BaseClient {
   /**
    * Submit a document verification request with OCR
    *
-   * Uses requestWithRetry() for automatic retry on transient failures.
+   * The call is made once and is not retried: every submission is processed
+   * and billed, and the platform does not replay this route from an
+   * idempotency key. Retry explicitly if the request fails.
    *
    * @param request - Document verification request with documents and customer info
    * @returns Verification response with status and reference
@@ -851,11 +883,11 @@ var KycClient = class extends BaseClient {
    * ```
    */
   async submitVerification(request, requestOptions) {
-    return this.requestWithRetry("/api/v1/kyc/submit", {
+    return this.request("/api/v1/kyc/submit", {
       method: "POST",
       body: JSON.stringify(request),
       headers: this.getUserHeaders()
-    }, void 0, void 0, requestOptions);
+    }, void 0, requestOptions);
   }
   /**
    * Get a KYC request by ID
@@ -912,14 +944,14 @@ var KycClient = class extends BaseClient {
    * ```typescript
    * // Accept a KYC request
    * await client.updateKycStatus({
-   *   reference: "shufti_ref_123",
+   *   reference: "kyc-ref-123",
    *   status: "accepted",
    *   reason: "All documents verified successfully"
    * });
    *
    * // Decline a KYC request
    * await client.updateKycStatus({
-   *   reference: "shufti_ref_456",
+   *   reference: "kyc-ref-456",
    *   status: "declined",
    *   reason: "Document expired"
    * });
@@ -935,6 +967,10 @@ var KycClient = class extends BaseClient {
   /**
    * Request additional documents from customer
    *
+   * @deprecated The platform does not expose this operation; the call always
+   * fails. Request additional documents from the Vesant console instead.
+   * This method will be removed in a future release.
+   *
    * @param request - Request with KYC ID and document types needed
    *
    * @example
@@ -1107,6 +1143,11 @@ var KycClient = class extends BaseClient {
   /**
    * Update KYC preferences for the tenant
    *
+   * @deprecated KYC preferences are managed in the Vesant console; the
+   * platform exposes no update operation to the SDK, so this call always
+   * fails. Use `getPreferences()` to read them. This method will be removed
+   * in a future release.
+   *
    * @param update - Fields to update
    * @returns Updated preferences
    *
@@ -1265,7 +1306,10 @@ var KYC_DECLINED_DESCRIPTIONS = {
   KYC_PROVIDER_REJECTED: "Identity verification was rejected by the verification provider",
   KYC_DECLINED: "Identity verification was declined"
 };
+function isKycDocumentExpiredCallbackEvent(value) {
+  return typeof value === "object" && value !== null && value.event === "kyc_document_expired";
+}
 
-export { KYC_DECLINED_DESCRIPTIONS, KycClient };
+export { KYC_DECLINED_DESCRIPTIONS, KycClient, isKycDocumentExpiredCallbackEvent };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map