vesant-sdk 1.7.0-dev.fce9898 → 1.7.0-dev.fe84882

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
@@ -318,8 +318,49 @@ interface RequestKycSubmitLinkRequest {
     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") */
+    /**
+     * Event that triggered the KYC request. Valid values: "onboarding",
+     * "first_withdrawal", "first_purchase", "manual". The tenant's KYC
+     * verification trigger preferences decide, per event, whether KYC is
+     * required (`kyc_required` in the response). "manual" always requires
+     * KYC and honors the tenant's allow-skip-on-manual option (`can_skip`).
+     * Omitted or unknown values default to KYC required with no skip.
+     */
     trigger_event?: string;
+    /**
+     * Registered customer identity data (optional). Seeds the customer's risk
+     * profile so document verification can cross-check the submitted document
+     * against trusted reference data (name/DOB match, address verification).
+     * Fields never overwrite data already on the profile.
+     */
+    customer_data?: KycCustomerData;
+}
+/**
+ * Customer identity data supplied by your platform on a submit-link request.
+ * Mirrors the geolocation `customer_data` contract. Every field is optional
+ * and never overwrites data already on the customer's risk profile.
+ */
+interface KycCustomerData {
+    /**
+     * Customer's registered full name. Used to match the OCR-extracted name
+     * on the submitted document.
+     */
+    full_name?: string;
+    /**
+     * Customer's registered date of birth. ISO 8601 date ("1999-06-02") or an
+     * RFC 3339 timestamp ("1986-09-06T18:30:00.000+00:00", as produced by
+     * `Date.prototype.toISOString()`) — for timestamps the date portion is
+     * used. Used for DOB matching against the submitted document.
+     */
+    date_of_birth?: string;
+    /** Customer's email address */
+    email?: string;
+    /** Customer's phone number */
+    phone?: string;
+    /** Customer's residential address. Used for address verification. */
+    address?: string;
+    /** Customer's country of residence */
+    country?: string;
 }
 /**
  * Trigger events that can request Event-Based Face Verification.
@@ -374,12 +415,34 @@ interface SubmitEventBasedFaceVerificationSessionRequest {
     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 {
     /** Generated KYC submission redirect URL */
     link: string;
     /** KYC request ID */
     kyc_id: string;
+    /**
+     * Whether KYC is required for the reported `trigger_event`, per the
+     * tenant's verification trigger preferences. `false` when the trigger
+     * is disabled for the tenant, or when the customer is already verified
+     * (in that case `link` and `kyc_id` are empty).
+     */
+    kyc_required: boolean;
+    /**
+     * Whether the user may skip verification. Only `true` for
+     * `trigger_event: "manual"` when the tenant enables allow-skip-on-manual,
+     * or when the customer is already verified.
+     */
+    can_skip: boolean;
 }
 /** Device class detected by the SDK (purely client-side — server doesn't care). */
 type EventBasedFaceVerificationDeviceType = 'mobile' | 'desktop';
