vesant-sdk 1.7.2 → 1.8.0-dev.00f6233

package/dist/index.js

@@ -298,7 +298,7 @@ var noopLogger = {
 };
 
 // src/core/version.ts
-var SDK_VERSION = "1.7.2";
+var SDK_VERSION = "1.8.0";
 
 // src/shared/browser-utils.ts
 function generateUUID() {
@@ -633,19 +633,20 @@ var BaseClient = class {
    * Handle error responses from API
    */
   handleErrorResponse(status, data, requestId) {
-    const message = data.error || data.message || `HTTP ${status}`;
+    const structured = data.error && typeof data.error === "object" && !Array.isArray(data.error) ? data.error : void 0;
+    const message = typeof data.error === "string" && data.error || typeof structured?.message === "string" && structured.message || typeof data.message === "string" && data.message || `HTTP ${status}`;
     const createError = () => {
       switch (status) {
         case 400:
-          return new VesantError(message, "BAD_REQUEST", 400);
+          return new VesantError(message, "BAD_REQUEST", 400, structured);
         case 401:
           return new AuthenticationError(message);
         case 403:
-          return new VesantError(message, "FORBIDDEN", 403);
+          return new VesantError(message, "FORBIDDEN", 403, structured);
         case 404:
-          return new VesantError(message, "NOT_FOUND", 404);
+          return new VesantError(message, "NOT_FOUND", 404, structured);
         case 409:
-          return new VesantError(message, "DUPLICATE_PROFILE", 409);
+          return new VesantError(message, "DUPLICATE_PROFILE", 409, structured);
         case 429: {
           const retryAfter = data.retry_after || data.retryAfter;
           return new RateLimitError(retryAfter);
@@ -656,7 +657,7 @@ var BaseClient = class {
         case 504:
           return new ServiceUnavailableError(message);
         default:
-          return new VesantError(message, "UNKNOWN_ERROR", status);
+          return new VesantError(message, "UNKNOWN_ERROR", status, structured);
       }
     };
     const error = createError();
@@ -1104,6 +1105,7 @@ function isCipherTextExpired(cipherText) {
 }
 
 // src/geolocation/client.ts
+var DEFAULT_GPS_CONFIG_TTL_MS = 5 * 60 * 1e3;
 var GeolocationClient = class extends BaseClient {
   constructor(config) {
     const baseConfig = {
@@ -1119,6 +1121,8 @@ var GeolocationClient = class extends BaseClient {
       environment: config.environment
     };
     super(baseConfig);
+    this.gpsConfigCache = null;
+    this.gpsConfigTtlMs = config.gpsConfigTtlMs ?? DEFAULT_GPS_CONFIG_TTL_MS;
   }
   // ============================================================================
   // IP Verification & Compliance
@@ -1204,7 +1208,42 @@ var GeolocationClient = class extends BaseClient {
    * ```
    */
   async getGPSConfig(requestOptions) {
-    return this.requestWithRetry("/api/v1/geo/config", void 0, void 0, void 0, requestOptions);
+    const cached = this.gpsConfigCache;
+    if (cached && cached.expiresAt > Date.now()) {
+      return cached.value;
+    }
+    return this.refreshGPSConfig(requestOptions);
+  }
+  /**
+   * Re-read the tenant's GPS requirement configuration, ignoring any copy held
+   * from an earlier read.
+   *
+   * These requirements are edited in the compliance console while your
+   * application is running. `getGPSConfig` reuses a fetched copy for a short
+   * period so a long-lived session does not call the API on every event; call
+   * this when you need a change to take effect immediately — for example right
+   * after an administrator saves new settings.
+   *
+   * @returns The current GPS requirement config per event type
+   *
+   * @example
+   * ```typescript
+   * const config = await client.refreshGPSConfig();
+   * if (config.require_gps.login) {
+   *   // GPS is now required for login
+   * }
+   * ```
+   */
+  async refreshGPSConfig(requestOptions) {
+    const value = await this.requestWithRetry(
+      "/api/v1/geo/config",
+      void 0,
+      void 0,
+      void 0,
+      requestOptions
+    );
+    this.gpsConfigCache = { value, expiresAt: Date.now() + this.gpsConfigTtlMs };
+    return value;
   }
   /**
    * Mint a short-lived, single-use device-signals nonce.
@@ -1621,17 +1660,27 @@ var RiskProfileClient = class extends BaseClient {
   /**
    * Update customer profile
    *
+   * Omitted fields keep their stored values. When the tenant has the
+   * **On Account Sensitive Action** KYC trigger enabled and the update changes
+   * the customer's name, date of birth or residential address, Vesant applies
+   * the other fields, holds the sensitive ones and answers `202` with a
+   * {@link ProfileUpdateHeldResponse} instead of the profile. Narrow with
+   * {@link isProfileUpdateHeld}, then request a `profile_change` submit link.
+   *
    * @param profileId - Profile UUID
    * @param updates - Fields to update
-   * @returns Updated customer profile
+   * @returns Updated customer profile, or the held change
    *
    * @example
    * ```typescript
-   * const updated = await client.updateProfile(profileId, {
+   * const result = await client.updateProfile(profileId, {
    *   location: 'New York, USA',
    *   location_compliance: 'compliant',
    *   last_recorded_activity: new Date().toISOString()
    * });
+   * if (isProfileUpdateHeld(result)) {
+   *   // name / DOB / address held: start KYC with trigger_event 'profile_change'
+   * }
    * ```
    */
   async updateProfile(profileId, updates, requestOptions) {
@@ -1671,6 +1720,11 @@ var RiskProfileClient = class extends BaseClient {
   }
 };
 
+// src/risk-profile/types.ts
+function isProfileUpdateHeld(result) {
+  return typeof result === "object" && result !== null && result.status === "kyc_required" && result.kyc_required === true;
+}
+
 // src/compliance/block-reasons.ts
 var sdkReasons = {
   // Jurisdiction
@@ -2201,11 +2255,12 @@ var ComplianceClient = class {
       if (profileResult) {
         profile = profileResult;
         if (!isBlocked && this.shouldUpdateProfile(profile, geoVerification.location.city)) {
-          profile = await this.riskClient.updateProfile(profile.id, {
+          const updated = await this.riskClient.updateProfile(profile.id, {
             last_recorded_activity: (/* @__PURE__ */ new Date()).toISOString(),
             location: `${geoVerification.location.city}, ${geoVerification.location.country}`,
             location_compliance: geoVerification.is_compliant ? "compliant" : "non-compliant"
           }, requestOptions);
+          profile = isProfileUpdateHeld(updated) ? updated.profile : updated;
         }
       } else {
         if (this.config.autoCreateProfiles && this.config.debug) {
@@ -3151,77 +3206,24 @@ 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}`);
-  }
-  /**
-   * List KYC requests with filters and pagination
-   *
-   * @param filters - Optional filters (status, search, date range)
-   * @param pagination - Optional pagination (page, page_size)
-   * @returns Paginated list of KYC requests
-   *
-   * @example
-   * ```typescript
-   * const requests = await client.listKycRequests(
-   *   { status: "pending", search: "john" },
-   *   { page: 1, page_size: 20 }
-   * );
-   * console.log(`Found ${requests.total} pending requests`);
-   * ```
-   */
-  async listKycRequests(filters, pagination) {
-    const params = {};
-    if (filters) {
-      addFilterParam(params, "status", filters.status);
-      addSimpleParams(params, filters, ["search", "fromDate", "toDate", "sortBy", "order"]);
-    }
-    if (pagination) {
-      if (pagination.page) params.page = pagination.page;
-      if (pagination.page_size) params.limit = pagination.page_size;
-    }
-    return this.request(
-      `/api/v1/kyc/requests${this.buildQueryString(params)}`,
-      { headers: this.getUserHeaders() }
-    );
-  }
-  /**
-   * Update KYC request status (accept/decline)
-   *
-   * @param request - Status update request with reference, status, and reason
-   *
-   * @example
-   * ```typescript
-   * // Accept a KYC request
-   * await client.updateKycStatus({
-   *   reference: "kyc-ref-123",
-   *   status: "accepted",
-   *   reason: "All documents verified successfully"
-   * });
-   *
-   * // Decline a KYC request
-   * await client.updateKycStatus({
-   *   reference: "kyc-ref-456",
-   *   status: "declined",
-   *   reason: "Document expired"
-   * });
-   * ```
-   */
-  async updateKycStatus(request) {
-    await this.request("/api/v1/kyc/status", {
-      method: "PUT",
-      body: JSON.stringify(request),
+    return this.request(`/api/v1/kyc/${encodeURIComponent(id)}`, {
       headers: this.getUserHeaders()
     });
   }
@@ -3253,63 +3255,28 @@ 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() }
-    );
-  }
-  // ============================================================================
-  // KYC Overview & Statistics
-  // ============================================================================
-  /**
-   * Get KYC overview statistics
-   *
-   * @param fromDate - Optional start date (ISO 8601)
-   * @param toDate - Optional end date (ISO 8601)
-   * @returns KYC statistics including counts by status
-   *
-   * @example
-   * ```typescript
-   * const overview = await client.getOverview(
-   *   "2024-01-01T00:00:00Z",
-   *   "2024-12-31T23:59:59Z"
-   * );
-   * console.log(`Total: ${overview.total}, Pending: ${overview.pending}`);
-   * console.log(`Approved: ${overview.approved}, Rejected: ${overview.rejected}`);
-   * ```
-   */
-  async getOverview(fromDate, toDate) {
-    const params = {};
-    if (fromDate) params.fromDate = fromDate;
-    if (toDate) params.toDate = toDate;
-    return this.request(
-      `/api/v1/kyc/overview${this.buildQueryString(params)}`
-    );
+    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 }));
   }
   // ============================================================================
   // Alert Management
   // ============================================================================
-  /**
-   * Get a KYC alert by ID
-   *
-   * @param alertId - Alert ID
-   * @returns Alert details
-   */
-  async getAlert(alertId) {
-    return this.request(`/api/v1/kyc/alerts/${alertId}`);
-  }
   /**
    * List KYC alerts with filters and pagination
    *
@@ -3329,6 +3296,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 = {};
@@ -3348,66 +3319,15 @@ var KycClient = class extends BaseClient {
       `/api/v1/kyc/alerts${this.buildQueryString(params)}`
     );
   }
-  /**
-   * Update a KYC alert
-   *
-   * @param alertId - Alert ID
-   * @param update - Fields to update (status, assigned_for, reason, alert_type)
-   *
-   * @example
-   * ```typescript
-   * // Assign an alert
-   * await client.updateAlert("alert_123", {
-   *   assigned_for: "analyst_user_id",
-   *   status: "in_progress"
-   * });
-   *
-   * // Resolve an alert
-   * await client.updateAlert("alert_123", {
-   *   status: "resolved",
-   *   reason: "Customer verified via phone call"
-   * });
-   *
-   * // Escalate an alert
-   * await client.updateAlert("alert_123", {
-   *   status: "escalated",
-   *   assigned_for: "manager_user_id",
-   *   reason: "Requires senior review - suspicious documents"
-   * });
-   * ```
-   */
-  async updateAlert(alertId, update) {
-    await this.request(`/api/v1/kyc/alerts/${alertId}`, {
-      method: "PUT",
-      body: JSON.stringify(update),
-      headers: this.getUserHeaders()
-    });
-  }
   // ============================================================================
   // KYC Preferences
   // ============================================================================
-  /**
-   * Get KYC preferences for the tenant
-   *
-   * @returns KYC preferences configuration
-   *
-   * @example
-   * ```typescript
-   * const prefs = await client.getPreferences();
-   * console.log(`Face verification required: ${prefs.is_face_verification_required}`);
-   * console.log(`Required documents: ${prefs.required_document_count}`);
-   * ```
-   */
-  async getPreferences() {
-    return this.request("/api/v1/kyc/preferences");
-  }
   /**
    * Update KYC preferences for the tenant
    *
    * @deprecated KYC preferences are managed in the Vesant console; the
    * platform exposes no update operation to the SDK, so this call always
-   * fails. Use `getPreferences()` to read them. This method will be removed
-   * in a future release.
+   * fails. This method will be removed in a future release.
    *
    * @param update - Fields to update
    * @returns Updated preferences
@@ -3570,6 +3490,12 @@ var KYC_DECLINED_DESCRIPTIONS = {
 function isKycDocumentExpiredCallbackEvent(value) {
   return typeof value === "object" && value !== null && value.event === "kyc_document_expired";
 }
+function isKycStatusCallbackEvent(value) {
+  return typeof value === "object" && value !== null && value.event === "kyc";
+}
+function isProfileChangeCallbackEvent(value) {
+  return typeof value === "object" && value !== null && value.event === "profile_change";
+}
 
 // src/tax/client.ts
 var TaxClient = class extends BaseClient {
@@ -3859,6 +3785,11 @@ function buildHandler(options) {
   return handler;
 }
 
+// src/webhooks/types.ts
+function isAmlBlockCallbackEvent(value) {
+  return typeof value === "object" && value !== null && value.event === "aml" && value.block === true;
+}
+
 exports.AuthenticationError = AuthenticationError;
 exports.BaseClient = BaseClient;
 exports.CGSError = CGSError;
@@ -3894,8 +3825,12 @@ exports.createWebhookMiddleware = createWebhookMiddleware;
 exports.decodeCipherText = decodeCipherText;
 exports.generateCipherText = generateCipherText;
 exports.gpsIntegrityInputFromPosition = gpsIntegrityInputFromPosition;
+exports.isAmlBlockCallbackEvent = isAmlBlockCallbackEvent;
 exports.isCipherTextExpired = isCipherTextExpired;
 exports.isKycDocumentExpiredCallbackEvent = isKycDocumentExpiredCallbackEvent;
+exports.isKycStatusCallbackEvent = isKycStatusCallbackEvent;
+exports.isProfileChangeCallbackEvent = isProfileChangeCallbackEvent;
+exports.isProfileUpdateHeld = isProfileUpdateHeld;
 exports.noopLogger = noopLogger;
 exports.paginate = paginate;
 exports.probeGeolocationPermission = probeGeolocationPermission;