@spare-technologies/spare-api 1.0.0-beta.10

package/dist/configuration.d.ts

@@ -0,0 +1,206 @@
+/**
+ * @module Configuration
+ * @description
+ * Configuration class for SpareApiClient implementing a auto-refresh credential pattern.
+ *
+ * Users provide credentials once (appId, apiKey, tenant) during instantiation.
+ * Configuration automatically handles:
+ * - Token exchange on first API request
+ * - Token caching in memory
+ * - Automatic token refresh when expiring (30-minute buffer)
+ * - Concurrent request safety (shared token across parallel requests)
+ *
+ * Client identity is derived from the JWT ob_account_id claim server-side — no clientId
+ * header is needed in SDK requests.
+ *
+ * @example
+ * ```ts
+ * const config = new Configuration({
+ *   appId: process.env.SPARE_APP_ID,
+ *   apiKey: process.env.SPARE_API_KEY,
+ *   tenant: 'UAE',
+ *   environment: 'sandbox'
+ * });
+ *
+ * // Single step: pass Configuration as authProvider
+ * const client = new SpareApiClient({ authProvider: config });
+ *
+ * // Token exchange happens automatically on first request
+ * const providers = await client.providers.list({ countryCode: 'AE' });
+ * ```
+ */
+/**
+ * Configuration options for SpareApiClient.
+ */
+export interface IConfigurationOptions {
+    /** @description Spare App ID from your Spare dashboard */
+    appId: string;
+    /** @description Spare API Key from your Spare dashboard */
+    apiKey: string;
+    /** @description Target tenant. Currently "UAE". */
+    tenant: string;
+    /** @description Optional: Custom base URL (overrides environment default) */
+    baseUrl?: string;
+    /** @description Optional: API environment. Defaults to "sandbox". */
+    environment?: 'sandbox';
+    /** @description Optional: Milliseconds before expiry to refresh token. Defaults to 30 minutes. */
+    refreshThresholdMs?: number;
+    /** @description Optional: Timeout in milliseconds for token exchange requests. Defaults to 10 seconds. */
+    tokenExchangeTimeout?: number;
+}
+/**
+ * Configuration class for SpareApiClient.
+ *
+ * Manages credentials and token lifecycle (exchange, refresh, caching).
+ * Implements a Configuration pattern where users construct Configuration once
+ * and the client handles token management transparently.
+ *
+ * Client identity is derived from the JWT ob_account_id claim server-side.
+ * Only X-Tenant is injected into every request via getAuthRequest().
+ *
+ * @implements {IAuthProvider} Compatible with Fern-generated client's AuthProvider interface
+ *
+ * @example
+ * ```ts
+ * const config = new Configuration({
+ *   appId: 'app_prod_123',
+ *   apiKey: 'sk_prod_456',
+ *   tenant: 'UAE',
+ *   environment: 'production'
+ * });
+ *
+ * const client = new SpareApiClient({ authProvider: config });
+ * const result = await client.providers.list({ countryCode: 'AE' });
+ * ```
+ */
+export declare class Configuration {
+    readonly appId: string;
+    readonly apiKey: string;
+    readonly tenant: string;
+    readonly baseUrl: string;
+    readonly environment: 'sandbox';
+    readonly refreshThresholdMs: number;
+    readonly tokenExchangeTimeout: number;
+    private accessToken;
+    private refreshToken;
+    private tokenExpiresAt;
+    private isRefreshing;
+    private refreshPromise;
+    private isExchanging;
+    private exchangePromise;
+    /**
+     * Construct a Configuration instance with credentials.
+     *
+     * @param {IConfigurationOptions} options - Configuration options
+     * @param {string} options.appId - App identifier from Spare dashboard
+     * @param {string} options.apiKey - API key from Spare dashboard
+     * @param {string} options.tenant - Target tenant (currently "UAE")
+     * @param {string} [options.environment="sandbox"] - API environment ("sandbox" or "production")
+     * @param {string} [options.baseUrl] - Custom base URL (overrides environment default)
+     * @param {number} [options.refreshThresholdMs=1800000] - Milliseconds before expiry to refresh (default: 30 min)
+     * @param {number} [options.tokenExchangeTimeout=10000] - Timeout in milliseconds for token exchange (default: 10s)
+     *
+     * @throws {Error} If required options (appId, apiKey, tenant) are missing
+     *
+     * @example
+     * ```ts
+     * const config = new Configuration({
+     *   appId: process.env.SPARE_APP_ID!,
+     *   apiKey: process.env.SPARE_API_KEY!,
+     *   tenant: 'UAE'
+     * });
+     * ```
+     */
+    constructor(options: IConfigurationOptions);
+    /**
+     * Get the base URL for API requests.
+     *
+     * Resolves the appropriate base URL based on environment or custom override.
+     *
+     * @returns {string} The resolved base URL (e.g., "https://api.sandbox.tryspare.ae")
+     *
+     * @example
+     * ```ts
+     * const config = new Configuration({ ..., environment: 'production' });
+     * config.getBaseUrl(); // "https://api.tryspare.ae"
+     * ```
+     */
+    getBaseUrl(): string;
+    /**
+     * Get authentication headers for API requests.
+     *
+     * This method is called automatically by the SDK on each API request.
+     * It handles token exchange on first call and auto-refresh when expired.
+     *
+     * @returns {Promise<Record<string, string>>} Authorization header with Bearer token
+     * @throws {Error} If token exchange fails or credentials are invalid
+     *
+     * @example
+     * ```ts
+     * const headers = await config.getAuthHeaders();
+     * // Returns: { Authorization: 'Bearer at_xyz...' }
+     * ```
+     */
+    getAuthHeaders(): Promise<Record<string, string>>;
+    /**
+     * Implements AuthProvider interface for Fern-generated SDK.
+     * Called by SpareApiClient on each request to get authentication headers.
+     *
+     * Returns Authorization header + multi-tenant headers (X-Tenant, X-Client-ID)
+     * so Configuration is the single source of truth for all credential-related headers.
+     *
+     * @returns {Promise<{ headers: Record<string, string> }>} AuthRequest with all headers
+     * @throws {Error} If token exchange fails or credentials are invalid
+     */
+    getAuthRequest(): Promise<{
+        headers: Record<string, string>;
+    }>;
+    /**
+     * Get access token, exchanging credentials if needed or refreshing if expired.
+     * Called internally by the client on each request.
+     * Handles token lifecycle with concurrent-safe refresh.
+     *
+     * @returns {Promise<string>} Valid access token
+     * @throws {Error} If token exchange or refresh fails
+     * @private
+     */
+    getAccessToken(): Promise<string>;
+    /**
+     * Exchange credentials for tokens (first-time setup).
+     * Called automatically on first API request.
+     * Implements timeout and comprehensive error handling.
+     * Uses a concurrent-safe lock to prevent duplicate exchanges.
+     *
+     * @returns {Promise<void>}
+     * @throws {Error} If API request fails, credentials are invalid, or timeout occurs
+     * @private
+     */
+    private exchangeCredentialsForToken;
+    /**
+     * Refresh access token before expiry.
+     * Handles concurrent refresh requests (multiple API calls in parallel).
+     * Uses a promise lock to ensure only one refresh happens at a time.
+     *
+     * @returns {Promise<void>}
+     * @throws {Error} If refresh fails
+     * @private
+     */
+    private refreshAccessToken;
+    /**
+     * Check if token is expired or about to expire (using refresh threshold buffer).
+     *
+     * @returns {boolean} True if token should be refreshed
+     * @private
+     */
+    private isTokenExpiredOrExpiring;
+    /**
+     * Get base options for HTTP requests (headers, baseUrl, etc).
+     * Used by the Fern-generated client to make authenticated requests.
+     *
+     * @returns {Record<string, unknown>} Base request options
+     *
+     * @internal
+     */
+    getBaseOptions(): Record<string, unknown>;
+}
+//# sourceMappingURL=configuration.d.ts.map

