vesant-sdk 1.7.0-dev.9f7da53 → 1.7.0-dev.a85efc5

package/dist/kyc/index.d.mts

@@ -57,6 +57,18 @@ interface KycRequest {
     other_reason?: string;
     /** @deprecated Use {@link warning_reasons}. */
     warnings?: Record<string, Record<string, string>>;
+    /**
+     * Tenant app should block onboarding/the action when true. Set when a
+     * failed verification matches a per-event KYC alert rule with the `block`
+     * reaction; sticky once set (a later non-blocking update won't clear it).
+     */
+    block: boolean;
+    /**
+     * Names the configured verification that triggered the block (e.g.
+     * `document_verification`, `face_verification`, `address_verification`,
+     * `age_verification`). Empty when {@link block} is false.
+     */
+    block_reason?: string;
     proofs?: Proof[];
     alerts?: KycAlert[];
     risk_profile?: KycCustomerProfile;
@@ -132,10 +144,10 @@ interface UpdateKycAlertRequest {
  *
  * - `enabled=false` → event blocked.
  * - `enabled=true`, `threshold=0` (or null/omitted) → every event of this
- *   type triggers Re-Use KYC, regardless of amount.
+ *   type triggers Event-Based Face Verification, regardless of amount.
  * - `enabled=true`, `threshold>0` → only amounts `>= threshold` trigger.
  */
-interface ReuseKycThresholdTrigger {
+interface EventBasedFaceVerificationThresholdTrigger {
     enabled: boolean;
     /** USD threshold; 0 / null / omitted means "any amount". */
     threshold: number;
@@ -148,15 +160,15 @@ interface ReuseKycThresholdTrigger {
  * `event_window_minutes <= window_minutes`. Either bound of 0 means
  * "don't enforce that bound".
  */
-interface ReuseKycFrequencyTrigger {
+interface EventBasedFaceVerificationFrequencyTrigger {
     enabled: boolean;
     /** Minimum number of events; 0 / null / omitted means "any count". */
     count: number;
     /** Maximum lookback window in minutes; 0 / null / omitted means "any window". */
     window_minutes: number;
 }
-/** Events that can trigger Re-Use KYC for a tenant. */
-interface ReuseKycTriggers {
+/** Events that can trigger Event-Based Face Verification for a tenant. */
+interface EventBasedFaceVerificationTriggers {
     login: boolean;
     password_change: boolean;
     name_change: boolean;
@@ -165,19 +177,19 @@ interface ReuseKycTriggers {
     new_device_or_location: boolean;
     device_fingerprint_change: boolean;
     payment_method_change: boolean;
-    deposit: ReuseKycThresholdTrigger;
-    withdrawal: ReuseKycThresholdTrigger;
-    large_bet_placement: ReuseKycThresholdTrigger;
-    high_frequency_betting: ReuseKycFrequencyTrigger;
+    deposit: EventBasedFaceVerificationThresholdTrigger;
+    withdrawal: EventBasedFaceVerificationThresholdTrigger;
+    large_bet_placement: EventBasedFaceVerificationThresholdTrigger;
+    high_frequency_betting: EventBasedFaceVerificationFrequencyTrigger;
     account_balance_transfer: boolean;
 }
 /**
- * Reactions taken when a customer exhausts the Re-Use KYC retry limit.
+ * 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.
  */
-interface ReuseKycReactions {
+interface EventBasedFaceVerificationReactions {
     /** Retries after the first attempt; total submissions = this + 1. */
     max_retry_attempts: number;
     trigger_alert: boolean;
@@ -193,7 +205,7 @@ interface KycPreferences {
     is_face_verification_required: boolean;
     is_address_verification_required: boolean;
     is_age_verification_required: boolean;
-    /** Master switch for the Re-Use KYC feature. */
+    /** Master switch for the Event-Based Face Verification feature. */
     is_reuse_kyc_enabled?: boolean;
     min_age: number;
     max_age: number;
@@ -202,10 +214,10 @@ interface KycPreferences {
     high_risk_score: number;
     medium_risk_score: number;
     supported_document_types: SupportedDocumentType[];
-    /** Per-event triggers for Re-Use KYC. */
-    reuse_kyc_triggers?: ReuseKycTriggers;
-    /** Retry / reaction policy for Re-Use KYC. */
-    reuse_kyc_reactions?: ReuseKycReactions;
+    /** Per-event triggers for Event-Based Face Verification. */
+    reuse_kyc_triggers?: EventBasedFaceVerificationTriggers;
+    /** Retry / reaction policy for Event-Based Face Verification. */
+    reuse_kyc_reactions?: EventBasedFaceVerificationReactions;
     created_at: string;
     updated_at: string;
 }
@@ -224,9 +236,9 @@ interface UpdateKycPreferencesRequest {
     medium_risk_score?: number;
     supported_document_types?: SupportedDocumentType[];
     /** Partial update — only the events present here are changed. */
-    reuse_kyc_triggers?: Partial<ReuseKycTriggers>;
+    reuse_kyc_triggers?: Partial<EventBasedFaceVerificationTriggers>;
     /** Partial update — only the keys present here are changed. */
-    reuse_kyc_reactions?: Partial<ReuseKycReactions>;
+    reuse_kyc_reactions?: Partial<EventBasedFaceVerificationReactions>;
 }
 interface Name {
     first_name?: string;
@@ -306,29 +318,36 @@ 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;
 }
 /**
- * Trigger events that can request Re-Use KYC.
+ * Trigger events that can request Event-Based Face Verification.
  *
  * Account-sensitive: any sensitive change to the account profile.
  * Transaction events: covered by the per-event rules in
- * `ReuseKycTriggers` (`deposit`, `withdrawal`, `large_bet_placement`,
+ * `EventBasedFaceVerificationTriggers` (`deposit`, `withdrawal`, `large_bet_placement`,
  * `high_frequency_betting`, `account_balance_transfer`).
  */
-type ReuseKycEvent = 'login' | 'password_change' | 'name_change' | 'phone_number_change' | 'two_factor_auth_change' | 'new_device_or_location' | 'device_fingerprint_change' | 'payment_method_change' | 'deposit' | 'withdrawal' | 'large_bet_placement' | 'high_frequency_betting' | 'account_balance_transfer';
-interface CreateReuseKycSessionRequest {
+type EventBasedFaceVerificationEvent = 'login' | 'password_change' | 'name_change' | 'phone_number_change' | 'two_factor_auth_change' | 'new_device_or_location' | 'device_fingerprint_change' | 'payment_method_change' | 'deposit' | 'withdrawal' | 'large_bet_placement' | 'high_frequency_betting' | 'account_balance_transfer';
+interface CreateEventBasedFaceVerificationSessionRequest {
     /** Unique reference for the KYC session (e.g., customer ID or transaction ID) */
     reference: string;
     /** Customer ID to associate with the KYC session */
     customer_id: string;
     /**
-     * The triggering event. One of the `ReuseKycEvent` union members.
+     * The triggering event. One of the `EventBasedFaceVerificationEvent` union members.
      * Required — when empty, the server falls through to the unknown-event
      * passthrough and allows the request silently.
      */
-    event: ReuseKycEvent;
+    event: EventBasedFaceVerificationEvent;
     /**
      * USD amount associated with the event. Required for threshold-gated
      * events (`deposit`, `withdrawal`, `large_bet_placement`); ignored for
@@ -352,32 +371,54 @@ interface CreateReuseKycSessionRequest {
     event_window_minutes?: number;
     /** URL to redirect user after validate the facial submission (optional) */
     redirect_url?: string;
-    /** URL to receive callback notifications via POST request when reuse KYC status changes (optional) */
+    /** URL to receive callback notifications via POST request when Event-Based Face Verification status changes (optional) */
     callback_url?: string;
 }
-interface SubmitReuseKycSessionRequest {
-    /** Reuse KYC session token generated from createReuseKycSession */
+interface SubmitEventBasedFaceVerificationSessionRequest {
+    /** Event-Based Face Verification session token generated from createEventBasedFaceVerificationSession */
     token: string;
     /** Base64 encoded face image or selfie for verification */
     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 ReuseKycDeviceType = 'mobile' | 'desktop';
-interface CreateReuseKycSessionResponse {
-    /** Reuse KYC session reference (echo of the request reference) */
+type EventBasedFaceVerificationDeviceType = 'mobile' | 'desktop';
+interface CreateEventBasedFaceVerificationSessionResponse {
+    /** Event-Based Face Verification session reference (echo of the request reference) */
     reference: string;
-    /** Generated reuse KYC session token, valid 10 minutes */
+    /** Generated Event-Based Face Verification session token, valid 10 minutes */
     token: string;
     /**
-     * Empty string when Re-Use KYC is required. When `is_required` is
+     * Empty string when Event-Based Face Verification is required. When `is_required` is
      * false, this contains the human-readable reason (e.g. feature
      * disabled, threshold not met, customer has no prior KYC).
      */
@@ -406,7 +447,7 @@ interface CreateReuseKycSessionResponse {
  * or freeze the account. Reaction flags are only populated when
  * `retry_limit_exceeded` is true.
  */
-interface ReuseKycReactionResult {
+interface EventBasedFaceVerificationReactionResult {
     /** Submissions the customer still has before the retry limit fires. */
     retries_remaining: number;
     /** True once the latest failed attempt exhausts the retry policy. */
@@ -414,27 +455,37 @@ interface ReuseKycReactionResult {
     trigger_alert: boolean;
     enforce_logout: boolean;
     freeze_account: boolean;
+    /** Tenant app should block the action/account when true. */
+    block: boolean;
     freeze_duration_minutes: number;
     /** Set when an alert was raised on the dashboard. */
     alert_id?: string;
 }
 /**
- * Shape of the webhook body POSTed to `callback_url` after a Re-Use KYC
+ * Shape of the webhook body POSTed to `callback_url` after a Event-Based Face Verification
  * submission completes (also returned synchronously from
- * `submitReuseKycSession`).
+ * `submitEventBasedFaceVerificationSession`).
  */
-interface ReuseKycCallback {
+interface EventBasedFaceVerificationCallback {
     event: 'reuse_kyc';
     reference: string;
     resource_id: string;
     status: KycStatus;
+    /**
+     * True when the tenant app should block the action/account. Mirrors the
+     * `block` reaction on {@link data} at the top level of the callback so
+     * consumers can branch without inspecting `data`. Omitted when false.
+     */
+    block?: boolean;
+    /** Names the event/verification that triggered the block. Omitted when not blocked. */
+    block_reason?: string;
     /** Structured decline reasons. */
     declined_reasons?: Reason[];
     /** @deprecated Use {@link declined_reasons}. */
     declined_reason?: string;
     /** @deprecated Use structured reasons. */
     warnings?: Record<string, Record<string, string>>;
-    data: ReuseKycReactionResult;
+    data: EventBasedFaceVerificationReactionResult;
 }
 /**
  * Server-side handoff session backed by Redis (TTL: 15 minutes). Shared
@@ -450,7 +501,7 @@ interface KycHandoffSession {
     face: string;
     /** True after a mobile device hits PUT /api/v1/kyc/session/connect. */
     mobile_connected: boolean;
-    /** True after the (normal-KYC) document submission completes; unused for Re-Use KYC. */
+    /** True after the (normal-KYC) document submission completes; unused for Event-Based Face Verification. */
     is_submitted: boolean;
 }
 interface CheckKycStatusRequest {
@@ -671,7 +722,7 @@ declare class KycClient extends BaseClient {
      */
     requestKycSubmitLink(request: RequestKycSubmitLinkRequest): Promise<RequestKycSubmitLinkResponse>;
     /**
-     * Create a Re-Use KYC session.
+     * Create a Event-Based Face Verification session.
      *
      * Inspect the response before showing UI:
      * - `is_required === false` → skip face capture; `reason` explains why.
@@ -681,35 +732,39 @@ declare class KycClient extends BaseClient {
      *
      * @param request - Reference, customer_id, event, amount (for threshold events), optional URLs.
      */
-    createReuseKycSession(request: CreateReuseKycSessionRequest): Promise<CreateReuseKycSessionResponse>;
+    createEventBasedFaceVerificationSession(request: CreateEventBasedFaceVerificationSessionRequest): Promise<CreateEventBasedFaceVerificationSessionResponse>;
     /**
-     * Submit a real-time face capture for an active Re-Use KYC session.
+     * 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 `createReuseKycSession` for desktop callers.
+     * QR handoff from `createEventBasedFaceVerificationSession` for desktop callers.
      *
      * 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 `createReuseKycSession`, plus the base64 selfie.
+     * @param request - Token from `createEventBasedFaceVerificationSession`, plus the base64 selfie.
      */
-    submitReuseKycSession(request: SubmitReuseKycSessionRequest): Promise<ReuseKycCallback>;
+    submitEventBasedFaceVerificationSession(request: SubmitEventBasedFaceVerificationSessionRequest): Promise<EventBasedFaceVerificationCallback>;
     /**
-     * Look up the current state of a Re-Use KYC session by its forward
-     * reference. Useful for desktop pollers waiting on the mobile handoff.
+     * 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 reference - The reference used when the session was created.
+     * @param token - The session token returned by `createEventBasedFaceVerificationSession`.
      */
-    getReuseKycSessionStatus(reference: string): Promise<ReuseKycCallback>;
+    getEventBasedFaceVerificationSessionStatus(token: string): Promise<EventBasedFaceVerificationCallback>;
     /**
      * 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 `createReuseKycSession`.
+     * @param token - The session token returned by `createEventBasedFaceVerificationSession`.
      */
     getHandoffSession(token: string): Promise<KycHandoffSession>;
     /**
@@ -763,7 +818,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: {
@@ -789,7 +844,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}`);
      * ```
      */
@@ -842,7 +897,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"
      * });
@@ -857,7 +912,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})`);
      * });
@@ -1043,4 +1098,4 @@ declare class KycClient extends BaseClient {
     createCustomerProfile(profile: CreateProfileRequest): Promise<CustomerProfile>;
 }
 
-export { type CheckKycStatusRequest, type CheckKycStatusResponse, CreateProfileRequest as CreateCustomerProfileRequest, type CreateReuseKycSessionRequest, type CreateReuseKycSessionResponse, CustomerProfile, ProfileFilters as CustomerProfileFilters, ProfileListResponse as CustomerProfileListResponse, type DocumentType, type DocumentVerificationRequest, type DocumentVerificationResponse, 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, type ReuseKycCallback, type ReuseKycDeviceType, type ReuseKycEvent, type ReuseKycFrequencyTrigger, type ReuseKycReactionResult, type ReuseKycReactions, type ReuseKycThresholdTrigger, type ReuseKycTriggers, RiskLevel, type SubmitReuseKycSessionRequest, 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 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 };