vesant-sdk 1.7.0-dev.b7f5c17 → 1.7.0-dev.c349626

package/dist/{client-DF7hlMEz.d.ts → client-0NOPDnT0.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?: {
@@ -227,7 +229,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;
@@ -624,16 +630,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 +637,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 +658,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 +730,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 */
@@ -995,20 +993,12 @@ 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>;
@@ -1031,4 +1021,4 @@ declare class GeolocationClient extends BaseClient {
     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 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 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 };

package/dist/{client-DrjgZoH_.d.mts → client-CvWNRwwg.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?: {
@@ -227,7 +229,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;
@@ -624,16 +630,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 +637,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 +658,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 +730,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 */
@@ -995,20 +993,12 @@ 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>;
@@ -1031,4 +1021,4 @@ declare class GeolocationClient extends BaseClient {
     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 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 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 };

package/dist/{client-B0qhE2kr.d.mts → client-Dps40EtF.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-CvWNRwwg.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-DtH2RLuy.d.ts → client-SMxqod4j.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-0NOPDnT0.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-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 };

package/dist/compliance/index.d.mts

@@ -1,8 +1,8 @@
 import { B as BlockReason } from '../types-CBQRNL-l.mjs';
-export { C as ComplianceClient, a as ComplianceLocationRequestInput, b as ComplianceLocationRequestResult, c as CurrencyRates, D as DEFAULT_CURRENCY_RATES, E as EventVerificationRequest, d as EventVerificationResponse, L as LoginVerificationRequest, e as LoginVerificationResponse, R as RegistrationVerificationRequest, f as RegistrationVerificationResponse, T as TransactionRiskResult, g as TransactionVerificationRequest, h as TransactionVerificationResponse } from '../client-B0qhE2kr.mjs';
-export { p as CreateLocationRequestRequest, H as LocationCaptureRequest, I as LocationCaptureResponse, a as LocationRequest, K as LocationRequestChannel, b as LocationRequestFilters, c as LocationRequestListResponse, M as LocationRequestResult, N as LocationRequestStatus, O as LocationShareInfo, R as ResendLocationRequestRequest } from '../client-DrjgZoH_.mjs';
+export { C as ComplianceClient, a as ComplianceLocationRequestInput, b as ComplianceLocationRequestResult, c as CurrencyRates, D as DEFAULT_CURRENCY_RATES, E as EventVerificationRequest, d as EventVerificationResponse, L as LoginVerificationRequest, e as LoginVerificationResponse, R as RegistrationVerificationRequest, f as RegistrationVerificationResponse, T as TransactionRiskResult, g as TransactionVerificationRequest, h as TransactionVerificationResponse } from '../client-Dps40EtF.mjs';
+export { p as CreateLocationRequestRequest, H as LocationCaptureRequest, I as LocationCaptureResponse, a as LocationRequest, K as LocationRequestChannel, b as LocationRequestFilters, c as LocationRequestListResponse, M as LocationRequestResult, N as LocationRequestStatus, O as LocationShareInfo, R as ResendLocationRequestRequest } from '../client-CvWNRwwg.mjs';
 import '../risk-profile/index.mjs';
-import '../client-BolQlL5e.mjs';
+import '../client-q9fN8Hhf.mjs';
 import '../types-BOFaMQxI.mjs';
 
 declare const sdkReasons: {

package/dist/compliance/index.d.ts

@@ -1,8 +1,8 @@
 import { B as BlockReason } from '../types-CBQRNL-l.js';
-export { C as ComplianceClient, a as ComplianceLocationRequestInput, b as ComplianceLocationRequestResult, c as CurrencyRates, D as DEFAULT_CURRENCY_RATES, E as EventVerificationRequest, d as EventVerificationResponse, L as LoginVerificationRequest, e as LoginVerificationResponse, R as RegistrationVerificationRequest, f as RegistrationVerificationResponse, T as TransactionRiskResult, g as TransactionVerificationRequest, h as TransactionVerificationResponse } from '../client-DtH2RLuy.js';
-export { p as CreateLocationRequestRequest, H as LocationCaptureRequest, I as LocationCaptureResponse, a as LocationRequest, K as LocationRequestChannel, b as LocationRequestFilters, c as LocationRequestListResponse, M as LocationRequestResult, N as LocationRequestStatus, O as LocationShareInfo, R as ResendLocationRequestRequest } from '../client-DF7hlMEz.js';
+export { C as ComplianceClient, a as ComplianceLocationRequestInput, b as ComplianceLocationRequestResult, c as CurrencyRates, D as DEFAULT_CURRENCY_RATES, E as EventVerificationRequest, d as EventVerificationResponse, L as LoginVerificationRequest, e as LoginVerificationResponse, R as RegistrationVerificationRequest, f as RegistrationVerificationResponse, T as TransactionRiskResult, g as TransactionVerificationRequest, h as TransactionVerificationResponse } from '../client-SMxqod4j.js';
+export { p as CreateLocationRequestRequest, H as LocationCaptureRequest, I as LocationCaptureResponse, a as LocationRequest, K as LocationRequestChannel, b as LocationRequestFilters, c as LocationRequestListResponse, M as LocationRequestResult, N as LocationRequestStatus, O as LocationShareInfo, R as ResendLocationRequestRequest } from '../client-0NOPDnT0.js';
 import '../risk-profile/index.js';
-import '../client-BolQlL5e.js';
+import '../client-q9fN8Hhf.js';
 import '../types-UGyDl1fd.js';
 
 declare const sdkReasons: {