package/dist/configuration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"configuration.d.ts","sourceRoot":"","sources":["../configuration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AA0BH;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,0DAA0D;IAC1D,KAAK,EAAE,MAAM,CAAC;IAEd,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;IAEf,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;IAEf,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,qEAAqE;IACrE,WAAW,CAAC,EAAE,SAAS,CAAC;IAExB,kGAAkG;IAClG,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAE5B,0GAA0G;IAC1G,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,aAAa;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,SAAS,CAAC;IAChC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IAGtC,OAAO,CAAC,WAAW,CAAuB;IAE1C,OAAO,CAAC,YAAY,CAAuB;IAE3C,OAAO,CAAC,cAAc,CAAuB;IAE7C,OAAO,CAAC,YAAY,CAAS;IAE7B,OAAO,CAAC,cAAc,CAA8B;IAEpD,OAAO,CAAC,YAAY,CAAS;IAE7B,OAAO,CAAC,eAAe,CAA8B;IAErD;;;;;;;;;;;;;;;;;;;;;;OAsBG;gBACS,OAAO,EAAE,qBAAqB;IAc1C;;;;;;;;;;;;OAYG;IACH,UAAU,IAAI,MAAM;IAIpB;;;;;;;;;;;;;;OAcG;IACG,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAYvD;;;;;;;;;OASG;IACG,cAAc,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,CAAC;IAUpE;;;;;;;;OAQG;IACG,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;IAoBvC;;;;;;;;;OASG;YAEW,2BAA2B;IA2EzC;;;;;;;;OAQG;YAEW,kBAAkB;IA0EhC;;;;;OAKG;IAEH,OAAO,CAAC,wBAAwB;IAKhC;;;;;;;OAOG;IACH,cAAc,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAO1C"}

package/dist/configuration.js

