@auth-craft/client 0.1.0 → 0.1.2

package/dist/transport/client.js

@@ -0,0 +1,940 @@
+import { err, ok } from 'ts-micro-result';
+import { DEFAULT_REFRESH_EARLY_MS } from './constants';
+import { RequestErrors } from './errors';
+import { MSG } from './messages';
+import { toResult } from './result';
+import { isFormData, serializeFormData } from './utils/formdata';
+/** Default max concurrent requests */
+const DEFAULT_MAX_CONCURRENT = 6;
+/** Default max queue size */
+const DEFAULT_MAX_QUEUE_SIZE = 1000;
+/** Default setup timeout (ms) */
+const DEFAULT_SETUP_TIMEOUT = 10000;
+/** Default request timeout (ms) */
+const DEFAULT_REQUEST_TIMEOUT = 30000;
+/**
+ * FetchGuard Client - main interface cho việc gọi API thông qua Web Worker
+ */
+export class FetchGuardClient {
+    worker;
+    messageId = 0;
+    // Using unknown because different messages have different response types
+    // (FetchEnvelope for FETCH, AuthResult for AUTH_CALL, etc.)
+    pendingRequests = new Map();
+    /** Track request URLs for debug hooks */
+    requestUrls = new Map();
+    /** Track request timing for metrics */
+    requestTimings = new Map();
+    authListeners = new Set();
+    readyListeners = new Set();
+    isReady = false;
+    requestQueue = [];
+    activeRequests = 0;
+    maxConcurrent;
+    maxQueueSize;
+    setupTimeout;
+    requestTimeout;
+    setupResolve;
+    setupReject;
+    debug;
+    retry;
+    dedupe;
+    /** In-flight requests for deduplication */
+    inFlightRequests = new Map();
+    /** Recent completed requests for time-window deduplication */
+    recentResults = new Map();
+    constructor(options) {
+        this.maxConcurrent = options.maxConcurrent ?? DEFAULT_MAX_CONCURRENT;
+        this.maxQueueSize = options.maxQueueSize ?? DEFAULT_MAX_QUEUE_SIZE;
+        this.setupTimeout = options.setupTimeout ?? DEFAULT_SETUP_TIMEOUT;
+        this.requestTimeout = options.requestTimeout ?? DEFAULT_REQUEST_TIMEOUT;
+        this.debug = options.debug;
+        this.retry = options.retry;
+        this.dedupe = options.dedupe;
+        // Use custom worker factory if provided, otherwise use built-in worker
+        if (options.workerFactory) {
+            this.worker = options.workerFactory();
+        }
+        else {
+            this.worker = new Worker(new URL('./worker.js', import.meta.url), {
+                type: 'module',
+            });
+        }
+        this.worker.onmessage = this.handleWorkerMessage.bind(this);
+        this.worker.onerror = this.handleWorkerError.bind(this);
+        this.initializeWorker(options);
+    }
+    /**
+     * Initialize worker with config and provider
+     */
+    async initializeWorker(options) {
+        const config = {
+            allowedDomains: options.allowedDomains || [],
+            refreshEarlyMs: options.refreshEarlyMs ?? DEFAULT_REFRESH_EARLY_MS,
+            defaultHeaders: options.defaultHeaders || {},
+        };
+        // Serialize provider config based on type
+        let providerConfig = null;
+        if (typeof options.provider === 'string') {
+            // String = registry lookup (advanced usage)
+            providerConfig = options.provider;
+        }
+        else if ('type' in options.provider && options.provider.type) {
+            // ProviderPresetConfig object (recommended)
+            providerConfig = options.provider;
+        }
+        else {
+            // TokenProvider instance - NOT SUPPORTED
+            throw new Error('Direct TokenProvider instance is not supported. Use ProviderPresetConfig instead:\n' +
+                '  { type: "cookie-auth", refreshUrl: "...", loginUrl: "...", logoutUrl: "..." }\n' +
+                'Or for custom providers, register in worker code and use string name.');
+        }
+        const message = {
+            id: this.generateMessageId(),
+            type: MSG.SETUP,
+            payload: {
+                config,
+                providerConfig,
+            },
+        };
+        return new Promise((resolve, reject) => {
+            // Setup will respond with READY (no id, so we track separately)
+            this.setupResolve = resolve;
+            this.setupReject = reject;
+            this.worker.postMessage(message);
+            setTimeout(() => {
+                if (this.setupReject) {
+                    this.setupReject(new Error('Worker setup timeout'));
+                    this.setupResolve = undefined;
+                    this.setupReject = undefined;
+                }
+            }, this.setupTimeout);
+        });
+    }
+    /**
+     * Handle worker messages
+     */
+    handleWorkerMessage(event) {
+        const { id, type, payload } = event.data;
+        if (type === MSG.FETCH_RESULT) {
+            // FETCH_RESULT contains FetchEnvelope (raw HTTP response)
+            // Worker doesn't judge HTTP status - client receives envelope as-is
+            const request = this.pendingRequests.get(id);
+            if (!request)
+                return;
+            const url = this.requestUrls.get(id);
+            const timing = this.requestTimings.get(id);
+            this.pendingRequests.delete(id);
+            this.requestUrls.delete(id);
+            this.requestTimings.delete(id);
+            this.onRequestComplete();
+            // Calculate metrics
+            const metrics = this.calculateMetrics(timing);
+            // Debug hook: onResponse
+            if (this.debug?.onResponse && url) {
+                this.debug.onResponse(url, payload, metrics);
+            }
+            request.resolve(ok(payload));
+            return;
+        }
+        if (type === MSG.FETCH_ERROR) {
+            // Network/timeout/cancel errors (no HTTP response)
+            const request = this.pendingRequests.get(id);
+            if (!request)
+                return;
+            const url = this.requestUrls.get(id);
+            const timing = this.requestTimings.get(id);
+            this.pendingRequests.delete(id);
+            this.requestUrls.delete(id);
+            this.requestTimings.delete(id);
+            this.onRequestComplete();
+            const errorMessage = String(payload?.error || 'Network error');
+            // Calculate metrics
+            const metrics = this.calculateMetrics(timing);
+            // Debug hook: onError
+            if (this.debug?.onError && url) {
+                this.debug.onError(url, { code: 'NETWORK_ERROR', message: errorMessage }, metrics);
+            }
+            request.resolve(err(RequestErrors.NetworkError({ message: errorMessage })));
+            return;
+        }
+        if (type === MSG.ERROR) {
+            const request = this.pendingRequests.get(id);
+            if (!request)
+                return;
+            this.pendingRequests.delete(id);
+            this.onRequestComplete();
+            request.resolve(err(payload.errors, payload.meta));
+            return;
+        }
+        if (type === MSG.SETUP_ERROR) {
+            // Setup failed - reject setup promise
+            if (this.setupReject) {
+                this.setupReject(new Error(`Worker setup failed: ${payload?.error || 'Unknown error'}`));
+                this.setupResolve = undefined;
+                this.setupReject = undefined;
+            }
+            return;
+        }
+        if (type === MSG.READY) {
+            this.isReady = true;
+            // Debug hook: onWorkerReady
+            this.debug?.onWorkerReady?.();
+            // Notify ready listeners
+            for (const listener of this.readyListeners) {
+                listener();
+            }
+            if (this.setupResolve) {
+                this.setupResolve();
+                this.setupResolve = undefined;
+                this.setupReject = undefined;
+            }
+            return;
+        }
+        if (type === MSG.PONG) {
+            const request = this.pendingRequests.get(id);
+            if (request) {
+                this.pendingRequests.delete(id);
+                this.onRequestComplete();
+                request.resolve(ok({ timestamp: payload?.timestamp }));
+            }
+            return;
+        }
+        if (type === MSG.AUTH_STATE_CHANGED) {
+            for (const cb of this.authListeners)
+                cb(payload);
+            return;
+        }
+        if (type === MSG.AUTH_CALL_RESULT) {
+            const request = this.pendingRequests.get(id);
+            if (request) {
+                this.pendingRequests.delete(id);
+                this.onRequestComplete();
+                request.resolve(ok(payload)); // payload is AuthResult
+            }
+            return;
+        }
+        if (type === MSG.TOKEN_REFRESHED) {
+            // Debug hook: onRefresh
+            this.debug?.onRefresh?.(payload?.reason);
+            return;
+        }
+    }
+    /**
+     * Handle worker errors
+     */
+    handleWorkerError(error) {
+        console.error('Worker error:', error);
+        // Debug hook: onWorkerError
+        this.debug?.onWorkerError?.(error);
+        // Reject all pending requests
+        for (const [_id, request] of this.pendingRequests) {
+            request.reject(new Error(`Worker error: ${error.message}`));
+        }
+        this.pendingRequests.clear();
+        this.requestUrls.clear();
+        this.requestTimings.clear();
+    }
+    /**
+     * Generate unique message ID
+     */
+    generateMessageId() {
+        return `msg_${++this.messageId}_${Date.now()}`;
+    }
+    /**
+     * Make API request with optional deduplication, retry, and AbortSignal support
+     *
+     * @param url - Full URL to fetch
+     * @param options - Request options including optional AbortSignal
+     * @returns Result with FetchEnvelope on success, error on failure
+     *
+     * @example
+     * // With AbortSignal
+     * const controller = new AbortController()
+     * setTimeout(() => controller.abort(), 5000)
+     * const result = await api.fetch('/slow', { signal: controller.signal })
+     */
+    async fetch(url, options = {}) {
+        // Extract signal from options (not passed to worker - handled client-side)
+        const { signal, ...restOptions } = options;
+        // Check if already aborted
+        if (signal?.aborted) {
+            return err(RequestErrors.Cancelled());
+        }
+        // Check for deduplication
+        const dedupeKey = this.getDedupeKey(url, restOptions);
+        if (dedupeKey) {
+            // Check for in-flight request
+            const inFlight = this.inFlightRequests.get(dedupeKey);
+            if (inFlight) {
+                // If we have a signal, wrap the in-flight promise to support cancellation
+                if (signal) {
+                    return this.wrapWithAbortSignal(inFlight, signal, null);
+                }
+                return inFlight;
+            }
+            // Check for recent result within time window
+            const window = this.dedupe?.window ?? 0;
+            if (window > 0) {
+                const recent = this.recentResults.get(dedupeKey);
+                if (recent && Date.now() - recent.timestamp < window) {
+                    return recent.result;
+                }
+            }
+            // Create deduped request
+            const promise = this.fetchWithRetryAndSignal(url, restOptions, signal ?? undefined);
+            this.inFlightRequests.set(dedupeKey, promise);
+            try {
+                const result = await promise;
+                // Store result for time-window deduplication
+                if (window > 0) {
+                    this.recentResults.set(dedupeKey, { result, timestamp: Date.now() });
+                    // Clean up old results after window expires
+                    setTimeout(() => this.recentResults.delete(dedupeKey), window);
+                }
+                return result;
+            }
+            finally {
+                this.inFlightRequests.delete(dedupeKey);
+            }
+        }
+        // No deduplication - just fetch with retry and signal
+        return this.fetchWithRetryAndSignal(url, restOptions, signal ?? undefined);
+    }
+    /**
+     * Wrap a promise with AbortSignal support
+     */
+    wrapWithAbortSignal(promise, signal, requestId) {
+        return new Promise((resolve) => {
+            // Handle abort
+            const abortHandler = () => {
+                if (requestId) {
+                    this.cancel(requestId);
+                }
+                resolve(err(RequestErrors.Cancelled()));
+            };
+            if (signal.aborted) {
+                abortHandler();
+                return;
+            }
+            signal.addEventListener('abort', abortHandler, { once: true });
+            promise.then((result) => {
+                signal.removeEventListener('abort', abortHandler);
+                resolve(result);
+            });
+        });
+    }
+    /**
+     * Fetch with retry logic and AbortSignal support (internal)
+     */
+    async fetchWithRetryAndSignal(url, options, signal) {
+        const maxAttempts = this.retry?.maxAttempts ?? 0;
+        const delay = this.retry?.delay ?? 1000;
+        const backoff = this.retry?.backoff ?? 1;
+        const maxDelay = this.retry?.maxDelay ?? 30000;
+        const jitter = this.retry?.jitter ?? 0;
+        const shouldRetry = this.retry?.shouldRetry ?? this.defaultShouldRetry;
+        let lastResult = null;
+        let currentDelay = delay;
+        // Initial attempt + retries
+        for (let attempt = 0; attempt <= maxAttempts; attempt++) {
+            // Check if aborted before each attempt
+            if (signal?.aborted) {
+                return err(RequestErrors.Cancelled());
+            }
+            const { id, result } = this.fetchWithId(url, options);
+            // If we have a signal, wrap result with abort support
+            if (signal) {
+                lastResult = await this.wrapWithAbortSignal(result, signal, id);
+            }
+            else {
+                lastResult = await result;
+            }
+            // Success or HTTP error (4xx/5xx) - don't retry
+            if (lastResult.ok) {
+                return lastResult;
+            }
+            // Check if cancelled
+            if (lastResult.errors[0]?.code === 'REQUEST_CANCELLED') {
+                return lastResult;
+            }
+            // Check if we should retry this error
+            const error = lastResult.errors[0];
+            const errorDetail = {
+                code: error?.code ?? 'NETWORK_ERROR',
+                message: error?.message ?? 'Unknown error',
+            };
+            // Don't retry if:
+            // - This was the last attempt
+            // - Error is not retryable (e.g., cancelled)
+            if (attempt >= maxAttempts || !shouldRetry(errorDetail)) {
+                return lastResult;
+            }
+            // Wait before retry (with exponential backoff and optional jitter)
+            // Jitter only applies when shouldRetry=true (we're actually retrying)
+            const cappedDelay = Math.min(currentDelay, maxDelay);
+            const jitteredDelay = this.applyJitter(cappedDelay, jitter);
+            // Check abort during delay
+            if (signal) {
+                const aborted = await this.sleepWithAbort(jitteredDelay, signal);
+                if (aborted) {
+                    return err(RequestErrors.Cancelled());
+                }
+            }
+            else {
+                await this.sleep(jitteredDelay);
+            }
+            currentDelay = currentDelay * backoff;
+        }
+        return lastResult;
+    }
+    /**
+     * Generate deduplication key for request
+     * Returns null if request should not be deduplicated
+     */
+    getDedupeKey(url, options) {
+        if (!this.dedupe?.enabled) {
+            return null;
+        }
+        // Use custom key generator if provided
+        if (this.dedupe.keyGenerator) {
+            return this.dedupe.keyGenerator(url, options);
+        }
+        // Default: only dedupe GET requests by URL
+        const method = (options.method ?? 'GET').toUpperCase();
+        if (method !== 'GET') {
+            return null;
+        }
+        return `GET:${url}`;
+    }
+    /**
+     * Apply jitter to a delay value
+     * Jitter adds ±(jitter * delay) randomness to prevent thundering herd
+     * @param delay - Base delay in milliseconds
+     * @param jitter - Jitter factor (0-1)
+     * @returns Jittered delay
+     */
+    applyJitter(delay, jitter) {
+        if (jitter <= 0)
+            return delay;
+        // Clamp jitter to valid range [0, 1]
+        const clampedJitter = Math.min(Math.max(jitter, 0), 1);
+        // Random value between -1 and 1
+        const randomFactor = Math.random() * 2 - 1;
+        // Apply jitter: delay ± (delay * jitter * random)
+        return Math.max(0, delay + delay * clampedJitter * randomFactor);
+    }
+    /**
+     * Default retry condition - only retry on NETWORK_ERROR
+     */
+    defaultShouldRetry(error) {
+        // Don't retry cancelled requests or parse errors
+        return error.code === 'NETWORK_ERROR';
+    }
+    /**
+     * Calculate request metrics from timing data
+     */
+    calculateMetrics(timing) {
+        if (!timing)
+            return undefined;
+        const endTime = Date.now();
+        const startTime = timing.createdAt;
+        const sentAt = timing.sentAt ?? startTime;
+        const duration = endTime - startTime;
+        const queueTime = sentAt - startTime;
+        const ipcTime = duration - queueTime; // Approximate: total - queue = IPC + server
+        return {
+            startTime,
+            endTime,
+            duration,
+            queueTime,
+            ipcTime,
+        };
+    }
+    /**
+     * Sleep helper for retry delay
+     */
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    /**
+     * Sleep with abort signal support
+     * Returns true if aborted, false if completed normally
+     */
+    sleepWithAbort(ms, signal) {
+        return new Promise((resolve) => {
+            if (signal.aborted) {
+                resolve(true);
+                return;
+            }
+            const timer = setTimeout(() => {
+                signal.removeEventListener('abort', abortHandler);
+                resolve(false);
+            }, ms);
+            const abortHandler = () => {
+                clearTimeout(timer);
+                resolve(true);
+            };
+            signal.addEventListener('abort', abortHandler, { once: true });
+        });
+    }
+    /**
+     * Fetch with id for external cancellation
+     * Returns { id, result, cancel }
+     * Now uses queue system for sequential processing
+     */
+    fetchWithId(url, options = {}) {
+        const id = this.generateMessageId();
+        // The Promise is resolved/rejected via pendingRequests (worker callback).
+        // The executor stays synchronous (no async); the serialize-and-send work
+        // runs separately and routes failures through the same reject path.
+        const result = new Promise((resolve, reject) => {
+            this.pendingRequests.set(id, {
+                resolve: (response) => resolve(response),
+                reject: (error) => reject(error),
+            });
+            // Track URL for debug hooks
+            this.requestUrls.set(id, url);
+            // Track timing for metrics
+            this.requestTimings.set(id, { createdAt: Date.now() });
+            // Debug hook: onRequest
+            this.debug?.onRequest?.(url, options);
+        });
+        // Serialize (FormData/Headers) then send — async, but kept out of the
+        // Promise executor (noAsyncPromiseExecutor). Failures reject via the
+        // pending request registered above.
+        void (async () => {
+            try {
+                const serializedOptions = { ...options };
+                let transferables;
+                // Serialize FormData body before sending to worker
+                if (options.body && isFormData(options.body)) {
+                    const { data, transferables: formDataTransferables } = await serializeFormData(options.body);
+                    // SerializedFormData will be deserialized back to FormData in worker
+                    serializedOptions.body = data;
+                    // ArrayBuffers for zero-copy transfer
+                    if (formDataTransferables.length > 0) {
+                        transferables = formDataTransferables;
+                    }
+                }
+                // Serialize Headers object to plain object (Headers cannot be cloned)
+                if (options.headers instanceof Headers) {
+                    const plainHeaders = {};
+                    options.headers.forEach((value, key) => {
+                        plainHeaders[key] = value;
+                    });
+                    serializedOptions.headers = plainHeaders;
+                }
+                const message = { id, type: MSG.FETCH, payload: { url, options: serializedOptions } };
+                await this.sendMessageQueued(message, 30000, transferables);
+            }
+            catch (error) {
+                const request = this.pendingRequests.get(id);
+                if (request) {
+                    this.pendingRequests.delete(id);
+                    this.requestUrls.delete(id);
+                    this.requestTimings.delete(id);
+                    request.reject(error instanceof Error ? error : new Error(String(error)));
+                }
+            }
+        })();
+        const cancel = () => this.cancel(id);
+        return { id, result, cancel };
+    }
+    /**
+     * Cancel a pending request by ID
+     */
+    cancel(id) {
+        const request = this.pendingRequests.get(id);
+        if (request) {
+            const url = this.requestUrls.get(id);
+            const timing = this.requestTimings.get(id);
+            this.pendingRequests.delete(id);
+            this.requestUrls.delete(id);
+            this.requestTimings.delete(id);
+            this.worker.postMessage({ id, type: MSG.CANCEL });
+            // Calculate metrics
+            const metrics = this.calculateMetrics(timing);
+            // Debug hook: onError for cancelled request
+            if (this.debug?.onError && url) {
+                this.debug.onError(url, { code: 'REQUEST_CANCELLED', message: 'Request cancelled' }, metrics);
+            }
+            request.reject(new Error('Request cancelled'));
+        }
+    }
+    /**
+     * Convenience methods
+     */
+    async get(url, options = {}) {
+        return this.fetch(url, { ...options, method: 'GET' });
+    }
+    async post(url, body, options = {}) {
+        // If body is FormData, use fetch directly (no JSON.stringify)
+        if (body && isFormData(body)) {
+            return this.fetch(url, {
+                ...options,
+                method: 'POST',
+                body,
+            });
+        }
+        // For non-FormData body, use JSON
+        const headers = new Headers(options.headers);
+        // Set Content-Type if not already set and body is being stringified
+        if (body && !headers.has('Content-Type')) {
+            headers.set('Content-Type', 'application/json');
+        }
+        return this.fetch(url, {
+            ...options,
+            headers,
+            method: 'POST',
+            body: body ? JSON.stringify(body) : undefined,
+        });
+    }
+    async put(url, body, options = {}) {
+        // If body is FormData, use fetch directly (no JSON.stringify)
+        if (body && isFormData(body)) {
+            return this.fetch(url, {
+                ...options,
+                method: 'PUT',
+                body,
+            });
+        }
+        // For non-FormData body, use JSON
+        const headers = new Headers(options.headers);
+        // Set Content-Type if not already set and body is being stringified
+        if (body && !headers.has('Content-Type')) {
+            headers.set('Content-Type', 'application/json');
+        }
+        return this.fetch(url, {
+            ...options,
+            headers,
+            method: 'PUT',
+            body: body ? JSON.stringify(body) : undefined,
+        });
+    }
+    async delete(url, options = {}) {
+        return this.fetch(url, { ...options, method: 'DELETE' });
+    }
+    async patch(url, body, options = {}) {
+        // If body is FormData, use fetch directly (no JSON.stringify)
+        if (body && isFormData(body)) {
+            return this.fetch(url, {
+                ...options,
+                method: 'PATCH',
+                body,
+            });
+        }
+        // For non-FormData body, use JSON
+        const headers = new Headers(options.headers);
+        // Set Content-Type if not already set and body is being stringified
+        if (body && !headers.has('Content-Type')) {
+            headers.set('Content-Type', 'application/json');
+        }
+        return this.fetch(url, {
+            ...options,
+            headers,
+            method: 'PATCH',
+            body: body ? JSON.stringify(body) : undefined,
+        });
+    }
+    /**
+     * Typed data-API call.
+     *
+     * Issues the HTTP request through the Worker (tokens stay isolated) and
+     * deserializes the backend's ts-micro-result envelope into a domain
+     * `Result<T>` — so callers no longer hand-write "judge status + parse JSON +
+     * map errors". This is the entry point the contract-driven typed client uses
+     * for `kind: 'data'` endpoints.
+     *
+     * Auth-lifecycle endpoints (login/refresh/exchange/logout) must NOT use this —
+     * they go through login()/exchangeToken()/logout() because they touch the
+     * Worker's refresh-token storage.
+     */
+    async callJson(method, url, body, options = {}) {
+        let envelope;
+        switch (method) {
+            case 'GET':
+                envelope = await this.get(url, options);
+                break;
+            case 'DELETE':
+                if (body !== undefined && !isFormData(body)) {
+                    const headers = new Headers(options.headers);
+                    if (!headers.has('Content-Type'))
+                        headers.set('Content-Type', 'application/json');
+                    envelope = await this.fetch(url, { ...options, headers, method: 'DELETE', body: JSON.stringify(body) });
+                }
+                else {
+                    envelope = await this.delete(url, options);
+                }
+                break;
+            case 'POST':
+                envelope = await this.post(url, body, options);
+                break;
+            case 'PUT':
+                envelope = await this.put(url, body, options);
+                break;
+            case 'PATCH':
+                envelope = await this.patch(url, body, options);
+                break;
+        }
+        return toResult(envelope);
+    }
+    /**
+     * Generic method to call any auth method on provider
+     * @param method - Method name (login, logout, loginWithPhone, etc.)
+     * @param emitEvent - Whether to emit AUTH_STATE_CHANGED event (default: true)
+     * @param args - Arguments to pass to the method
+     * @returns Promise<Result<AuthResult>> - Always returns AuthResult
+     */
+    async call(method, emitEvent, ...args) {
+        const id = this.generateMessageId();
+        const message = { id, type: MSG.AUTH_CALL, payload: { method, args, emitEvent } };
+        return new Promise((resolve, reject) => {
+            this.pendingRequests.set(id, {
+                resolve: (r) => resolve(r),
+                reject: (e) => reject(e),
+            });
+            this.sendMessageQueued(message, 15000).catch((error) => {
+                const request = this.pendingRequests.get(id);
+                if (request) {
+                    this.pendingRequests.delete(id);
+                    request.reject(error);
+                }
+            });
+        });
+    }
+    /**
+     * Convenience wrapper for login
+     * @param payload - Login credentials
+     * @param url - Optional URL override
+     * @param emitEvent - Whether to emit AUTH_STATE_CHANGED event (default: true)
+     */
+    async login(payload, url, emitEvent = true) {
+        const args = [];
+        if (typeof payload !== 'undefined') {
+            args.push(payload);
+        }
+        if (typeof url !== 'undefined') {
+            // If payload is undefined but url is provided, need to pass undefined explicitly
+            if (args.length === 0) {
+                args.push(undefined);
+            }
+            args.push(url);
+        }
+        return this.call('login', emitEvent, ...args);
+    }
+    /**
+     * Convenience wrapper for logout
+     * @param payload - Optional logout payload
+     * @param emitEvent - Whether to emit AUTH_STATE_CHANGED event (default: true)
+     */
+    async logout(payload, emitEvent = true) {
+        const args = typeof payload === 'undefined' ? [] : [payload];
+        return this.call('logout', emitEvent, ...args);
+    }
+    /**
+     * Convenience wrapper for refreshToken
+     * @param emitEvent - Whether to emit AUTH_STATE_CHANGED event (default: true)
+     */
+    async refreshToken(emitEvent = true) {
+        return this.call('refreshToken', emitEvent);
+    }
+    /**
+     * Exchange current token for a new one with different context
+     *
+     * Useful for:
+     * - Switching tenants in multi-tenant apps
+     * - Changing authorization scope
+     * - Impersonating users (admin feature)
+     *
+     * @param url - URL to call for token exchange
+     * @param options - Exchange options (method, payload, headers)
+     * @param emitEvent - Whether to emit AUTH_STATE_CHANGED event (default: true)
+     *
+     * @example
+     * // Switch tenant
+     * await api.exchangeToken('https://auth.example.com/auth/select-tenant', {
+     *   payload: { tenantId: 'tenant_123' }
+     * })
+     *
+     * // Change scope with PUT method
+     * await api.exchangeToken('https://auth.example.com/auth/switch-context', {
+     *   method: 'PUT',
+     *   payload: { scope: 'admin' }
+     * })
+     *
+     * // With custom headers (overrides defaultHeaders)
+     * await api.exchangeToken('https://auth.example.com/auth/impersonate', {
+     *   payload: { userId: 'user_456' },
+     *   headers: { 'X-Impersonate-Reason': 'support-ticket-123' }
+     * })
+     */
+    async exchangeToken(url, options, emitEvent = true) {
+        const args = [url];
+        if (options) {
+            args.push(options);
+        }
+        return this.call('exchangeToken', emitEvent, ...args);
+    }
+    /**
+     * Check if worker is ready
+     */
+    ready() {
+        return this.isReady;
+    }
+    /**
+     * Wait for worker to be ready
+     * Returns immediately if already ready
+     */
+    async whenReady() {
+        if (this.isReady)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            this.readyListeners.add(resolve);
+        });
+    }
+    /**
+     * Subscribe to ready event
+     * Callback is called immediately if already ready
+     */
+    onReady(callback) {
+        if (this.isReady) {
+            // Already ready - call immediately
+            callback();
+        }
+        this.readyListeners.add(callback);
+        // Return unsubscribe function
+        return () => {
+            this.readyListeners.delete(callback);
+        };
+    }
+    /**
+     * Subscribe to auth state changes
+     */
+    onAuthStateChanged(cb) {
+        this.authListeners.add(cb);
+        return () => this.authListeners.delete(cb);
+    }
+    /** Send PING and await PONG */
+    async ping() {
+        const id = this.generateMessageId();
+        const message = { id, type: MSG.PING, payload: { timestamp: Date.now() } };
+        return new Promise((resolve, reject) => {
+            this.pendingRequests.set(id, {
+                resolve: (r) => resolve(r),
+                reject: (e) => reject(e),
+            });
+            this.sendMessageQueued(message, 5000).catch((error) => {
+                const request = this.pendingRequests.get(id);
+                if (request) {
+                    this.pendingRequests.delete(id);
+                    request.reject(error);
+                }
+            });
+        });
+    }
+    /**
+     * Send message through queue system
+     * All messages go through queue for sequential processing
+     * @param transferables - Optional Transferable objects for zero-copy postMessage
+     */
+    sendMessageQueued(message, timeoutMs = this.requestTimeout, transferables) {
+        return new Promise((resolve, reject) => {
+            // Check queue size limit to prevent memory leak
+            if (this.requestQueue.length >= this.maxQueueSize) {
+                reject(err(RequestErrors.QueueFull({ size: this.requestQueue.length, maxSize: this.maxQueueSize })));
+                return;
+            }
+            const timeout = setTimeout(() => {
+                const index = this.requestQueue.findIndex((item) => item.id === message.id);
+                if (index !== -1) {
+                    this.requestQueue.splice(index, 1);
+                }
+                this.pendingRequests.delete(message.id);
+                this.requestUrls.delete(message.id);
+                this.requestTimings.delete(message.id);
+                reject(err(RequestErrors.Timeout()));
+            }, timeoutMs);
+            const queueItem = {
+                id: message.id,
+                message,
+                transferables,
+                resolve: resolve,
+                reject,
+                timeout,
+            };
+            this.requestQueue.push(queueItem);
+            this.processQueue();
+        });
+    }
+    /**
+     * Process message queue with concurrency limit
+     *
+     * Uses semaphore pattern to allow N concurrent requests.
+     * Benefits:
+     * - Higher throughput than sequential processing
+     * - Backpressure via maxConcurrent limit
+     * - Better error isolation (one failure doesn't affect others)
+     */
+    processQueue() {
+        // Process as many items as we can within concurrency limit
+        while (this.requestQueue.length > 0 && this.activeRequests < this.maxConcurrent) {
+            const item = this.requestQueue.shift();
+            if (!item)
+                continue;
+            this.activeRequests++;
+            // Update timing: mark when request is actually sent to worker
+            const timing = this.requestTimings.get(item.id);
+            if (timing) {
+                timing.sentAt = Date.now();
+            }
+            try {
+                // Use transferables for zero-copy transfer when available (e.g., FormData with files)
+                if (item.transferables && item.transferables.length > 0) {
+                    this.worker.postMessage(item.message, item.transferables);
+                }
+                else {
+                    this.worker.postMessage(item.message);
+                }
+                // Note: activeRequests is decremented when response is received
+                // in handleWorkerMessage, not here
+            }
+            catch (error) {
+                this.activeRequests--;
+                clearTimeout(item.timeout);
+                item.reject(error instanceof Error ? error : new Error(String(error)));
+                // Continue processing queue after error
+                this.processQueue();
+            }
+        }
+    }
+    /**
+     * Called when a request completes (success or error)
+     * Decrements active count and processes next items in queue
+     */
+    onRequestComplete() {
+        this.activeRequests--;
+        this.processQueue();
+    }
+    /**
+     * Cleanup - terminate worker
+     */
+    destroy() {
+        this.worker.terminate();
+        this.pendingRequests.clear();
+        this.requestUrls.clear();
+        this.requestTimings.clear();
+        for (const item of this.requestQueue) {
+            clearTimeout(item.timeout);
+            item.reject(new Error('Client destroyed'));
+        }
+        this.requestQueue = [];
+    }
+}
+/**
+ * Factory function to create FetchGuard client
+ */
+export function createClient(options) {
+    return new FetchGuardClient(options);
+}
+//# sourceMappingURL=client.js.map