@rendomnet/apiservice 1.3.8 → 1.4.1

package/dist/index.d.mts

@@ -0,0 +1,358 @@
+interface OAuthToken {
+    access_token: string;
+    expires_in: number;
+    id_token: string;
+    refresh_token: string;
+    scope: string;
+    token_type: string;
+}
+interface Token {
+    accountId: string;
+    access_token: string;
+    refresh_token: string;
+    provider: string;
+    enabled?: boolean;
+    updatedAt?: string;
+    primary?: boolean;
+}
+interface AccountData {
+    lastRequestTime?: number;
+    lastFailed?: boolean;
+    token?: Token;
+}
+interface DelayStrategy {
+    calculate: (attempt: number, response?: any) => number;
+}
+interface ApiCallParams {
+    accountId: string;
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    route: string;
+    base?: string;
+    body?: object;
+    data?: object;
+    headers?: Record<string, string>;
+    queryParams?: URLSearchParams;
+    accessToken?: string;
+    useAuth?: boolean;
+    noContentType?: boolean;
+    contentType?: string;
+    cacheTime?: number;
+    files?: File[];
+    abortSignal?: AbortSignal;
+}
+interface HookSettings {
+    /**
+     * Whether to retry the API call when this hook is triggered
+     */
+    shouldRetry: boolean;
+    /**
+     * Whether to apply delay between retries
+     */
+    useRetryDelay: boolean;
+    /**
+     * The maximum number of retry attempts for this status code
+     */
+    maxRetries?: number;
+    /**
+     * Wait for an existing hook to complete before starting a new one
+     * Useful for avoiding duplicate refresh token calls
+     */
+    preventConcurrentCalls?: boolean;
+    /**
+     * The main handler function called when this status code is encountered
+     * Return an object to update the API call parameters for the retry
+     */
+    handler: (accountId: string, response: any) => Promise<any>;
+    /**
+     * Called when all retry attempts for this status code have failed
+     */
+    onMaxRetriesExceeded?: (accountId: string, error: any) => Promise<void>;
+    /**
+     * Called when the handler function throws an error
+     */
+    onHandlerError?: (accountId: string, error: any) => Promise<void>;
+    /**
+     * Custom strategy for calculating delay between retries
+     */
+    delayStrategy?: DelayStrategy;
+    /**
+     * Maximum delay in milliseconds between retries
+     */
+    maxDelay?: number;
+}
+type StatusCode = string | number;
+interface AuthProvider {
+    /**
+     * Returns headers or other auth data for a request
+     */
+    getAuthHeaders(accountId?: string): Promise<Record<string, string>>;
+    /**
+     * Optional: refresh credentials if supported (for OAuth, etc.)
+     */
+    refresh?(refreshToken: string, accountId?: string): Promise<any>;
+}
+interface ApiKeyAuthProviderOptions {
+    apiKey: string;
+    headerName?: string;
+    queryParamName?: string;
+}
+interface BasicAuthProviderOptions {
+    username: string;
+    password: string;
+}
+type TokenService$1 = {
+    get: (accountId?: string) => Promise<Token>;
+    set: (token: Partial<Token>, accountId?: string) => Promise<void>;
+    refresh?: (refreshToken: string, accountId?: string) => Promise<OAuthToken>;
+};
+
+declare class FetchError extends Error {
+    name: string;
+    status: number;
+    code: string;
+    message: string;
+    data: any;
+    constructor(response: Response, data?: any, code?: string);
+}
+
+/**
+ * Handles caching of API responses
+ */
+declare class CacheManager {
+    private cache;
+    private cacheTime;
+    /**
+     * Get data from cache if available and not expired
+     */
+    getFromCache(apiCallParams: ApiCallParams): any;
+    /**
+     * Save data to cache
+     */
+    saveToCache(apiCallParams: ApiCallParams, data: any): void;
+    /**
+     * Generate a unique key for caching based on request parameters
+     */
+    private getRequestKey;
+    /**
+     * Set the default cache time in milliseconds
+     */
+    setCacheTime(milliseconds: number): void;
+    /**
+     * Clear the entire cache
+     */
+    clearCache(): void;
+}
+
+/**
+ * Handles retry logic and delay strategies for failed API calls
+ */
+declare class RetryManager {
+    private defaultMaxDelay;
+    private defaultMaxRetries;
+    /**
+     * Default exponential backoff strategy with full jitter
+     */
+    private defaultDelayStrategy;
+    /**
+     * Calculate and wait for appropriate delay time before retry
+     */
+    calculateAndDelay(params: {
+        attempt: number;
+        response?: any;
+        hook: HookSettings;
+    }): Promise<void>;
+    /**
+     * Extract retry-after value from response
+     */
+    private getRetryAfterValue;
+    /**
+     * Get the default maximum number of retries
+     */
+    getDefaultMaxRetries(): number;
+    /**
+     * Set the default maximum number of retries
+     */
+    setDefaultMaxRetries(maxRetries: number): void;
+    /**
+     * Set the default maximum delay between retries
+     */
+    setDefaultMaxDelay(maxDelay: number): void;
+}
+
+/**
+ * Manages hooks for different status codes and their processing
+ */
+declare class HookManager {
+    private hooks;
+    private hookPromises;
+    /**
+     * Set hooks for different status codes
+     */
+    setHooks(hooks: Record<StatusCode, HookSettings>): void;
+    /**
+     * Get a hook for a specific status code
+     */
+    getHook(status: StatusCode): HookSettings | undefined;
+    /**
+     * Process a hook for a specific status code
+     */
+    processHook(accountId: string, status: StatusCode, error: any): Promise<Record<string, any> | null>;
+    /**
+     * Handle a retry failure with the appropriate hook
+     */
+    handleRetryFailure(accountId: string, status: StatusCode, error: any): Promise<void>;
+    /**
+     * Check if a hook exists and should retry for a given status
+     */
+    shouldRetry(status: StatusCode): boolean;
+}
+
+/**
+ * Handles HTTP requests to external APIs
+ */
+declare class HttpClient {
+    /**
+     * Make an HTTP request
+     */
+    makeRequest(apiParams: ApiCallParams, authToken: Token | Record<string, any>): Promise<any>;
+    /**
+     * Build URL with query parameters
+     */
+    private buildUrl;
+    /**
+     * Prepare form data for file uploads
+     */
+    private prepareFormData;
+    /**
+     * Build fetch options for request
+     */
+    private buildFetchOptions;
+    /**
+     * Handle API response
+     */
+    private handleResponse;
+}
+
+/**
+ * Manages account data and state
+ */
+declare class AccountManager {
+    private accounts;
+    private readonly DEFAULT_ACCOUNT;
+    /**
+     * Update account data for a specific account
+     */
+    updateAccountData(accountId: string | undefined, data: Partial<AccountData>): void;
+    /**
+     * Get account data for a specific account
+     */
+    getAccountData(accountId?: string): AccountData;
+    /**
+     * Check if an account's last request failed
+     */
+    didLastRequestFail(accountId?: string): boolean;
+    /**
+     * Set account's last request as failed
+     */
+    setLastRequestFailed(accountId?: string, failed?: boolean): void;
+    /**
+     * Update the last request time for an account
+     */
+    updateLastRequestTime(accountId?: string): void;
+}
+
+type TokenService = {
+    get: (accountId?: string) => Promise<Token>;
+    set: (token: Partial<Token>, accountId?: string) => Promise<void>;
+    refresh?: (refreshToken: string, accountId?: string) => Promise<OAuthToken>;
+};
+declare class TokenAuthProvider implements AuthProvider {
+    private tokenService;
+    constructor(tokenService: TokenService);
+    getAuthHeaders(accountId?: string): Promise<Record<string, string>>;
+    refresh(accountId: string): Promise<void>;
+}
+
+declare class ApiKeyAuthProvider implements AuthProvider {
+    private apiKey;
+    private headerName?;
+    private queryParamName?;
+    constructor(options: ApiKeyAuthProviderOptions);
+    getAuthHeaders(): Promise<Record<string, string>>;
+}
+
+declare class BasicAuthProvider implements AuthProvider {
+    private username;
+    private password;
+    constructor(options: BasicAuthProviderOptions);
+    getAuthHeaders(): Promise<Record<string, string>>;
+}
+
+/**
+ * ApiService - Core API service for making authenticated API calls
+ * with caching, retry, and hook support.
+ */
+declare class ApiService {
+    provider: string;
+    private authProvider;
+    private baseUrl;
+    private cacheManager;
+    private retryManager;
+    private hookManager;
+    private httpClient;
+    private accountManager;
+    private maxAttempts;
+    constructor();
+    /**
+     * Setup the API service
+     */
+    setup({ provider, authProvider, hooks, cacheTime, baseUrl, }: {
+        provider: string;
+        authProvider: AuthProvider;
+        hooks?: Record<StatusCode, HookSettings | null>;
+        cacheTime: number;
+        baseUrl?: string;
+    }): void;
+    /**
+     * Create a default handler for 401 (Unauthorized) errors
+     * that implements standard credential refresh behavior
+     */
+    private createDefaultAuthRefreshHandler;
+    /**
+     * Set the maximum number of retry attempts
+     */
+    setMaxAttempts(attempts: number): void;
+    /**
+     * Update account data
+     */
+    updateAccountData(accountId: string, data: Partial<Record<string, any>>): void;
+    /**
+     * Make an API call with all features (caching, retry, hooks)
+     */
+    call(apiCallParams: Omit<ApiCallParams, 'accountId'> & {
+        accountId?: string;
+        abortSignal?: AbortSignal;
+    }): Promise<any>;
+    /**
+     * Legacy method for backward compatibility
+     * @deprecated Use call() instead
+     */
+    makeApiCall(apiCallParams: Omit<ApiCallParams, 'accountId'> & {
+        accountId?: string;
+        abortSignal?: AbortSignal;
+    }): Promise<any>;
+    /**
+     * Make a request with retry capability
+     */
+    private makeRequestWithRetry;
+    /**
+     * Set the cache time in milliseconds
+     */
+    setCacheTime(milliseconds: number): void;
+    /**
+     * Clear the cache
+     */
+    clearCache(): void;
+}
+
+export { type AccountData, AccountManager, type ApiCallParams, ApiKeyAuthProvider, type ApiKeyAuthProviderOptions, type AuthProvider, BasicAuthProvider, type BasicAuthProviderOptions, CacheManager, type DelayStrategy, FetchError, HookManager, type HookSettings, HttpClient, type OAuthToken, RetryManager, type StatusCode, type Token, TokenAuthProvider, type TokenService$1 as TokenService, ApiService as default };