@@ -0,0 +1,391 @@
+/**
+ * @module Configuration
+ * @description
+ * Configuration class for SpareApiClient implementing a auto-refresh credential pattern.
+ *
+ * Users provide credentials once (appId, apiKey, tenant) during instantiation.
+ * Configuration automatically handles:
+ * - Token exchange on first API request
+ * - Token caching in memory
+ * - Automatic token refresh when expiring (30-minute buffer)
+ * - Concurrent request safety (shared token across parallel requests)
+ *
+ * Client identity is derived from the JWT ob_account_id claim server-side — no clientId
+ * header is needed in SDK requests.
+ *
+ * @example
+ * ```ts
+ * const config = new Configuration({
+ *   appId: process.env.SPARE_APP_ID,
+ *   apiKey: process.env.SPARE_API_KEY,
+ *   tenant: 'UAE',
+ *   environment: 'sandbox'
+ * });
+ *
+ * // Single step: pass Configuration as authProvider
+ * const client = new SpareApiClient({ authProvider: config });
+ *
+ * // Token exchange happens automatically on first request
+ * const providers = await client.providers.list({ countryCode: 'AE' });
+ * ```
+ */
+/**
+ * API host per tenant (region) and environment. The base URL is resolved from the tenant and
+ * environment together, so the host always matches the X-Tenant header. Add a row per country
+ * as it launches; consumers can still pass an explicit `baseUrl` to override (local development,
+ * on-prem, or a region not yet listed here).
+ */
+const TENANT_HOSTS = {
+    UAE: {
+        sandbox: 'https://api.sandbox.tryspare.ae',
+    },
+};
+/** Resolves the API base URL for a tenant and environment. */
+function resolveTenantBaseUrl(tenant, environment) {
+    const hosts = TENANT_HOSTS[tenant];
+    if (!hosts) {
+        const supported = Object.keys(TENANT_HOSTS).join(', ');
+        throw new Error(`Unsupported tenant "${tenant}". Supported tenants: ${supported}. Pass an explicit baseUrl to override.`);
+    }
+    return hosts[environment];
+}
+/**
+ * Configuration class for SpareApiClient.
+ *
+ * Manages credentials and token lifecycle (exchange, refresh, caching).
+ * Implements a Configuration pattern where users construct Configuration once
+ * and the client handles token management transparently.
+ *
+ * Client identity is derived from the JWT ob_account_id claim server-side.
+ * Only X-Tenant is injected into every request via getAuthRequest().
+ *
+ * @implements {IAuthProvider} Compatible with Fern-generated client's AuthProvider interface
+ *
+ * @example
+ * ```ts
+ * const config = new Configuration({
+ *   appId: 'app_prod_123',
+ *   apiKey: 'sk_prod_456',
+ *   tenant: 'UAE',
+ *   environment: 'production'
+ * });
+ *
+ * const client = new SpareApiClient({ authProvider: config });
+ * const result = await client.providers.list({ countryCode: 'AE' });
+ * ```
+ */
+export class Configuration {
+    /**
+     * Construct a Configuration instance with credentials.
+     *
+     * @param {IConfigurationOptions} options - Configuration options
+     * @param {string} options.appId - App identifier from Spare dashboard
+     * @param {string} options.apiKey - API key from Spare dashboard
+     * @param {string} options.tenant - Target tenant (currently "UAE")
+     * @param {string} [options.environment="sandbox"] - API environment ("sandbox" or "production")
+     * @param {string} [options.baseUrl] - Custom base URL (overrides environment default)
+     * @param {number} [options.refreshThresholdMs=1800000] - Milliseconds before expiry to refresh (default: 30 min)
+     * @param {number} [options.tokenExchangeTimeout=10000] - Timeout in milliseconds for token exchange (default: 10s)
+     *
+     * @throws {Error} If required options (appId, apiKey, tenant) are missing
+     *
+     * @example
+     * ```ts
+     * const config = new Configuration({
+     *   appId: process.env.SPARE_APP_ID!,
+     *   apiKey: process.env.SPARE_API_KEY!,
+     *   tenant: 'UAE'
+     * });
+     * ```
+     */
+    constructor(options) {
+        // biome-ignore lint/style/useNamingConvention: private state management
+        this.accessToken = null;
+        // biome-ignore lint/style/useNamingConvention: private state management
+        this.refreshToken = null;
+        // biome-ignore lint/style/useNamingConvention: private state management
+        this.tokenExpiresAt = null;
+        // biome-ignore lint/style/useNamingConvention: private state management
+        this.isRefreshing = false;
+        // biome-ignore lint/style/useNamingConvention: private state management
+        this.refreshPromise = null;
+        // biome-ignore lint/style/useNamingConvention: private state management
+        this.isExchanging = false;
+        // biome-ignore lint/style/useNamingConvention: private state management
+        this.exchangePromise = null;
+        if (!options.appId)
+            throw new Error('appId is required');
+        if (!options.apiKey)
+            throw new Error('apiKey is required');
+        if (!options.tenant)
+            throw new Error('tenant is required');
+        this.appId = options.appId;
+        this.apiKey = options.apiKey;
+        this.tenant = options.tenant;
+        this.environment = options.environment ?? 'sandbox';
+        this.refreshThresholdMs = options.refreshThresholdMs ?? 30 * 60 * 1000;
+        this.tokenExchangeTimeout = options.tokenExchangeTimeout ?? 10 * 1000;
+        this.baseUrl = options.baseUrl ?? resolveTenantBaseUrl(this.tenant, this.environment);
+    }
+    /**
+     * Get the base URL for API requests.
+     *
+     * Resolves the appropriate base URL based on environment or custom override.
+     *
+     * @returns {string} The resolved base URL (e.g., "https://api.sandbox.tryspare.ae")
+     *
+     * @example
+     * ```ts
+     * const config = new Configuration({ ..., environment: 'production' });
+     * config.getBaseUrl(); // "https://api.tryspare.ae"
+     * ```
+     */
+    getBaseUrl() {
+        return this.baseUrl;
+    }
+    /**
+     * Get authentication headers for API requests.
+     *
+     * This method is called automatically by the SDK on each API request.
+     * It handles token exchange on first call and auto-refresh when expired.
+     *
+     * @returns {Promise<Record<string, string>>} Authorization header with Bearer token
+     * @throws {Error} If token exchange fails or credentials are invalid
+     *
+     * @example
+     * ```ts
+     * const headers = await config.getAuthHeaders();
+     * // Returns: { Authorization: 'Bearer at_xyz...' }
+     * ```
+     */
+    async getAuthHeaders() {
+        try {
+            const token = await this.getAccessToken();
+            return { Authorization: `Bearer ${token}` };
+        }
+        catch (error) {
+            throw new SpareApiError(error instanceof Error ? error.message : 'Failed to get auth headers', 500);
+        }
+    }
+    /**
+     * Implements AuthProvider interface for Fern-generated SDK.
+     * Called by SpareApiClient on each request to get authentication headers.
+     *
+     * Returns Authorization header + multi-tenant headers (X-Tenant, X-Client-ID)
+     * so Configuration is the single source of truth for all credential-related headers.
+     *
+     * @returns {Promise<{ headers: Record<string, string> }>} AuthRequest with all headers
+     * @throws {Error} If token exchange fails or credentials are invalid
+     */
+    async getAuthRequest() {
+        const authHeaders = await this.getAuthHeaders();
+        return {
+            headers: {
+                ...authHeaders,
+                'x-tenant': this.tenant,
+            },
+        };
+    }
+    /**
+     * Get access token, exchanging credentials if needed or refreshing if expired.
+     * Called internally by the client on each request.
+     * Handles token lifecycle with concurrent-safe refresh.
+     *
+     * @returns {Promise<string>} Valid access token
+     * @throws {Error} If token exchange or refresh fails
+     * @private
+     */
+    async getAccessToken() {
+        // If token is not yet loaded, exchange credentials (with concurrent safety)
+        if (!this.accessToken) {
+            // Prevent concurrent exchange calls
+            if (this.isExchanging && this.exchangePromise) {
+                await this.exchangePromise;
+            }
+            else {
+                await this.exchangeCredentialsForToken();
+            }
+        }
+        // If token is expired or about to expire (refresh buffer), refresh
+        if (this.isTokenExpiredOrExpiring()) {
+            await this.refreshAccessToken();
+        }
+        // biome-ignore lint/style/noNonNullAssertion: token is guaranteed to exist after exchange or refresh
+        return this.accessToken;
+    }
+    /**
+     * Exchange credentials for tokens (first-time setup).
+     * Called automatically on first API request.
+     * Implements timeout and comprehensive error handling.
+     * Uses a concurrent-safe lock to prevent duplicate exchanges.
+     *
+     * @returns {Promise<void>}
+     * @throws {Error} If API request fails, credentials are invalid, or timeout occurs
+     * @private
+     */
+    // biome-ignore lint/style/useNamingConvention: private method
+    async exchangeCredentialsForToken() {
+        // Prevent concurrent exchange calls by returning shared promise
+        if (this.isExchanging && this.exchangePromise) {
+            return this.exchangePromise;
+        }
+        this.isExchanging = true;
+        this.exchangePromise = (async () => {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), this.tokenExchangeTimeout);
+            try {
+                const response = await fetch(`${this.baseUrl}/auth/api-keys/sessions`, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'X-Tenant': this.tenant,
+                        'app-id': this.appId,
+                        'x-api-key': this.apiKey,
+                    },
+                    signal: controller.signal,
+                });
+                if (!response.ok) {
+                    const errorBody = await response.text();
+                    throw new SpareApiError(`Token exchange failed: ${response.status} ${response.statusText}. ` +
+                        `Verify appId, apiKey, and tenant are correct.\n${errorBody}`, response.status);
+                }
+                const data = (await response.json());
+                // API returns bare object with snake_case fields, not wrapped in { data }
+                // Expected: { access_token, refresh_token, expires_in, type: "Bearer" }
+                const accessToken = (data['access_token'] ?? data['accessToken']);
+                const refreshToken = (data['refresh_token'] ?? data['refreshToken']);
+                const expiresIn = (data['expires_in'] ?? data['expiresIn']);
+                if (!(accessToken && refreshToken)) {
+                    throw new SpareApiError(`Missing accessToken or refreshToken in exchange response. Got keys: ${Object.keys(data).join(', ')}`, 500);
+                }
+                this.accessToken = accessToken;
+                this.refreshToken = refreshToken;
+                // Calculate expiresAt from expiresIn (seconds) or use default
+                this.tokenExpiresAt = expiresIn
+                    ? Date.now() + expiresIn * 1000
+                    : Date.now() + this.refreshThresholdMs * 2;
+            }
+            catch (error) {
+                if (error instanceof Error && error.name === 'AbortError') {
+                    throw new SpareApiError(`Token exchange timed out after ${this.tokenExchangeTimeout}ms. ` +
+                        'Check appId, apiKey, tenant, and network connectivity.', 408);
+                }
+                if (error instanceof SpareApiError)
+                    throw error;
+                throw new SpareApiError(`Token exchange failed: ${error instanceof Error ? error.message : String(error)}`, 500);
+            }
+            finally {
+                clearTimeout(timeoutId);
+                this.isExchanging = false;
+                this.exchangePromise = null;
+            }
+        })();
+        return this.exchangePromise;
+    }
+    /**
+     * Refresh access token before expiry.
+     * Handles concurrent refresh requests (multiple API calls in parallel).
+     * Uses a promise lock to ensure only one refresh happens at a time.
+     *
+     * @returns {Promise<void>}
+     * @throws {Error} If refresh fails
+     * @private
+     */
+    // biome-ignore lint/style/useNamingConvention: private method
+    async refreshAccessToken() {
+        // Prevent concurrent refresh calls by returning shared promise
+        if (this.isRefreshing && this.refreshPromise) {
+            return this.refreshPromise;
+        }
+        this.isRefreshing = true;
+        this.refreshPromise = (async () => {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), this.tokenExchangeTimeout);
+            try {
+                const response = await fetch(`${this.baseUrl}/auth/api-keys/sessions/refresh`, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'X-Tenant': this.tenant,
+                    },
+                    body: JSON.stringify({
+                        refreshToken: this.refreshToken,
+                    }),
+                    signal: controller.signal,
+                });
+                if (!response.ok) {
+                    const errorBody = await response.text();
+                    throw new SpareApiError(`Token refresh failed: ${response.status} ${response.statusText}\n${errorBody}`, response.status);
+                }
+                const data = (await response.json());
+                // API returns bare object with snake_case fields
+                // Expected: { access_token, refresh_token, expires_in, type: "Bearer" }
+                const accessToken = (data['access_token'] ?? data['accessToken']);
+                const refreshToken = (data['refresh_token'] ?? data['refreshToken']);
+                const expiresIn = (data['expires_in'] ?? data['expiresIn']);
+                if (!(accessToken && refreshToken)) {
+                    throw new SpareApiError(`Missing tokens in refresh response. Got keys: ${Object.keys(data).join(', ')}`, 500);
+                }
+                this.accessToken = accessToken;
+                this.refreshToken = refreshToken;
+                // Calculate expiresAt from expiresIn (seconds) or use default
+                this.tokenExpiresAt = expiresIn
+                    ? Date.now() + expiresIn * 1000
+                    : Date.now() + this.refreshThresholdMs * 2;
+            }
+            catch (error) {
+                if (error instanceof Error && error.name === 'AbortError') {
+                    throw new SpareApiError(`Token refresh timed out after ${this.tokenExchangeTimeout}ms`, 408);
+                }
+                if (error instanceof SpareApiError)
+                    throw error;
+                throw new SpareApiError(`Token refresh failed: ${error instanceof Error ? error.message : String(error)}`, 500);
+            }
+            finally {
+                clearTimeout(timeoutId);
+                this.isRefreshing = false;
+                this.refreshPromise = null;
+            }
+        })();
+        return this.refreshPromise;
+    }
+    /**
+     * Check if token is expired or about to expire (using refresh threshold buffer).
+     *
+     * @returns {boolean} True if token should be refreshed
+     * @private
+     */
+    // biome-ignore lint/style/useNamingConvention: private method
+    isTokenExpiredOrExpiring() {
+        if (!this.tokenExpiresAt)
+            return true;
+        return Date.now() >= this.tokenExpiresAt - this.refreshThresholdMs;
+    }
+    /**
+     * Get base options for HTTP requests (headers, baseUrl, etc).
+     * Used by the Fern-generated client to make authenticated requests.
+     *
+     * @returns {Record<string, unknown>} Base request options
+     *
+     * @internal
+     */
+    getBaseOptions() {
+        return {
+            headers: {
+                'X-Tenant': this.tenant,
+            },
+        };
+    }
+}
+/**
+ * Custom error class for Spare API errors.
+ * Includes HTTP status code for better error handling.
+ */
+class SpareApiError extends Error {
+    constructor(message, statusCode) {
+        super(message);
+        this.statusCode = statusCode;
+        this.name = 'SpareApiError';
+    }
+}
+//# sourceMappingURL=configuration.js.map

