vesant-sdk 1.8.0-dev.153299b → 1.8.0-dev.237d268

package/dist/kyc/index.d.mts

@@ -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;
@@ -261,6 +269,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 +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. */
@@ -493,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
@@ -619,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.
      */
@@ -1244,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
      *
-     * @param id - KYC request ID
-     * @returns KYC request details including proofs and alerts
+     * 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 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 +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>;
     /**
@@ -1294,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>;
     /**
@@ -1318,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}`);
      * });
      * ```
      */
@@ -1346,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>;
     /**
@@ -1353,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>;
     /**
@@ -1374,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>;
     /**
@@ -1403,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>;
     /**
@@ -1416,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>;
     /**

package/dist/kyc/index.d.ts

@@ -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;
@@ -261,6 +269,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 +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. */
@@ -493,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
@@ -619,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.
      */
@@ -1244,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
      *
-     * @param id - KYC request ID
-     * @returns KYC request details including proofs and alerts
+     * 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 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 +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>;
     /**
@@ -1294,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>;
     /**
@@ -1318,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}`);
      * });
      * ```
      */
@@ -1346,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>;
     /**
@@ -1353,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>;
     /**
@@ -1374,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>;
     /**
@@ -1403,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>;
     /**
@@ -1416,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>;
     /**

package/dist/kyc/index.js

@@ -892,19 +892,26 @@ var KycClient = class extends BaseClient {
     }, void 0, requestOptions);
   }
   /**
-   * Get a KYC request by ID
+   * Get a KYC record by ID
    *
-   * @param id - KYC request ID
-   * @returns KYC request details including proofs and alerts
+   * 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 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}`));
    * ```
    */
   async getKycRequest(id) {
-    return this.request(`/api/v1/kyc/requests/${id}`);
+    return this.request(`/api/v1/kyc/${encodeURIComponent(id)}`, {
+      headers: this.getUserHeaders()
+    });
   }
   /**
    * List KYC requests with filters and pagination
@@ -921,6 +928,10 @@ var KycClient = class 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.
    */
   async listKycRequests(filters, pagination) {
     const params = {};
@@ -958,6 +969,10 @@ var KycClient = class 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.
    */
   async updateKycStatus(request) {
     await this.request("/api/v1/kyc/status", {
@@ -994,22 +1009,24 @@ var KycClient = class 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}`);
    * });
    * ```
    */
   async getProofDownloadURLs(kycId) {
-    return this.request(
-      `/api/v1/kyc/proofs/${kycId}`,
-      { headers: this.getUserHeaders() }
-    );
+    const kyc = await this.getKycRequest(kycId);
+    return (kyc.proofs ?? []).filter((proof) => typeof proof.link === "string" && proof.link !== "").map((proof) => ({ id: proof.id, type: proof.type, url: proof.link }));
   }
   // ============================================================================
   // KYC Overview & Statistics
@@ -1030,6 +1047,10 @@ var KycClient = class 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.
    */
   async getOverview(fromDate, toDate) {
     const params = {};
@@ -1047,6 +1068,10 @@ var KycClient = class 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.
    */
   async getAlert(alertId) {
     return this.request(`/api/v1/kyc/alerts/${alertId}`);
@@ -1070,6 +1095,10 @@ var KycClient = class 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.
    */
   async listAlerts(filters, pagination) {
     const params = {};
@@ -1116,6 +1145,10 @@ var KycClient = class 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.
    */
   async updateAlert(alertId, update) {
     await this.request(`/api/v1/kyc/alerts/${alertId}`, {
@@ -1138,6 +1171,10 @@ var KycClient = class 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.
    */
   async getPreferences() {
     return this.request("/api/v1/kyc/preferences");