fetchguard 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,551 @@
+import * as ts_micro_result from 'ts-micro-result';
+import { Result, SerializedResult } from 'ts-micro-result';
+import * as ts_micro_result_factories_errors_advanced from 'ts-micro-result/factories/errors-advanced';
+
+/**
+ * FetchGuard Business Types
+ *
+ * Contains domain logic types: Provider, Config, API Response, etc.
+ * For message protocol types, see messages.ts
+ */
+/**
+ * Token info returned from provider
+ */
+interface TokenInfo {
+    token: string;
+    expiresAt?: number;
+    refreshToken?: string;
+    user?: unknown;
+}
+/**
+ * Interface for token provider
+ *
+ * Provider has 3 required methods:
+ * - refreshToken: Refresh access token when expired
+ * - login: Login with credentials
+ * - logout: Logout (clear tokens)
+ *
+ * User can add custom auth methods (loginWithPhone, loginWithGoogle, etc.)
+ * All custom methods must return Result<TokenInfo> for token retrieval
+ */
+interface TokenProvider {
+    /**
+     * Refresh tokens (required)
+     * @param refreshToken - Current refresh token (from worker memory, null if not available)
+     * @returns Result<TokenInfo> with new tokens
+     */
+    refreshToken(refreshToken: string | null): Promise<Result<TokenInfo>>;
+    /**
+     * Login with credentials (required)
+     * @param payload - Login credentials (email/password, etc.)
+     * @returns Result<TokenInfo> with tokens
+     */
+    login(payload: unknown): Promise<Result<TokenInfo>>;
+    /**
+     * Logout - clear tokens (required)
+     * @param payload - Optional logout payload
+     * @returns Result<TokenInfo> with all fields reset (token = '', refreshToken = undefined, user = undefined)
+     */
+    logout(payload?: unknown): Promise<Result<TokenInfo>>;
+    /**
+     * Custom auth methods (optional)
+     * Examples: loginWithPhone, loginWithGoogle, loginWithFacebook, etc.
+     * All must return Result<TokenInfo> for token retrieval
+     */
+    [key: string]: (...args: any[]) => Promise<Result<TokenInfo>>;
+}
+/**
+ * Interface for refresh token storage - only stores refresh token
+ *
+ * Access token is always stored in worker memory.
+ * Refresh token storage is OPTIONAL:
+ * - If available (IndexedDB): persist refresh token for reuse after reload
+ * - If not (undefined): cookie-based auth (httpOnly cookie)
+ */
+interface RefreshTokenStorage {
+    get(): Promise<string | null>;
+    set(token: string | null): Promise<void>;
+}
+/**
+ * Interface for token parser - parse token from backend response
+ * Parser returns complete TokenInfo (including user data)
+ */
+interface TokenParser {
+    parse(response: Response): Promise<TokenInfo>;
+}
+/**
+ * Interface for auth strategy - defines how to call auth APIs
+ *
+ * Strategy focuses only on API calls, returns Response
+ * Provider handles parsing and storage
+ *
+ * All methods are required
+ */
+interface AuthStrategy {
+    /** Refresh access token */
+    refresh(refreshToken: string | null): Promise<Response>;
+    /** Login with credentials */
+    login(payload: unknown): Promise<Response>;
+    /** Logout */
+    logout(payload?: unknown): Promise<Response>;
+}
+/**
+ * Provider preset configuration for built-in auth strategies
+ */
+interface ProviderPresetConfig {
+    type: 'cookie-auth' | 'body-auth';
+    refreshUrl: string;
+    loginUrl: string;
+    logoutUrl: string;
+    refreshTokenKey?: string;
+}
+/**
+ * Configuration for FetchGuard client
+ */
+interface FetchGuardOptions {
+    /**
+     * Token provider - 3 options:
+     * 1. TokenProvider instance (for custom providers)
+     * 2. ProviderPresetConfig object (for built-in presets)
+     * 3. string (for registry lookup - advanced usage)
+     */
+    provider: TokenProvider | ProviderPresetConfig | string;
+    /** List of allowed domains (wildcard supported) */
+    allowedDomains?: string[];
+    /** Debug mode */
+    debug?: boolean;
+    /** Early refresh time for tokens (ms) */
+    refreshEarlyMs?: number;
+    /** Default timeout for requests (ms) */
+    defaultTimeoutMs?: number;
+    /** Default retry count */
+    retryCount?: number;
+    /** Delay between retries (ms) */
+    retryDelayMs?: number;
+}
+/**
+ * Internal worker configuration
+ */
+interface WorkerConfig {
+    allowedDomains: string[];
+    debug: boolean;
+    refreshEarlyMs: number;
+    defaultTimeoutMs: number;
+    retryCount: number;
+    retryDelayMs: number;
+}
+/**
+ * Extended RequestInit with FetchGuard-specific options
+ */
+interface FetchGuardRequestInit extends RequestInit {
+    /** Whether this request requires authentication. Default: true */
+    requiresAuth?: boolean;
+    /** Include response headers in result metadata and FETCH_RESULT payload */
+    includeHeaders?: boolean;
+}
+/**
+ * API response wrapper
+ */
+interface ApiResponse<T = unknown> {
+    data: T;
+    status: number;
+    headers: Record<string, string>;
+}
+
+/**
+ * FetchGuard Client - main interface cho việc gọi API thông qua Web Worker
+ */
+declare class FetchGuardClient {
+    private worker;
+    private messageId;
+    private pendingRequests;
+    private authListeners;
+    private requestQueue;
+    private isProcessingQueue;
+    private queueTimeout;
+    private setupResolve?;
+    private setupReject?;
+    constructor(options: FetchGuardOptions);
+    /**
+     * Initialize worker with config and provider
+     */
+    private initializeWorker;
+    /**
+     * Handle worker messages
+     */
+    private handleWorkerMessage;
+    /**
+     * Handle worker errors
+     */
+    private handleWorkerError;
+    /**
+     * Generate unique message ID
+     */
+    private generateMessageId;
+    /**
+     * Make API request
+     */
+    fetch(url: string, options?: FetchGuardRequestInit): Promise<Result<ApiResponse>>;
+    /**
+     * Fetch with id for external cancellation
+     * Returns { id, result, cancel }
+     * Now uses queue system for sequential processing
+     */
+    fetchWithId(url: string, options?: FetchGuardRequestInit): {
+        id: string;
+        result: Promise<Result<ApiResponse>>;
+        cancel: () => void;
+    };
+    /**
+     * Cancel a pending request by ID
+     */
+    cancel(id: string): void;
+    /**
+     * Convenience methods
+     */
+    get(url: string, options?: Omit<FetchGuardRequestInit, 'method' | 'body'>): Promise<Result<ApiResponse>>;
+    post(url: string, body?: any, options?: Omit<FetchGuardRequestInit, 'method' | 'body'>): Promise<Result<ApiResponse>>;
+    put(url: string, body?: any, options?: Omit<FetchGuardRequestInit, 'method' | 'body'>): Promise<Result<ApiResponse>>;
+    delete(url: string, options?: Omit<FetchGuardRequestInit, 'method' | 'body'>): Promise<Result<ApiResponse>>;
+    patch(url: string, body?: any, options?: Omit<FetchGuardRequestInit, 'method' | 'body'>): Promise<Result<ApiResponse>>;
+    /**
+     * Generic method to call any auth method on provider
+     * @param method - Method name (login, logout, loginWithPhone, etc.)
+     * @param args - Arguments to pass to the method
+     * @returns Result with success (auth state changes emitted via AUTH_STATE_CHANGED event)
+     */
+    call(method: string, ...args: unknown[]): Promise<Result<void>>;
+    /**
+     * Convenience wrapper for login
+     * Note: Auth state changes are emitted via onAuthStateChanged event
+     */
+    login(payload?: unknown): Promise<Result<void>>;
+    /**
+     * Convenience wrapper for logout
+     * Note: Auth state changes are emitted via onAuthStateChanged event
+     */
+    logout(payload?: unknown): Promise<Result<void>>;
+    onAuthStateChanged(cb: (state: {
+        authenticated: boolean;
+        expiresAt?: number | null;
+        user?: unknown;
+    }) => void): () => void;
+    /** Send PING and await PONG */
+    ping(): Promise<Result<{
+        timestamp: number;
+    }>>;
+    /**
+     * Send message through queue system
+     * All messages go through queue for sequential processing
+     */
+    private sendMessageQueued;
+    /**
+     * Process message queue sequentially
+     * Benefits:
+     * - Sequential processing prevents worker overload
+     * - Better error isolation (one failure doesn't affect others)
+     * - 50ms delay between requests for backpressure
+     */
+    private processQueue;
+    /**
+     * Cleanup - terminate worker
+     */
+    destroy(): void;
+}
+/**
+ * Factory function to create FetchGuard client
+ */
+declare function createClient(options: FetchGuardOptions): FetchGuardClient;
+
+/**
+ * MESSAGE PAYLOADS - SINGLE SOURCE OF TRUTH
+ *
+ * Define all message payloads here. Type unions and MSG constants are auto-generated.
+ *
+ * USAGE:
+ * - To add a new message: Just add one line to the appropriate interface
+ * - Payload types are automatically inferred
+ * - MSG constants are automatically generated
+ *
+ * EXAMPLE:
+ * ```typescript
+ * interface MainPayloads {
+ *   NEW_MESSAGE: { foo: string }  // Add this line
+ * }
+ * // => Automatically get MainToWorkerMessage union with NEW_MESSAGE
+ * // => Automatically get MSG.NEW_MESSAGE = 'NEW_MESSAGE'
+ * ```
+ */
+/**
+ * Payloads for messages sent from Main thread → Worker thread
+ */
+interface MainPayloads {
+    SETUP: {
+        config: WorkerConfig;
+        providerConfig: ProviderPresetConfig | string | null;
+    };
+    FETCH: {
+        url: string;
+        options?: FetchGuardRequestInit;
+    };
+    AUTH_CALL: {
+        method: string;
+        args: unknown[];
+    };
+    CANCEL: undefined;
+    PING: {
+        timestamp: number;
+    };
+}
+/**
+ * Payloads for messages sent from Worker thread → Main thread
+ */
+interface WorkerPayloads {
+    RESULT: {
+        result: SerializedResult | object;
+    };
+    READY: undefined;
+    PONG: {
+        timestamp: number;
+    };
+    LOG: {
+        level: 'info' | 'warn' | 'error';
+        message: string;
+    };
+    AUTH_STATE_CHANGED: {
+        authenticated: boolean;
+        expiresAt?: number | null;
+        user?: unknown;
+    };
+    FETCH_RESULT: {
+        status: number;
+        headers?: Record<string, string>;
+        body: string;
+    };
+    FETCH_ERROR: {
+        error: string;
+        status?: number;
+    };
+}
+/**
+ * Generate message type from payload definition
+ * Handles optional payloads (undefined) gracefully
+ */
+type MessageFromPayloads<P> = {
+    [K in keyof P]: {
+        id: string;
+        type: K;
+    } & (P[K] extends undefined ? {} : {
+        payload: P[K];
+    });
+}[keyof P];
+/**
+ * Message type unions - auto-generated from payload interfaces
+ */
+type MainToWorkerMessage = MessageFromPayloads<MainPayloads>;
+type WorkerToMainMessage = MessageFromPayloads<WorkerPayloads>;
+/**
+ * Message type unions for compile-time type checking
+ */
+type MainType = keyof MainPayloads;
+type WorkerType = keyof WorkerPayloads;
+type MessageType = MainType | WorkerType;
+/**
+ * MSG constants object - auto-generated from payload keys
+ * Usage: MSG.SETUP, MSG.FETCH, etc.
+ */
+declare const MSG: { readonly [K in MessageType]: K; };
+
+/**
+ * Error definitions organized by domain
+ * Using ts-micro-result's defineError for consistency
+ */
+/**
+ * General errors
+ */
+declare const GeneralErrors: {
+    readonly Unexpected: (params?: ts_micro_result.BaseErrorParams) => ts_micro_result.ErrorDetail;
+    readonly UnknownMessage: (params?: ts_micro_result.BaseErrorParams) => ts_micro_result.ErrorDetail;
+    readonly ResultParse: (params?: ts_micro_result.BaseErrorParams) => ts_micro_result.ErrorDetail;
+};
+/**
+ * Initialization errors
+ */
+declare const InitErrors: {
+    readonly NotInitialized: (params?: ts_micro_result.BaseErrorParams) => ts_micro_result.ErrorDetail;
+    readonly ProviderInitFailed: (params?: ts_micro_result.BaseErrorParams) => ts_micro_result.ErrorDetail;
+    readonly InitFailed: (params?: ts_micro_result.BaseErrorParams) => ts_micro_result.ErrorDetail;
+};
+/**
+ * Authentication & Token errors
+ */
+declare const AuthErrors: {
+    readonly TokenRefreshFailed: (params?: ts_micro_result.BaseErrorParams) => ts_micro_result.ErrorDetail;
+    readonly LoginFailed: (params?: ts_micro_result.BaseErrorParams) => ts_micro_result.ErrorDetail;
+    readonly LogoutFailed: (params?: ts_micro_result.BaseErrorParams) => ts_micro_result.ErrorDetail;
+    readonly NotAuthenticated: (params?: ts_micro_result.BaseErrorParams) => ts_micro_result.ErrorDetail;
+};
+/**
+ * Domain validation errors
+ */
+declare const DomainErrors: {
+    readonly NotAllowed: (params?: ({
+        url: any;
+    } & Partial<ts_micro_result_factories_errors_advanced.BaseErrorParams>) | undefined) => ts_micro_result.ErrorDetail;
+};
+/**
+ * Network & HTTP errors
+ */
+declare const NetworkErrors: {
+    readonly NetworkError: (params?: ts_micro_result.BaseErrorParams) => ts_micro_result.ErrorDetail;
+    readonly HttpError: (params?: ts_micro_result.BaseErrorParams) => ts_micro_result.ErrorDetail;
+    readonly FetchError: (params?: ts_micro_result.BaseErrorParams) => ts_micro_result.ErrorDetail;
+};
+/**
+ * Request errors
+ */
+declare const RequestErrors: {
+    readonly Cancelled: (params?: ts_micro_result.BaseErrorParams) => ts_micro_result.ErrorDetail;
+    readonly Timeout: (params?: ts_micro_result.BaseErrorParams) => ts_micro_result.ErrorDetail;
+};
+
+/**
+ * Register a token provider with name
+ */
+declare function registerProvider(name: string, provider: TokenProvider): void;
+/**
+ * Get provider by name
+ */
+declare function getProvider(name: string): TokenProvider;
+/**
+ * Check if provider exists
+ */
+declare function hasProvider(name: string): boolean;
+/**
+ * Get list of all provider names
+ */
+declare function listProviders(): string[];
+/**
+ * Remove provider
+ */
+declare function unregisterProvider(name: string): boolean;
+/**
+ * Remove all providers
+ */
+declare function clearProviders(): void;
+
+/**
+ * Custom auth method type
+ */
+type CustomAuthMethod = (...args: any[]) => Promise<Result<TokenInfo>>;
+/**
+ * Configuration for creating provider
+ *
+ * refreshStorage: OPTIONAL - to load refresh token initially when worker starts
+ * - undefined: cookie-based auth (httpOnly cookie, no need to load)
+ * - RefreshTokenStorage: body-based auth (load from IndexedDB on startup)
+ *
+ * strategy: AuthStrategy with refresh (required), login/logout (required)
+ *
+ * customMethods: OPTIONAL - custom auth methods (loginWithPhone, loginWithGoogle, etc.)
+ */
+interface ProviderConfig {
+    refreshStorage?: RefreshTokenStorage;
+    parser: TokenParser;
+    strategy: AuthStrategy;
+    customMethods?: Record<string, CustomAuthMethod>;
+}
+/**
+ * Factory function to create TokenProvider from modular components
+ *
+ * Provider automatically handles refresh token:
+ * - If refreshToken is null and storage exists → load from storage initially
+ * - If refreshToken exists → use token from worker memory
+ * - Cookie-based (no storage) → always null
+ *
+ * Custom methods:
+ * - User can add custom auth methods (loginWithPhone, loginWithGoogle, etc.)
+ * - Custom methods will be spread into provider object
+ */
+declare function createProvider(config: ProviderConfig): TokenProvider;
+
+/**
+ * IndexedDB storage - only stores refresh token in IndexedDB
+ * Suitable for body-based refresh strategy
+ * Persists refresh token for reuse after reload
+ */
+declare function createIndexedDBStorage(dbName?: string, refreshTokenKey?: string): RefreshTokenStorage;
+
+/**
+ * Body parser - parse token from response body (JSON)
+ * Expects response format: { data: { accessToken, refreshToken, expiresAt?, user? } }
+ */
+declare const bodyParser: TokenParser;
+
+/**
+ * Cookie parser - parse access token from response body
+ * Expects response format: { data: { accessToken, expiresAt?, user? } }
+ * Refresh token is automatically set by backend into httpOnly cookie
+ */
+declare const cookieParser: TokenParser;
+
+/**
+ * Cookie auth strategy - all auth operations via httpOnly cookies
+ * Suitable for SSR and cross-domain authentication
+ *
+ * Refresh token is sent automatically via httpOnly cookie
+ * Credentials are sent in request body
+ */
+declare function createCookieStrategy(config: {
+    refreshUrl: string;
+    loginUrl: string;
+    logoutUrl: string;
+}): AuthStrategy;
+/**
+ * Standard cookie strategy
+ */
+declare const cookieStrategy: AuthStrategy;
+
+/**
+ * Body auth strategy - all auth operations via request body
+ * Suitable for SPA applications
+ *
+ * All tokens/credentials are sent in request body
+ */
+declare function createBodyStrategy(config: {
+    refreshUrl: string;
+    loginUrl: string;
+    logoutUrl: string;
+}): AuthStrategy;
+/**
+ * Standard body strategy
+ */
+declare const bodyStrategy: AuthStrategy;
+
+/**
+ * Cookie Provider - uses httpOnly cookies
+ * Suitable for SSR and cross-domain authentication
+ *
+ * Access token: Worker memory
+ * Refresh token: httpOnly cookie (managed by backend)
+ */
+declare function createCookieProvider(config: {
+    refreshUrl: string;
+    loginUrl: string;
+    logoutUrl: string;
+}): TokenProvider;
+/**
+ * Body Provider - refresh token in response body, persisted to IndexedDB
+ * Suitable for SPA applications
+ *
+ * Access token: Worker memory
+ * Refresh token: IndexedDB (persists across reload)
+ */
+declare function createBodyProvider(config: {
+    refreshUrl: string;
+    loginUrl: string;
+    logoutUrl: string;
+    refreshTokenKey?: string;
+}): TokenProvider;
+
+export { type ApiResponse, AuthErrors, type AuthStrategy, DomainErrors, FetchGuardClient, type FetchGuardOptions, type FetchGuardRequestInit, GeneralErrors, InitErrors, MSG, type MainToWorkerMessage, type MessageType, NetworkErrors, type ProviderConfig, type ProviderPresetConfig, type RefreshTokenStorage, RequestErrors, type TokenInfo, type TokenParser, type TokenProvider, type WorkerConfig, type WorkerToMainMessage, bodyParser, bodyStrategy, clearProviders, cookieParser, cookieStrategy, createBodyProvider, createBodyStrategy, createClient, createCookieProvider, createCookieStrategy, createIndexedDBStorage, createProvider, getProvider, hasProvider, listProviders, registerProvider, unregisterProvider };