package/dist/configuration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"configuration.js","sourceRoot":"","sources":["../configuration.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * @module Configuration\n * @description\n * Configuration class for SpareApiClient implementing a auto-refresh credential pattern.\n *\n * Users provide credentials once (appId, apiKey, tenant) during instantiation.\n * Configuration automatically handles:\n * - Token exchange on first API request\n * - Token caching in memory\n * - Automatic token refresh when expiring (30-minute buffer)\n * - Concurrent request safety (shared token across parallel requests)\n *\n * Client identity is derived from the JWT ob_account_id claim server-side — no clientId\n * header is needed in SDK requests.\n *\n * @example\n * ```ts\n * const config = new Configuration({\n *   appId: process.env.SPARE_APP_ID,\n *   apiKey: process.env.SPARE_API_KEY,\n *   tenant: 'UAE',\n *   environment: 'sandbox'\n * });\n *\n * // Single step: pass Configuration as authProvider\n * const client = new SpareApiClient({ authProvider: config });\n *\n * // Token exchange happens automatically on first request\n * const providers = await client.providers.list({ countryCode: 'AE' });\n * ```\n */\n\n/**\n * API host per tenant (region) and environment. The base URL is resolved from the tenant and\n * environment together, so the host always matches the X-Tenant header. Add a row per country\n * as it launches; consumers can still pass an explicit `baseUrl` to override (local development,\n * on-prem, or a region not yet listed here).\n */\nconst TENANT_HOSTS = {\n  UAE: {\n    sandbox: 'https://api.sandbox.tryspare.ae',\n  },\n} as const;\n\n/** Resolves the API base URL for a tenant and environment. */\nfunction resolveTenantBaseUrl(tenant: string, environment: 'sandbox'): string {\n  const hosts = TENANT_HOSTS[tenant as keyof typeof TENANT_HOSTS];\n  if (!hosts) {\n    const supported = Object.keys(TENANT_HOSTS).join(', ');\n    throw new Error(\n      `Unsupported tenant \"${tenant}\". Supported tenants: ${supported}. Pass an explicit baseUrl to override.`\n    );\n  }\n  return hosts[environment];\n}\n\n/**\n * Configuration options for SpareApiClient.\n */\nexport interface IConfigurationOptions {\n  /** @description Spare App ID from your Spare dashboard */\n  appId: string;\n\n  /** @description Spare API Key from your Spare dashboard */\n  apiKey: string;\n\n  /** @description Target tenant. Currently \"UAE\". */\n  tenant: string;\n\n  /** @description Optional: Custom base URL (overrides environment default) */\n  baseUrl?: string;\n\n  /** @description Optional: API environment. Defaults to \"sandbox\". */\n  environment?: 'sandbox';\n\n  /** @description Optional: Milliseconds before expiry to refresh token. Defaults to 30 minutes. */\n  refreshThresholdMs?: number;\n\n  /** @description Optional: Timeout in milliseconds for token exchange requests. Defaults to 10 seconds. */\n  tokenExchangeTimeout?: number;\n}\n\n/**\n * Configuration class for SpareApiClient.\n *\n * Manages credentials and token lifecycle (exchange, refresh, caching).\n * Implements a Configuration pattern where users construct Configuration once\n * and the client handles token management transparently.\n *\n * Client identity is derived from the JWT ob_account_id claim server-side.\n * Only X-Tenant is injected into every request via getAuthRequest().\n *\n * @implements {IAuthProvider} Compatible with Fern-generated client's AuthProvider interface\n *\n * @example\n * ```ts\n * const config = new Configuration({\n *   appId: 'app_prod_123',\n *   apiKey: 'sk_prod_456',\n *   tenant: 'UAE',\n *   environment: 'production'\n * });\n *\n * const client = new SpareApiClient({ authProvider: config });\n * const result = await client.providers.list({ countryCode: 'AE' });\n * ```\n */\nexport class Configuration {\n  readonly appId: string;\n  readonly apiKey: string;\n  readonly tenant: string;\n  readonly baseUrl: string;\n  readonly environment: 'sandbox';\n  readonly refreshThresholdMs: number;\n  readonly tokenExchangeTimeout: number;\n\n  // biome-ignore lint/style/useNamingConvention: private state management\n  private accessToken: string | null = null;\n  // biome-ignore lint/style/useNamingConvention: private state management\n  private refreshToken: string | null = null;\n  // biome-ignore lint/style/useNamingConvention: private state management\n  private tokenExpiresAt: number | null = null;\n  // biome-ignore lint/style/useNamingConvention: private state management\n  private isRefreshing = false;\n  // biome-ignore lint/style/useNamingConvention: private state management\n  private refreshPromise: Promise<void> | null = null;\n  // biome-ignore lint/style/useNamingConvention: private state management\n  private isExchanging = false;\n  // biome-ignore lint/style/useNamingConvention: private state management\n  private exchangePromise: Promise<void> | null = null;\n\n  /**\n   * Construct a Configuration instance with credentials.\n   *\n   * @param {IConfigurationOptions} options - Configuration options\n   * @param {string} options.appId - App identifier from Spare dashboard\n   * @param {string} options.apiKey - API key from Spare dashboard\n   * @param {string} options.tenant - Target tenant (currently \"UAE\")\n   * @param {string} [options.environment=\"sandbox\"] - API environment (\"sandbox\" or \"production\")\n   * @param {string} [options.baseUrl] - Custom base URL (overrides environment default)\n   * @param {number} [options.refreshThresholdMs=1800000] - Milliseconds before expiry to refresh (default: 30 min)\n   * @param {number} [options.tokenExchangeTimeout=10000] - Timeout in milliseconds for token exchange (default: 10s)\n   *\n   * @throws {Error} If required options (appId, apiKey, tenant) are missing\n   *\n   * @example\n   * ```ts\n   * const config = new Configuration({\n   *   appId: process.env.SPARE_APP_ID!,\n   *   apiKey: process.env.SPARE_API_KEY!,\n   *   tenant: 'UAE'\n   * });\n   * ```\n   */\n  constructor(options: IConfigurationOptions) {\n    if (!options.appId) throw new Error('appId is required');\n    if (!options.apiKey) throw new Error('apiKey is required');\n    if (!options.tenant) throw new Error('tenant is required');\n\n    this.appId = options.appId;\n    this.apiKey = options.apiKey;\n    this.tenant = options.tenant;\n    this.environment = options.environment ?? 'sandbox';\n    this.refreshThresholdMs = options.refreshThresholdMs ?? 30 * 60 * 1000;\n    this.tokenExchangeTimeout = options.tokenExchangeTimeout ?? 10 * 1000;\n    this.baseUrl = options.baseUrl ?? resolveTenantBaseUrl(this.tenant, this.environment);\n  }\n\n  /**\n   * Get the base URL for API requests.\n   *\n   * Resolves the appropriate base URL based on environment or custom override.\n   *\n   * @returns {string} The resolved base URL (e.g., \"https://api.sandbox.tryspare.ae\")\n   *\n   * @example\n   * ```ts\n   * const config = new Configuration({ ..., environment: 'production' });\n   * config.getBaseUrl(); // \"https://api.tryspare.ae\"\n   * ```\n   */\n  getBaseUrl(): string {\n    return this.baseUrl;\n  }\n\n  /**\n   * Get authentication headers for API requests.\n   *\n   * This method is called automatically by the SDK on each API request.\n   * It handles token exchange on first call and auto-refresh when expired.\n   *\n   * @returns {Promise<Record<string, string>>} Authorization header with Bearer token\n   * @throws {Error} If token exchange fails or credentials are invalid\n   *\n   * @example\n   * ```ts\n   * const headers = await config.getAuthHeaders();\n   * // Returns: { Authorization: 'Bearer at_xyz...' }\n   * ```\n   */\n  async getAuthHeaders(): Promise<Record<string, string>> {\n    try {\n      const token = await this.getAccessToken();\n      return { Authorization: `Bearer ${token}` };\n    } catch (error) {\n      throw new SpareApiError(\n        error instanceof Error ? error.message : 'Failed to get auth headers',\n        500\n      );\n    }\n  }\n\n  /**\n   * Implements AuthProvider interface for Fern-generated SDK.\n   * Called by SpareApiClient on each request to get authentication headers.\n   *\n   * Returns Authorization header + multi-tenant headers (X-Tenant, X-Client-ID)\n   * so Configuration is the single source of truth for all credential-related headers.\n   *\n   * @returns {Promise<{ headers: Record<string, string> }>} AuthRequest with all headers\n   * @throws {Error} If token exchange fails or credentials are invalid\n   */\n  async getAuthRequest(): Promise<{ headers: Record<string, string> }> {\n    const authHeaders = await this.getAuthHeaders();\n    return {\n      headers: {\n        ...authHeaders,\n        'x-tenant': this.tenant,\n      },\n    };\n  }\n\n  /**\n   * Get access token, exchanging credentials if needed or refreshing if expired.\n   * Called internally by the client on each request.\n   * Handles token lifecycle with concurrent-safe refresh.\n   *\n   * @returns {Promise<string>} Valid access token\n   * @throws {Error} If token exchange or refresh fails\n   * @private\n   */\n  async getAccessToken(): Promise<string> {\n    // If token is not yet loaded, exchange credentials (with concurrent safety)\n    if (!this.accessToken) {\n      // Prevent concurrent exchange calls\n      if (this.isExchanging && this.exchangePromise) {\n        await this.exchangePromise;\n      } else {\n        await this.exchangeCredentialsForToken();\n      }\n    }\n\n    // If token is expired or about to expire (refresh buffer), refresh\n    if (this.isTokenExpiredOrExpiring()) {\n      await this.refreshAccessToken();\n    }\n\n    // biome-ignore lint/style/noNonNullAssertion: token is guaranteed to exist after exchange or refresh\n    return this.accessToken!;\n  }\n\n  /**\n   * Exchange credentials for tokens (first-time setup).\n   * Called automatically on first API request.\n   * Implements timeout and comprehensive error handling.\n   * Uses a concurrent-safe lock to prevent duplicate exchanges.\n   *\n   * @returns {Promise<void>}\n   * @throws {Error} If API request fails, credentials are invalid, or timeout occurs\n   * @private\n   */\n  // biome-ignore lint/style/useNamingConvention: private method\n  private async exchangeCredentialsForToken(): Promise<void> {\n    // Prevent concurrent exchange calls by returning shared promise\n    if (this.isExchanging && this.exchangePromise) {\n      return this.exchangePromise;\n    }\n\n    this.isExchanging = true;\n    this.exchangePromise = (async () => {\n      const controller = new AbortController();\n      const timeoutId = setTimeout(() => controller.abort(), this.tokenExchangeTimeout);\n\n      try {\n        const response = await fetch(`${this.baseUrl}/auth/api-keys/sessions`, {\n          method: 'POST',\n          headers: {\n            'Content-Type': 'application/json',\n            'X-Tenant': this.tenant,\n            'app-id': this.appId,\n            'x-api-key': this.apiKey,\n          },\n          signal: controller.signal,\n        });\n\n        if (!response.ok) {\n          const errorBody = await response.text();\n          throw new SpareApiError(\n            `Token exchange failed: ${response.status} ${response.statusText}. ` +\n              `Verify appId, apiKey, and tenant are correct.\\n${errorBody}`,\n            response.status\n          );\n        }\n\n        const data = (await response.json()) as Record<string, unknown>;\n        // API returns bare object with snake_case fields, not wrapped in { data }\n        // Expected: { access_token, refresh_token, expires_in, type: \"Bearer\" }\n        const accessToken = (data['access_token'] ?? data['accessToken']) as string | undefined;\n        const refreshToken = (data['refresh_token'] ?? data['refreshToken']) as string | undefined;\n        const expiresIn = (data['expires_in'] ?? data['expiresIn']) as number | undefined;\n\n        if (!(accessToken && refreshToken)) {\n          throw new SpareApiError(\n            `Missing accessToken or refreshToken in exchange response. Got keys: ${Object.keys(data).join(', ')}`,\n            500\n          );\n        }\n\n        this.accessToken = accessToken;\n        this.refreshToken = refreshToken;\n        // Calculate expiresAt from expiresIn (seconds) or use default\n        this.tokenExpiresAt = expiresIn\n          ? Date.now() + expiresIn * 1000\n          : Date.now() + this.refreshThresholdMs * 2;\n      } catch (error) {\n        if (error instanceof Error && error.name === 'AbortError') {\n          throw new SpareApiError(\n            `Token exchange timed out after ${this.tokenExchangeTimeout}ms. ` +\n              'Check appId, apiKey, tenant, and network connectivity.',\n            408\n          );\n        }\n        if (error instanceof SpareApiError) throw error;\n        throw new SpareApiError(\n          `Token exchange failed: ${error instanceof Error ? error.message : String(error)}`,\n          500\n        );\n      } finally {\n        clearTimeout(timeoutId);\n        this.isExchanging = false;\n        this.exchangePromise = null;\n      }\n    })();\n\n    return this.exchangePromise;\n  }\n\n  /**\n   * Refresh access token before expiry.\n   * Handles concurrent refresh requests (multiple API calls in parallel).\n   * Uses a promise lock to ensure only one refresh happens at a time.\n   *\n   * @returns {Promise<void>}\n   * @throws {Error} If refresh fails\n   * @private\n   */\n  // biome-ignore lint/style/useNamingConvention: private method\n  private async refreshAccessToken(): Promise<void> {\n    // Prevent concurrent refresh calls by returning shared promise\n    if (this.isRefreshing && this.refreshPromise) {\n      return this.refreshPromise;\n    }\n\n    this.isRefreshing = true;\n    this.refreshPromise = (async () => {\n      const controller = new AbortController();\n      const timeoutId = setTimeout(() => controller.abort(), this.tokenExchangeTimeout);\n\n      try {\n        const response = await fetch(`${this.baseUrl}/auth/api-keys/sessions/refresh`, {\n          method: 'POST',\n          headers: {\n            'Content-Type': 'application/json',\n            'X-Tenant': this.tenant,\n          },\n          body: JSON.stringify({\n            refreshToken: this.refreshToken,\n          }),\n          signal: controller.signal,\n        });\n\n        if (!response.ok) {\n          const errorBody = await response.text();\n          throw new SpareApiError(\n            `Token refresh failed: ${response.status} ${response.statusText}\\n${errorBody}`,\n            response.status\n          );\n        }\n\n        const data = (await response.json()) as Record<string, unknown>;\n        // API returns bare object with snake_case fields\n        // Expected: { access_token, refresh_token, expires_in, type: \"Bearer\" }\n        const accessToken = (data['access_token'] ?? data['accessToken']) as string | undefined;\n        const refreshToken = (data['refresh_token'] ?? data['refreshToken']) as string | undefined;\n        const expiresIn = (data['expires_in'] ?? data['expiresIn']) as number | undefined;\n\n        if (!(accessToken && refreshToken)) {\n          throw new SpareApiError(\n            `Missing tokens in refresh response. Got keys: ${Object.keys(data).join(', ')}`,\n            500\n          );\n        }\n\n        this.accessToken = accessToken;\n        this.refreshToken = refreshToken;\n        // Calculate expiresAt from expiresIn (seconds) or use default\n        this.tokenExpiresAt = expiresIn\n          ? Date.now() + expiresIn * 1000\n          : Date.now() + this.refreshThresholdMs * 2;\n      } catch (error) {\n        if (error instanceof Error && error.name === 'AbortError') {\n          throw new SpareApiError(\n            `Token refresh timed out after ${this.tokenExchangeTimeout}ms`,\n            408\n          );\n        }\n        if (error instanceof SpareApiError) throw error;\n        throw new SpareApiError(\n          `Token refresh failed: ${error instanceof Error ? error.message : String(error)}`,\n          500\n        );\n      } finally {\n        clearTimeout(timeoutId);\n        this.isRefreshing = false;\n        this.refreshPromise = null;\n      }\n    })();\n\n    return this.refreshPromise;\n  }\n\n  /**\n   * Check if token is expired or about to expire (using refresh threshold buffer).\n   *\n   * @returns {boolean} True if token should be refreshed\n   * @private\n   */\n  // biome-ignore lint/style/useNamingConvention: private method\n  private isTokenExpiredOrExpiring(): boolean {\n    if (!this.tokenExpiresAt) return true;\n    return Date.now() >= this.tokenExpiresAt - this.refreshThresholdMs;\n  }\n\n  /**\n   * Get base options for HTTP requests (headers, baseUrl, etc).\n   * Used by the Fern-generated client to make authenticated requests.\n   *\n   * @returns {Record<string, unknown>} Base request options\n   *\n   * @internal\n   */\n  getBaseOptions(): Record<string, unknown> {\n    return {\n      headers: {\n        'X-Tenant': this.tenant,\n      },\n    };\n  }\n}\n\n/**\n * Custom error class for Spare API errors.\n * Includes HTTP status code for better error handling.\n */\nclass SpareApiError extends Error {\n  constructor(\n    message: string,\n    readonly statusCode: number\n  ) {\n    super(message);\n    this.name = 'SpareApiError';\n  }\n}\n"]}

package/dist/core/auth/AuthProvider.d.ts

@@ -0,0 +1,8 @@
+import type { EndpointMetadata } from "../fetcher/EndpointMetadata.js";
+import type { AuthRequest } from "./AuthRequest.js";
+export interface AuthProvider {
+    getAuthRequest(arg?: {
+        endpointMetadata?: EndpointMetadata;
+    }): Promise<AuthRequest>;
+}
+//# sourceMappingURL=AuthProvider.d.ts.map

package/dist/core/auth/AuthProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AuthProvider.d.ts","sourceRoot":"","sources":["../../../core/auth/AuthProvider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AACvE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,MAAM,WAAW,YAAY;IACzB,cAAc,CAAC,GAAG,CAAC,EAAE;QAAE,gBAAgB,CAAC,EAAE,gBAAgB,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;CACvF"}