vesant-sdk 1.7.0 → 1.7.1-dev.ec505dc

package/dist/{client-DtH2RLuy.d.ts → client-BY4Quazn.d.ts}

@@ -1,6 +1,6 @@
-import { D as DeviceFingerprintRequest, L as LocationVerification, V as ValidateCipherTextResponse, a as LocationRequest, G as GeolocationClient, b as LocationRequestFilters, c as LocationRequestListResponse } from './client-DF7hlMEz.js';
+import { D as DeviceFingerprintRequest, L as LocationVerification, V as ValidateCipherTextResponse, a as LocationRequest, G as GeolocationClient, b as LocationRequestFilters, c as LocationRequestListResponse } from './client-C-u9lE8N.js';
 import { RiskProfileClient } from './risk-profile/index.js';
-import { V as VesantConfig, R as RequestOptions } from './client-BolQlL5e.js';
+import { V as VesantConfig, R as RequestOptions } from './client-q9fN8Hhf.js';
 import { C as CustomerProfile } from './types-UGyDl1fd.js';
 import { E as EntityType, B as BlockReason, P as PaginationParams } from './types-CBQRNL-l.js';
 

package/dist/{client-DF7hlMEz.d.ts → client-C-u9lE8N.d.ts}

@@ -1,4 +1,4 @@
-import { L as Logger, B as BaseClient, R as RequestOptions } from './client-BolQlL5e.js';
+import { L as Logger, B as BaseClient, R as RequestOptions } from './client-q9fN8Hhf.js';
 import { B as BlockReason, P as PaginationParams } from './types-CBQRNL-l.js';
 
 interface DeviceFingerprintRequest {
@@ -47,6 +47,8 @@ interface CipherTextPayload {
         heading?: number;
         speed?: number;
         timestamp: number;
+        /** Advisory client-side GPS integrity flags; the server weighs these as risk factors. */
+        integrity_flags?: string[];
     };
     /** Network information */
     network?: {
@@ -74,9 +76,12 @@ type CipherTextReason = 'registration' | 'login' | 'transaction' | 'interval_che
 interface CipherTextOptions {
     /** Reason for collection (required) */
     reason: CipherTextReason;
-    /** Public signing key (pk_) for HMAC signing (produces v02 signed cipherText) */
+    /**
+     * @deprecated No longer used and ignored; envelope validation is handled by the
+     * server. This field will be removed in a future release.
+     */
     signingKey?: string;
-    /** @deprecated Use signingKey instead. API key for HMAC signing (backward compat) */
+    /** @deprecated No longer used and ignored; see signingKey. */
     apiKey?: string;
     /** Request GPS location (default: false) */
     requestLocation?: boolean;
@@ -106,6 +111,11 @@ interface CipherTextResult {
     /** Expiry time for the cipherText */
     expiresAt: string;
 }
+/**
+ * Honest name for CipherTextResult: a base64 JSON device-signals envelope
+ * (not encryption). Prefer this name; `CipherTextResult` remains as an alias.
+ */
+type DeviceSignalsEnvelope = CipherTextResult;
 /**
  * Decrypted cipherText data (returned by server after validation)
  */
@@ -227,7 +237,11 @@ interface ValidateCipherTextResponse {
     };
 }
 interface VerifyIPRequest {
-    ip_address: string;
+    /**
+     * Optional. Omit to let the server derive the connecting IP — the SDK never
+     * asserts the client IP (spoofable, and the server extracts it authoritatively).
+     */
+    ip_address?: string;
     user_id: string;
     event_type: string;
     device_fingerprint?: DeviceFingerprintRequest;
@@ -483,7 +497,9 @@ interface GeolocationConfigResponse {
     };
     /** When true, GPS-verified location overrides anonymizer-based blocking */
     trust_gps_over_anonymizer: boolean;
-    /** Public signing key (pk_) for client-side HMAC signing */
+    /**
+     * @deprecated No longer used by the SDK and ignored if present.
+     */
     signing_key?: string;
 }
 interface GeolocationClientConfig {
@@ -624,16 +640,6 @@ interface ResendLocationRequestRequest {
     email?: string;
     phone?: string;
 }
-interface WiFiNetwork {
-    /** MAC address (BSSID) */
-    macAddress: string;
-    /** Signal strength in dBm (negative number) */
-    signalStrength?: number;
-    /** WiFi channel */
-    channel?: number;
-    /** Network name (optional) */
-    ssid?: string;
-}
 interface LocationCaptureRequest {
     /** GPS latitude (if available) */
     latitude?: number;
@@ -641,8 +647,8 @@ interface LocationCaptureRequest {
     longitude?: number;
     /** GPS accuracy in meters */
     accuracy?: number;
-    /** WiFi networks for positioning (if GPS not available) */
-    wifi_networks?: WiFiNetwork[];
+    /** Advisory client-side GPS integrity flags; the server weighs these as risk factors. */
+    integrity_flags?: string[];
     /** User agent string */
     user_agent?: string;
     /** Device metadata */
@@ -662,6 +668,10 @@ interface LocationShareInfo {
     status: string;
     is_expired: boolean;
     is_completed: boolean;
+    /**
+     * Server-only hint. The web SDK cannot enumerate WiFi networks (no browser API
+     * for BSSIDs); this flag is informational and never satisfied client-side.
+     */
     requires_wifi: boolean;
 }
 interface LocationCaptureResponse {
@@ -730,8 +740,6 @@ interface UseLocationCaptureOptions {
     autoFetch?: boolean;
     /** Auto-request GPS permission on mount */
     autoRequestGPS?: boolean;
-    /** Collect WiFi data as fallback (requires explicit permission) */
-    collectWiFi?: boolean;
 }
 interface UseLocationCaptureResult {
     /** Location share info */
@@ -774,7 +782,6 @@ interface UseLocationCaptureResult {
  * transient failures gracefully.
  */
 declare class GeolocationClient extends BaseClient {
-    private cachedSigningKey?;
     constructor(config: GeolocationClientConfig);
     /**
      * Verify an IP address and check compliance
@@ -835,15 +842,6 @@ declare class GeolocationClient extends BaseClient {
      * ```
      */
     getGPSConfig(requestOptions?: RequestOptions): Promise<GeolocationConfigResponse>;
-    /**
-     * Fetch the signing key from the dedicated authenticated endpoint.
-     *
-     * Falls back to getGPSConfig() for backward compatibility with older servers
-     * that don't expose `/api/v1/geo/signing-key`.
-     *
-     * @returns The signing key string, or undefined if unavailable
-     */
-    fetchSigningKey(requestOptions?: RequestOptions): Promise<string | undefined>;
     /**
      * Validate a cipherText generated by the frontend SDK
      *
@@ -995,40 +993,30 @@ declare class GeolocationClient 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 }
-     *   ]
-     * });
      * ```
      */
     captureLocation(token: string, capture: LocationCaptureRequest, requestOptions?: RequestOptions): Promise<LocationCaptureResponse>;
     /**
-     * Generate a signed cipherText containing device and location data.
-     *
-     * Automatically passes the client's API key for HMAC signing (v02 format).
-     * If no API key is configured, falls back to unsigned v01 format.
+     * Generate a device-signals envelope containing device and location data,
+     * validated by the server.
      *
-     * @param options - Options for cipherText generation
+     * @param options - Options for envelope generation
      * @param gpsConfig - Optional GPS config (from getGPSConfig)
-     * @returns CipherText result with the signed string
+     * @returns The device-signals envelope result
      *
      * @example
      * ```typescript
      * const result = await client.generateCipherText({ reason: 'login' });
-     * console.log(result.cipherText); // v02 signed cipherText
+     * console.log(result.cipherText); // device-signals envelope
      * ```
      */
     generateCipherText(options: Omit<CipherTextOptions, 'apiKey' | 'signingKey'>, gpsConfig?: GeolocationConfigResponse): Promise<CipherTextResult>;
 }
 
-export { type UseLocationRequestsResult as $, type APIError as A, type GeolocationClientConfig as B, type CipherTextCustomerData as C, type DeviceFingerprintRequest as D, type GeolocationConfigResponse as E, type GeolocationRecord as F, GeolocationClient as G, type LocationCaptureRequest as H, type LocationCaptureResponse as I, type JurisdictionConfig as J, type LocationRequestChannel as K, type LocationVerification as L, type LocationRequestResult as M, type LocationRequestStatus as N, type LocationShareInfo as O, type UpdateGeofenceRuleRequest as P, type UpdateJurisdictionRequest as Q, type ResendLocationRequestRequest as R, type UseAlertsOptions as S, type UseAlertsResult as T, type UpdateDeviceTrustRequest as U, type ValidateCipherTextResponse as V, type UseGeolocationOptions as W, type UseGeolocationResult as X, type UseLocationCaptureOptions as Y, type UseLocationCaptureResult as Z, type UseLocationRequestsOptions as _, type LocationRequest as a, type ValidateCipherTextRequest as a0, type VerifyIPRequest as a1, type WiFiNetwork as a2, type LocationRequestFilters as b, type LocationRequestListResponse as c, type AlertFilters as d, type AlertListResponse as e, type AlertSeverity as f, type AlertStatus as g, type AlertType as h, type CipherTextOptions as i, type CipherTextPayload as j, type CipherTextReason as k, type CipherTextResult as l, type ComplianceCheckResponse as m, type CreateGeofenceRuleRequest as n, type CreateJurisdictionRequest as o, type CreateLocationRequestRequest as p, type DashboardMetrics as q, type DecryptedCipherText as r, type DeviceFingerprint as s, type DeviceTrustResult as t, type GeoIPResult as u, type GeofenceAction as v, type GeofenceEvaluation as w, type GeofenceRule as x, type GeofenceRuleType as y, type GeolocationAlert as z };
+export { type UseLocationRequestsOptions as $, type APIError as A, type GeolocationAlert as B, type CipherTextCustomerData as C, type DeviceFingerprintRequest as D, type GeolocationClientConfig as E, type GeolocationConfigResponse as F, GeolocationClient as G, type GeolocationRecord as H, type LocationCaptureRequest as I, type JurisdictionConfig as J, type LocationCaptureResponse as K, type LocationVerification as L, type LocationRequestChannel as M, type LocationRequestResult as N, type LocationRequestStatus as O, type LocationShareInfo as P, type UpdateGeofenceRuleRequest as Q, type ResendLocationRequestRequest as R, type UpdateJurisdictionRequest as S, type UseAlertsOptions as T, type UpdateDeviceTrustRequest as U, type ValidateCipherTextResponse as V, type UseAlertsResult as W, type UseGeolocationOptions as X, type UseGeolocationResult as Y, type UseLocationCaptureOptions as Z, type UseLocationCaptureResult as _, type LocationRequest as a, type UseLocationRequestsResult as a0, type ValidateCipherTextRequest as a1, type VerifyIPRequest as a2, type LocationRequestFilters as b, type LocationRequestListResponse as c, type AlertFilters as d, type AlertListResponse as e, type AlertSeverity as f, type AlertStatus as g, type AlertType as h, type CipherTextOptions as i, type CipherTextPayload as j, type CipherTextReason as k, type CipherTextResult as l, type ComplianceCheckResponse as m, type CreateGeofenceRuleRequest as n, type CreateJurisdictionRequest as o, type CreateLocationRequestRequest as p, type DashboardMetrics as q, type DecryptedCipherText as r, type DeviceFingerprint as s, type DeviceSignalsEnvelope as t, type DeviceTrustResult as u, type GeoIPResult as v, type GeofenceAction as w, type GeofenceEvaluation as x, type GeofenceRule as y, type GeofenceRuleType as z };

package/dist/{client-B0qhE2kr.d.mts → client-CX1jcLNZ.d.mts}

@@ -1,6 +1,6 @@
-import { D as DeviceFingerprintRequest, L as LocationVerification, V as ValidateCipherTextResponse, a as LocationRequest, G as GeolocationClient, b as LocationRequestFilters, c as LocationRequestListResponse } from './client-DrjgZoH_.mjs';
+import { D as DeviceFingerprintRequest, L as LocationVerification, V as ValidateCipherTextResponse, a as LocationRequest, G as GeolocationClient, b as LocationRequestFilters, c as LocationRequestListResponse } from './client-Yxat9wAO.mjs';
 import { RiskProfileClient } from './risk-profile/index.mjs';
-import { V as VesantConfig, R as RequestOptions } from './client-BolQlL5e.mjs';
+import { V as VesantConfig, R as RequestOptions } from './client-q9fN8Hhf.mjs';
 import { C as CustomerProfile } from './types-BOFaMQxI.mjs';
 import { E as EntityType, B as BlockReason, P as PaginationParams } from './types-CBQRNL-l.mjs';
 

package/dist/{client-DrjgZoH_.d.mts → client-Yxat9wAO.d.mts}

@@ -1,4 +1,4 @@
-import { L as Logger, B as BaseClient, R as RequestOptions } from './client-BolQlL5e.mjs';
+import { L as Logger, B as BaseClient, R as RequestOptions } from './client-q9fN8Hhf.mjs';
 import { B as BlockReason, P as PaginationParams } from './types-CBQRNL-l.mjs';
 
 interface DeviceFingerprintRequest {
@@ -47,6 +47,8 @@ interface CipherTextPayload {
         heading?: number;
         speed?: number;
         timestamp: number;
+        /** Advisory client-side GPS integrity flags; the server weighs these as risk factors. */
+        integrity_flags?: string[];
     };
     /** Network information */
     network?: {
@@ -74,9 +76,12 @@ type CipherTextReason = 'registration' | 'login' | 'transaction' | 'interval_che
 interface CipherTextOptions {
     /** Reason for collection (required) */
     reason: CipherTextReason;
-    /** Public signing key (pk_) for HMAC signing (produces v02 signed cipherText) */
+    /**
+     * @deprecated No longer used and ignored; envelope validation is handled by the
+     * server. This field will be removed in a future release.
+     */
     signingKey?: string;
-    /** @deprecated Use signingKey instead. API key for HMAC signing (backward compat) */
+    /** @deprecated No longer used and ignored; see signingKey. */
     apiKey?: string;
     /** Request GPS location (default: false) */
     requestLocation?: boolean;
@@ -106,6 +111,11 @@ interface CipherTextResult {
     /** Expiry time for the cipherText */
     expiresAt: string;
 }
+/**
+ * Honest name for CipherTextResult: a base64 JSON device-signals envelope
+ * (not encryption). Prefer this name; `CipherTextResult` remains as an alias.
+ */
+type DeviceSignalsEnvelope = CipherTextResult;
 /**
  * Decrypted cipherText data (returned by server after validation)
  */
@@ -227,7 +237,11 @@ interface ValidateCipherTextResponse {
     };
 }
 interface VerifyIPRequest {
-    ip_address: string;
+    /**
+     * Optional. Omit to let the server derive the connecting IP — the SDK never
+     * asserts the client IP (spoofable, and the server extracts it authoritatively).
+     */
+    ip_address?: string;
     user_id: string;
     event_type: string;
     device_fingerprint?: DeviceFingerprintRequest;
@@ -483,7 +497,9 @@ interface GeolocationConfigResponse {
     };
     /** When true, GPS-verified location overrides anonymizer-based blocking */
     trust_gps_over_anonymizer: boolean;
-    /** Public signing key (pk_) for client-side HMAC signing */
+    /**
+     * @deprecated No longer used by the SDK and ignored if present.
+     */
     signing_key?: string;
 }
 interface GeolocationClientConfig {
@@ -624,16 +640,6 @@ interface ResendLocationRequestRequest {
     email?: string;
     phone?: string;
 }
-interface WiFiNetwork {
-    /** MAC address (BSSID) */
-    macAddress: string;
-    /** Signal strength in dBm (negative number) */
-    signalStrength?: number;
-    /** WiFi channel */
-    channel?: number;
-    /** Network name (optional) */
-    ssid?: string;
-}
 interface LocationCaptureRequest {
     /** GPS latitude (if available) */
     latitude?: number;
@@ -641,8 +647,8 @@ interface LocationCaptureRequest {
     longitude?: number;
     /** GPS accuracy in meters */
     accuracy?: number;
-    /** WiFi networks for positioning (if GPS not available) */
-    wifi_networks?: WiFiNetwork[];
+    /** Advisory client-side GPS integrity flags; the server weighs these as risk factors. */
+    integrity_flags?: string[];
     /** User agent string */
     user_agent?: string;
     /** Device metadata */
@@ -662,6 +668,10 @@ interface LocationShareInfo {
     status: string;
     is_expired: boolean;
     is_completed: boolean;
+    /**
+     * Server-only hint. The web SDK cannot enumerate WiFi networks (no browser API
+     * for BSSIDs); this flag is informational and never satisfied client-side.
+     */
     requires_wifi: boolean;
 }
 interface LocationCaptureResponse {
@@ -730,8 +740,6 @@ interface UseLocationCaptureOptions {
     autoFetch?: boolean;
     /** Auto-request GPS permission on mount */
     autoRequestGPS?: boolean;
-    /** Collect WiFi data as fallback (requires explicit permission) */
-    collectWiFi?: boolean;
 }
 interface UseLocationCaptureResult {
     /** Location share info */
@@ -774,7 +782,6 @@ interface UseLocationCaptureResult {
  * transient failures gracefully.
  */
 declare class GeolocationClient extends BaseClient {
-    private cachedSigningKey?;
     constructor(config: GeolocationClientConfig);
     /**
      * Verify an IP address and check compliance
@@ -835,15 +842,6 @@ declare class GeolocationClient extends BaseClient {
      * ```
      */
     getGPSConfig(requestOptions?: RequestOptions): Promise<GeolocationConfigResponse>;
-    /**
-     * Fetch the signing key from the dedicated authenticated endpoint.
-     *
-     * Falls back to getGPSConfig() for backward compatibility with older servers
-     * that don't expose `/api/v1/geo/signing-key`.
-     *
-     * @returns The signing key string, or undefined if unavailable
-     */
-    fetchSigningKey(requestOptions?: RequestOptions): Promise<string | undefined>;
     /**
      * Validate a cipherText generated by the frontend SDK
      *
@@ -995,40 +993,30 @@ declare class GeolocationClient 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 }
-     *   ]
-     * });
      * ```
      */
     captureLocation(token: string, capture: LocationCaptureRequest, requestOptions?: RequestOptions): Promise<LocationCaptureResponse>;
     /**
-     * Generate a signed cipherText containing device and location data.
-     *
-     * Automatically passes the client's API key for HMAC signing (v02 format).
-     * If no API key is configured, falls back to unsigned v01 format.
+     * Generate a device-signals envelope containing device and location data,
+     * validated by the server.
      *
-     * @param options - Options for cipherText generation
+     * @param options - Options for envelope generation
      * @param gpsConfig - Optional GPS config (from getGPSConfig)
-     * @returns CipherText result with the signed string
+     * @returns The device-signals envelope result
      *
      * @example
      * ```typescript
      * const result = await client.generateCipherText({ reason: 'login' });
-     * console.log(result.cipherText); // v02 signed cipherText
+     * console.log(result.cipherText); // device-signals envelope
      * ```
      */
     generateCipherText(options: Omit<CipherTextOptions, 'apiKey' | 'signingKey'>, gpsConfig?: GeolocationConfigResponse): Promise<CipherTextResult>;
 }
 
-export { type UseLocationRequestsResult as $, type APIError as A, type GeolocationClientConfig as B, type CipherTextCustomerData as C, type DeviceFingerprintRequest as D, type GeolocationConfigResponse as E, type GeolocationRecord as F, GeolocationClient as G, type LocationCaptureRequest as H, type LocationCaptureResponse as I, type JurisdictionConfig as J, type LocationRequestChannel as K, type LocationVerification as L, type LocationRequestResult as M, type LocationRequestStatus as N, type LocationShareInfo as O, type UpdateGeofenceRuleRequest as P, type UpdateJurisdictionRequest as Q, type ResendLocationRequestRequest as R, type UseAlertsOptions as S, type UseAlertsResult as T, type UpdateDeviceTrustRequest as U, type ValidateCipherTextResponse as V, type UseGeolocationOptions as W, type UseGeolocationResult as X, type UseLocationCaptureOptions as Y, type UseLocationCaptureResult as Z, type UseLocationRequestsOptions as _, type LocationRequest as a, type ValidateCipherTextRequest as a0, type VerifyIPRequest as a1, type WiFiNetwork as a2, type LocationRequestFilters as b, type LocationRequestListResponse as c, type AlertFilters as d, type AlertListResponse as e, type AlertSeverity as f, type AlertStatus as g, type AlertType as h, type CipherTextOptions as i, type CipherTextPayload as j, type CipherTextReason as k, type CipherTextResult as l, type ComplianceCheckResponse as m, type CreateGeofenceRuleRequest as n, type CreateJurisdictionRequest as o, type CreateLocationRequestRequest as p, type DashboardMetrics as q, type DecryptedCipherText as r, type DeviceFingerprint as s, type DeviceTrustResult as t, type GeoIPResult as u, type GeofenceAction as v, type GeofenceEvaluation as w, type GeofenceRule as x, type GeofenceRuleType as y, type GeolocationAlert as z };
+export { type UseLocationRequestsOptions as $, type APIError as A, type GeolocationAlert as B, type CipherTextCustomerData as C, type DeviceFingerprintRequest as D, type GeolocationClientConfig as E, type GeolocationConfigResponse as F, GeolocationClient as G, type GeolocationRecord as H, type LocationCaptureRequest as I, type JurisdictionConfig as J, type LocationCaptureResponse as K, type LocationVerification as L, type LocationRequestChannel as M, type LocationRequestResult as N, type LocationRequestStatus as O, type LocationShareInfo as P, type UpdateGeofenceRuleRequest as Q, type ResendLocationRequestRequest as R, type UpdateJurisdictionRequest as S, type UseAlertsOptions as T, type UpdateDeviceTrustRequest as U, type ValidateCipherTextResponse as V, type UseAlertsResult as W, type UseGeolocationOptions as X, type UseGeolocationResult as Y, type UseLocationCaptureOptions as Z, type UseLocationCaptureResult as _, type LocationRequest as a, type UseLocationRequestsResult as a0, type ValidateCipherTextRequest as a1, type VerifyIPRequest as a2, type LocationRequestFilters as b, type LocationRequestListResponse as c, type AlertFilters as d, type AlertListResponse as e, type AlertSeverity as f, type AlertStatus as g, type AlertType as h, type CipherTextOptions as i, type CipherTextPayload as j, type CipherTextReason as k, type CipherTextResult as l, type ComplianceCheckResponse as m, type CreateGeofenceRuleRequest as n, type CreateJurisdictionRequest as o, type CreateLocationRequestRequest as p, type DashboardMetrics as q, type DecryptedCipherText as r, type DeviceFingerprint as s, type DeviceSignalsEnvelope as t, type DeviceTrustResult as u, type GeoIPResult as v, type GeofenceAction as w, type GeofenceEvaluation as x, type GeofenceRule as y, type GeofenceRuleType as z };

package/dist/{client-BolQlL5e.d.mts → client-q9fN8Hhf.d.mts}

@@ -50,6 +50,80 @@ declare class CircuitBreaker {
     reset(): void;
 }
 
+/**
+ * Pluggable authentication for BaseClient.
+ *
+ * A TokenProvider supplies the credential used for the Authorization header on
+ * every request, resolved per-request (async) so callers can source short-lived
+ * or rotating credentials (OAuth2 client-credentials, STS, Vault / Secrets
+ * Manager) instead of a single static API key. The default StaticApiKeyProvider
+ * preserves the original `apiKey` behavior with zero change for existing callers.
+ */
+interface AuthCredential {
+    /** Authorization scheme (e.g. 'Bearer'); defaults to 'Bearer' when omitted. */
+    scheme?: string;
+    /** The credential value (bearer token / API key). */
+    token: string;
+}
+interface TokenProviderContext {
+    tenantId: string;
+    requestId: string;
+    /** When true, bypass any cache and obtain a fresh credential (e.g. after a 401). */
+    forceRefresh?: boolean;
+}
+interface TokenProvider {
+    /** Resolve the credential for a request, or null to send no Authorization header. */
+    getCredential(ctx: TokenProviderContext): Promise<AuthCredential | null>;
+    /** Whether this provider can obtain a fresh credential on demand (drives 401 retry). */
+    canRefresh?(): boolean;
+}
+/**
+ * Default provider: wraps a static API key. Returns null when the key is empty
+ * so the client sends no Authorization header, matching the pre-provider behavior.
+ */
+declare class StaticApiKeyProvider implements TokenProvider {
+    private readonly apiKey;
+    constructor(apiKey: string);
+    getCredential(): Promise<AuthCredential | null>;
+    canRefresh(): boolean;
+}
+interface CachedToken {
+    token: string;
+    expiresAt?: number;
+}
+interface RefreshingTokenProviderOptions {
+    /** Fetches a fresh token. `expiresAt` is epoch milliseconds (optional). */
+    fetchToken: () => Promise<CachedToken>;
+    /** Refresh this many ms before expiry (default: 30_000). */
+    skewMs?: number;
+    /** Authorization scheme to emit (default: 'Bearer'). */
+    scheme?: string;
+    /** Observe each successful (re)fetch — for logging / metrics. */
+    onRotate?: (meta: {
+        expiresAt?: number;
+    }) => void;
+    /** Injectable clock (default: Date.now). */
+    now?: () => number;
+}
+/**
+ * Caches a fetched token and refreshes it when it is within the skew window of
+ * expiry or when `forceRefresh` is requested. Concurrent refreshes are de-duped
+ * into a single in-flight fetch.
+ */
+declare class RefreshingTokenProvider implements TokenProvider {
+    private readonly opts;
+    private cached;
+    private inFlight;
+    private readonly skewMs;
+    private readonly scheme;
+    private readonly now;
+    constructor(opts: RefreshingTokenProviderOptions);
+    canRefresh(): boolean;
+    getCredential(ctx?: TokenProviderContext): Promise<AuthCredential | null>;
+    private isExpiring;
+    private refresh;
+}
+
 /**
  * Configuration types for Vesant SDK clients
  */
@@ -82,6 +156,16 @@ interface BaseClientConfig {
     tenantId: string;
     /** Optional API key for authentication */
     apiKey?: string;
+    /**
+     * Pluggable auth token provider. When set, it supplies the Authorization
+     * credential per-request (overriding `apiKey`), enabling OAuth2 / STS / rotating
+     * secrets and single-shot 401 re-auth. Defaults to a static-apiKey provider.
+     */
+    authProvider?: TokenProvider;
+    /** Observe credential rotation triggered by a 401 re-auth (logging / metrics). */
+    onCredentialRotated?: (meta: {
+        reason: string;
+    }) => void;
     /** Custom headers to include in all requests */
     headers?: Record<string, string>;
     /** Request timeout in milliseconds (default: 10000) */
@@ -108,6 +192,16 @@ interface VesantConfig {
     tenantId: string;
     /** Optional API key for authentication */
     apiKey?: string;
+    /**
+     * Pluggable auth token provider. When set, it supplies the Authorization
+     * credential per-request (overriding `apiKey`), enabling OAuth2 / STS / rotating
+     * secrets and single-shot 401 re-auth. Defaults to a static-apiKey provider.
+     */
+    authProvider?: TokenProvider;
+    /** Observe credential rotation triggered by a 401 re-auth (logging / metrics). */
+    onCredentialRotated?: (meta: {
+        reason: string;
+    }) => void;
     /** Custom headers to include in all requests */
     headers?: Record<string, string>;
     /** Request timeout in milliseconds (default: 10000) */
@@ -195,7 +289,15 @@ declare abstract class BaseClient {
     private interceptors;
     private circuitBreaker;
     private rateLimitTracker;
+    private authProvider;
     constructor(config: BaseClientConfig);
+    /**
+     * 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.
+     */
+    private resolveIdempotencyKey;
     /**
      * Make an HTTP request with timeout and error handling
      */
@@ -237,4 +339,4 @@ declare abstract class BaseClient {
     }>;
 }
 
-export { BaseClient as B, type CGSConfig as C, type Logger as L, type RequestOptions as R, type VesantConfig as V, type BaseClientConfig as a, CircuitBreaker as b, type CircuitBreakerConfig as c, type CircuitBreakerState as d, type CircuitBreakerStatus as e, type RateLimitStatus as f, RateLimitTracker as g, type RequestInterceptor as h, type RequiredBaseClientConfig as i, type RequiredCGSConfig as j, type RequiredVesantConfig as k };
+export { type AuthCredential as A, BaseClient as B, type CGSConfig as C, type Logger as L, type RequestOptions as R, StaticApiKeyProvider as S, type TokenProvider as T, type VesantConfig as V, type BaseClientConfig as a, CircuitBreaker as b, type CircuitBreakerConfig as c, type CircuitBreakerState as d, type CircuitBreakerStatus as e, type RateLimitStatus as f, RateLimitTracker as g, RefreshingTokenProvider as h, type RefreshingTokenProviderOptions as i, type RequestInterceptor as j, type RequiredBaseClientConfig as k, type RequiredCGSConfig as l, type RequiredVesantConfig as m, type TokenProviderContext as n };

package/dist/{client-BolQlL5e.d.ts → client-q9fN8Hhf.d.ts}

@@ -50,6 +50,80 @@ declare class CircuitBreaker {
     reset(): void;
 }
 
+/**
+ * Pluggable authentication for BaseClient.
+ *
+ * A TokenProvider supplies the credential used for the Authorization header on
+ * every request, resolved per-request (async) so callers can source short-lived
+ * or rotating credentials (OAuth2 client-credentials, STS, Vault / Secrets
+ * Manager) instead of a single static API key. The default StaticApiKeyProvider
+ * preserves the original `apiKey` behavior with zero change for existing callers.
+ */
+interface AuthCredential {
+    /** Authorization scheme (e.g. 'Bearer'); defaults to 'Bearer' when omitted. */
+    scheme?: string;
+    /** The credential value (bearer token / API key). */
+    token: string;
+}
+interface TokenProviderContext {
+    tenantId: string;
+    requestId: string;
+    /** When true, bypass any cache and obtain a fresh credential (e.g. after a 401). */
+    forceRefresh?: boolean;
+}
+interface TokenProvider {
+    /** Resolve the credential for a request, or null to send no Authorization header. */
+    getCredential(ctx: TokenProviderContext): Promise<AuthCredential | null>;
+    /** Whether this provider can obtain a fresh credential on demand (drives 401 retry). */
+    canRefresh?(): boolean;
+}
+/**
+ * Default provider: wraps a static API key. Returns null when the key is empty
+ * so the client sends no Authorization header, matching the pre-provider behavior.
+ */
+declare class StaticApiKeyProvider implements TokenProvider {
+    private readonly apiKey;
+    constructor(apiKey: string);
+    getCredential(): Promise<AuthCredential | null>;
+    canRefresh(): boolean;
+}
+interface CachedToken {
+    token: string;
+    expiresAt?: number;
+}
+interface RefreshingTokenProviderOptions {
+    /** Fetches a fresh token. `expiresAt` is epoch milliseconds (optional). */
+    fetchToken: () => Promise<CachedToken>;
+    /** Refresh this many ms before expiry (default: 30_000). */
+    skewMs?: number;
+    /** Authorization scheme to emit (default: 'Bearer'). */
+    scheme?: string;
+    /** Observe each successful (re)fetch — for logging / metrics. */
+    onRotate?: (meta: {
+        expiresAt?: number;
+    }) => void;
+    /** Injectable clock (default: Date.now). */
+    now?: () => number;
+}
+/**
+ * Caches a fetched token and refreshes it when it is within the skew window of
+ * expiry or when `forceRefresh` is requested. Concurrent refreshes are de-duped
+ * into a single in-flight fetch.
+ */
+declare class RefreshingTokenProvider implements TokenProvider {
+    private readonly opts;
+    private cached;
+    private inFlight;
+    private readonly skewMs;
+    private readonly scheme;
+    private readonly now;
+    constructor(opts: RefreshingTokenProviderOptions);
+    canRefresh(): boolean;
+    getCredential(ctx?: TokenProviderContext): Promise<AuthCredential | null>;
+    private isExpiring;
+    private refresh;
+}
+
 /**
  * Configuration types for Vesant SDK clients
  */
@@ -82,6 +156,16 @@ interface BaseClientConfig {
     tenantId: string;
     /** Optional API key for authentication */
     apiKey?: string;
+    /**
+     * Pluggable auth token provider. When set, it supplies the Authorization
+     * credential per-request (overriding `apiKey`), enabling OAuth2 / STS / rotating
+     * secrets and single-shot 401 re-auth. Defaults to a static-apiKey provider.
+     */
+    authProvider?: TokenProvider;
+    /** Observe credential rotation triggered by a 401 re-auth (logging / metrics). */
+    onCredentialRotated?: (meta: {
+        reason: string;
+    }) => void;
     /** Custom headers to include in all requests */
     headers?: Record<string, string>;
     /** Request timeout in milliseconds (default: 10000) */
@@ -108,6 +192,16 @@ interface VesantConfig {
     tenantId: string;
     /** Optional API key for authentication */
     apiKey?: string;
+    /**
+     * Pluggable auth token provider. When set, it supplies the Authorization
+     * credential per-request (overriding `apiKey`), enabling OAuth2 / STS / rotating
+     * secrets and single-shot 401 re-auth. Defaults to a static-apiKey provider.
+     */
+    authProvider?: TokenProvider;
+    /** Observe credential rotation triggered by a 401 re-auth (logging / metrics). */
+    onCredentialRotated?: (meta: {
+        reason: string;
+    }) => void;
     /** Custom headers to include in all requests */
     headers?: Record<string, string>;
     /** Request timeout in milliseconds (default: 10000) */
@@ -195,7 +289,15 @@ declare abstract class BaseClient {
     private interceptors;
     private circuitBreaker;
     private rateLimitTracker;
+    private authProvider;
     constructor(config: BaseClientConfig);
+    /**
+     * 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.
+     */
+    private resolveIdempotencyKey;
     /**
      * Make an HTTP request with timeout and error handling
      */
@@ -237,4 +339,4 @@ declare abstract class BaseClient {
     }>;
 }
 
-export { BaseClient as B, type CGSConfig as C, type Logger as L, type RequestOptions as R, type VesantConfig as V, type BaseClientConfig as a, CircuitBreaker as b, type CircuitBreakerConfig as c, type CircuitBreakerState as d, type CircuitBreakerStatus as e, type RateLimitStatus as f, RateLimitTracker as g, type RequestInterceptor as h, type RequiredBaseClientConfig as i, type RequiredCGSConfig as j, type RequiredVesantConfig as k };
+export { type AuthCredential as A, BaseClient as B, type CGSConfig as C, type Logger as L, type RequestOptions as R, StaticApiKeyProvider as S, type TokenProvider as T, type VesantConfig as V, type BaseClientConfig as a, CircuitBreaker as b, type CircuitBreakerConfig as c, type CircuitBreakerState as d, type CircuitBreakerStatus as e, type RateLimitStatus as f, RateLimitTracker as g, RefreshingTokenProvider as h, type RefreshingTokenProviderOptions as i, type RequestInterceptor as j, type RequiredBaseClientConfig as k, type RequiredCGSConfig as l, type RequiredVesantConfig as m, type TokenProviderContext as n };