vesant-sdk 1.7.0 → 1.7.1-dev.096c933

package/dist/kyc/index.d.mts

@@ -1,6 +1,6 @@
 import { P as ProfileFilters, b as ProfileListResponse, C as CustomerProfile, a as CreateProfileRequest } from '../types-BOFaMQxI.mjs';
 import { c as Reason, R as RiskLevel, P as PaginationParams } from '../types-CBQRNL-l.mjs';
-import { B as BaseClient } from '../client-BolQlL5e.mjs';
+import { B as BaseClient, R as RequestOptions } from '../client-q9fN8Hhf.mjs';
 
 /**
  * TypeScript type definitions for Vesant KYC Service API
@@ -11,7 +11,11 @@ import { B as BaseClient } from '../client-BolQlL5e.mjs';
  * - services/kyc-service/internal/handler/
  */
 
-type KycStatus = 'pending' | 'accepted' | 'declined' | 'review.pending' | 'unknown';
+type KycStatus = 
+/** Submit link issued but the customer has not submitted documents yet — not "in progress". */
+'awaiting_kyc'
+/** Documents submitted, verification in progress. */
+ | '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';
@@ -539,17 +543,22 @@ interface KycHandoffSession {
     is_submitted: boolean;
 }
 interface CheckKycStatusRequest {
-    /** User ID to check KYC status for */
+    /** Customer identifier. Sent for context only — the lookup is by kyc_id. */
     user_id: string;
-    /** Authentication token */
+    /** The KYC request ID returned by requestKycSubmitLink; drives the status lookup. */
     kyc_id: string;
 }
 /**
  * Response from checkKycStatus. Always returns the same shape.
  *
- * `additional_data` is `null` when `status === 'pending'`.
- * When `status !== 'pending'`, `additional_data` contains the full KYC record
- * including document details, proofs, and the customer's risk profile.
+ * `additional_data` is `null` when `status` is `'awaiting_kyc'` or `'pending'`.
+ * Otherwise it contains the full KYC record including document details,
+ * proofs, and the customer's risk profile.
+ *
+ * `status === 'awaiting_kyc'` means the submit link was issued but the
+ * customer has not submitted documents — treat it as "not started", never as
+ * "in progress". Check `link_expired`: `false` → re-surface the existing
+ * link; `true` → request a fresh one via `requestKycSubmitLink`.
  */
 interface CheckKycStatusResponse {
     id: string;
@@ -578,8 +587,12 @@ interface CheckKycStatusResponse {
     is_address_verification_required: boolean;
     is_age_verification_required: boolean;
     created_at: string;
-    /** Full KYC record with document details, proofs, and risk profile. Null when status is 'pending'. */
+    /** Full KYC record with document details, proofs, and risk profile. Null when status is 'awaiting_kyc' or 'pending'. */
     additional_data: KycRequest | null;
+    /** Present when status is 'awaiting_kyc': whether the submit link has expired (request a new one when true). */
+    link_expired?: boolean;
+    /** Present when status is 'awaiting_kyc': the submit link's expiry time (RFC 3339). */
+    link_expires_at?: string;
 }
 interface RequestAdditionalDocumentsRequest {
     /** KYC request ID */
@@ -768,7 +781,7 @@ declare class KycClient extends BaseClient {
      * console.log(`KYC ID: ${result.kyc_id}`);
      * ```
      */
-    requestKycSubmitLink(request: RequestKycSubmitLinkRequest): Promise<RequestKycSubmitLinkResponse>;
+    requestKycSubmitLink(request: RequestKycSubmitLinkRequest, requestOptions?: RequestOptions): Promise<RequestKycSubmitLinkResponse>;
     /**
      * Create a Event-Based Face Verification session.
      *
@@ -794,7 +807,7 @@ declare class KycClient extends BaseClient {
      *
      * @param request - Token from `createEventBasedFaceVerificationSession`, plus the base64 selfie.
      */
-    submitEventBasedFaceVerificationSession(request: SubmitEventBasedFaceVerificationSessionRequest): Promise<EventBasedFaceVerificationCallback>;
+    submitEventBasedFaceVerificationSession(request: SubmitEventBasedFaceVerificationSessionRequest, requestOptions?: RequestOptions): Promise<EventBasedFaceVerificationCallback>;
     /**
      * 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.
@@ -883,7 +896,7 @@ declare class KycClient extends BaseClient {
      * console.log(`Verification submitted: ${result.reference}`);
      * ```
      */
-    submitVerification(request: DocumentVerificationRequest): Promise<DocumentVerificationResponse>;
+    submitVerification(request: DocumentVerificationRequest, requestOptions?: RequestOptions): Promise<DocumentVerificationResponse>;
     /**
      * Get a KYC request by ID
      *

package/dist/kyc/index.d.ts

@@ -1,6 +1,6 @@
 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';
+import { B as BaseClient, R as RequestOptions } from '../client-q9fN8Hhf.js';
 
 /**
  * TypeScript type definitions for Vesant KYC Service API
@@ -11,7 +11,11 @@ import { B as BaseClient } from '../client-BolQlL5e.js';
  * - services/kyc-service/internal/handler/
  */
 
-type KycStatus = 'pending' | 'accepted' | 'declined' | 'review.pending' | 'unknown';
+type KycStatus = 
+/** Submit link issued but the customer has not submitted documents yet — not "in progress". */
+'awaiting_kyc'
+/** Documents submitted, verification in progress. */
+ | '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';
@@ -539,17 +543,22 @@ interface KycHandoffSession {
     is_submitted: boolean;
 }
 interface CheckKycStatusRequest {
-    /** User ID to check KYC status for */
+    /** Customer identifier. Sent for context only — the lookup is by kyc_id. */
     user_id: string;
-    /** Authentication token */
+    /** The KYC request ID returned by requestKycSubmitLink; drives the status lookup. */
     kyc_id: string;
 }
 /**
  * Response from checkKycStatus. Always returns the same shape.
  *
- * `additional_data` is `null` when `status === 'pending'`.
- * When `status !== 'pending'`, `additional_data` contains the full KYC record
- * including document details, proofs, and the customer's risk profile.
+ * `additional_data` is `null` when `status` is `'awaiting_kyc'` or `'pending'`.
+ * Otherwise it contains the full KYC record including document details,
+ * proofs, and the customer's risk profile.
+ *
+ * `status === 'awaiting_kyc'` means the submit link was issued but the
+ * customer has not submitted documents — treat it as "not started", never as
+ * "in progress". Check `link_expired`: `false` → re-surface the existing
+ * link; `true` → request a fresh one via `requestKycSubmitLink`.
  */
 interface CheckKycStatusResponse {
     id: string;
@@ -578,8 +587,12 @@ interface CheckKycStatusResponse {
     is_address_verification_required: boolean;
     is_age_verification_required: boolean;
     created_at: string;
-    /** Full KYC record with document details, proofs, and risk profile. Null when status is 'pending'. */
+    /** Full KYC record with document details, proofs, and risk profile. Null when status is 'awaiting_kyc' or 'pending'. */
     additional_data: KycRequest | null;
+    /** Present when status is 'awaiting_kyc': whether the submit link has expired (request a new one when true). */
+    link_expired?: boolean;
+    /** Present when status is 'awaiting_kyc': the submit link's expiry time (RFC 3339). */
+    link_expires_at?: string;
 }
 interface RequestAdditionalDocumentsRequest {
     /** KYC request ID */
@@ -768,7 +781,7 @@ declare class KycClient extends BaseClient {
      * console.log(`KYC ID: ${result.kyc_id}`);
      * ```
      */
-    requestKycSubmitLink(request: RequestKycSubmitLinkRequest): Promise<RequestKycSubmitLinkResponse>;
+    requestKycSubmitLink(request: RequestKycSubmitLinkRequest, requestOptions?: RequestOptions): Promise<RequestKycSubmitLinkResponse>;
     /**
      * Create a Event-Based Face Verification session.
      *
@@ -794,7 +807,7 @@ declare class KycClient extends BaseClient {
      *
      * @param request - Token from `createEventBasedFaceVerificationSession`, plus the base64 selfie.
      */
-    submitEventBasedFaceVerificationSession(request: SubmitEventBasedFaceVerificationSessionRequest): Promise<EventBasedFaceVerificationCallback>;
+    submitEventBasedFaceVerificationSession(request: SubmitEventBasedFaceVerificationSessionRequest, requestOptions?: RequestOptions): Promise<EventBasedFaceVerificationCallback>;
     /**
      * 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.
@@ -883,7 +896,7 @@ declare class KycClient extends BaseClient {
      * console.log(`Verification submitted: ${result.reference}`);
      * ```
      */
-    submitVerification(request: DocumentVerificationRequest): Promise<DocumentVerificationResponse>;
+    submitVerification(request: DocumentVerificationRequest, requestOptions?: RequestOptions): Promise<DocumentVerificationResponse>;
     /**
      * Get a KYC request by ID
      *

package/dist/kyc/index.js

@@ -1,5 +1,18 @@
 'use strict';
 
+// src/core/auth.ts
+var StaticApiKeyProvider = class {
+  constructor(apiKey) {
+    this.apiKey = apiKey;
+  }
+  async getCredential() {
+    return this.apiKey ? { scheme: "Bearer", token: this.apiKey } : null;
+  }
+  canRefresh() {
+    return false;
+  }
+};
+
 // src/core/errors.ts
 var VesantError = class _VesantError extends Error {
   constructor(message, code, statusCode, details) {
@@ -216,7 +229,7 @@ function createConsoleLogger() {
 }
 
 // src/core/version.ts
-var SDK_VERSION = "1.7.0";
+var SDK_VERSION = "1.7.1";
 
 // src/shared/browser-utils.ts
 function generateUUID() {
@@ -241,6 +254,12 @@ var BaseClient = class {
     if (!config.tenantId?.trim()) {
       throw new ValidationError("tenantId is required and must be a non-empty string", ["tenantId"]);
     }
+    if (typeof fetch === "undefined") {
+      throw new VesantError(
+        "The Vesant SDK requires a global fetch (Node.js >= 18). Upgrade Node or provide a fetch polyfill.",
+        "RUNTIME_UNSUPPORTED"
+      );
+    }
     this.interceptors = config.interceptors || [];
     this.logger = config.logger || createConsoleLogger();
     let environment = config.environment;
@@ -259,11 +278,12 @@ var BaseClient = class {
       environment,
       headers: config.headers || {},
       timeout: config.timeout || 1e4,
-      retries: config.retries || 3,
+      retries: config.retries ?? 3,
       debug: config.debug || false,
       interceptors: this.interceptors,
       logger: this.logger
     };
+    this.authProvider = config.authProvider ?? (apiKey ? new StaticApiKeyProvider(apiKey) : void 0);
     if (config.circuitBreaker) {
       this.circuitBreaker = new CircuitBreaker(config.circuitBreaker);
     }
@@ -271,6 +291,19 @@ var BaseClient = class {
       this.rateLimitTracker = new RateLimitTracker();
     }
   }
+  /**
+   * Resolve the Idempotency-Key for a request. Mutating methods (POST/PUT/PATCH)
+   * get the caller-supplied key or a freshly minted UUID; non-mutating methods get
+   * none. requestWithRetry resolves this once and injects it so every retry reuses
+   * one key (letting the server dedup replays); a direct request() resolves per call.
+   */
+  resolveIdempotencyKey(method, requestOptions) {
+    const isMutating = ["POST", "PUT", "PATCH"].includes((method || "GET").toUpperCase());
+    if (!isMutating) {
+      return void 0;
+    }
+    return requestOptions?.idempotencyKey ?? generateUUID();
+  }
   /**
    * Make an HTTP request with timeout and error handling
    */
@@ -296,15 +329,20 @@ var BaseClient = class {
       ...this.config.headers,
       ...options.headers || {}
     };
-    if (this.config.apiKey) {
-      headers["Authorization"] = `Bearer ${this.config.apiKey}`;
+    const credential = await this.authProvider?.getCredential({
+      tenantId: this.config.tenantId,
+      requestId
+    });
+    if (credential) {
+      headers["Authorization"] = `${credential.scheme ?? "Bearer"} ${credential.token}`;
     }
     if (this.config.environment === "sandbox") {
       headers["X-Sandbox"] = "true";
     }
     const method = (options.method || "GET").toUpperCase();
-    if (["POST", "PUT", "PATCH"].includes(method)) {
-      headers["Idempotency-Key"] = requestOptions?.idempotencyKey || generateUUID();
+    const idempotencyKey = this.resolveIdempotencyKey(method, requestOptions);
+    if (idempotencyKey) {
+      headers["Idempotency-Key"] = idempotencyKey;
     }
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
@@ -325,10 +363,28 @@ var BaseClient = class {
       if (this.config.debug) {
         this.logger.debug(`${finalOptions.method || "GET"} ${endpoint}`);
       }
-      const response = await fetch(url, {
+      let response = await fetch(url, {
         ...finalOptions,
         signal: controller.signal
       });
+      if (response.status === 401 && this.authProvider?.canRefresh?.()) {
+        const refreshed = await this.authProvider.getCredential({
+          tenantId: this.config.tenantId,
+          requestId,
+          forceRefresh: true
+        });
+        if (refreshed) {
+          this.config.onCredentialRotated?.({ reason: "unauthorized" });
+          finalOptions = {
+            ...finalOptions,
+            headers: {
+              ...finalOptions.headers,
+              Authorization: `${refreshed.scheme ?? "Bearer"} ${refreshed.token}`
+            }
+          };
+          response = await fetch(url, { ...finalOptions, signal: controller.signal });
+        }
+      }
       clearTimeout(timeoutId);
       if (this.rateLimitTracker) {
         this.rateLimitTracker.updateFromHeaders(response.headers);
@@ -417,9 +473,11 @@ var BaseClient = class {
    */
   async requestWithRetry(endpoint, options = {}, serviceURL, retries = this.config.retries, requestOptions) {
     let lastError;
+    const idempotencyKey = this.resolveIdempotencyKey(options.method || "GET", requestOptions);
+    const attemptOptions = idempotencyKey ? { ...requestOptions, idempotencyKey } : requestOptions;
     for (let attempt = 0; attempt <= retries; attempt++) {
       try {
-        return await this.request(endpoint, options, serviceURL, requestOptions);
+        return await this.request(endpoint, options, serviceURL, attemptOptions);
       } catch (error) {
         lastError = error instanceof Error ? error : new Error("Unknown error");
         if (requestOptions?.signal?.aborted) {
@@ -516,6 +574,9 @@ var BaseClient = class {
     if (config.interceptors) {
       this.interceptors = config.interceptors;
     }
+    if (config.authProvider !== void 0 || config.apiKey !== void 0) {
+      this.authProvider = this.config.authProvider ?? (this.config.apiKey ? new StaticApiKeyProvider(this.config.apiKey) : void 0);
+    }
   }
   /**
    * Get current configuration (readonly)
@@ -632,12 +693,12 @@ var KycClient = class extends BaseClient {
    * console.log(`KYC ID: ${result.kyc_id}`);
    * ```
    */
-  async requestKycSubmitLink(request) {
+  async requestKycSubmitLink(request, requestOptions) {
     return this.requestWithRetry("/api/v1/kyc/request", {
       method: "POST",
       body: JSON.stringify(request),
       headers: this.getUserHeaders()
-    });
+    }, void 0, void 0, requestOptions);
   }
   /**
    * Create a Event-Based Face Verification session.
@@ -670,12 +731,12 @@ var KycClient = class extends BaseClient {
    *
    * @param request - Token from `createEventBasedFaceVerificationSession`, plus the base64 selfie.
    */
-  async submitEventBasedFaceVerificationSession(request) {
+  async submitEventBasedFaceVerificationSession(request, requestOptions) {
     return this.request("/api/v1/kyc/face/submit", {
       method: "POST",
       body: JSON.stringify(request),
       headers: this.getUserHeaders()
-    });
+    }, void 0, requestOptions);
   }
   /**
    * Look up the current state of a Event-Based Face Verification session by its
@@ -791,12 +852,12 @@ var KycClient = class extends BaseClient {
    * console.log(`Verification submitted: ${result.reference}`);
    * ```
    */
-  async submitVerification(request) {
+  async submitVerification(request, requestOptions) {
     return this.requestWithRetry("/api/v1/kyc/submit", {
       method: "POST",
       body: JSON.stringify(request),
       headers: this.getUserHeaders()
-    });
+    }, void 0, void 0, requestOptions);
   }
   /**
    * Get a KYC request by ID