vesant-sdk 1.8.0-dev.2445740 → 1.8.0-dev.2b393a5

package/dist/kyc/index.d.mts

@@ -1,4 +1,4 @@
-import { P as ProfileFilters, b as ProfileListResponse, C as CustomerProfile, a as CreateProfileRequest } from '../types-DfbnIaW_.mjs';
+import { C as CustomerProfile, P as ProfileFilters, b as ProfileListResponse, a as CreateProfileRequest } from '../types-DbvVph_0.mjs';
 import { c as Reason, R as RiskLevel, P as PaginationParams } from '../types-CBQRNL-l.mjs';
 import { B as BaseClient, R as RequestOptions } from '../client-q9fN8Hhf.mjs';
 
@@ -15,7 +15,7 @@ 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';
+ | 'pending' | 'accepted' | 'declined' | 'review.pending';
 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';
@@ -111,7 +111,8 @@ interface KycRequest {
     block_reason?: string;
     proofs?: Proof[];
     alerts?: KycAlert[];
-    risk_profile?: KycCustomerProfile;
+    /** The customer's risk profile (`risk_category`, `risk_score`, `kyc_status`, ...). */
+    risk_profile?: CustomerProfile;
     created_at: string;
     updated_at: string;
 }
@@ -119,30 +120,34 @@ interface Proof {
     id: string;
     kyc_id: string;
     type: ProofType;
-    document: string;
+    /** Storage key. The platform never returns it; use `link` to download. */
+    document?: string;
     document_number?: string;
+    /** Document type the customer selected (e.g. `passport`). */
+    selected_type?: string;
+    /** Short-lived download URL, attached on `getKycRequest`. */
+    link?: string;
     created_at: string;
 }
 interface ProofDownloadURL {
+    /** Proof ID on the KYC record. */
+    id: string;
     type: ProofType;
     url: string;
-    expires_at: string;
-}
-interface KycCustomerProfile {
-    id: string;
-    tenant_id: string;
-    customer_id: string;
-    first_name?: string;
-    last_name?: string;
-    email?: string;
-    risk_score: number;
-    risk_level: RiskLevel;
-    kyc_status?: string;
-    pep_status?: boolean;
-    sanctions_status?: boolean;
-    created_at: string;
-    updated_at: string;
+    /** Not sent by the platform; the link itself is short-lived. */
+    expires_at?: string;
 }
