vesant-sdk 1.6.6 → 1.7.0-dev.7d59b3e

package/dist/index.mjs

@@ -240,7 +240,7 @@ var noopLogger = {
 };
 
 // src/core/version.ts
-var SDK_VERSION = "1.6.6";
+var SDK_VERSION = "1.7.0";
 
 // src/shared/browser-utils.ts
 function generateUUID() {
@@ -650,8 +650,9 @@ async function computeHmacSha256(message, secret) {
     const { createHmac } = await import('crypto');
     return createHmac("sha256", secret).update(message).digest("hex");
   } catch {
-    throw new Error(
-      "No crypto implementation available. Requires Web Crypto API or Node.js crypto module."
+    throw new VesantError(
+      "No crypto implementation available. Requires Web Crypto API or Node.js crypto module.",
+      "CRYPTO_UNAVAILABLE"
     );
   }
 }
@@ -785,7 +786,7 @@ function encodePayload(payload) {
   } else if (typeof Buffer !== "undefined") {
     return Buffer.from(json, "utf-8").toString("base64");
   }
-  throw new Error("No base64 encoding method available");
+  throw new VesantError("No base64 encoding method available", "BASE64_UNAVAILABLE");
 }
 async function generateCipherText(options, config) {
   const warnings = [];
@@ -810,8 +811,9 @@ async function generateCipherText(options, config) {
     if (location) {
       locationData = location;
     } else if (gpsRequiredByConfig) {
-      throw new Error(
-        `GPS location is required for ${options.reason} by tenant configuration, but GPS was not available or permission was denied`
+      throw new VesantError(
+        `GPS location is required for ${options.reason} by tenant configuration, but GPS was not available or permission was denied`,
+        "GPS_REQUIRED"
       );
     } else {
       warnings.push("GPS location not available or permission denied");
@@ -930,10 +932,9 @@ var GeolocationClient = class extends BaseClient {
     if (!request.ip_address?.trim()) {
       throw new ValidationError("ip_address is required and must be a non-empty string", ["ip_address"]);
     }
-    const enrichedRequest = request.device_fingerprint ? request : { ...request, device_fingerprint: collectDeviceFingerprint() };
     return this.requestWithRetry("/api/v1/geo/verify", {
       method: "POST",
-      body: JSON.stringify(enrichedRequest)
+      body: JSON.stringify(request)
     }, void 0, void 0, requestOptions);
   }
   /**
@@ -1158,6 +1159,7 @@ var GeolocationClient = class extends BaseClient {
       risk_level: risk.level ?? "low",
       risk_score: risk.score ?? 0,
       risk_reasons: risk.is_blocked && risk.block_reasons ? risk.block_reasons : risk.factors ?? [],
+      risk_reasons_structured: risk.block_reasons_structured ?? [],
       jurisdiction: cipherTextResult.jurisdiction,
       geofence_evaluation: cipherTextResult.geofence_evaluation,
       record_id: cipherTextResult.record_id ?? "",
@@ -1337,24 +1339,6 @@ var GeolocationClient = class extends BaseClient {
   // Utility Methods (inherited from BaseClient: healthCheck, updateConfig, getConfig, buildQueryString)
   // ============================================================================
 };
-function collectDeviceFingerprint() {
-  const deviceId = generateDeviceId();
-  const browserInfo = getBrowserInfo();
-  const userAgent = typeof navigator !== "undefined" ? navigator.userAgent : "server";
-  const platform = typeof navigator !== "undefined" ? navigator.platform || "unknown" : "server";
-  return {
-    device_id: deviceId,
-    user_agent: userAgent,
-    platform,
-    browser: browserInfo.browser,
-    browser_version: browserInfo.browser_version,
-    os: browserInfo.os,
-    os_version: browserInfo.os_version,
-    screen_resolution: typeof screen !== "undefined" ? `${screen.width}x${screen.height}` : void 0,
-    language: typeof navigator !== "undefined" ? navigator.language : void 0,
-    timezone: Intl?.DateTimeFormat?.()?.resolvedOptions?.()?.timeZone
-  };
-}
 
 // src/risk-profile/client.ts
 var RiskProfileClient = class extends BaseClient {
@@ -1471,6 +1455,81 @@ var RiskProfileClient = class extends BaseClient {
   }
 };
 
+// src/compliance/block-reasons.ts
+var sdkReasons = {
+  // Jurisdiction
+  jurisdictionBlocked: (country, countryISO) => ({
+    code: "JURISDICTION_BLOCKED",
+    message: "Access from a blocked jurisdiction",
+    metadata: { country, country_iso: countryISO }
+  }),
+  jurisdictionNonCompliant: () => ({
+    code: "JURISDICTION_NON_COMPLIANT",
+    message: "Location does not meet compliance requirements"
+  }),
+  jurisdictionRegistrationDenied: () => ({
+    code: "JURISDICTION_REGISTRATION_DENIED",
+    message: "Registration is not permitted in this jurisdiction"
+  }),
+  jurisdictionRestricted: () => ({
+    code: "JURISDICTION_RESTRICTED",
+    message: "Access from a restricted jurisdiction"
+  }),
+  // Risk
+  riskCriticalLevel: () => ({
+    code: "RISK_CRITICAL_LEVEL",
+    message: "Risk assessment reached critical threshold"
+  }),
+  accountSuspended: () => ({
+    code: "RISK_ACCOUNT_SUSPENDED",
+    message: "Customer account is suspended"
+  }),
+  sanctionsMatch: () => ({
+    code: "RISK_SANCTIONS_MATCH",
+    message: "Customer profile matched against sanctions list"
+  }),
+  riskHighLocation: () => ({
+    code: "RISK_HIGH_LOCATION",
+    message: "High-risk geographic location"
+  }),
+  riskHighCustomer: () => ({
+    code: "RISK_HIGH_CUSTOMER",
+    message: "Customer flagged as high risk"
+  }),
+  // Device
+  ciphertextInvalid: () => ({
+    code: "DEVICE_CIPHERTEXT_INVALID",
+    message: "Device verification payload failed validation"
+  }),
+  gpsIPMismatch: () => ({
+    code: "DEVICE_GPS_IP_MISMATCH",
+    message: "GPS location does not match IP-derived location"
+  }),
+  gpsRequired: () => ({
+    code: "DEVICE_GPS_REQUIRED",
+    message: "GPS verification is required but was not provided"
+  }),
+  // Transaction
+  transactionHighAmount: (amount, currency, threshold) => ({
+    code: "TRANSACTION_HIGH_AMOUNT",
+    message: "Transaction amount exceeds high-value threshold",
+    metadata: { amount, currency, threshold }
+  }),
+  transactionElevatedAmount: (amount, currency, threshold) => ({
+    code: "TRANSACTION_ELEVATED_AMOUNT",
+    message: "Transaction amount exceeds elevated-value threshold",
+    metadata: { amount, currency, threshold }
+  }),
+  transactionJurisdictionLimit: () => ({
+    code: "TRANSACTION_JURISDICTION_LIMIT",
+    message: "Transaction amount exceeds jurisdiction limit"
+  }),
+  anonymizationDetected: () => ({
+    code: "NETWORK_ANONYMIZER_DETECTED",
+    message: "Anonymization tool detected"
+  })
+};
+
 // src/compliance/types.ts
 var DEFAULT_CURRENCY_RATES = {
   USD: 1,
@@ -1617,10 +1676,10 @@ var ComplianceClient = class {
           device_fingerprint: request.deviceFingerprint
         }, requestOptions);
       }
-      const blockReasons = this.evaluateRegistrationBlock(geoVerification, cipherTextResult);
-      if (blockReasons.length > 0) {
+      const structuredBlockReasons = this.evaluateRegistrationBlock(geoVerification, cipherTextResult);
+      if (structuredBlockReasons.length > 0) {
         if (this.config.debug) {
-          this.logger.debug("Registration blocked at geo stage", { blockReasons });
+          this.logger.debug("Registration blocked at geo stage", { blockReasons: structuredBlockReasons });
         }
         return {
           allowed: false,
@@ -1628,9 +1687,7 @@ var ComplianceClient = class {
           profile: null,
           requiresKYC: false,
           requiresEDD: false,
-          blockReasons,
-          processingTime: Date.now() - startTime,
-          cipherTextValidation: cipherTextResult
+          ...this.buildReasonTail(structuredBlockReasons, startTime, cipherTextResult)
         };
       }
       const profile = await this.riskClient.createProfile({
@@ -1664,14 +1721,12 @@ var ComplianceClient = class {
         profile,
         requiresKYC,
         requiresEDD,
-        blockReasons: [],
-        processingTime: Date.now() - startTime,
-        cipherTextValidation: cipherTextResult
+        ...this.buildReasonTail([], startTime, cipherTextResult)
       };
     } catch (error) {
       if (this.config.debug) {
         this.logger.error("Registration verification failed", {
-          code: error instanceof Error ? error.code : void 0,
+          code: error instanceof VesantError ? error.code : void 0,
           message: error instanceof Error ? error.message : "Unknown error"
         });
       }
@@ -1700,52 +1755,62 @@ var ComplianceClient = class {
   evaluateRegistrationBlock(geoVerification, cipherTextResult) {
     const blockReasons = [];
     if (geoVerification.is_blocked) {
-      blockReasons.push(...geoVerification.risk_reasons ?? []);
+      blockReasons.push(...geoVerification.risk_reasons_structured ?? []);
     }
     if (!geoVerification.is_compliant) {
-      if (!blockReasons.includes("non_compliant_jurisdiction")) {
-        blockReasons.push("non_compliant_jurisdiction");
+      if (!blockReasons.some((r) => r.code === "JURISDICTION_NON_COMPLIANT")) {
+        blockReasons.push(sdkReasons.jurisdictionNonCompliant());
       }
     }
     const jurisdiction = geoVerification.jurisdiction;
     if (jurisdiction) {
       if (jurisdiction.allow_registration === false) {
-        blockReasons.push("registration_not_allowed_in_jurisdiction");
+        blockReasons.push(sdkReasons.jurisdictionRegistrationDenied());
       }
       if (jurisdiction.status === "blocked" || jurisdiction.status === "sanctioned") {
-        if (!blockReasons.includes("blocked_jurisdiction")) {
-          blockReasons.push("blocked_jurisdiction");
+        if (!blockReasons.some((r) => r.code === "JURISDICTION_BLOCKED")) {
+          blockReasons.push(sdkReasons.jurisdictionBlocked(jurisdiction.country_name ?? "", jurisdiction.country_iso ?? ""));
         }
       }
       if (jurisdiction.status === "restricted" && jurisdiction.allow_registration === false) {
-        if (!blockReasons.includes("restricted_jurisdiction_no_registration")) {
-          blockReasons.push("restricted_jurisdiction_no_registration");
+        if (!blockReasons.some((r) => r.code === "JURISDICTION_RESTRICTED")) {
+          blockReasons.push(sdkReasons.jurisdictionRestricted());
         }
       }
     }
     if (geoVerification.geofence_evaluation?.blocked) {
-      blockReasons.push(...geoVerification.geofence_evaluation.reasons ?? []);
+      blockReasons.push(
+        ...(geoVerification.geofence_evaluation.reasons ?? []).map((m) => ({
+          code: "JURISDICTION_GEOFENCE_VIOLATION",
+          message: m
+        }))
+      );
     }
     if (geoVerification.risk_level === "critical") {
-      if (!blockReasons.includes("critical_risk_level")) {
-        blockReasons.push("critical_risk_level");
+      if (!blockReasons.some((r) => r.code === "RISK_CRITICAL_LEVEL")) {
+        blockReasons.push(sdkReasons.riskCriticalLevel());
       }
     }
     if (cipherTextResult) {
       if (!cipherTextResult.valid) {
-        blockReasons.push("ciphertext_validation_failed");
+        blockReasons.push(sdkReasons.ciphertextInvalid());
       }
       if (cipherTextResult.risk?.is_blocked) {
-        blockReasons.push(...cipherTextResult.risk.block_reasons || []);
+        blockReasons.push(...cipherTextResult.risk.block_reasons_structured ?? []);
       }
       if (cipherTextResult.risk?.location_mismatch) {
-        blockReasons.push("gps_ip_location_mismatch");
+        blockReasons.push(sdkReasons.gpsIPMismatch());
       }
     }
     if (geoVerification.gps_required && !cipherTextResult) {
-      blockReasons.push("gps_verification_required");
+      blockReasons.push(sdkReasons.gpsRequired());
     }
-    return [...new Set(blockReasons)];
+    const seen = /* @__PURE__ */ new Set();
+    return blockReasons.filter((r) => {
+      if (seen.has(r.code)) return false;
+      seen.add(r.code);
+      return true;
+    });
   }
   /**
    * Validate registration request has all required fields
@@ -1916,9 +1981,7 @@ var ComplianceClient = class {
           geolocation: geoVerification,
           profile: null,
           requiresStepUp: false,
-          blockReasons: loginBlockReasons,
-          processingTime: Date.now() - startTime,
-          cipherTextValidation: cipherTextResult
+          ...this.buildReasonTail(loginBlockReasons, startTime, cipherTextResult)
         };
       }
       let profile;
@@ -1938,14 +2001,13 @@ var ComplianceClient = class {
         profile = await this.createProfileFromGeo(request.customerId, geoVerification);
       }
       const requiresStepUp = geoVerification.risk_level === "high" || geoVerification.risk_level === "critical" || cipherTextResult?.risk?.location_mismatch === true;
+      const loginFinalStructured = isBlocked || profile.customer_status === "suspended" ? this.getBlockReasons(geoVerification, profile, cipherTextResult) : [];
       return {
         allowed: !isBlocked && profile.customer_status !== "suspended",
         geolocation: geoVerification,
         profile,
         requiresStepUp,
-        blockReasons: isBlocked || profile.customer_status === "suspended" ? this.getBlockReasons(geoVerification, profile, cipherTextResult) : [],
-        processingTime: Date.now() - startTime,
-        cipherTextValidation: cipherTextResult
+        ...this.buildReasonTail(loginFinalStructured, startTime, cipherTextResult)
       };
     } catch (error) {
       throw new ComplianceError("Login verification failed", error instanceof Error ? error.message : void 0);
@@ -2027,20 +2089,19 @@ var ComplianceClient = class {
       }
       const geoBlocked = !geoVerification.is_compliant || geoVerification.is_blocked || !!cipherTextResult?.risk?.is_blocked || cipherTextResult?.valid === false || geoVerification.gps_required && !cipherTextResult;
       if (geoBlocked && !profileResult) {
+        const earlyStructured = this.getTransactionBlockReasons(
+          geoVerification,
+          { score: 0, level: "low", factors: [], allowed: false, requiresManualReview: false },
+          true,
+          cipherTextResult
+        );
         return {
           allowed: false,
           geolocation: geoVerification,
           profile: null,
           transactionRisk: { score: 0, level: "low", factors: [], allowed: false, requiresManualReview: false },
           requiresApproval: false,
-          blockReasons: this.getTransactionBlockReasons(
-            geoVerification,
-            { score: 0, level: "low", factors: [], allowed: false, requiresManualReview: false },
-            true,
-            cipherTextResult
-          ),
-          processingTime: Date.now() - startTime,
-          cipherTextValidation: cipherTextResult
+          ...this.buildReasonTail(earlyStructured, startTime, cipherTextResult)
         };
       }
       if (!profileResult) {
@@ -2060,20 +2121,19 @@ var ComplianceClient = class {
         geoVerification.jurisdiction
       );
       const isAllowed = !geoBlocked && jurisdictionAllowed && transactionRisk.allowed && profile.customer_status !== "suspended";
+      const txStructured = this.getTransactionBlockReasons(
+        geoVerification,
+        transactionRisk,
+        jurisdictionAllowed,
+        cipherTextResult
+      );
       return {
         allowed: isAllowed,
         geolocation: geoVerification,
         profile,
         transactionRisk,
         requiresApproval: transactionRisk.requiresManualReview,
-        blockReasons: this.getTransactionBlockReasons(
-          geoVerification,
-          transactionRisk,
-          jurisdictionAllowed,
-          cipherTextResult
-        ),
-        processingTime: Date.now() - startTime,
-        cipherTextValidation: cipherTextResult
+        ...this.buildReasonTail(txStructured, startTime, cipherTextResult)
       };
     } catch (error) {
       throw new ComplianceError("Transaction verification failed", error instanceof Error ? error.message : void 0);
@@ -2126,30 +2186,42 @@ var ComplianceClient = class {
       }
     }
     const cipherTextBlocked = cipherTextResult ? !cipherTextResult.valid || cipherTextResult.risk?.is_blocked === true : false;
-    const blockReasons = [...geoVerification.risk_reasons ?? []];
+    const structuredEventReasons = [...geoVerification.risk_reasons_structured ?? []];
     if (cipherTextResult) {
       if (!cipherTextResult.valid) {
-        blockReasons.push("ciphertext_validation_failed");
+        structuredEventReasons.push(sdkReasons.ciphertextInvalid());
       }
       if (cipherTextResult.risk?.is_blocked) {
-        blockReasons.push(...cipherTextResult.risk.block_reasons || []);
+        structuredEventReasons.push(...cipherTextResult.risk.block_reasons_structured ?? []);
       }
     }
     const gpsBlocked = geoVerification.gps_required && !cipherTextResult;
     if (gpsBlocked) {
-      blockReasons.push("gps_verification_required");
+      structuredEventReasons.push(sdkReasons.gpsRequired());
     }
+    const seen = /* @__PURE__ */ new Set();
+    const dedupedStructured = structuredEventReasons.filter((r) => {
+      if (seen.has(r.code)) return false;
+      seen.add(r.code);
+      return true;
+    });
     return {
       allowed: geoVerification.is_compliant && !geoVerification.is_blocked && !cipherTextBlocked && !gpsBlocked,
       geolocation: geoVerification,
-      blockReasons: [...new Set(blockReasons)],
-      processingTime: Date.now() - startTime,
-      cipherTextValidation: cipherTextResult
+      ...this.buildReasonTail(dedupedStructured, startTime, cipherTextResult)
     };
   }
   // ============================================================================
   // Helper Methods
   // ============================================================================
+  buildReasonTail(structured, startTime, cipherTextResult) {
+    return {
+      blockReasons: structured.map((r) => r.message),
+      blockReasonsStructured: structured,
+      processingTime: Date.now() - startTime,
+      cipherTextValidation: cipherTextResult
+    };
+  }
   shouldUpdateProfile(profile, newCity) {
     return !profile.location || !profile.location.includes(newCity);
   }
@@ -2226,7 +2298,8 @@ var ComplianceClient = class {
       is_blocked: risk.is_blocked,
       risk_level: risk.level,
       risk_score: risk.score,
-      risk_reasons: risk.is_blocked && risk.block_reasons ? risk.block_reasons : risk.factors ?? [],
+      risk_reasons: [],
+      risk_reasons_structured: risk.is_blocked && risk.block_reasons_structured ? risk.block_reasons_structured : [],
       jurisdiction: ct.jurisdiction,
       geofence_evaluation: ct.geofence_evaluation,
       record_id: ct.record_id ?? "",
@@ -2241,35 +2314,35 @@ var ComplianceClient = class {
       );
     }
     let riskScore = 0;
-    const factors = [];
+    const structuredFactors = [];
     const normalizedAmount = this.normalizeToUSD(amount, currency);
     if (normalizedAmount > 1e4) {
       riskScore += 30;
-      factors.push("high_transaction_amount");
+      structuredFactors.push(sdkReasons.transactionHighAmount(normalizedAmount, currency, 1e4));
     } else if (normalizedAmount > 5e3) {
       riskScore += 15;
-      factors.push("elevated_transaction_amount");
+      structuredFactors.push(sdkReasons.transactionElevatedAmount(normalizedAmount, currency, 5e3));
     }
     riskScore += geoVerification.risk_score * 0.4;
     if (geoVerification.risk_level === "high" || geoVerification.risk_level === "critical") {
-      factors.push("high_risk_location");
+      structuredFactors.push(sdkReasons.riskHighLocation());
     }
     riskScore += profile.risk_score * 0.3;
     if (profile.risk_category === "high" || profile.risk_category === "critical") {
-      factors.push("high_risk_customer");
+      structuredFactors.push(sdkReasons.riskHighCustomer());
     }
     if (geoVerification.location.is_vpn || geoVerification.location.is_proxy) {
       riskScore += 20;
-      factors.push("anonymization_detected");
+      structuredFactors.push(sdkReasons.anonymizationDetected());
     }
     if (profile.customer_status === "suspended") {
       riskScore += 50;
-      factors.push("account_suspended");
+      structuredFactors.push(sdkReasons.accountSuspended());
     }
     if (cipherTextResult) {
       if (cipherTextResult.risk?.location_mismatch) {
         riskScore += 20;
-        factors.push("gps_ip_location_mismatch");
+        structuredFactors.push(sdkReasons.gpsIPMismatch());
       }
       if (cipherTextResult.risk?.score) {
         riskScore += cipherTextResult.risk.score * 0.2;
@@ -2278,7 +2351,8 @@ var ComplianceClient = class {
     return {
       score: Math.min(riskScore, 100),
       level: this.getRiskLevel(riskScore),
-      factors,
+      factors: structuredFactors.map((r) => r.message),
+      factorsStructured: structuredFactors,
       allowed: riskScore < 70,
       requiresManualReview: riskScore >= 60 && riskScore < 70
     };
@@ -2303,52 +2377,62 @@ var ComplianceClient = class {
   getBlockReasons(geoVerification, profile, cipherTextResult) {
     const reasons = [];
     if (geoVerification.is_blocked) {
-      reasons.push(...geoVerification.risk_reasons ?? []);
+      reasons.push(...geoVerification.risk_reasons_structured ?? []);
     }
     if (profile) {
       if (profile.customer_status === "suspended") {
-        reasons.push("account_suspended");
+        reasons.push(sdkReasons.accountSuspended());
       }
       if (profile.has_sanctions) {
-        reasons.push("sanctions_match");
+        reasons.push(sdkReasons.sanctionsMatch());
       }
     }
     if (cipherTextResult) {
       if (!cipherTextResult.valid) {
-        reasons.push("ciphertext_validation_failed");
+        reasons.push(sdkReasons.ciphertextInvalid());
       }
       if (cipherTextResult.risk?.is_blocked) {
-        reasons.push(...cipherTextResult.risk.block_reasons || []);
+        reasons.push(...cipherTextResult.risk.block_reasons_structured ?? []);
       }
     }
     if (geoVerification.gps_required && !cipherTextResult) {
-      reasons.push("gps_verification_required");
+      reasons.push(sdkReasons.gpsRequired());
     }
-    return [...new Set(reasons)];
+    const seen = /* @__PURE__ */ new Set();
+    return reasons.filter((r) => {
+      if (seen.has(r.code)) return false;
+      seen.add(r.code);
+      return true;
+    });
   }
   getTransactionBlockReasons(geoVerification, transactionRisk, jurisdictionAllowed, cipherTextResult) {
     const reasons = [];
     if (!geoVerification.is_compliant) {
-      reasons.push("non_compliant_jurisdiction");
+      reasons.push(sdkReasons.jurisdictionNonCompliant());
     }
     if (!jurisdictionAllowed) {
-      reasons.push("exceeds_jurisdiction_limit");
+      reasons.push(sdkReasons.transactionJurisdictionLimit());
     }
     if (!transactionRisk.allowed) {
-      reasons.push(...transactionRisk.factors);
+      reasons.push(...transactionRisk.factorsStructured ?? []);
     }
     if (cipherTextResult) {
       if (!cipherTextResult.valid) {
-        reasons.push("ciphertext_validation_failed");
+        reasons.push(sdkReasons.ciphertextInvalid());
       }
       if (cipherTextResult.risk?.is_blocked) {
-        reasons.push(...cipherTextResult.risk.block_reasons || []);
+        reasons.push(...cipherTextResult.risk.block_reasons_structured ?? []);
       }
     }
     if (geoVerification.gps_required && !cipherTextResult) {
-      reasons.push("gps_verification_required");
+      reasons.push(sdkReasons.gpsRequired());
     }
-    return [...new Set(reasons)];
+    const seen = /* @__PURE__ */ new Set();
+    return reasons.filter((r) => {
+      if (seen.has(r.code)) return false;
+      seen.add(r.code);
+      return true;
+    });
   }
   // ============================================================================
   // Location Request Methods
@@ -2626,23 +2710,19 @@ var KycClient = class extends BaseClient {
    *
    * Generates a link that the user can visit to submit their KYC documents.
    *
-   * @param request - Request containing the user ID, redirect URL, callback URL, and trigger event
-   * @returns Response containing kyc_required, can_skip, and optionally the redirect link and KYC ID
+   * @param request - Request containing the user ID, optional redirect URL, and optional callback URL (receives POST requests)
+   * @returns Response containing the redirect link and KYC ID
    *
    * @example
    * ```typescript
    * const result = await client.requestKycSubmitLink({
    *   user_id: "user_123",
-   *   redirect_url: "https://merchant.com/kyc-complete",
-   *   callback_url: "https://merchant.com/api/kyc-webhook",
-   *   trigger_event: "onboarding"
+   *   redirect_url: "https://merchant.com/kyc-complete", // optional
+   *   callback_url: "https://merchant.com/api/kyc-webhook" // optional - receives POST requests on status change
    * });
    *
-   * if (result.kyc_required && result.link) {
-   *   console.log(`Redirect user to: ${result.link}`);
-   * } else if (result.can_skip) {
-   *   console.log("KYC not required, user can proceed");
-   * }
+   * console.log(`Redirect user to: ${result.link}`);
+   * console.log(`KYC ID: ${result.kyc_id}`);
    * ```
    */
   async requestKycSubmitLink(request) {
@@ -2653,40 +2733,88 @@ var KycClient = class extends BaseClient {
     });
   }
   /**
-   * Create a reuse KYC session for validate a user with existing KYC verification
+   * 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.
    *
-   * @param request - Request containing the reference, customer_id, optional redirect URL, and callback URL (receives POST requests)
+   * @param request - Reference, customer_id, event, amount (for threshold events), optional URLs.
    */
-  async createReuseKycSession(request) {
-    return this.requestWithRetry("/api/v1/kyc/face/session", {
+  async createEventBasedFaceVerificationSession(request) {
+    return this.request("/api/v1/kyc/face/session", {
       method: "POST",
       body: JSON.stringify(request),
       headers: this.getUserHeaders()
     });
   }
   /**
-   * Submit a reuse KYC session for validate a user with existing KYC verification
+   * Submit a real-time face capture for an active Event-Based Face Verification session.
+   *
+   * **Mobile-only.** The server rejects desktop User-Agents with HTTP
+   * 400 (`face capture must be completed on a mobile device`). Use the
+   * QR handoff from `createEventBasedFaceVerificationSession` for desktop callers.
+   *
+   * The `data` field on the response carries `retries_remaining`,
+   * `retry_limit_exceeded`, and the reaction flags (`enforce_logout`,
+   * `freeze_account`, etc.) so the tenant app can act on a final failure.
    *
-   * @param request - Request containing the reference, token and proof (receives POST requests)
+   * @param request - Token from `createEventBasedFaceVerificationSession`, plus the base64 selfie.
    */
-  async submitReuseKycSession(request) {
-    return this.requestWithRetry("/api/v1/kyc/face/submit", {
+  async submitEventBasedFaceVerificationSession(request) {
+    return this.request("/api/v1/kyc/face/submit", {
       method: "POST",
       body: JSON.stringify(request),
       headers: this.getUserHeaders()
     });
   }
   /**
-   * Check reuse KYC session status for a reference
-   * @param reference - The unique reference used for the reuse KYC session (e.g., customer ID or transaction ID)
-   * @returns Response with kyc_status and message (reason)
-   * **/
-  async getReuseKycSessionStatus(reference) {
-    return this.requestWithRetry(`/api/v1/kyc/face/verify/${encodeURIComponent(reference)}`, {
+   * Look up the current state of a Event-Based Face Verification session by its
+   * session token. Useful for desktop pollers waiting on the mobile handoff.
+   *
+   * The lookup is scoped by the unguessable, server-issued session token (not
+   * the enumerable forward reference): the endpoint is public/unauthenticated,
+   * and scoping by the token is what prevents cross-tenant status reads.
+   *
+   * @param token - The session token returned by `createEventBasedFaceVerificationSession`.
+   */
+  async getEventBasedFaceVerificationSessionStatus(token) {
+    return this.requestWithRetry(`/api/v1/kyc/face/verify/${encodeURIComponent(token)}`, {
       method: "GET",
       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.
+   *
+   * @param token - The session token returned by `createEventBasedFaceVerificationSession`.
+   */
+  async getHandoffSession(token) {
+    return this.request(
+      `/api/v1/kyc/session${this.buildQueryString({ token })}`,
+      { headers: this.getUserHeaders() }
+    );
+  }
+  /**
+   * Attach a mobile device to a desktop-initiated session. The mobile
+   * client calls this after scanning the QR code. The desktop poller
+   * sees `mobile_connected: true` on the next `getHandoffSession`.
+   *
+   * @param token - The session token transferred via the QR payload.
+   * @param isDisconnect - Pass true to release the session (default false).
+   */
+  async connectMobileSession(token, isDisconnect = false) {
+    return this.request("/api/v1/kyc/session/connect", {
+      method: "PUT",
+      body: JSON.stringify({ token, is_disconnect: isDisconnect }),
+      headers: this.getUserHeaders()
+    });
+  }
   /**
    * Check KYC status for a user
    *
@@ -3045,8 +3173,9 @@ var KycClient = class extends BaseClient {
    */
   async riskProfileRequest(path, options = {}) {
     if (!this.riskProfileBaseURL) {
-      throw new Error(
-        "Risk Profile Service URL not configured. Please provide riskProfileBaseURL in KycClientConfig."
+      throw new ValidationError(
+        "Risk Profile Service URL not configured. Please provide riskProfileBaseURL in KycClientConfig.",
+        ["riskProfileBaseURL"]
       );
     }
     return this.request(path, {
@@ -3158,6 +3287,19 @@ var KycClient = class extends BaseClient {
   // ============================================================================
 };
 
+// src/kyc/types.ts
+var KYC_DECLINED_DESCRIPTIONS = {
+  KYC_DOCUMENT_EXPIRED: "The submitted document has expired",
+  KYC_DOCUMENT_INVALID: "The submitted document could not be verified",
+  KYC_FACE_MISMATCH: "Face verification did not match the identity document",
+  KYC_AGE_REQUIREMENT: "Age requirement not met",
+  KYC_DUPLICATE_IDENTITY: "This identity has already been verified under another account",
+  KYC_ADDRESS_MISMATCH: "Address verification failed",
+  KYC_NAME_MISMATCH: "Name on document does not match the registered name",
+  KYC_PROVIDER_REJECTED: "Identity verification was rejected by the verification provider",
+  KYC_DECLINED: "Identity verification was declined"
+};
+
 // src/tax/client.ts
 var TaxClient = class extends BaseClient {
   constructor(config) {
@@ -3224,41 +3366,6 @@ var TaxClient = class extends BaseClient {
       { ...requestOptions, responseType: "arraybuffer" }
     );
   }
-  async runReminders() {
-    return this.request("/api/v1/tax/reminders/run", {
-      method: "POST"
-    });
-  }
-  /**
-   * Update only the reminder configuration (frequency + max count) without
-   * touching any other tax rule settings. Fetches current rules first and
-   * merges the reminder fields before sending the update.
-   *
-   * Requires the caller to be authenticated as a Tenant Super Admin.
-   * Throws VesantError with status 403 if the role requirement is not met.
-   */
-  async updateReminderConfig(input) {
-    const current = await this.getTaxRules();
-    return this.updateTaxRules({
-      trigger_account_creation: current.trigger_account_creation,
-      trigger_first_withdrawal: current.trigger_first_withdrawal,
-      trigger_threshold: current.trigger_threshold,
-      trigger_manual: current.trigger_manual,
-      trigger_tin_invalid: current.trigger_tin_invalid,
-      trigger_w8ben_expiry: current.trigger_w8ben_expiry,
-      trigger_tin_expired: current.trigger_tin_expired,
-      us_withholding_enabled: current.us_withholding_enabled,
-      non_us_withholding_enabled: current.non_us_withholding_enabled,
-      transaction_action: current.transaction_action,
-      w8ben_expiry_warning_days: current.w8ben_expiry_warning_days,
-      tin_verification_due_date: current.tin_verification_due_date,
-      email_sending_method: current.email_sending_method,
-      display_tin_links_on_platform: current.display_tin_links_on_platform,
-      tax_treaty_support: current.tax_treaty_support,
-      reminder_frequency_days: input.reminder_frequency_days,
-      reminder_max_count: input.reminder_max_count
-    });
-  }
   // ==========================================================================
   // P2 — Tenant Tax Rules
   // ==========================================================================
@@ -3302,136 +3409,15 @@ var TaxClient = class extends BaseClient {
   }
 };
 
-// src/transaction/client.ts
-var TransactionClient = class extends BaseClient {
-  constructor(config) {
-    super(config);
-  }
-  // ==========================================================================
-  // Transaction creation
-  // ==========================================================================
-  /**
-   * Submit a new transaction record to the monitoring service.
-   *
-   * The gateway endpoint is `POST /api/v1/tm/transactions` and returns 201
-   * with no body on success.  The SDK method resolves to `void` to reflect
-   * that behaviour.
-   *
-   * @param request - Data required to create the transaction
-   * @param requestOptions - Optional request options (e.g. AbortSignal)
-   *
-   * @example
-   * ```ts
-   * const client = new TransactionClient({
-   *   baseURL: process.env.API_GATEWAY_URL!,
-   *   tenantId: 'tenant-123',
-   *   apiKey: 'pk_test_...',
-   * });
-   *
-   * await client.createTransaction({
-   *   tx_id: 'tx-1',
-   *   reference: 'ref-1',
-   *   tenant_id: 'tenant-123',
-   *   customer_id: 'cust-1',
-   *   transaction_type: 'deposit',
-   *   transaction_mode: 'ach',
-   *   amount: '100.00',
-   *   currency: 'USD',
-   *   status: 'pending',
-   *   source_account: 'acct-1',
-   *   destination_account: 'acct-2',
-   *   country: 'US',
-   *   ip_address: '10.0.0.1',
-   *   metadata: {},
-   *   benificiary_comment: '',
-   *   transaction_date: new Date().toISOString(),
-   * });
-   * ```
-   */
-  async createTransaction(request, requestOptions) {
-    const data = await this.requestWithRetry("/api/v1/tm/transactions", {
-      method: "POST",
-      body: JSON.stringify(request)
-    }, void 0, void 0, requestOptions);
-    return data;
-  }
-  /**
-   * 
-   * @param transactionId tx_id of the transaction 
-   * @param requestOptions  optional request options (e.g. AbortSignal)
-   */
-  async getTransaction(transactionId, requestOptions) {
-    await this.requestWithRetry(`/api/v1/tm/transactions/status/${transactionId}`, {
-      method: "GET"
-    }, void 0, void 0, requestOptions);
-  }
-};
-
-// src/fraud/client.ts
-var FraudClient = class extends BaseClient {
-  /**
-   * Submit a single fraud event for scoring.
-   */
-  async scoreEvent(request, requestOptions) {
-    this.validateScoreRequest(request);
-    return this.requestWithRetry(
-      "/api/v1/fraud/score",
-      {
-        method: "POST",
-        body: JSON.stringify(request)
-      },
-      void 0,
-      void 0,
-      requestOptions
-    );
-  }
-  /**
-   * Submit multiple fraud events for scoring.
-   */
-  async scoreEventsBulk(requests, requestOptions) {
-    if (!Array.isArray(requests) || requests.length === 0) {
-      throw new ValidationError(
-        "Invalid bulk score request: at least one score request is required",
-        ["requests"]
-      );
-    }
-    requests.forEach((request, index) => this.validateScoreRequest(request, index));
-    return this.requestWithRetry(
-      "/api/v1/fraud/score/bulk",
-      {
-        method: "POST",
-        body: JSON.stringify(requests)
-      },
-      void 0,
-      void 0,
-      requestOptions
-    );
-  }
-  validateScoreRequest(request, index) {
-    const errors = [];
-    const prefix = index === void 0 ? "" : `requests[${index}].`;
-    if (!request.customer_id?.trim()) {
-      errors.push(`${prefix}customer_id is required`);
-    }
-    if (!request.sift_user_id?.trim()) {
-      errors.push(`${prefix}sift_user_id is required`);
-    }
-    if (!request.event_type?.trim()) {
-      errors.push(`${prefix}event_type is required`);
-    }
-    if (errors.length > 0) {
-      throw new ValidationError(`Invalid fraud score request: ${errors.join(", ")}`, errors);
-    }
-  }
-};
-
 // src/webhooks/handler.ts
 var WebhookHandler = class {
   constructor(config) {
     this.handlers = /* @__PURE__ */ new Map();
     this.anyHandlers = [];
+    this.seenEventIds = /* @__PURE__ */ new Map();
     this.secret = config.secret;
     this.tolerance = config.tolerance ?? 3e5;
+    this.replayProtection = config.replayProtection ?? true;
   }
   /**
    * Register a handler for a specific event type.
@@ -3455,7 +3441,7 @@ var WebhookHandler = class {
   async verifyAndParse(body, signature) {
     const isValid = await verifyWebhookSignature(body, signature, this.secret);
     if (!isValid) {
-      throw new Error("Invalid webhook signature");
+      throw new ValidationError("Invalid webhook signature", ["signature"]);
     }
     return this.parseAndValidate(body);
   }
@@ -3475,16 +3461,34 @@ var WebhookHandler = class {
   parseAndValidate(body) {
     const event = JSON.parse(body);
     if (!event.type || !event.id || !event.timestamp) {
-      throw new Error("Invalid webhook event: missing required fields (type, id, timestamp)");
+      throw new ValidationError("Invalid webhook event: missing required fields (type, id, timestamp)", ["type", "id", "timestamp"]);
     }
     if (this.tolerance > 0) {
       const eventTime = new Date(event.timestamp).getTime();
       const now = Date.now();
       if (Math.abs(now - eventTime) > this.tolerance) {
-        throw new Error(
-          `Webhook event timestamp is outside tolerance window (${this.tolerance}ms)`
+        throw new ValidationError(
+          `Webhook event timestamp is outside tolerance window (${this.tolerance}ms)`,
+          ["timestamp"]
+        );
+      }
+    }
+    if (this.replayProtection) {
+      if (this.seenEventIds.has(event.id)) {
+        throw new ValidationError(
+          `Duplicate webhook event: ${event.id} has already been processed`,
+          ["id"]
         );
       }
+      const now = Date.now();
+      this.seenEventIds.set(event.id, now);
+      if (this.seenEventIds.size > 1e3) {
+        for (const [id, seenAt] of this.seenEventIds) {
+          if (now - seenAt > this.tolerance) {
+            this.seenEventIds.delete(id);
+          }
+        }
+      }
     }
     return event;
   }
@@ -3517,6 +3521,8 @@ function createWebhookMiddleware(options) {
         res.status(401).json({ error: message });
       } else if (message.includes("tolerance") || message.includes("timestamp")) {
         res.status(400).json({ error: message });
+      } else if (message.includes("Duplicate")) {
+        res.status(409).json({ error: message });
       } else if (next) {
         next(error);
       } else {
@@ -3545,7 +3551,7 @@ function createNextWebhookHandler(options) {
       });
     } catch (error) {
       const message = error instanceof Error ? error.message : "Webhook processing failed";
-      const status = message.includes("signature") ? 401 : message.includes("tolerance") || message.includes("timestamp") ? 400 : 500;
+      const status = message.includes("signature") ? 401 : message.includes("tolerance") || message.includes("timestamp") ? 400 : message.includes("Duplicate") ? 409 : 500;
       return new Response(JSON.stringify({ error: message }), {
         status,
         headers: { "Content-Type": "application/json" }
@@ -3568,6 +3574,6 @@ function buildHandler(options) {
   return handler;
 }
 
-export { AuthenticationError, BaseClient, CGSError, CircuitBreaker, CircuitBreakerOpenError, ComplianceBlockedError, ComplianceClient, ComplianceError, DEFAULT_CURRENCY_RATES, FraudClient, GeolocationClient, KycClient, NetworkError, RateLimitError, RateLimitTracker, RiskProfileClient, SDK_VERSION, ServiceUnavailableError, TaxClient, TimeoutError, TransactionClient, ValidationError, VesantError, WebhookHandler, createConsoleLogger, createNextWebhookHandler, createWebhookMiddleware, decodeCipherText, generateCipherText, isCipherTextExpired, noopLogger, verifyWebhookSignature };
+export { AuthenticationError, BaseClient, CGSError, CircuitBreaker, CircuitBreakerOpenError, ComplianceBlockedError, ComplianceClient, ComplianceError, DEFAULT_CURRENCY_RATES, GeolocationClient, KYC_DECLINED_DESCRIPTIONS, KycClient, NetworkError, RateLimitError, RateLimitTracker, RiskProfileClient, SDK_VERSION, ServiceUnavailableError, TaxClient, TimeoutError, ValidationError, VesantError, WebhookHandler, createConsoleLogger, createNextWebhookHandler, createWebhookMiddleware, decodeCipherText, generateCipherText, isCipherTextExpired, noopLogger, sdkReasons, verifyWebhookSignature };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map