package/dist/index.d.ts

@@ -1,4 +1,293 @@
-import { AuthProvider, ApiCallParams, HookSettings, StatusCode } from './types';
+interface OAuthToken {
+    access_token: string;
+    expires_in: number;
+    id_token: string;
+    refresh_token: string;
+    scope: string;
+    token_type: string;
+}
+interface Token {
+    accountId: string;
+    access_token: string;
+    refresh_token: string;
+    provider: string;
+    enabled?: boolean;
+    updatedAt?: string;
+    primary?: boolean;
+}
+interface AccountData {
+    lastRequestTime?: number;
+    lastFailed?: boolean;
+    token?: Token;
+}
+interface DelayStrategy {
+    calculate: (attempt: number, response?: any) => number;
+}
+interface ApiCallParams {
+    accountId: string;
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    route: string;
+    base?: string;
+    body?: object;
+    data?: object;
+    headers?: Record<string, string>;
+    queryParams?: URLSearchParams;
+    accessToken?: string;
+    useAuth?: boolean;
+    noContentType?: boolean;
+    contentType?: string;
+    cacheTime?: number;
+    files?: File[];
+    abortSignal?: AbortSignal;
+}
+interface HookSettings {
+    /**
+     * Whether to retry the API call when this hook is triggered
+     */
+    shouldRetry: boolean;
+    /**
+     * Whether to apply delay between retries
+     */
+    useRetryDelay: boolean;
+    /**
+     * The maximum number of retry attempts for this status code
+     */
+    maxRetries?: number;
+    /**
+     * Wait for an existing hook to complete before starting a new one
+     * Useful for avoiding duplicate refresh token calls
+     */
+    preventConcurrentCalls?: boolean;
+    /**
+     * The main handler function called when this status code is encountered
+     * Return an object to update the API call parameters for the retry
+     */
+    handler: (accountId: string, response: any) => Promise<any>;
+    /**
+     * Called when all retry attempts for this status code have failed
+     */
+    onMaxRetriesExceeded?: (accountId: string, error: any) => Promise<void>;
+    /**
+     * Called when the handler function throws an error
+     */
+    onHandlerError?: (accountId: string, error: any) => Promise<void>;
+    /**
+     * Custom strategy for calculating delay between retries
+     */
+    delayStrategy?: DelayStrategy;
+    /**
+     * Maximum delay in milliseconds between retries
+     */
+    maxDelay?: number;
+}
+type StatusCode = string | number;
+interface AuthProvider {
+    /**
+     * Returns headers or other auth data for a request
+     */
+    getAuthHeaders(accountId?: string): Promise<Record<string, string>>;
+    /**
+     * Optional: refresh credentials if supported (for OAuth, etc.)
+     */
+    refresh?(refreshToken: string, accountId?: string): Promise<any>;
+}
+interface ApiKeyAuthProviderOptions {
+    apiKey: string;
+    headerName?: string;
+    queryParamName?: string;
+}
+interface BasicAuthProviderOptions {
+    username: string;
+    password: string;
+}
+type TokenService$1 = {
+    get: (accountId?: string) => Promise<Token>;
+    set: (token: Partial<Token>, accountId?: string) => Promise<void>;
+    refresh?: (refreshToken: string, accountId?: string) => Promise<OAuthToken>;
+};
+
+declare class FetchError extends Error {
+    name: string;
+    status: number;
+    code: string;
+    message: string;
+    data: any;
+    constructor(response: Response, data?: any, code?: string);
+}
+
+/**
+ * Handles caching of API responses
+ */
+declare class CacheManager {
+    private cache;
+    private cacheTime;
+    /**
+     * Get data from cache if available and not expired
+     */
+    getFromCache(apiCallParams: ApiCallParams): any;
+    /**
+     * Save data to cache
+     */
+    saveToCache(apiCallParams: ApiCallParams, data: any): void;
+    /**
+     * Generate a unique key for caching based on request parameters
+     */
+    private getRequestKey;
+    /**
+     * Set the default cache time in milliseconds
+     */
+    setCacheTime(milliseconds: number): void;
+    /**
+     * Clear the entire cache
+     */
+    clearCache(): void;
+}
+
+/**
+ * Handles retry logic and delay strategies for failed API calls
+ */
+declare class RetryManager {
+    private defaultMaxDelay;
+    private defaultMaxRetries;
+    /**
+     * Default exponential backoff strategy with full jitter
+     */
+    private defaultDelayStrategy;
+    /**
+     * Calculate and wait for appropriate delay time before retry
+     */
+    calculateAndDelay(params: {
+        attempt: number;
+        response?: any;
+        hook: HookSettings;
+    }): Promise<void>;
+    /**
+     * Extract retry-after value from response
+     */
+    private getRetryAfterValue;
+    /**
+     * Get the default maximum number of retries
+     */
+    getDefaultMaxRetries(): number;
+    /**
+     * Set the default maximum number of retries
+     */
+    setDefaultMaxRetries(maxRetries: number): void;
+    /**
+     * Set the default maximum delay between retries
+     */
+    setDefaultMaxDelay(maxDelay: number): void;
+}
+
+/**
+ * Manages hooks for different status codes and their processing
+ */
+declare class HookManager {
+    private hooks;
+    private hookPromises;
+    /**
+     * Set hooks for different status codes
+     */
+    setHooks(hooks: Record<StatusCode, HookSettings>): void;
+    /**
+     * Get a hook for a specific status code
+     */
+    getHook(status: StatusCode): HookSettings | undefined;
+    /**
+     * Process a hook for a specific status code
+     */
+    processHook(accountId: string, status: StatusCode, error: any): Promise<Record<string, any> | null>;
+    /**
+     * Handle a retry failure with the appropriate hook
+     */
+    handleRetryFailure(accountId: string, status: StatusCode, error: any): Promise<void>;
+    /**
+     * Check if a hook exists and should retry for a given status
+     */
+    shouldRetry(status: StatusCode): boolean;
+}
+
+/**
+ * Handles HTTP requests to external APIs
+ */
+declare class HttpClient {
+    /**
+     * Make an HTTP request
+     */
+    makeRequest(apiParams: ApiCallParams, authToken: Token | Record<string, any>): Promise<any>;
+    /**
+     * Build URL with query parameters
+     */
+    private buildUrl;
+    /**
+     * Prepare form data for file uploads
+     */
+    private prepareFormData;
+    /**
+     * Build fetch options for request
+     */
+    private buildFetchOptions;
+    /**
+     * Handle API response
+     */
+    private handleResponse;
+}
+
+/**
+ * Manages account data and state
+ */
+declare class AccountManager {
+    private accounts;
+    private readonly DEFAULT_ACCOUNT;
+    /**
+     * Update account data for a specific account
+     */
+    updateAccountData(accountId: string | undefined, data: Partial<AccountData>): void;
+    /**
+     * Get account data for a specific account
+     */
+    getAccountData(accountId?: string): AccountData;
+    /**
+     * Check if an account's last request failed
+     */
+    didLastRequestFail(accountId?: string): boolean;
+    /**
+     * Set account's last request as failed
+     */
+    setLastRequestFailed(accountId?: string, failed?: boolean): void;
+    /**
+     * Update the last request time for an account
+     */
+    updateLastRequestTime(accountId?: string): void;
+}
+
+type TokenService = {
+    get: (accountId?: string) => Promise<Token>;
+    set: (token: Partial<Token>, accountId?: string) => Promise<void>;
+    refresh?: (refreshToken: string, accountId?: string) => Promise<OAuthToken>;
+};
+declare class TokenAuthProvider implements AuthProvider {
+    private tokenService;
+    constructor(tokenService: TokenService);
+    getAuthHeaders(accountId?: string): Promise<Record<string, string>>;
+    refresh(accountId: string): Promise<void>;
+}
+
+declare class ApiKeyAuthProvider implements AuthProvider {
+    private apiKey;
+    private headerName?;
+    private queryParamName?;
+    constructor(options: ApiKeyAuthProviderOptions);
+    getAuthHeaders(): Promise<Record<string, string>>;
+}
+
+declare class BasicAuthProvider implements AuthProvider {
+    private username;
+    private password;
+    constructor(options: BasicAuthProviderOptions);
+    getAuthHeaders(): Promise<Record<string, string>>;
+}
+
 /**
  * ApiService - Core API service for making authenticated API calls
  * with caching, retry, and hook support.
@@ -65,4 +354,5 @@ declare class ApiService {
      */
     clearCache(): void;
 }
-export default ApiService;
+
+export { type AccountData, AccountManager, type ApiCallParams, ApiKeyAuthProvider, type ApiKeyAuthProviderOptions, type AuthProvider, BasicAuthProvider, type BasicAuthProviderOptions, CacheManager, type DelayStrategy, FetchError, HookManager, type HookSettings, HttpClient, type OAuthToken, RetryManager, type StatusCode, type Token, TokenAuthProvider, type TokenService$1 as TokenService, ApiService as default };