+/**
+ * The customer's risk profile as embedded on a KYC record
+ * (`additional_data.risk_profile`). The platform preloads the full
+ * `customer_profiles` row, so this is the same shape as
+ * {@link CustomerProfile}: read `risk_category` / `risk_score`, `kyc_status`,
+ * `is_pep`, `has_sanctions`. There is no `risk_level` field on the wire.
+ *
+ * @deprecated Use {@link CustomerProfile}; this alias is kept for existing
+ * imports and will be removed in a future major.
+ */
+type KycCustomerProfile = CustomerProfile;
 interface KycAlert {
     id: string;
     kyc_id: string;
@@ -261,6 +266,16 @@ interface KycVerificationTriggers {
     first_purchase: boolean;
     /** Re-trigger verification once the customer's identity document has expired. */
     auto_trigger_on_id_expiration: boolean;
+    /**
+     * Manual KYC Verification: whether customers may start a verification
+     * themselves (`trigger_event: "manual"`), independent of the event
+     * triggers and of their status. On by default. When on, a `manual`
+     * request always returns a link — an already verified customer included.
+     * When off, it answers `kyc_required: false` with reason
+     * `KYC_NOT_REQUIRED_TRIGGER_DISABLED`; hide your Verification option in
+     * that case.
+     */
+    manual: boolean;
     /** Hold sensitive profile changes (name, DOB, address) behind KYC. */
     account_sensitive_action?: AccountSensitiveActionTrigger;
 }
@@ -430,8 +445,9 @@ interface UpdateKycStatusRequest {
 }
 /**
  * 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).
+ * the tenant's KYC verification trigger preferences (`manual` to the Manual
+ * KYC Verification toggle), except `login` (only for an expired identity
+ * document).
  */
 type KycTriggerEvent = 'onboarding' | 'first_withdrawal' | 'first_purchase'
 /** Aliases of `first_withdrawal` / `first_purchase` — same tenant toggles. */
@@ -493,8 +509,12 @@ interface RequestKycSubmitLinkRequest {
     /**
      * 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"
+     * (`kyc_required` in the response). "manual" — the customer starting
+     * verification themselves — is governed by the tenant's Manual KYC
+     * Verification toggle (on by default): when on it always returns a link,
+     * even for an already verified customer, and honors the
+     * allow-skip-on-manual option (`can_skip`); when off it answers
+     * `kyc_required: false` with `KYC_NOT_REQUIRED_TRIGGER_DISABLED`. "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
@@ -619,7 +639,8 @@ interface RequestKycSubmitLinkResponse {
      * Whether the user may skip verification. `true` for
      * `trigger_event: "manual"` when the tenant enables allow-skip-on-manual,
      * for `"login"` when an expired identity document triggered the request
-     * (offer "Remind me later"), and when the customer is already verified.
+     * (offer "Remind me later"), and when the customer is already verified
+     * (except on `"manual"`, which always issues a link while enabled).
      * Always `false` at `"withdrawal"` / `"purchase"` — that is where a
      * postponed re-verification becomes mandatory.
      */
@@ -640,9 +661,9 @@ interface RequestKycSubmitLinkResponse {
  * 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*.
+ * It is sent only while the tenant's auto-trigger-on-ID-expiration setting is
+ * enabled; with the setting off the document is still flagged as expired, but
+ * no webhook is sent.
  */
 interface KycDocumentExpiredCallbackEvent {
     /** Always `"kyc_document_expired"` — dispatch on this. */
@@ -684,10 +705,49 @@ interface KycCallbackReactions {
     trigger_alert: boolean;
     block: boolean;
     freeze_account: boolean;
-    /** Set when `freeze_account` is true: the tenant's default freeze window. */
+    /** Set when `freeze_account` is true: the freeze window the tenant set for the rules that fired. */
     freeze_duration_minutes?: number;
     enforce_logout: boolean;
 }
+/**
+ * Body POSTed to your KYC `callback_url` whenever a document verification
+ * reaches an outcome (`accepted`, `declined`, `review.pending`). This is a flat
+ * callback, not a platform event envelope: there is no `event_type`, `id` or
+ * `timestamp`, so it cannot go through `WebhookHandler`. Verify it with
+ * `verifyWebhookSignature`, narrow it with {@link isKycStatusCallbackEvent},
+ * and deduplicate on `resource_id` + `status` yourself.
+ */
+interface KycStatusCallbackEvent {
+    /** Always `"kyc"` — dispatch on this. */
+    event: 'kyc';
+    /** The verification reference (your customer identifier). */
+    reference: string;
+    /** Vesant KYC record ID (`kyc_id`). */
+    resource_id: string;
+    /** Verification outcome. `awaiting_kyc` / `pending` are never sent. */
+    status: 'accepted' | 'declined' | 'review.pending';
+    /**
+     * `true` when your app should block the triggering action. Set when a
+     * failed verification matched a per-event alert rule with the `block`
+     * reaction. Sticky once set on the record. Omitted when `false`.
+     */
+    block?: boolean;
+    /** The event that triggered the block; omitted when not blocked. */
+    block_reason?: string;
+    /** Comma-joined decline text; the structured list is `data.declined_reasons`. */
+    declined_reason?: string;
+    /** @deprecated Legacy category → message map; use `data.warning_reasons`. */
+    warnings?: Record<string, Record<string, string>>;
+    /** Present only when a rule with reactions matched (On Account Sensitive Action). */
+    reactions?: KycCallbackReactions;
+    /** The full KYC record, with `risk_profile` and proof download links. */
+    data: KycRequest;
+}
+/**
+ * Type guard for the KYC status callback. Narrows an already
+ * signature-verified, parsed payload to {@link KycStatusCallbackEvent}.
+ */
+declare function isKycStatusCallbackEvent(value: unknown): value is KycStatusCallbackEvent;
 /**
  * Body POSTed to your `callback_url` when a held sensitive profile change is
  * settled. Signed with `X-Webhook-Signature: sha256=<hex>` (HMAC-SHA256 of the
@@ -795,7 +855,11 @@ interface EventBasedFaceVerificationReactionResult {
     /** Tenant app should block the action/account when true. */
     block: boolean;
     freeze_duration_minutes: number;
-    /** Set when an alert was raised on the dashboard. */
+    /**
+     * Reserved. The dashboard alert is raised after the submit response and
+     * the webhook have been built, so neither carries the alert id today;
+     * read it from `listAlerts()` / the console instead.
+     */
     alert_id?: string;
 }
 /**
@@ -809,12 +873,12 @@ interface EventBasedFaceVerificationCallback {
     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.
+     * Reserved and not populated on face verification callbacks: the block
+     * decision is `data.block`. Only the document-KYC `kyc` callback sets a
+     * top-level `block`.
      */
     block?: boolean;
-    /** Names the event/verification that triggered the block. Omitted when not blocked. */
+    /** Reserved and not populated; see `data.block`. */
     block_reason?: string;
     /**
      * Structured decline reasons. Returned by
@@ -1244,15 +1308,20 @@ declare class KycClient extends BaseClient {
      */
     submitVerification(request: DocumentVerificationRequest, requestOptions?: RequestOptions): Promise<DocumentVerificationResponse>;
     /**
-     * Get a KYC request by ID
+     * Get a KYC record by ID
+     *
+     * Works with your tenant API key. Each entry in `proofs` carries a
+     * short-lived `link` for downloading that document, and `reference` holds
+     * your own customer reference (the `forward_reference`).
      *
-     * @param id - KYC request ID
-     * @returns KYC request details including proofs and alerts
+     * @param id - KYC record ID (the `kyc_id` returned by `requestKycSubmitLink`)
+     * @returns KYC record including proofs (with download links) and alerts
      *
      * @example
      * ```typescript
      * const kyc = await client.getKycRequest("550e8400-e29b-41d4-a716-446655440000");
      * console.log(`Status: ${kyc.status}, ID Verified: ${kyc.id_verified}`);
+     * kyc.proofs?.forEach(proof => console.log(`${proof.type}: ${proof.link}`));
      * ```
      */
     getKycRequest(id: string): Promise<KycRequest>;
@@ -1271,6 +1340,10 @@ declare class KycClient extends BaseClient {
      * );
      * console.log(`Found ${requests.total} pending requests`);
      * ```
+     *
+     * @remarks Console session only. This endpoint accepts a Vesant console
+     * (dashboard login) token, not a tenant API key; called with an API key it
+     * fails with `AuthenticationError` or a permission error.
      */
     listKycRequests(filters?: KycRequestFilters, pagination?: PaginationParams): Promise<KycRequestListResponse>;
     /**
@@ -1294,6 +1367,10 @@ declare class KycClient extends BaseClient {
      *   reason: "Document expired"
      * });
      * ```
+     *
+     * @remarks Console session only. This endpoint accepts a Vesant console
+     * (dashboard login) token, not a tenant API key; called with an API key it
+     * fails with `AuthenticationError` or a permission error.
      */
     updateKycStatus(request: UpdateKycStatusRequest): Promise<void>;
     /**
@@ -1318,14 +1395,18 @@ declare class KycClient extends BaseClient {
     /**
      * Get downloadable URLs for KYC proofs/documents
      *
-     * @param kycId - KYC request ID
-     * @returns Array of proof download URLs with expiration
+     * Derived from the `proofs` of `getKycRequest`: the platform attaches a
+     * short-lived download link to every proof on the KYC record, so no
+     * separate endpoint is needed. Proofs without a link are omitted.
+     *
+     * @param kycId - KYC record ID
+     * @returns Array of proof download URLs
      *
      * @example
      * ```typescript
      * const proofs = await client.getProofDownloadURLs("550e8400-e29b-41d4-a716-446655440000");
      * proofs.forEach(proof => {
-     *   console.log(`${proof.type}: ${proof.url} (expires: ${proof.expires_at})`);
+     *   console.log(`${proof.type}: ${proof.url}`);
      * });
      * ```
      */
@@ -1346,6 +1427,10 @@ declare class KycClient extends BaseClient {
      * console.log(`Total: ${overview.total}, Pending: ${overview.pending}`);
      * console.log(`Approved: ${overview.approved}, Rejected: ${overview.rejected}`);
      * ```
+     *
+     * @remarks Console session only. This endpoint accepts a Vesant console
+     * (dashboard login) token, not a tenant API key; called with an API key it
+     * fails with `AuthenticationError` or a permission error.
      */
     getOverview(fromDate?: string, toDate?: string): Promise<KycOverview>;
     /**
@@ -1353,6 +1438,10 @@ declare class KycClient extends BaseClient {
      *
      * @param alertId - Alert ID
      * @returns Alert details
+     *
+     * @remarks Console session only. This endpoint accepts a Vesant console
+     * (dashboard login) token, not a tenant API key; called with an API key it
+     * fails with `AuthenticationError` or a permission error.
      */
     getAlert(alertId: string): Promise<KycAlert>;
     /**
@@ -1374,6 +1463,10 @@ declare class KycClient extends BaseClient {
      * );
      * console.log(`Found ${alerts.total} alerts`);
      * ```
+     *
+     * @remarks Console session only. This endpoint accepts a Vesant console
+     * (dashboard login) token, not a tenant API key; called with an API key it
+     * fails with `AuthenticationError` or a permission error.
      */
     listAlerts(filters?: KycAlertFilters, pagination?: PaginationParams): Promise<KycAlertListResponse>;
     /**
@@ -1403,6 +1496,10 @@ declare class KycClient extends BaseClient {
      *   reason: "Requires senior review - suspicious documents"
      * });
      * ```
+     *
+     * @remarks Console session only. This endpoint accepts a Vesant console
+     * (dashboard login) token, not a tenant API key; called with an API key it
+     * fails with `AuthenticationError` or a permission error.
      */
     updateAlert(alertId: string, update: UpdateKycAlertRequest): Promise<void>;
     /**
@@ -1416,6 +1513,10 @@ declare class KycClient extends BaseClient {
      * console.log(`Face verification required: ${prefs.is_face_verification_required}`);
      * console.log(`Required documents: ${prefs.required_document_count}`);
      * ```
+     *
+     * @remarks Console session only. This endpoint accepts a Vesant console
+     * (dashboard login) token, not a tenant API key; called with an API key it
+     * fails with `AuthenticationError` or a permission error.
      */
     getPreferences(): Promise<KycPreferences>;
     /**
@@ -1514,4 +1615,4 @@ declare class KycClient extends BaseClient {
     createCustomerProfile(profile: CreateProfileRequest): Promise<CustomerProfile>;
 }
 
-export { type AccountSensitiveActionTrigger, 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, type KycCallbackReactions, 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 ProfileChangeCallbackEvent, type ProfileChangeField, type ProfileChangeStatus, 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, isProfileChangeCallbackEvent };
+export { type AccountSensitiveActionTrigger, 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, type KycCallbackReactions, 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 KycStatusCallbackEvent, type KycTriggerEvent, type KycVerificationTriggers, type Name, PaginationParams, type ProfileChangeCallbackEvent, type ProfileChangeField, type ProfileChangeStatus, 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, isKycStatusCallbackEvent, isProfileChangeCallbackEvent };