vesant-sdk 1.8.0-dev.31d63f0 → 1.8.0-dev.32e3a40

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-BOFaMQxI.mjs';
+import { P as ProfileFilters, b as ProfileListResponse, C as CustomerProfile, a as CreateProfileRequest } from '../types-DfbnIaW_.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';
 
@@ -119,14 +119,22 @@ 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;
+    /** Not sent by the platform; the link itself is short-lived. */
+    expires_at?: string;
 }
 interface KycCustomerProfile {
     id: string;
@@ -243,6 +251,17 @@ interface EventBasedFaceVerificationReactions {
     /** @deprecated Never populated; read `data.freeze_duration_minutes` on the callback instead. */
     freeze_duration_minutes?: number;
 }
+/**
+ * On Account Sensitive Action: hold a change to the customer's name, date of
+ * birth or residential address behind a full KYC verification. Configured in
+ * the Vesant console; off by default. See {@link ProfileUpdateHeldResponse}.
+ */
+interface AccountSensitiveActionTrigger {
+    enabled: boolean;
+    full_name: boolean;
+    date_of_birth: boolean;
+    residential_address: boolean;
+}
 /** Per-event toggles that decide when a submit-link request requires KYC. */
 interface KycVerificationTriggers {
     onboarding: boolean;
@@ -250,6 +269,18 @@ 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;
 }
 interface KycSkipOptions {
     /** Let a `manual` trigger be skipped (`can_skip` on the submit-link response). */
@@ -417,8 +448,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. */
@@ -429,7 +461,16 @@ type KycTriggerEvent = 'onboarding' | 'first_withdrawal' | 'first_purchase'
  * (asked, skippable — "Remind me later"), or verified with a valid document
  * (not asked). One call covers every customer.
  */
- | 'login';
+ | 'login'
+/**
+ * The customer changed their name, date of birth or address and
+ * `updateProfile` answered `202` with `kyc_required: true`. Required — not
+ * skippable — while Vesant holds a pending change for the customer; not
+ * required when nothing is held or the tenant switched the trigger off.
+ * The verification is seeded with the requested identity and, on approval,
+ * releases the held change. See the `profile_change` webhook.
+ */
+ | 'profile_change';
 /**
  * Why verification is — or is not — being asked for. Codes are stable;
  * `message` is display-ready text you can show the customer as-is.
@@ -453,10 +494,14 @@ type KycRequestReasonCode =
  | 'KYC_REQUIRED_ID_EXPIRED'
 /** Verification was explicitly requested by the tenant. */
  | 'KYC_REQUIRED_MANUAL'
+/** Required before a held name / date of birth / address change is applied. */
+ | 'KYC_REQUIRED_PROFILE_CHANGE'
 /** 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';
+ | 'KYC_NOT_REQUIRED_TRIGGER_DISABLED'
+/** Not required — `profile_change` was sent but Vesant holds no pending change for the customer. */
+ | 'KYC_NOT_REQUIRED_NO_PENDING_CHANGE';
 interface RequestKycSubmitLinkRequest {
     /** User ID to generate KYC submission link for */
     user_id: string;
@@ -467,8 +512,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
@@ -593,7 +642,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.
      */
@@ -641,6 +691,79 @@ interface KycDocumentExpiredCallbackEvent {
  * signature-verified, parsed payload to {@link KycDocumentExpiredCallbackEvent}.
  */
 declare function isKycDocumentExpiredCallbackEvent(value: unknown): value is KycDocumentExpiredCallbackEvent;
+/** Sensitive profile field held behind KYC by On Account Sensitive Action. */
+type ProfileChangeField = 'full_name' | 'date_of_birth' | 'residential_address';
+/** How a held profile change ended. */
+type ProfileChangeStatus = 'approved' | 'rejected' | 'expired';
+/**
+ * Reactions a verification fired, mirrored from the tenant's KYC alert
+ * configuration. Vesant holds no account state on your platform: these flags
+ * tell you what the tenant configured, they do not do it. Present on the
+ * `kyc` status callback only when a rule with reactions matched — today the
+ * On Account Sensitive Action rules.
+ */
+interface KycCallbackReactions {
+    /** The alert rules that fired, e.g. `["profile_change_name"]`. */
+    events: string[];
+    trigger_alert: boolean;
+    block: boolean;
+    freeze_account: boolean;
+    /** Set when `freeze_account` is true: the tenant's default freeze window. */
+    freeze_duration_minutes?: number;
+    enforce_logout: boolean;
+}
+/**
+ * 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
+ * raw body), like every other Vesant callback.
+ *
+ * Sent once per held change: `approved` after the customer's `profile_change`
+ * verification was accepted and the verified values were written to the
+ * profile; `rejected` after it was declined and the profile was left as it
+ * was; `expired` when no verification arrived within the hold window (seven
+ * days by default). On `rejected`, show the customer `declined_reasons` — this
+ * is the "KYC decline message" for the change.
+ */
+interface ProfileChangeCallbackEvent {
+    /** Always `"profile_change"` — dispatch on this. */
+    event: 'profile_change';
+    /** Your customer identifier (the `user_id` you supplied). */
+    reference: string;
+    /** The pending change id returned by `updateProfile`. */
+    resource_id: string;
+    status: ProfileChangeStatus;
+    /** First decline message, `rejected` only. */
+    declined_reason?: string;
+    /** Structured decline, `rejected` only. */
+    declined_reasons?: Reason[];
+    data: {
+        customer_id: string;
+        profile_id: string;
+        pending_change_id: string;
+        /** The verification that settled the change; empty if it expired unverified. */
+        kyc_id: string;
+        changed_fields: ProfileChangeField[];
+        /** What the customer asked for. */
+        requested_values: Partial<Record<ProfileChangeField, string>>;
+        /** What the profile held before the change. */
+        previous_values: Partial<Record<ProfileChangeField, string>>;
+        /**
+         * What the document verified, `approved` only. The verified values are
+         * what was written to the profile — when they differ from
+         * `requested_values` (`values_match: false`) the document wins and a
+         * review alert is raised in the Vesant console.
+         */
+        verified_values?: Partial<Record<ProfileChangeField, string>>;
+        values_match?: boolean | null;
+        expires_at: string;
+        resolved_at?: string | null;
+    };
+}
+/**
+ * Type guard for the held-profile-change webhook. Narrows an already
+ * signature-verified, parsed payload to {@link ProfileChangeCallbackEvent}.
+ */
+declare function isProfileChangeCallbackEvent(value: unknown): value is ProfileChangeCallbackEvent;
 /** Device class detected by the SDK (purely client-side — server doesn't care). */
 type EventBasedFaceVerificationDeviceType = 'mobile' | 'desktop';
 interface CreateEventBasedFaceVerificationSessionResponse {
@@ -1145,15 +1268,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>;
@@ -1172,6 +1300,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>;
     /**
@@ -1195,6 +1327,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>;
     /**
@@ -1219,14 +1355,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}`);
      * });
      * ```
      */
@@ -1247,6 +1387,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>;
     /**
@@ -1254,6 +1398,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>;
     /**
@@ -1275,6 +1423,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>;
     /**
@@ -1304,6 +1456,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>;
     /**
@@ -1317,6 +1473,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>;
     /**
@@ -1415,4 +1575,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 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 };
+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 };