vesant-sdk 1.6.6 → 1.7.0-dev.e0ee6d5

package/dist/compliance/index.js

@@ -1,5 +1,80 @@
 'use strict';
 
+// 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/core/errors.ts
 var VesantError = class _VesantError extends Error {
   constructor(message, code, statusCode, details) {
@@ -224,7 +299,7 @@ function createConsoleLogger() {
 }
 
 // src/core/version.ts
-var SDK_VERSION = "1.6.6";
+var SDK_VERSION = "1.7.0";
 
 // src/shared/browser-utils.ts
 function generateUUID() {
@@ -727,7 +802,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 = [];
@@ -752,8 +827,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");
@@ -847,10 +923,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);
   }
   /**
@@ -1075,6 +1150,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 ?? "",
@@ -1254,24 +1330,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 {
@@ -1534,10 +1592,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,
@@ -1545,9 +1603,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({
@@ -1581,14 +1637,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"
         });
       }
@@ -1617,52 +1671,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
@@ -1833,9 +1897,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;
@@ -1855,14 +1917,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);
@@ -1944,20 +2005,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) {
@@ -1977,20 +2037,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);
@@ -2043,30 +2102,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);
   }
@@ -2143,7 +2214,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 ?? "",
@@ -2158,35 +2230,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;
@@ -2195,7 +2267,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
     };
@@ -2220,52 +2293,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
@@ -2485,5 +2568,6 @@ var ComplianceClient = class {
 
 exports.ComplianceClient = ComplianceClient;
 exports.DEFAULT_CURRENCY_RATES = DEFAULT_CURRENCY_RATES;
+exports.sdkReasons = sdkReasons;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map