vesant-sdk 1.7.0-dev.a85efc5 → 1.7.0-dev.ab635a0

package/dist/index.mjs

@@ -1,3 +1,59 @@
+// src/core/auth.ts
+var StaticApiKeyProvider = class {
+  constructor(apiKey) {
+    this.apiKey = apiKey;
+  }
+  async getCredential() {
+    return this.apiKey ? { scheme: "Bearer", token: this.apiKey } : null;
+  }
+  canRefresh() {
+    return false;
+  }
+};
+var RefreshingTokenProvider = class {
+  constructor(opts) {
+    this.opts = opts;
+    this.cached = null;
+    this.inFlight = null;
+    this.skewMs = opts.skewMs ?? 3e4;
+    this.scheme = opts.scheme ?? "Bearer";
+    this.now = opts.now ?? (() => Date.now());
+  }
+  canRefresh() {
+    return true;
+  }
+  async getCredential(ctx) {
+    const forceRefresh = ctx?.forceRefresh ?? false;
+    if (!forceRefresh && this.cached && !this.isExpiring(this.cached)) {
+      return { scheme: this.scheme, token: this.cached.token };
+    }
+    const fresh = await this.refresh();
+    return { scheme: this.scheme, token: fresh.token };
+  }
+  isExpiring(token) {
+    if (token.expiresAt === void 0) {
+      return false;
+    }
+    return this.now() >= token.expiresAt - this.skewMs;
+  }
+  refresh() {
+    if (this.inFlight) {
+      return this.inFlight;
+    }
+    this.inFlight = (async () => {
+      try {
+        const fresh = await this.opts.fetchToken();
+        this.cached = fresh;
+        this.opts.onRotate?.({ expiresAt: fresh.expiresAt });
+        return fresh;
+      } finally {
+        this.inFlight = null;
+      }
+    })();
+    return this.inFlight;
+  }
+};
+
 // src/core/errors.ts
 var VesantError = class _VesantError extends Error {
   constructor(message, code, statusCode, details) {
@@ -322,6 +378,12 @@ var BaseClient = class {
     if (!config.tenantId?.trim()) {
       throw new ValidationError("tenantId is required and must be a non-empty string", ["tenantId"]);
     }
+    if (typeof fetch === "undefined") {
+      throw new VesantError(
+        "The Vesant SDK requires a global fetch (Node.js >= 18). Upgrade Node or provide a fetch polyfill.",
+        "RUNTIME_UNSUPPORTED"
+      );
+    }
     this.interceptors = config.interceptors || [];
     this.logger = config.logger || createConsoleLogger();
     let environment = config.environment;
@@ -340,11 +402,12 @@ var BaseClient = class {
       environment,
       headers: config.headers || {},
       timeout: config.timeout || 1e4,
-      retries: config.retries || 3,
+      retries: config.retries ?? 3,
       debug: config.debug || false,
       interceptors: this.interceptors,
       logger: this.logger
     };
+    this.authProvider = config.authProvider ?? (apiKey ? new StaticApiKeyProvider(apiKey) : void 0);
     if (config.circuitBreaker) {
       this.circuitBreaker = new CircuitBreaker(config.circuitBreaker);
     }
@@ -352,6 +415,19 @@ var BaseClient = class {
       this.rateLimitTracker = new RateLimitTracker();
     }
   }
+  /**
+   * Resolve the Idempotency-Key for a request. Mutating methods (POST/PUT/PATCH)
+   * get the caller-supplied key or a freshly minted UUID; non-mutating methods get
+   * none. requestWithRetry resolves this once and injects it so every retry reuses
+   * one key (letting the server dedup replays); a direct request() resolves per call.
+   */
+  resolveIdempotencyKey(method, requestOptions) {
+    const isMutating = ["POST", "PUT", "PATCH"].includes((method || "GET").toUpperCase());
+    if (!isMutating) {
+      return void 0;
+    }
+    return requestOptions?.idempotencyKey ?? generateUUID();
+  }
   /**
    * Make an HTTP request with timeout and error handling
    */
@@ -377,15 +453,20 @@ var BaseClient = class {
       ...this.config.headers,
       ...options.headers || {}
     };
-    if (this.config.apiKey) {
-      headers["Authorization"] = `Bearer ${this.config.apiKey}`;
+    const credential = await this.authProvider?.getCredential({
+      tenantId: this.config.tenantId,
+      requestId
+    });
+    if (credential) {
+      headers["Authorization"] = `${credential.scheme ?? "Bearer"} ${credential.token}`;
     }
     if (this.config.environment === "sandbox") {
       headers["X-Sandbox"] = "true";
     }
     const method = (options.method || "GET").toUpperCase();
-    if (["POST", "PUT", "PATCH"].includes(method)) {
-      headers["Idempotency-Key"] = requestOptions?.idempotencyKey || generateUUID();
+    const idempotencyKey = this.resolveIdempotencyKey(method, requestOptions);
+    if (idempotencyKey) {
+      headers["Idempotency-Key"] = idempotencyKey;
     }
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
@@ -406,10 +487,28 @@ var BaseClient = class {
       if (this.config.debug) {
         this.logger.debug(`${finalOptions.method || "GET"} ${endpoint}`);
       }
-      const response = await fetch(url, {
+      let response = await fetch(url, {
         ...finalOptions,
         signal: controller.signal
       });
+      if (response.status === 401 && this.authProvider?.canRefresh?.()) {
+        const refreshed = await this.authProvider.getCredential({
+          tenantId: this.config.tenantId,
+          requestId,
+          forceRefresh: true
+        });
+        if (refreshed) {
+          this.config.onCredentialRotated?.({ reason: "unauthorized" });
+          finalOptions = {
+            ...finalOptions,
+            headers: {
+              ...finalOptions.headers,
+              Authorization: `${refreshed.scheme ?? "Bearer"} ${refreshed.token}`
+            }
+          };
+          response = await fetch(url, { ...finalOptions, signal: controller.signal });
+        }
+      }
       clearTimeout(timeoutId);
       if (this.rateLimitTracker) {
         this.rateLimitTracker.updateFromHeaders(response.headers);
@@ -498,9 +597,11 @@ var BaseClient = class {
    */
   async requestWithRetry(endpoint, options = {}, serviceURL, retries = this.config.retries, requestOptions) {
     let lastError;
+    const idempotencyKey = this.resolveIdempotencyKey(options.method || "GET", requestOptions);
+    const attemptOptions = idempotencyKey ? { ...requestOptions, idempotencyKey } : requestOptions;
     for (let attempt = 0; attempt <= retries; attempt++) {
       try {
-        return await this.request(endpoint, options, serviceURL, requestOptions);
+        return await this.request(endpoint, options, serviceURL, attemptOptions);
       } catch (error) {
         lastError = error instanceof Error ? error : new Error("Unknown error");
         if (requestOptions?.signal?.aborted) {
@@ -597,6 +698,9 @@ var BaseClient = class {
     if (config.interceptors) {
       this.interceptors = config.interceptors;
     }
+    if (config.authProvider !== void 0 || config.apiKey !== void 0) {
+      this.authProvider = this.config.authProvider ?? (this.config.apiKey ? new StaticApiKeyProvider(this.config.apiKey) : void 0);
+    }
   }
   /**
    * Get current configuration (readonly)
@@ -624,8 +728,69 @@ var BaseClient = class {
   }
 };
 
+// src/core/pagination.ts
+async function* paginate(fetchPage) {
+  let page = 1;
+  let totalPages;
+  do {
+    const response = await fetchPage(page);
+    const items = response.data ?? [];
+    for (const item of items) {
+      yield item;
+    }
+    totalPages = response.total_pages ?? page;
+    if (items.length === 0) {
+      break;
+    }
+    page += 1;
+  } while (page <= totalPages);
+}
+async function collectAll(fetchPage) {
+  const items = [];
+  for await (const item of paginate(fetchPage)) {
+    items.push(item);
+  }
+  return items;
+}
+
+// src/core/dedup.ts
+var InMemoryDedupStore = class {
+  constructor(opts = {}) {
+    this.expiryById = /* @__PURE__ */ new Map();
+    this.maxEntries = opts.maxEntries ?? 1e3;
+    this.now = opts.now ?? (() => Date.now());
+  }
+  async seen(id) {
+    return this.expiryById.has(id);
+  }
+  async mark(id, ttlMs) {
+    const now = this.now();
+    this.expiryById.set(id, now + ttlMs);
+    if (this.expiryById.size > this.maxEntries) {
+      for (const [key, expiresAt] of this.expiryById) {
+        if (now > expiresAt) {
+          this.expiryById.delete(key);
+        }
+      }
+    }
+  }
+};
+
 // src/core/webhook-utils.ts
-async function verifyWebhookSignature(payload, signature, secret) {
+async function verifyWebhookSignature(payload, signature, secret, opts = {}) {
+  const signed = parseSignedTimestamp(signature);
+  if (signed) {
+    const tolerance = opts.tolerance ?? 3e5;
+    const now = opts.now?.() ?? Date.now();
+    if (tolerance > 0 && Math.abs(now - signed.t * 1e3) > tolerance) {
+      return false;
+    }
+    const expected = await computeHmacSha256(`${signed.t}.${payload}`, secret);
+    return constantTimeEqual(signed.v1, expected);
+  }
+  if (opts.allowLegacy === false) {
+    return false;
+  }
   const hexDigest = await computeHmacSha256(payload, secret);
   const expectedPrefixed = `sha256=${hexDigest}`;
   if (signature.startsWith("sha256=")) {
@@ -633,6 +798,25 @@ async function verifyWebhookSignature(payload, signature, secret) {
   }
   return constantTimeEqual(signature, hexDigest);
 }
+function parseSignedTimestamp(signature) {
+  if (!signature.includes("t=") || !signature.includes("v1=")) {
+    return null;
+  }
+  let t;
+  let v1;
+  for (const part of signature.split(",")) {
+    const eq = part.indexOf("=");
+    if (eq === -1) continue;
+    const key = part.slice(0, eq).trim();
+    const value = part.slice(eq + 1).trim();
+    if (key === "t") t = Number(value);
+    else if (key === "v1") v1 = value;
+  }
+  if (t === void 0 || Number.isNaN(t) || !v1) {
+    return null;
+  }
+  return { t, v1 };
+}
 async function computeHmacSha256(message, secret) {
   if (typeof globalThis.crypto !== "undefined" && globalThis.crypto.subtle) {
     const encoder = new TextEncoder();
@@ -667,6 +851,61 @@ function constantTimeEqual(a, b) {
   return result === 0;
 }
 
+// src/geolocation/integrity.ts
+var isNil = (v) => v === null || v === void 0;
+function assessGpsIntegrity(input, opts = {}) {
+  const flags = [];
+  const now = opts.now ?? (() => Date.now());
+  const maxAgeMs = opts.maxAgeMs ?? 6e4;
+  const minAccuracy = opts.minAccuracyMeters ?? 1;
+  const { accuracy, altitude, altitudeAccuracy, heading, speed, timestamp } = input;
+  if (isNil(accuracy)) {
+    flags.push("accuracy_missing");
+  } else if (accuracy === 0) {
+    flags.push("accuracy_zero");
+  } else if (accuracy < minAccuracy) {
+    flags.push("accuracy_implausibly_small");
+  }
+  const hasMotion = !isNil(heading) || !isNil(speed);
+  if (hasMotion && (isNil(accuracy) || accuracy === 0)) {
+    flags.push("motion_without_accuracy");
+  }
+  if (!isNil(altitude) && isNil(altitudeAccuracy)) {
+    flags.push("altitude_without_accuracy");
+  }
+  if (timestamp !== void 0 && now() - timestamp > maxAgeMs) {
+    flags.push("stale_timestamp");
+  }
+  if (opts.permissionState === "denied" || opts.permissionState === "prompt") {
+    flags.push(`permission_${opts.permissionState}`);
+  }
+  return { suspicious: flags.length > 0, flags };
+}
+function gpsIntegrityInputFromPosition(position) {
+  const c = position.coords;
+  return {
+    latitude: c.latitude,
+    longitude: c.longitude,
+    accuracy: c.accuracy,
+    altitude: c.altitude,
+    altitudeAccuracy: c.altitudeAccuracy,
+    heading: c.heading,
+    speed: c.speed,
+    timestamp: position.timestamp
+  };
+}
+async function probeGeolocationPermission() {
+  try {
+    if (typeof navigator === "undefined" || !navigator.permissions?.query) {
+      return "unavailable";
+    }
+    const status = await navigator.permissions.query({ name: "geolocation" });
+    return status.state;
+  } catch {
+    return "unavailable";
+  }
+}
+
 // src/geolocation/ciphertext.ts
 var CIPHER_TEXT_EXPIRY_MINUTES = 5;
 async function computeHMAC(key, message) {
@@ -719,6 +958,7 @@ async function requestGPSLocation(timeout = 1e4, highAccuracy = true) {
   if (typeof navigator === "undefined" || !navigator.geolocation) {
     return null;
   }
+  const permissionState = await probeGeolocationPermission();
   return new Promise((resolve) => {
     navigator.geolocation.getCurrentPosition(
       (position) => {
@@ -735,6 +975,7 @@ async function requestGPSLocation(timeout = 1e4, highAccuracy = true) {
           resolve(null);
           return;
         }
+        const { flags } = assessGpsIntegrity(gpsIntegrityInputFromPosition(position), { permissionState });
         resolve({
           latitude,
           longitude,
@@ -743,7 +984,8 @@ async function requestGPSLocation(timeout = 1e4, highAccuracy = true) {
           altitude_accuracy: position.coords.altitudeAccuracy ?? void 0,
           heading: position.coords.heading ?? void 0,
           speed: position.coords.speed ?? void 0,
-          timestamp: position.timestamp
+          timestamp: position.timestamp,
+          integrity_flags: flags.length ? flags : void 0
         });
       },
       () => {
@@ -810,6 +1052,9 @@ async function generateCipherText(options, config) {
     );
     if (location) {
       locationData = location;
+      if (location.integrity_flags?.length) {
+        warnings.push(`GPS integrity flags (advisory): ${location.integrity_flags.join(", ")}`);
+      }
     } else if (gpsRequiredByConfig) {
       throw new VesantError(
         `GPS location is required for ${options.reason} by tenant configuration, but GPS was not available or permission was denied`,
@@ -929,8 +1174,8 @@ var GeolocationClient = class extends BaseClient {
    * ```
    */
   async verifyIP(request, requestOptions) {
-    if (!request.ip_address?.trim()) {
-      throw new ValidationError("ip_address is required and must be a non-empty string", ["ip_address"]);
+    if (request.ip_address !== void 0 && !request.ip_address.trim()) {
+      throw new ValidationError("ip_address, when provided, must be a non-empty string", ["ip_address"]);
     }
     return this.requestWithRetry("/api/v1/geo/verify", {
       method: "POST",
@@ -1280,20 +1525,12 @@ var GeolocationClient = class extends BaseClient {
    *
    * @example
    * ```typescript
-   * // Using GPS (preferred)
+   * // GPS (the web SDK is GPS + IP only; the server handles the IP fallback)
    * const result = await client.captureLocation(token, {
    *   latitude: 37.7749,
    *   longitude: -122.4194,
    *   accuracy: 10
    * });
-   *
-   * // Using WiFi positioning (fallback)
-   * const result = await client.captureLocation(token, {
-   *   wifi_networks: [
-   *     { macAddress: "00:11:22:33:44:55", signalStrength: -50 },
-   *     { macAddress: "AA:BB:CC:DD:EE:FF", signalStrength: -70 }
-   *   ]
-   * });
    * ```
    */
   async captureLocation(token, capture, requestOptions) {
@@ -2707,7 +2944,13 @@ 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, optional redirect URL, and optional callback URL (receives POST requests)
+   * Optionally pass the customer's registered identity data as
+   * `customer_data` (same shape as the geolocation `customer_data` block).
+   * It seeds the customer's risk profile so document verification can
+   * cross-check the submitted document against trusted reference data;
+   * fields never overwrite data already on the profile.
+   *
+   * @param request - Request containing the user ID, optional redirect URL, optional callback URL (receives POST requests), and optional customer identity data
    * @returns Response containing the redirect link and KYC ID
    *
    * @example
@@ -2715,19 +2958,27 @@ var KycClient = class extends BaseClient {
    * const result = await client.requestKycSubmitLink({
    *   user_id: "user_123",
    *   redirect_url: "https://merchant.com/kyc-complete", // optional
-   *   callback_url: "https://merchant.com/api/kyc-webhook" // optional - receives POST requests on status change
+   *   callback_url: "https://merchant.com/api/kyc-webhook", // optional - receives POST requests on status change
+   *   customer_data: { // optional - seeds the risk profile for document cross-checks
+   *     full_name: "John Doe",
+   *     date_of_birth: "1999-06-02", // ISO 8601
+   *     email: "john@example.com",
+   *     phone: "+94771234567",
+   *     address: "12 Main St, Colombo", // used for address verification
+   *     country: "LK"
+   *   }
    * });
    *
    * console.log(`Redirect user to: ${result.link}`);
    * console.log(`KYC ID: ${result.kyc_id}`);
    * ```
    */
-  async requestKycSubmitLink(request) {
+  async requestKycSubmitLink(request, requestOptions) {
     return this.requestWithRetry("/api/v1/kyc/request", {
       method: "POST",
       body: JSON.stringify(request),
       headers: this.getUserHeaders()
-    });
+    }, void 0, void 0, requestOptions);
   }
   /**
    * Create a Event-Based Face Verification session.
@@ -2760,12 +3011,12 @@ var KycClient = class extends BaseClient {
    *
    * @param request - Token from `createEventBasedFaceVerificationSession`, plus the base64 selfie.
    */
-  async submitEventBasedFaceVerificationSession(request) {
+  async submitEventBasedFaceVerificationSession(request, requestOptions) {
     return this.request("/api/v1/kyc/face/submit", {
       method: "POST",
       body: JSON.stringify(request),
       headers: this.getUserHeaders()
-    });
+    }, void 0, requestOptions);
   }
   /**
    * Look up the current state of a Event-Based Face Verification session by its
@@ -2881,12 +3132,12 @@ var KycClient = class extends BaseClient {
    * console.log(`Verification submitted: ${result.reference}`);
    * ```
    */
-  async submitVerification(request) {
+  async submitVerification(request, requestOptions) {
     return this.requestWithRetry("/api/v1/kyc/submit", {
       method: "POST",
       body: JSON.stringify(request),
       headers: this.getUserHeaders()
-    });
+    }, void 0, void 0, requestOptions);
   }
   /**
    * Get a KYC request by ID
@@ -3326,10 +3577,13 @@ var TaxClient = class extends BaseClient {
       { method: "POST" }
     );
   }
-  async checkTINStatus(customerID) {
+  async checkTINStatus(customerID, requestOptions) {
     return this.requestWithRetry(
       `/api/v1/tax/customer-tax-profiles/${customerID}/check-tin`,
-      { method: "POST" }
+      { method: "POST" },
+      void 0,
+      void 0,
+      requestOptions
     );
   }
   async reRequestTaxForm(customerID, input) {
@@ -3410,14 +3664,24 @@ var TaxClient = class extends BaseClient {
 };
 
 // src/webhooks/handler.ts
+function resolveEventId(event) {
+  if (event.id) {
+    return event.id;
+  }
+  if (event.event_type === "notification.created") {
+    return event.notification?.id;
+  }
+  return void 0;
+}
 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;
+    this.allowLegacySignature = config.allowLegacySignature ?? true;
+    this.dedupStore = config.dedupStore ?? new InMemoryDedupStore();
   }
   /**
    * Register a handler for a specific event type.
@@ -3439,7 +3703,10 @@ var WebhookHandler = class {
    * Verify signature and parse the webhook body.
    */
   async verifyAndParse(body, signature) {
-    const isValid = await verifyWebhookSignature(body, signature, this.secret);
+    const isValid = await verifyWebhookSignature(body, signature, this.secret, {
+      tolerance: this.tolerance,
+      allowLegacy: this.allowLegacySignature
+    });
     if (!isValid) {
       throw new ValidationError("Invalid webhook signature", ["signature"]);
     }
@@ -3455,18 +3722,21 @@ var WebhookHandler = class {
   /**
    * Parse an event without signature verification (for testing).
    */
-  parseEvent(body) {
+  async parseEvent(body) {
     return this.parseAndValidate(body);
   }
-  parseAndValidate(body) {
+  async parseAndValidate(body) {
     const event = JSON.parse(body);
-    if (!event.type || !event.id || !event.timestamp) {
-      throw new ValidationError("Invalid webhook event: missing required fields (type, id, timestamp)", ["type", "id", "timestamp"]);
+    const eventId = resolveEventId(event);
+    if (!event.event_type || !eventId || !event.timestamp) {
+      throw new ValidationError(
+        "Invalid webhook event: missing required fields (event_type, id, timestamp)",
+        ["event_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) {
+      if (Math.abs(Date.now() - eventTime) > this.tolerance) {
         throw new ValidationError(
           `Webhook event timestamp is outside tolerance window (${this.tolerance}ms)`,
           ["timestamp"]
@@ -3474,26 +3744,18 @@ var WebhookHandler = class {
       }
     }
     if (this.replayProtection) {
-      if (this.seenEventIds.has(event.id)) {
+      if (await this.dedupStore.seen(eventId)) {
         throw new ValidationError(
-          `Duplicate webhook event: ${event.id} has already been processed`,
+          `Duplicate webhook event: ${eventId} 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);
-          }
-        }
-      }
+      await this.dedupStore.mark(eventId, this.tolerance);
     }
     return event;
   }
   async dispatch(event) {
-    const typeHandlers = this.handlers.get(event.type) || [];
+    const typeHandlers = this.handlers.get(event.event_type) || [];
     const allHandlers = [...typeHandlers, ...this.anyHandlers];
     for (const handler of allHandlers) {
       await handler(event);
@@ -3574,6 +3836,6 @@ function buildHandler(options) {
   return handler;
 }
 
-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 };
+export { AuthenticationError, BaseClient, CGSError, CircuitBreaker, CircuitBreakerOpenError, ComplianceBlockedError, ComplianceClient, ComplianceError, DEFAULT_CURRENCY_RATES, GeolocationClient, InMemoryDedupStore, KYC_DECLINED_DESCRIPTIONS, KycClient, NetworkError, RateLimitError, RateLimitTracker, RefreshingTokenProvider, RiskProfileClient, SDK_VERSION, ServiceUnavailableError, StaticApiKeyProvider, TaxClient, TimeoutError, ValidationError, VesantError, WebhookHandler, assessGpsIntegrity, collectAll, createConsoleLogger, createNextWebhookHandler, createWebhookMiddleware, decodeCipherText, generateCipherText, gpsIntegrityInputFromPosition, isCipherTextExpired, noopLogger, paginate, probeGeolocationPermission, sdkReasons, verifyWebhookSignature };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map