vesant-sdk 1.7.1-dev.301c6df → 1.7.1-dev.328baf7

package/dist/kyc/index.d.mts

@@ -11,7 +11,11 @@ import { B as BaseClient, R as RequestOptions } from '../client-q9fN8Hhf.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';
@@ -311,6 +315,48 @@ interface UpdateKycStatusRequest {
     /** Shufti warnings data */
     warnings?: Record<string, Record<string, string>>;
 }
+/**
+ * Events that can trigger a KYC request. Each maps to a per-event toggle in
+ * the tenant's KYC verification trigger preferences, except `manual` (always
+ * required) and `login` (only for an expired identity document).
+ */
+type KycTriggerEvent = 'onboarding' | 'first_withdrawal' | 'first_purchase'
+/** Aliases of `first_withdrawal` / `first_purchase` — same tenant toggles. */
+ | 'withdrawal' | 'purchase' | 'manual'
+/**
+ * The customer is signing in. Answers for any state: never verified (asked,
+ * not skippable, per the tenant's onboarding policy), document expired
+ * (asked, skippable — "Remind me later"), or verified with a valid document
+ * (not asked). One call covers every customer.
+ */
+ | 'login';
+/**
+ * Why verification is — or is not — being asked for. Codes are stable;
+ * `message` is display-ready text you can show the customer as-is.
+ */
+interface KycRequestReason {
+    code: KycRequestReasonCode | (string & Record<string, never>);
+    message: string;
+}
+/**
+ * Reason codes returned by `requestKycSubmitLink`. Treat unrecognised codes
+ * as "verification required" and fall back to `message` for display.
+ */
+type KycRequestReasonCode = 
+/** Required to complete registration. */
+'KYC_REQUIRED_ONBOARDING'
+/** Required before the customer's first withdrawal. */
+ | 'KYC_REQUIRED_FIRST_WITHDRAWAL'
+/** Required before the customer's first purchase. */
+ | 'KYC_REQUIRED_FIRST_PURCHASE'
+/** The customer's identity document has expired and must be re-verified. */
+ | 'KYC_REQUIRED_ID_EXPIRED'
+/** Verification was explicitly requested by the tenant. */
+ | 'KYC_REQUIRED_MANUAL'
+/** Not required — the customer already has an accepted verification. */
+ | 'KYC_NOT_REQUIRED_ALREADY_VERIFIED'
+/** Not required — the tenant has this trigger event switched off. */
+ | 'KYC_NOT_REQUIRED_TRIGGER_DISABLED';
 interface RequestKycSubmitLinkRequest {
     /** User ID to generate KYC submission link for */
     user_id: string;
@@ -319,14 +365,20 @@ interface RequestKycSubmitLinkRequest {
     /** URL to receive callback notifications via POST request when KYC status changes (optional) */
     callback_url?: string;
     /**
-     * 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`).
+     * Event that triggered the KYC request. 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`). "login"
+     * answers for any customer state — never verified (asked, not skippable),
+     * document expired (asked, skippable so you can offer "Remind me later"),
+     * or verified and valid (not asked) — so a platform that gates entry on KYC
+     * needs only this one call at sign-in. The same expired document is *not*
+     * skippable on withdrawal / purchase events: it is enforced on
+     * "first_withdrawal", "withdrawal", "first_purchase" and "purchase" alike,
+     * so keep sending whichever of those you already send.
      * Omitted or unknown values default to KYC required with no skip.
      */
-    trigger_event?: string;
+    trigger_event?: KycTriggerEvent | (string & Record<string, never>);
     /**
      * Registered customer identity data (optional). Seeds the customer's risk
      * profile so document verification can cross-check the submitted document
@@ -438,12 +490,57 @@ interface RequestKycSubmitLinkResponse {
      */
     kyc_required: boolean;
     /**
-     * Whether the user may skip verification. Only `true` for
+     * Whether the user may skip verification. `true` for
      * `trigger_event: "manual"` when the tenant enables allow-skip-on-manual,
-     * or when the customer is already verified.
+     * for `"login"` when an expired identity document triggered the request
+     * (offer "Remind me later"), and when the customer is already verified.
+     * Always `false` at `"withdrawal"` / `"purchase"` — that is where a
+     * postponed re-verification becomes mandatory.
      */
     can_skip: boolean;
+    /**
+     * Why verification is — or is not — being asked for. Use `reason.code` to
+     * branch (for example `KYC_REQUIRED_ID_EXPIRED` warrants a different prompt
+     * than a first-time verification) and `reason.message` for display.
+     */
+    reason?: KycRequestReason;
+}
+/**
+ * Body POSTed to your `callback_url` when a customer's identity document
+ * passes its expiry date. Signed with `X-Webhook-Signature: sha256=<hex>`
+ * (HMAC-SHA256 of the raw body), like every other Vesant callback.
+ *
+ * An expiry happens on a **date**, not on a customer action, so this webhook
+ * is the only signal for it — nothing the customer does triggers it. Delivered
+ * once per customer, when the document first becomes expired.
+ *
+ * It is sent regardless of the tenant's auto-trigger-on-ID-expiration setting:
+ * that setting governs whether verification is *enforced*, not whether you are
+ * *told*.
+ */
+interface KycDocumentExpiredCallbackEvent {
+    /** Always `"kyc_document_expired"` — dispatch on this. */
+    event: 'kyc_document_expired';
+    /** Your customer identifier (the `user_id` you supplied). */
+    reference: string;
+    /** The customer's risk-profile ID. */
+    resource_id: string;
+    /**
+     * Always `"expired"`. Describes the document — not the customer's KYC
+     * status, which remains `accepted` until they re-verify.
+     */
+    status: 'expired';
+    data: {
+        customer_id: string;
+        /** The document's expiry date (ISO 8601 `YYYY-MM-DD`). */
+        id_expiry_date: string;
+    };
 }
+/**
+ * Type guard for the identity-document expiry webhook. Narrows an already
+ * signature-verified, parsed payload to {@link KycDocumentExpiredCallbackEvent}.
+ */
+declare function isKycDocumentExpiredCallbackEvent(value: unknown): value is KycDocumentExpiredCallbackEvent;
 /** Device class detected by the SDK (purely client-side — server doesn't care). */
 type EventBasedFaceVerificationDeviceType = 'mobile' | 'desktop';
 interface CreateEventBasedFaceVerificationSessionResponse {
@@ -474,6 +571,13 @@ interface CreateEventBasedFaceVerificationSessionResponse {
      * (`reuse_kyc_reactions.max_retry_attempts + 1`).
      */
     max_attempts: number;
+    /**
+     * Hosted verification journey URL. When present, the capture runs on a
+     * hosted page (embedded by `FaceCaptureModal` in an iframe) instead of the
+     * SDK's local camera; the verdict is read via the session status poll.
+     * Absent when the platform runs the local-capture flow.
+     */
+    verification_url?: string;
 }
 /**
  * Reaction outcome returned on every face-submit callback. Tenant apps
@@ -522,9 +626,10 @@ interface EventBasedFaceVerificationCallback {
     data: EventBasedFaceVerificationReactionResult;
 }
 /**
- * Server-side handoff session backed by Redis (TTL: 15 minutes). Shared
- * with the normal KYC mobile/desktop handoff. Desktop clients poll this
- * to detect when a mobile device has attached to the same token via QR.
+ * Server-side handoff state backed by the normal KYC Redis store (15-minute
+ * cache TTL). Event-Based Face Verification remains valid for 10 minutes;
+ * this cache does not extend that session. Desktop clients poll it to detect
+ * when a mobile device has attached to the same token via QR.
  */
 interface KycHandoffSession {
     document: string;
@@ -539,17 +644,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 +688,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 */
@@ -773,10 +887,9 @@ declare class KycClient extends BaseClient {
      * Create a Event-Based Face Verification session.
      *
      * Inspect the response before showing UI:
-     * - `is_required === false` → skip face capture; `reason` explains why.
-     * - `device_type === 'desktop'` → render `qr_payload` as a QR; the
-     *   mobile device picks up the session via the connect endpoint.
-     * - `device_type === 'mobile'` → open the face capture modal directly.
+     * - `is_required === false` → skip face verification; `reason` explains why.
+     * - `verification_url` present → embed the hosted journey and poll status.
+     * - `verification_url` absent → use the local camera / QR fallback.
      *
      * @param request - Reference, customer_id, event, amount (for threshold events), optional URLs.
      */
@@ -806,11 +919,22 @@ declare class KycClient extends BaseClient {
      * @param token - The session token returned by `createEventBasedFaceVerificationSession`.
      */
     getEventBasedFaceVerificationSessionStatus(token: string): Promise<EventBasedFaceVerificationCallback>;
+    /**
+     * Mint a fresh hosted verification journey for the next attempt on an
+     * active session whose previous hosted-journey attempt was declined.
+     * Only valid while the session is active and attempts remain; the
+     * response carries the new `verification_url` to embed. Used internally
+     * by `FaceCaptureModal`'s Try Again flow in hosted-journey mode.
+     *
+     * @param token - The session token returned by `createEventBasedFaceVerificationSession`.
+     */
+    retryEventBasedFaceVerificationJourney(token: string): Promise<CreateEventBasedFaceVerificationSessionResponse>;
     /**
      * Fetch the Redis-backed handoff session for a token. Same backing
-     * store as normal KYC (`kyc:session:<token>`, 15-minute TTL). Desktop
-     * callers poll `mobile_connected` to detect when a mobile device has
-     * scanned the QR and attached.
+     * store as normal KYC (`kyc:session:<token>`, 15-minute TTL). The
+     * Event-Based Face Verification database session still expires after
+     * 10 minutes. Desktop callers poll `mobile_connected` to detect when a
+     * mobile device has scanned the QR and attached.
      *
      * @param token - The session token returned by `createEventBasedFaceVerificationSession`.
      */
@@ -1146,4 +1270,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 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 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 };

package/dist/kyc/index.d.ts

@@ -11,7 +11,11 @@ import { B as BaseClient, R as RequestOptions } from '../client-q9fN8Hhf.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';
@@ -311,6 +315,48 @@ interface UpdateKycStatusRequest {
     /** Shufti warnings data */
     warnings?: Record<string, Record<string, string>>;
 }
+/**
+ * Events that can trigger a KYC request. Each maps to a per-event toggle in
+ * the tenant's KYC verification trigger preferences, except `manual` (always
+ * required) and `login` (only for an expired identity document).
+ */
+type KycTriggerEvent = 'onboarding' | 'first_withdrawal' | 'first_purchase'
+/** Aliases of `first_withdrawal` / `first_purchase` — same tenant toggles. */
+ | 'withdrawal' | 'purchase' | 'manual'
+/**
+ * The customer is signing in. Answers for any state: never verified (asked,
+ * not skippable, per the tenant's onboarding policy), document expired
+ * (asked, skippable — "Remind me later"), or verified with a valid document
+ * (not asked). One call covers every customer.
+ */
+ | 'login';
+/**
+ * Why verification is — or is not — being asked for. Codes are stable;
+ * `message` is display-ready text you can show the customer as-is.
+ */
+interface KycRequestReason {
+    code: KycRequestReasonCode | (string & Record<string, never>);
+    message: string;
+}
+/**
+ * Reason codes returned by `requestKycSubmitLink`. Treat unrecognised codes
+ * as "verification required" and fall back to `message` for display.
+ */
+type KycRequestReasonCode = 
+/** Required to complete registration. */
+'KYC_REQUIRED_ONBOARDING'
+/** Required before the customer's first withdrawal. */
+ | 'KYC_REQUIRED_FIRST_WITHDRAWAL'
+/** Required before the customer's first purchase. */
+ | 'KYC_REQUIRED_FIRST_PURCHASE'
+/** The customer's identity document has expired and must be re-verified. */
+ | 'KYC_REQUIRED_ID_EXPIRED'
+/** Verification was explicitly requested by the tenant. */
+ | 'KYC_REQUIRED_MANUAL'
+/** Not required — the customer already has an accepted verification. */
+ | 'KYC_NOT_REQUIRED_ALREADY_VERIFIED'
+/** Not required — the tenant has this trigger event switched off. */
+ | 'KYC_NOT_REQUIRED_TRIGGER_DISABLED';
 interface RequestKycSubmitLinkRequest {
     /** User ID to generate KYC submission link for */
     user_id: string;
@@ -319,14 +365,20 @@ interface RequestKycSubmitLinkRequest {
     /** URL to receive callback notifications via POST request when KYC status changes (optional) */
     callback_url?: string;
     /**
-     * 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`).
+     * Event that triggered the KYC request. 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`). "login"
+     * answers for any customer state — never verified (asked, not skippable),
+     * document expired (asked, skippable so you can offer "Remind me later"),
+     * or verified and valid (not asked) — so a platform that gates entry on KYC
+     * needs only this one call at sign-in. The same expired document is *not*
+     * skippable on withdrawal / purchase events: it is enforced on
+     * "first_withdrawal", "withdrawal", "first_purchase" and "purchase" alike,
+     * so keep sending whichever of those you already send.
      * Omitted or unknown values default to KYC required with no skip.
      */
-    trigger_event?: string;
+    trigger_event?: KycTriggerEvent | (string & Record<string, never>);
     /**
      * Registered customer identity data (optional). Seeds the customer's risk
      * profile so document verification can cross-check the submitted document
@@ -438,12 +490,57 @@ interface RequestKycSubmitLinkResponse {
      */
     kyc_required: boolean;
     /**
-     * Whether the user may skip verification. Only `true` for
+     * Whether the user may skip verification. `true` for
      * `trigger_event: "manual"` when the tenant enables allow-skip-on-manual,
-     * or when the customer is already verified.
+     * for `"login"` when an expired identity document triggered the request
+     * (offer "Remind me later"), and when the customer is already verified.
+     * Always `false` at `"withdrawal"` / `"purchase"` — that is where a
+     * postponed re-verification becomes mandatory.
      */
     can_skip: boolean;
+    /**
+     * Why verification is — or is not — being asked for. Use `reason.code` to
+     * branch (for example `KYC_REQUIRED_ID_EXPIRED` warrants a different prompt
+     * than a first-time verification) and `reason.message` for display.
+     */
+    reason?: KycRequestReason;
+}
+/**
+ * Body POSTed to your `callback_url` when a customer's identity document
+ * passes its expiry date. Signed with `X-Webhook-Signature: sha256=<hex>`
+ * (HMAC-SHA256 of the raw body), like every other Vesant callback.
+ *
+ * An expiry happens on a **date**, not on a customer action, so this webhook
+ * is the only signal for it — nothing the customer does triggers it. Delivered
+ * once per customer, when the document first becomes expired.
+ *
+ * It is sent regardless of the tenant's auto-trigger-on-ID-expiration setting:
+ * that setting governs whether verification is *enforced*, not whether you are
+ * *told*.
+ */
+interface KycDocumentExpiredCallbackEvent {
+    /** Always `"kyc_document_expired"` — dispatch on this. */
+    event: 'kyc_document_expired';
+    /** Your customer identifier (the `user_id` you supplied). */
+    reference: string;
+    /** The customer's risk-profile ID. */
+    resource_id: string;
+    /**
+     * Always `"expired"`. Describes the document — not the customer's KYC
+     * status, which remains `accepted` until they re-verify.
+     */
+    status: 'expired';
+    data: {
+        customer_id: string;
+        /** The document's expiry date (ISO 8601 `YYYY-MM-DD`). */
+        id_expiry_date: string;
+    };
 }
+/**
+ * Type guard for the identity-document expiry webhook. Narrows an already
+ * signature-verified, parsed payload to {@link KycDocumentExpiredCallbackEvent}.
+ */
+declare function isKycDocumentExpiredCallbackEvent(value: unknown): value is KycDocumentExpiredCallbackEvent;
 /** Device class detected by the SDK (purely client-side — server doesn't care). */
 type EventBasedFaceVerificationDeviceType = 'mobile' | 'desktop';
 interface CreateEventBasedFaceVerificationSessionResponse {
@@ -474,6 +571,13 @@ interface CreateEventBasedFaceVerificationSessionResponse {
      * (`reuse_kyc_reactions.max_retry_attempts + 1`).
      */
     max_attempts: number;
+    /**
+     * Hosted verification journey URL. When present, the capture runs on a
+     * hosted page (embedded by `FaceCaptureModal` in an iframe) instead of the
+     * SDK's local camera; the verdict is read via the session status poll.
+     * Absent when the platform runs the local-capture flow.
+     */
+    verification_url?: string;
 }
 /**
  * Reaction outcome returned on every face-submit callback. Tenant apps
@@ -522,9 +626,10 @@ interface EventBasedFaceVerificationCallback {
     data: EventBasedFaceVerificationReactionResult;
 }
 /**
- * Server-side handoff session backed by Redis (TTL: 15 minutes). Shared
- * with the normal KYC mobile/desktop handoff. Desktop clients poll this
- * to detect when a mobile device has attached to the same token via QR.
+ * Server-side handoff state backed by the normal KYC Redis store (15-minute
+ * cache TTL). Event-Based Face Verification remains valid for 10 minutes;
+ * this cache does not extend that session. Desktop clients poll it to detect
+ * when a mobile device has attached to the same token via QR.
  */
 interface KycHandoffSession {
     document: string;
@@ -539,17 +644,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 +688,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 */
@@ -773,10 +887,9 @@ declare class KycClient extends BaseClient {
      * Create a Event-Based Face Verification session.
      *
      * Inspect the response before showing UI:
-     * - `is_required === false` → skip face capture; `reason` explains why.
-     * - `device_type === 'desktop'` → render `qr_payload` as a QR; the
-     *   mobile device picks up the session via the connect endpoint.
-     * - `device_type === 'mobile'` → open the face capture modal directly.
+     * - `is_required === false` → skip face verification; `reason` explains why.
+     * - `verification_url` present → embed the hosted journey and poll status.
+     * - `verification_url` absent → use the local camera / QR fallback.
      *
      * @param request - Reference, customer_id, event, amount (for threshold events), optional URLs.
      */
@@ -806,11 +919,22 @@ declare class KycClient extends BaseClient {
      * @param token - The session token returned by `createEventBasedFaceVerificationSession`.
      */
     getEventBasedFaceVerificationSessionStatus(token: string): Promise<EventBasedFaceVerificationCallback>;
+    /**
+     * Mint a fresh hosted verification journey for the next attempt on an
+     * active session whose previous hosted-journey attempt was declined.
+     * Only valid while the session is active and attempts remain; the
+     * response carries the new `verification_url` to embed. Used internally
+     * by `FaceCaptureModal`'s Try Again flow in hosted-journey mode.
+     *
+     * @param token - The session token returned by `createEventBasedFaceVerificationSession`.
+     */
+    retryEventBasedFaceVerificationJourney(token: string): Promise<CreateEventBasedFaceVerificationSessionResponse>;
     /**
      * Fetch the Redis-backed handoff session for a token. Same backing
-     * store as normal KYC (`kyc:session:<token>`, 15-minute TTL). Desktop
-     * callers poll `mobile_connected` to detect when a mobile device has
-     * scanned the QR and attached.
+     * store as normal KYC (`kyc:session:<token>`, 15-minute TTL). The
+     * Event-Based Face Verification database session still expires after
+     * 10 minutes. Desktop callers poll `mobile_connected` to detect when a
+     * mobile device has scanned the QR and attached.
      *
      * @param token - The session token returned by `createEventBasedFaceVerificationSession`.
      */
@@ -1146,4 +1270,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 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 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 };

package/dist/kyc/index.js

@@ -704,10 +704,9 @@ var KycClient = class extends BaseClient {
    * Create a Event-Based Face Verification session.
    *
    * Inspect the response before showing UI:
-   * - `is_required === false` → skip face capture; `reason` explains why.
-   * - `device_type === 'desktop'` → render `qr_payload` as a QR; the
-   *   mobile device picks up the session via the connect endpoint.
-   * - `device_type === 'mobile'` → open the face capture modal directly.
+   * - `is_required === false` → skip face verification; `reason` explains why.
+   * - `verification_url` present → embed the hosted journey and poll status.
+   * - `verification_url` absent → use the local camera / QR fallback.
    *
    * @param request - Reference, customer_id, event, amount (for threshold events), optional URLs.
    */
@@ -754,11 +753,28 @@ var KycClient = class extends BaseClient {
       headers: this.getUserHeaders()
     });
   }
+  /**
+   * Mint a fresh hosted verification journey for the next attempt on an
+   * active session whose previous hosted-journey attempt was declined.
+   * Only valid while the session is active and attempts remain; the
+   * response carries the new `verification_url` to embed. Used internally
+   * by `FaceCaptureModal`'s Try Again flow in hosted-journey mode.
+   *
+   * @param token - The session token returned by `createEventBasedFaceVerificationSession`.
+   */
+  async retryEventBasedFaceVerificationJourney(token) {
+    return this.request("/api/v1/kyc/face/onsite/journey", {
+      method: "POST",
+      body: JSON.stringify({ token }),
+      headers: this.getUserHeaders()
+    });
+  }
   /**
    * Fetch the Redis-backed handoff session for a token. Same backing
-   * store as normal KYC (`kyc:session:<token>`, 15-minute TTL). Desktop
-   * callers poll `mobile_connected` to detect when a mobile device has
-   * scanned the QR and attached.
+   * store as normal KYC (`kyc:session:<token>`, 15-minute TTL). The
+   * Event-Based Face Verification database session still expires after
+   * 10 minutes. Desktop callers poll `mobile_connected` to detect when a
+   * mobile device has scanned the QR and attached.
    *
    * @param token - The session token returned by `createEventBasedFaceVerificationSession`.
    */
@@ -1267,8 +1283,12 @@ var KYC_DECLINED_DESCRIPTIONS = {
   KYC_PROVIDER_REJECTED: "Identity verification was rejected by the verification provider",
   KYC_DECLINED: "Identity verification was declined"
 };
+function isKycDocumentExpiredCallbackEvent(value) {
+  return typeof value === "object" && value !== null && value.event === "kyc_document_expired";
+}
 
 exports.KYC_DECLINED_DESCRIPTIONS = KYC_DECLINED_DESCRIPTIONS;
 exports.KycClient = KycClient;
+exports.isKycDocumentExpiredCallbackEvent = isKycDocumentExpiredCallbackEvent;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map