@@ -657,7 +720,7 @@ interface UseKycPreferencesResult extends BaseHookState {
  */
 declare class KycClient extends BaseClient {
     private userId?;
-    private riskProfileBaseURL?;
+    private readonly riskProfileBaseURL?;
     constructor(config: KycClientConfig);
     /**
      * Set the user ID for operations requiring user context
@@ -676,7 +739,13 @@ 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, optional redirect URL, and optional callback URL (receives POST requests)
+     * 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
      *
      * @example
@@ -684,14 +753,22 @@ declare class KycClient extends BaseClient {
      * const result = await client.requestKycSubmitLink({
      *   user_id: "user_123",
      *   redirect_url: "https://merchant.com/kyc-complete", // optional
-     *   callback_url: "https://merchant.com/api/kyc-webhook" // optional - receives POST requests on status change
+     *   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
+     *     full_name: "John Doe",
+     *     date_of_birth: "1999-06-02", // ISO 8601
+     *     email: "john@example.com",
+     *     phone: "+94771234567",
+     *     address: "12 Main St, Colombo", // used for address verification
+     *     country: "LK"
+     *   }
      * });
      *
      * console.log(`Redirect user to: ${result.link}`);
      * 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.
      *
@@ -717,7 +794,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.
@@ -789,7 +866,7 @@ declare class KycClient extends BaseClient {
      * @example
      * ```typescript
      * const result = await client.submitVerification({
-     *   reference: "customer_123",
+     *   reference: "4d2aff34-ab86-422d-992e-50b1234a5b67",
      *   email: "customer@example.com",
      *   country: "US",
      *   document: {
@@ -806,7 +883,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
      *
@@ -815,7 +892,7 @@ declare class KycClient extends BaseClient {
      *
      * @example
      * ```typescript
-     * const kyc = await client.getKycRequest("kyc_abc123");
+     * const kyc = await client.getKycRequest("550e8400-e29b-41d4-a716-446655440000");
      * console.log(`Status: ${kyc.status}, ID Verified: ${kyc.id_verified}`);
      * ```
      */
@@ -868,7 +945,7 @@ declare class KycClient extends BaseClient {
      * @example
      * ```typescript
      * await client.requestAdditionalDocuments({
-     *   id: "kyc_abc123",
+     *   id: "550e8400-e29b-41d4-a716-446655440000",
      *   document_types: ["address", "document_two"],
      *   message: "Please provide proof of address and secondary ID"
      * });
@@ -883,7 +960,7 @@ declare class KycClient extends BaseClient {
      *
      * @example
      * ```typescript
-     * const proofs = await client.getProofDownloadURLs("kyc_abc123");
+     * const proofs = await client.getProofDownloadURLs("550e8400-e29b-41d4-a716-446655440000");
      * proofs.forEach(proof => {
      *   console.log(`${proof.type}: ${proof.url} (expires: ${proof.expires_at})`);
      * });
@@ -1069,4 +1146,4 @@ declare class KycClient extends BaseClient {
     createCustomerProfile(profile: CreateProfileRequest): Promise<CustomerProfile>;
 }
 
-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 };
+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 KycCustomerData, 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.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
@@ -318,8 +318,49 @@ interface RequestKycSubmitLinkRequest {
     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") */
+    /**
+     * Event that triggered the KYC request. Valid values: "onboarding",
+     * "first_withdrawal", "first_purchase", "manual". The tenant's KYC
+     * verification trigger preferences decide, per event, whether KYC is
+     * required (`kyc_required` in the response). "manual" always requires
+     * KYC and honors the tenant's allow-skip-on-manual option (`can_skip`).
+     * Omitted or unknown values default to KYC required with no skip.
+     */
     trigger_event?: string;
+    /**
+     * Registered customer identity data (optional). Seeds the customer's risk
+     * profile so document verification can cross-check the submitted document
+     * against trusted reference data (name/DOB match, address verification).
+     * Fields never overwrite data already on the profile.
+     */
+    customer_data?: KycCustomerData;
+}
+/**
+ * Customer identity data supplied by your platform on a submit-link request.
+ * Mirrors the geolocation `customer_data` contract. Every field is optional
+ * and never overwrites data already on the customer's risk profile.
+ */
+interface KycCustomerData {
+    /**
+     * Customer's registered full name. Used to match the OCR-extracted name
+     * on the submitted document.
+     */
+    full_name?: string;
+    /**
+     * Customer's registered date of birth. ISO 8601 date ("1999-06-02") or an
+     * RFC 3339 timestamp ("1986-09-06T18:30:00.000+00:00", as produced by
+     * `Date.prototype.toISOString()`) — for timestamps the date portion is
+     * used. Used for DOB matching against the submitted document.
+     */
+    date_of_birth?: string;
+    /** Customer's email address */
+    email?: string;
+    /** Customer's phone number */
+    phone?: string;
+    /** Customer's residential address. Used for address verification. */
+    address?: string;
+    /** Customer's country of residence */
+    country?: string;
 }
 /**
  * Trigger events that can request Event-Based Face Verification.
@@ -374,12 +415,34 @@ interface SubmitEventBasedFaceVerificationSessionRequest {
     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 {
     /** Generated KYC submission redirect URL */
     link: string;
     /** KYC request ID */
     kyc_id: string;
+    /**
+     * Whether KYC is required for the reported `trigger_event`, per the
+     * tenant's verification trigger preferences. `false` when the trigger
+     * is disabled for the tenant, or when the customer is already verified
+     * (in that case `link` and `kyc_id` are empty).
+     */
+    kyc_required: boolean;
+    /**
+     * Whether the user may skip verification. Only `true` for
+     * `trigger_event: "manual"` when the tenant enables allow-skip-on-manual,
+     * or when the customer is already verified.
+     */
+    can_skip: boolean;
 }
 /** Device class detected by the SDK (purely client-side — server doesn't care). */
 type EventBasedFaceVerificationDeviceType = 'mobile' | 'desktop';
@@ -657,7 +720,7 @@ interface UseKycPreferencesResult extends BaseHookState {
  */
 declare class KycClient extends BaseClient {
     private userId?;
-    private riskProfileBaseURL?;
+    private readonly riskProfileBaseURL?;
     constructor(config: KycClientConfig);
     /**
      * Set the user ID for operations requiring user context
@@ -676,7 +739,13 @@ 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, optional redirect URL, and optional callback URL (receives POST requests)
+     * 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
      *
      * @example
@@ -684,14 +753,22 @@ declare class KycClient extends BaseClient {
      * const result = await client.requestKycSubmitLink({
      *   user_id: "user_123",
      *   redirect_url: "https://merchant.com/kyc-complete", // optional
-     *   callback_url: "https://merchant.com/api/kyc-webhook" // optional - receives POST requests on status change
+     *   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
+     *     full_name: "John Doe",
+     *     date_of_birth: "1999-06-02", // ISO 8601
+     *     email: "john@example.com",
+     *     phone: "+94771234567",
+     *     address: "12 Main St, Colombo", // used for address verification
+     *     country: "LK"
+     *   }
      * });
      *
      * console.log(`Redirect user to: ${result.link}`);
      * 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.
      *
@@ -717,7 +794,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.
@@ -789,7 +866,7 @@ declare class KycClient extends BaseClient {
      * @example
      * ```typescript
      * const result = await client.submitVerification({
-     *   reference: "customer_123",
+     *   reference: "4d2aff34-ab86-422d-992e-50b1234a5b67",
      *   email: "customer@example.com",
      *   country: "US",
      *   document: {
@@ -806,7 +883,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
      *
@@ -815,7 +892,7 @@ declare class KycClient extends BaseClient {
      *
      * @example
      * ```typescript
-     * const kyc = await client.getKycRequest("kyc_abc123");
+     * const kyc = await client.getKycRequest("550e8400-e29b-41d4-a716-446655440000");
      * console.log(`Status: ${kyc.status}, ID Verified: ${kyc.id_verified}`);
      * ```
      */
@@ -868,7 +945,7 @@ declare class KycClient extends BaseClient {
      * @example
      * ```typescript
      * await client.requestAdditionalDocuments({
-     *   id: "kyc_abc123",
+     *   id: "550e8400-e29b-41d4-a716-446655440000",
      *   document_types: ["address", "document_two"],
      *   message: "Please provide proof of address and secondary ID"
      * });
@@ -883,7 +960,7 @@ declare class KycClient extends BaseClient {
      *
      * @example
      * ```typescript
-     * const proofs = await client.getProofDownloadURLs("kyc_abc123");
+     * const proofs = await client.getProofDownloadURLs("550e8400-e29b-41d4-a716-446655440000");
      * proofs.forEach(proof => {
      *   console.log(`${proof.type}: ${proof.url} (expires: ${proof.expires_at})`);
      * });
@@ -1069,4 +1146,4 @@ declare class KycClient extends BaseClient {
     createCustomerProfile(profile: CreateProfileRequest): Promise<CustomerProfile>;
 }
 
-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 };
+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 KycCustomerData, 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

@@ -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) {
@@ -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)
@@ -603,7 +664,13 @@ 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, optional redirect URL, and optional callback URL (receives POST requests)
+   * 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
    *
    * @example
@@ -611,19 +678,27 @@ var KycClient = class extends BaseClient {
    * const result = await client.requestKycSubmitLink({
    *   user_id: "user_123",
    *   redirect_url: "https://merchant.com/kyc-complete", // optional
-   *   callback_url: "https://merchant.com/api/kyc-webhook" // optional - receives POST requests on status change
+   *   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
+   *     full_name: "John Doe",
+   *     date_of_birth: "1999-06-02", // ISO 8601
+   *     email: "john@example.com",
+   *     phone: "+94771234567",
+   *     address: "12 Main St, Colombo", // used for address verification
+   *     country: "LK"
+   *   }
    * });
    *
    * console.log(`Redirect user to: ${result.link}`);
    * 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.
@@ -656,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
@@ -760,7 +835,7 @@ var KycClient = class extends BaseClient {
    * @example
    * ```typescript
    * const result = await client.submitVerification({
-   *   reference: "customer_123",
+   *   reference: "4d2aff34-ab86-422d-992e-50b1234a5b67",
    *   email: "customer@example.com",
    *   country: "US",
    *   document: {
@@ -777,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
@@ -792,7 +867,7 @@ var KycClient = class extends BaseClient {
    *
    * @example
    * ```typescript
-   * const kyc = await client.getKycRequest("kyc_abc123");
+   * const kyc = await client.getKycRequest("550e8400-e29b-41d4-a716-446655440000");
    * console.log(`Status: ${kyc.status}, ID Verified: ${kyc.id_verified}`);
    * ```
    */
@@ -867,7 +942,7 @@ var KycClient = class extends BaseClient {
    * @example
    * ```typescript
    * await client.requestAdditionalDocuments({
-   *   id: "kyc_abc123",
+   *   id: "550e8400-e29b-41d4-a716-446655440000",
    *   document_types: ["address", "document_two"],
    *   message: "Please provide proof of address and secondary ID"
    * });
@@ -888,7 +963,7 @@ var KycClient = class extends BaseClient {
    *
    * @example
    * ```typescript
-   * const proofs = await client.getProofDownloadURLs("kyc_abc123");
+   * const proofs = await client.getProofDownloadURLs("550e8400-e29b-41d4-a716-446655440000");
    * proofs.forEach(proof => {
    *   console.log(`${proof.type}: ${proof.url} (expires: ${proof.expires_at})`);
    * });