vesant-sdk 1.7.1-dev.afc5a32 → 1.7.1-dev.c2ac5a5

package/dist/kyc/index.d.mts

@@ -23,6 +23,8 @@ 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';
+/** Document types a tenant can accept as proof of address. */
+type SupportedAddressDocumentType = 'id_card' | 'passport' | 'driving_license' | 'utility_bill' | 'bank_statement' | 'rent_agreement' | 'employer_letter' | 'insurance_agreement' | 'tax_bill' | 'envelope' | 'cpr_smart_card_reader_copy' | 'property_tax' | 'lease_agreement' | 'insurance_card' | 'permanent_residence_permit' | 'credit_card_statement' | 'insurance_policy' | 'e_commerce_receipt' | 'bank_letter_receipt' | 'birth_certificate' | 'salary_slip';
 interface KycRequest {
     id: string;
     reference: string;
@@ -34,6 +36,35 @@ interface KycRequest {
     dob?: string;
     full_address?: string;
     email?: string;
+    gender?: string;
+    height?: string;
+    country?: string;
+    country_code?: string;
+    nationality?: string;
+    authority?: string;
+    document_type?: string;
+    document_number?: string;
+    personal_number?: string;
+    place_of_birth?: string;
+    issue_date?: string;
+    expiry_date?: string;
+    age?: number;
+    document_two_type?: string;
+    document_two_number?: string;
+    document_two_first_name?: string;
+    document_two_middle_name?: string;
+    document_two_last_name?: string;
+    document_two_dob?: string;
+    document_two_gender?: string;
+    document_two_height?: string;
+    document_two_country?: string;
+    document_two_country_code?: string;
+    document_two_nationality?: string;
+    document_two_authority?: string;
+    document_two_personal_number?: string;
+    document_two_place_of_birth?: string;
+    document_two_issue_date?: string;
+    document_two_expiry_date?: string;
     id_verified: boolean;
     address_verified: boolean;
     face_verified: boolean;
@@ -41,8 +72,13 @@ interface KycRequest {
     status: KycStatus;
     location?: string;
     identity_hash?: string;
+    /** True when verification could not run because of an internal failure. */
+    is_internal_error?: boolean;
+    /** The `trigger_event` the submit link was requested with. */
+    event?: string;
     required_document_count: number;
     supported_document_types?: SupportedDocumentType[];
+    supported_address_document_types?: SupportedAddressDocumentType[];
     is_id_verification_required: boolean;
     is_face_verification_required: boolean;
     is_address_verification_required: boolean;
@@ -188,27 +224,70 @@ interface EventBasedFaceVerificationTriggers {
     account_balance_transfer: boolean;
 }
 /**
- * Reactions taken when a customer exhausts the Event-Based Face Verification 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.
+ * Retry budget for Event-Based Face Verification. This is the only field the
+ * platform stores here; the reactions taken when the budget is exhausted
+ * (`trigger_alert`, `enforce_logout`, `freeze_account`, `block`,
+ * `freeze_duration_minutes`) come from the tenant's per-event KYC alert
+ * configuration and are reported on
+ * {@link EventBasedFaceVerificationReactionResult}.
  */
 interface EventBasedFaceVerificationReactions {
     /** 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;
+    /** @deprecated Never populated; read `data.trigger_alert` on the callback instead. */
+    trigger_alert?: boolean;
+    /** @deprecated Never populated; read `data.enforce_logout` on the callback instead. */
+    enforce_logout?: boolean;
+    /** @deprecated Never populated; read `data.freeze_account` on the callback instead. */
+    freeze_account?: boolean;
+    /** @deprecated Never populated; read `data.freeze_duration_minutes` on the callback instead. */
+    freeze_duration_minutes?: number;
+}
+/** Per-event toggles that decide when a submit-link request requires KYC. */
+interface KycVerificationTriggers {
+    onboarding: boolean;
+    first_withdrawal: boolean;
+    first_purchase: boolean;
+    /** Re-trigger verification once the customer's identity document has expired. */
+    auto_trigger_on_id_expiration: boolean;
+}
+interface KycSkipOptions {
+    /** Let a `manual` trigger be skipped (`can_skip` on the submit-link response). */
+    allow_skip_on_manual: boolean;
+}
+/** Tenant-defined reasons available to reviewers for a given resource. */
+interface KycOtherReason {
+    resource: string;
+    reasons: string[];
+}
+/** Disclosure text shown to the customer on the hosted submission page. */
+interface KycDisclosureConsent {
+    data_collected: string[];
+    data_usage: string[];
+    data_sharing: {
+        third_party_providers: boolean;
+        regulatory_authorities: boolean;
+        internal_systems: boolean;
+        provider_names?: string[];
+    };
+    data_retention_period: string;
+    customer_rights: {
+        can_access: boolean;
+        can_correct: boolean;
+        can_delete: boolean;
+        contact_info?: string;
+    };
 }
 interface KycPreferences {
     id: string;
     tenant_id: string;
     approve_kyc_reasons: string[];
+    other_reasons?: KycOtherReason[];
     is_document_verification_required: boolean;
     is_face_verification_required: boolean;
     is_address_verification_required: boolean;
     is_age_verification_required: boolean;
+    is_duplicate_verification_required?: boolean;
     /** Master switch for the Event-Based Face Verification feature. */
     is_reuse_kyc_enabled?: boolean;
     min_age: number;
@@ -218,13 +297,34 @@ interface KycPreferences {
     high_risk_score: number;
     medium_risk_score: number;
     supported_document_types: SupportedDocumentType[];
+    supported_address_document_types?: SupportedAddressDocumentType[];
+    /** Tenant-level callback URL used when a submit-link request passes none. */
+    callback_url?: string;
+    address_fuzzy_match?: boolean;
+    document_fuzzy_match?: boolean;
+    document_translate?: boolean;
+    decline_on_single_step?: boolean;
+    allow_warnings?: boolean;
+    backside_proof_required?: boolean;
+    document_two_backside_proof_required?: boolean;
+    verification_mode?: string;
+    document_upload_option?: boolean;
+    disclosure_consent?: KycDisclosureConsent;
+    /** Per-event toggles for document verification (`requestKycSubmitLink`). */
+    kyc_triggers?: KycVerificationTriggers;
+    kyc_skip_options?: KycSkipOptions;
     /** Per-event triggers for Event-Based Face Verification. */
     reuse_kyc_triggers?: EventBasedFaceVerificationTriggers;
-    /** Retry / reaction policy for Event-Based Face Verification. */
+    /** Retry budget for Event-Based Face Verification. */
     reuse_kyc_reactions?: EventBasedFaceVerificationReactions;
     created_at: string;
     updated_at: string;
 }
+/**
+ * @deprecated KYC preferences are managed in the Vesant console; the platform
+ * exposes no update operation to the SDK, so `updatePreferences` always fails.
+ * This type will be removed in a future release.
+ */
 interface UpdateKycPreferencesRequest {
     reasons?: string[];
     is_document_verification_required?: boolean;
@@ -306,13 +406,13 @@ interface DocumentVerificationResponse {
     message?: string;
 }
 interface UpdateKycStatusRequest {
-    /** Shufti reference or KYC ID */
+    /** Provider reference or KYC ID */
     reference: string;
     /** Target status */
     status: KycStatus;
     /** Acceptance/decline reason */
     reason?: string;
-    /** Shufti warnings data */
+    /** Provider warnings data */
     warnings?: Record<string, Record<string, string>>;
 }
 /**
@@ -617,9 +717,13 @@ interface EventBasedFaceVerificationCallback {
     block?: boolean;
     /** Names the event/verification that triggered the block. Omitted when not blocked. */
     block_reason?: string;
-    /** Structured decline reasons. */
+    /**
+     * Structured decline reasons. Returned by
+     * `getEventBasedFaceVerificationSessionStatus`; the submit response and the
+     * webhook carry {@link declined_reason} only.
+     */
     declined_reasons?: Reason[];
-    /** @deprecated Use {@link declined_reasons}. */
+    /** Decline text. Present on the submit response, the webhook, and status lookups. */
     declined_reason?: string;
     /** @deprecated Use structured reasons. */
     warnings?: Record<string, Record<string, string>>;
@@ -669,20 +773,28 @@ interface CheckKycStatusResponse {
     address_verified: boolean;
     face_verified: boolean;
     age_verified: boolean;
-    /** Structured decline reasons. Present when status is `declined`. */
+    /**
+     * Structured decline reasons. The platform currently returns these only on
+     * the full record: read `additional_data.declined_reasons` and fall back to
+     * {@link declined_reason}. This top-level field is reserved and not populated.
+     */
     declined_reasons?: Reason[];
-    /** Structured, non-blocking warnings. */
+    /**
+     * Structured, non-blocking warnings. Currently returned only as
+     * `additional_data.warning_reasons`; this top-level field is not populated.
+     */
     warning_reasons?: Reason[];
-    /** @deprecated Use {@link declined_reasons}. */
+    /** Comma-joined decline text. Always present on a declined response. */
     declined_reason?: string;
-    /** @deprecated Use the `code` on {@link declined_reasons}. */
+    /** Legacy decline code; prefer the `code` on `additional_data.declined_reasons`. */
     declined_code?: KycDeclinedCode;
     other_reason?: string;
     accepted_reason?: string;
-    /** @deprecated Use {@link warning_reasons}. */
+    /** Legacy warning map; prefer `additional_data.warning_reasons`. */
     warnings?: Record<string, Record<string, string>>;
     required_document_count: number;
     supported_document_types?: SupportedDocumentType[];
+    supported_address_document_types?: SupportedAddressDocumentType[];
     is_id_verification_required: boolean;
     is_face_verification_required: boolean;
     is_address_verification_required: boolean;
@@ -811,6 +923,7 @@ interface UseKycOverviewResult extends BaseHookState {
 }
 interface UseKycPreferencesResult extends BaseHookState {
     preferences: KycPreferences | null;
+    /** @deprecated The platform exposes no preference-update operation; this call always fails. */
     updatePreferences: (update: UpdateKycPreferencesRequest) => Promise<void>;
     refresh: () => Promise<void>;
 }
@@ -829,8 +942,9 @@ interface UseKycPreferencesResult extends BaseHookState {
  * - Automatic timeout management
  * - Debug logging
  *
- * All KYC verification calls use requestWithRetry() to handle
- * transient failures gracefully.
+ * Read calls use requestWithRetry() to ride out transient failures.
+ * Calls that create or bill something (submit link, document submit,
+ * face session, face submit, hosted journey retry) are made exactly once.
  */
 declare class KycClient extends BaseClient {
     private userId?;
@@ -853,19 +967,27 @@ declare class KycClient 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
@@ -878,6 +1000,7 @@ declare class KycClient extends BaseClient {
      *   }
      * });
      *
+     * if (!result.kyc_required) return proceed();
      * console.log(`Redirect user to: ${result.link}`);
      * console.log(`KYC ID: ${result.kyc_id}`);
      * ```
@@ -897,9 +1020,9 @@ declare class KycClient 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`,
@@ -954,25 +1077,30 @@ declare class KycClient 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
      * }
@@ -982,7 +1110,9 @@ declare class KycClient 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
@@ -1047,14 +1177,14 @@ declare class KycClient 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"
      * });
@@ -1064,6 +1194,10 @@ declare class KycClient 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
@@ -1182,6 +1316,11 @@ declare class KycClient 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
      *
@@ -1270,4 +1409,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 KycCustomerData, type KycCustomerProfile, type KycDeclinedCode, type KycDocumentExpiredCallbackEvent, type KycHandoffSession, type KycOverview, type KycPagination, type KycPreferences, type KycRequest, type KycRequestFilters, type KycRequestListResponse, type KycRequestReason, type KycRequestReasonCode, type KycStatus, type KycTriggerEvent, 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, isKycDocumentExpiredCallbackEvent };
+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 KycDisclosureConsent, type KycDocumentExpiredCallbackEvent, type KycHandoffSession, type KycOtherReason, type KycOverview, type KycPagination, type KycPreferences, type KycRequest, type KycRequestFilters, type KycRequestListResponse, type KycRequestReason, type KycRequestReasonCode, type KycSkipOptions, type KycStatus, type KycTriggerEvent, type KycVerificationTriggers, type Name, PaginationParams, type Proof, type ProofDownloadURL, type ProofType, type RequestAdditionalDocumentsRequest, type RequestKycSubmitLinkRequest, type RequestKycSubmitLinkResponse, RiskLevel, type SubmitEventBasedFaceVerificationSessionRequest, type SubmittedDocument, type SupportedAddressDocumentType, 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, isKycDocumentExpiredCallbackEvent };