vesant-sdk 1.7.0 → 1.7.1-dev.0520b46

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-5q4whhGu.mjs';
+export { p as CreateLocationRequestRequest, I as LocationCaptureRequest, K as LocationCaptureResponse, a as LocationRequest, M as LocationRequestChannel, b as LocationRequestFilters, c as LocationRequestListResponse, N as LocationRequestResult, O as LocationRequestStatus, P as LocationShareInfo, R as ResendLocationRequestRequest } from '../client-XDEhh9VN.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-DUHC-68_.js';
+export { p as CreateLocationRequestRequest, I as LocationCaptureRequest, K as LocationCaptureResponse, a as LocationRequest, M as LocationRequestChannel, b as LocationRequestFilters, c as LocationRequestListResponse, N as LocationRequestResult, O as LocationRequestStatus, P as LocationShareInfo, R as ResendLocationRequestRequest } from '../client-BaUekQT8.js';
 import '../risk-profile/index.js';
-import '../client-BolQlL5e.js';
+import '../client-q9fN8Hhf.js';
 import '../types-UGyDl1fd.js';
 
 declare const sdkReasons: {