fetchguard 1.6.3 → 2.1.0

package/dist/index.js

@@ -18,7 +18,8 @@ var MSG = Object.freeze({
   AUTH_STATE_CHANGED: "AUTH_STATE_CHANGED",
   AUTH_CALL_RESULT: "AUTH_CALL_RESULT",
   FETCH_RESULT: "FETCH_RESULT",
-  FETCH_ERROR: "FETCH_ERROR"
+  FETCH_ERROR: "FETCH_ERROR",
+  TOKEN_REFRESHED: "TOKEN_REFRESHED"
 });
 
 // src/constants.ts
@@ -26,65 +27,101 @@ var DEFAULT_REFRESH_EARLY_MS = 6e4;
 
 // src/errors.ts
 import { defineError, defineErrorAdvanced } from "ts-micro-result";
+
+// src/error-codes.ts
+var ERROR_CODES = {
+  // General
+  UNEXPECTED: "UNEXPECTED",
+  UNKNOWN_MESSAGE: "UNKNOWN_MESSAGE",
+  RESULT_PARSE_ERROR: "RESULT_PARSE_ERROR",
+  // Init
+  INIT_ERROR: "INIT_ERROR",
+  PROVIDER_INIT_FAILED: "PROVIDER_INIT_FAILED",
+  INIT_FAILED: "INIT_FAILED",
+  // Auth
+  TOKEN_REFRESH_FAILED: "TOKEN_REFRESH_FAILED",
+  TOKEN_EXCHANGE_FAILED: "TOKEN_EXCHANGE_FAILED",
+  LOGIN_FAILED: "LOGIN_FAILED",
+  LOGOUT_FAILED: "LOGOUT_FAILED",
+  NOT_AUTHENTICATED: "NOT_AUTHENTICATED",
+  // Domain
+  DOMAIN_NOT_ALLOWED: "DOMAIN_NOT_ALLOWED",
+  // Request
+  NETWORK_ERROR: "NETWORK_ERROR",
+  REQUEST_CANCELLED: "REQUEST_CANCELLED",
+  HTTP_ERROR: "HTTP_ERROR",
+  RESPONSE_PARSE_FAILED: "RESPONSE_PARSE_FAILED",
+  QUEUE_FULL: "QUEUE_FULL",
+  REQUEST_TIMEOUT: "REQUEST_TIMEOUT"
+};
+
+// src/errors.ts
 var GeneralErrors = {
-  Unexpected: defineError("UNEXPECTED", "Unexpected error", 500),
-  UnknownMessage: defineError("UNKNOWN_MESSAGE", "Unknown message type", 400),
-  ResultParse: defineError("RESULT_PARSE_ERROR", "Failed to parse result", 500)
+  Unexpected: defineError(ERROR_CODES.UNEXPECTED, "Unexpected error"),
+  UnknownMessage: defineError(ERROR_CODES.UNKNOWN_MESSAGE, "Unknown message type"),
+  ResultParse: defineError(ERROR_CODES.RESULT_PARSE_ERROR, "Failed to parse result")
 };
 var InitErrors = {
-  NotInitialized: defineError("INIT_ERROR", "Worker not initialized", 500),
-  ProviderInitFailed: defineError("PROVIDER_INIT_FAILED", "Failed to initialize provider", 500),
-  InitFailed: defineError("INIT_FAILED", "Initialization failed", 500)
+  NotInitialized: defineError(ERROR_CODES.INIT_ERROR, "Worker not initialized"),
+  ProviderInitFailed: defineError(ERROR_CODES.PROVIDER_INIT_FAILED, "Failed to initialize provider"),
+  InitFailed: defineError(ERROR_CODES.INIT_FAILED, "Initialization failed")
 };
 var AuthErrors = {
-  TokenRefreshFailed: defineError("TOKEN_REFRESH_FAILED", "Token refresh failed", 401),
-  LoginFailed: defineError("LOGIN_FAILED", "Login failed", 401),
-  LogoutFailed: defineError("LOGOUT_FAILED", "Logout failed", 500),
-  NotAuthenticated: defineError("NOT_AUTHENTICATED", "User is not authenticated", 401)
+  TokenRefreshFailed: defineError(ERROR_CODES.TOKEN_REFRESH_FAILED, "Token refresh failed"),
+  TokenExchangeFailed: defineError(ERROR_CODES.TOKEN_EXCHANGE_FAILED, "Token exchange failed"),
+  LoginFailed: defineError(ERROR_CODES.LOGIN_FAILED, "Login failed"),
+  LogoutFailed: defineError(ERROR_CODES.LOGOUT_FAILED, "Logout failed"),
+  NotAuthenticated: defineError(ERROR_CODES.NOT_AUTHENTICATED, "User is not authenticated")
 };
 var DomainErrors = {
-  NotAllowed: defineErrorAdvanced("DOMAIN_NOT_ALLOWED", "Domain not allowed: {url}", 403)
+  NotAllowed: defineErrorAdvanced(ERROR_CODES.DOMAIN_NOT_ALLOWED, "Domain not allowed: {url}")
 };
 var RequestErrors = {
   // Network errors (connection failed, no response)
-  NetworkError: defineError("NETWORK_ERROR", "Network error", 500),
-  Cancelled: defineError("REQUEST_CANCELLED", "Request was cancelled", 499),
+  NetworkError: defineError(ERROR_CODES.NETWORK_ERROR, "Network error"),
+  Cancelled: defineError(ERROR_CODES.REQUEST_CANCELLED, "Request was cancelled"),
   // HTTP errors (server responded with error status)
-  HttpError: defineErrorAdvanced("HTTP_ERROR", "HTTP {status} error", 500),
+  HttpError: defineErrorAdvanced(ERROR_CODES.HTTP_ERROR, "HTTP {status} error"),
   // Response parsing errors
-  ResponseParseFailed: defineError("RESPONSE_PARSE_FAILED", "Failed to parse response body", 500)
+  ResponseParseFailed: defineError(ERROR_CODES.RESPONSE_PARSE_FAILED, "Failed to parse response body"),
+  // Queue errors
+  QueueFull: defineErrorAdvanced(ERROR_CODES.QUEUE_FULL, "Request queue full ({size}/{maxSize})"),
+  // Timeout errors
+  Timeout: defineError(ERROR_CODES.REQUEST_TIMEOUT, "Request timed out")
 };
 
 // src/utils/formdata.ts
 async function serializeFormData(formData) {
   const entries = [];
+  const transferables = [];
+  const orderedEntries = [];
+  let index = 0;
   formData.forEach((value, key) => {
-    if (value instanceof File) {
-    } else {
-      entries.push([key, String(value)]);
-    }
+    orderedEntries.push({ index, key, value });
+    index++;
   });
-  const filePromises = [];
-  formData.forEach((value, key) => {
-    if (value instanceof File) {
-      const promise = (async () => {
-        const arrayBuffer = await value.arrayBuffer();
-        const uint8Array = new Uint8Array(arrayBuffer);
+  await Promise.all(
+    orderedEntries.map(async ({ index: idx, key, value }) => {
+      if (value instanceof File) {
+        const buffer = await value.arrayBuffer();
         const serializedFile = {
           name: value.name,
           type: value.type,
-          data: Array.from(uint8Array)
-          // Convert to number array
+          buffer
         };
-        entries.push([key, serializedFile]);
-      })();
-      filePromises.push(promise);
-    }
-  });
-  await Promise.all(filePromises);
+        entries[idx] = [key, serializedFile];
+        transferables.push(buffer);
+      } else {
+        entries[idx] = [key, String(value)];
+      }
+    })
+  );
   return {
-    _type: "FormData",
-    entries
+    data: {
+      _type: "FormData",
+      entries
+    },
+    transferables
   };
 }
 function deserializeFormData(serialized) {
@@ -93,8 +130,7 @@ function deserializeFormData(serialized) {
     if (typeof value === "string") {
       formData.append(key, value);
     } else {
-      const uint8Array = new Uint8Array(value.data);
-      const file = new File([uint8Array], value.name, { type: value.type });
+      const file = new File([value.buffer], value.name, { type: value.type });
       formData.append(key, file);
     }
   }
@@ -108,22 +144,46 @@ function isSerializedFormData(body) {
 }
 
 // src/client.ts
+var DEFAULT_MAX_CONCURRENT = 6;
+var DEFAULT_MAX_QUEUE_SIZE = 1e3;
+var DEFAULT_SETUP_TIMEOUT = 1e4;
+var DEFAULT_REQUEST_TIMEOUT = 3e4;
 var FetchGuardClient = class {
   worker;
   messageId = 0;
   // Using unknown because different messages have different response types
-  // (ApiResponse for FETCH, AuthResult for AUTH_CALL, etc.)
+  // (FetchEnvelope for FETCH, AuthResult for AUTH_CALL, etc.)
   pendingRequests = /* @__PURE__ */ new Map();
+  /** Track request URLs for debug hooks */
+  requestUrls = /* @__PURE__ */ new Map();
+  /** Track request timing for metrics */
+  requestTimings = /* @__PURE__ */ new Map();
   authListeners = /* @__PURE__ */ new Set();
   readyListeners = /* @__PURE__ */ new Set();
   isReady = false;
   requestQueue = [];
-  isProcessingQueue = false;
-  queueTimeout = 3e4;
-  // 30 seconds
+  activeRequests = 0;
+  maxConcurrent;
+  maxQueueSize;
+  setupTimeout;
+  requestTimeout;
   setupResolve;
   setupReject;
+  debug;
+  retry;
+  dedupe;
+  /** In-flight requests for deduplication */
+  inFlightRequests = /* @__PURE__ */ new Map();
+  /** Recent completed requests for time-window deduplication */
+  recentResults = /* @__PURE__ */ 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;
     this.worker = new Worker(new URL("./worker.js", import.meta.url), {
       type: "module"
     });
@@ -168,7 +228,7 @@ var FetchGuardClient = class {
           this.setupResolve = void 0;
           this.setupReject = void 0;
         }
-      }, 1e4);
+      }, this.setupTimeout);
     });
   }
   /**
@@ -179,31 +239,35 @@ var FetchGuardClient = class {
     if (type === MSG.FETCH_RESULT) {
       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);
-      const status = payload?.status;
-      if (status >= 200 && status < 400) {
-        request.resolve(ok(payload));
-      } else {
-        request.resolve(err(
-          RequestErrors.HttpError({ status }),
-          {
-            body: String(payload?.body ?? ""),
-            headers: payload?.headers ?? {}
-          },
-          payload?.status
-        ));
+      this.requestUrls.delete(id);
+      this.requestTimings.delete(id);
+      this.onRequestComplete();
+      const metrics = this.calculateMetrics(timing);
+      if (this.debug?.onResponse && url) {
+        this.debug.onResponse(url, payload, metrics);
       }
+      request.resolve(ok(payload));
       return;
     }
     if (type === MSG.FETCH_ERROR) {
       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);
-      const status = typeof payload?.status === "number" ? payload.status : void 0;
+      this.requestUrls.delete(id);
+      this.requestTimings.delete(id);
+      this.onRequestComplete();
+      const errorMessage = String(payload?.error || "Network error");
+      const metrics = this.calculateMetrics(timing);
+      if (this.debug?.onError && url) {
+        this.debug.onError(url, { code: "NETWORK_ERROR", message: errorMessage }, metrics);
+      }
       request.resolve(err(
-        RequestErrors.NetworkError({ message: String(payload?.error || "Network error") }),
-        void 0,
-        status
+        RequestErrors.NetworkError({ message: errorMessage })
       ));
       return;
     }
@@ -211,7 +275,8 @@ var FetchGuardClient = class {
       const request = this.pendingRequests.get(id);
       if (!request) return;
       this.pendingRequests.delete(id);
-      request.resolve(err(payload.errors, payload.meta, payload.status));
+      this.onRequestComplete();
+      request.resolve(err(payload.errors, payload.meta));
       return;
     }
     if (type === MSG.SETUP_ERROR) {
@@ -224,6 +289,7 @@ var FetchGuardClient = class {
     }
     if (type === MSG.READY) {
       this.isReady = true;
+      this.debug?.onWorkerReady?.();
       for (const listener of this.readyListeners) {
         listener();
       }
@@ -238,6 +304,7 @@ var FetchGuardClient = class {
       const request = this.pendingRequests.get(id);
       if (request) {
         this.pendingRequests.delete(id);
+        this.onRequestComplete();
         request.resolve(ok({ timestamp: payload?.timestamp }));
       }
       return;
@@ -250,20 +317,28 @@ var FetchGuardClient = class {
       const request = this.pendingRequests.get(id);
       if (request) {
         this.pendingRequests.delete(id);
+        this.onRequestComplete();
         request.resolve(ok(payload));
       }
       return;
     }
+    if (type === MSG.TOKEN_REFRESHED) {
+      this.debug?.onRefresh?.(payload?.reason);
+      return;
+    }
   }
   /**
    * Handle worker errors
    */
   handleWorkerError(error) {
     console.error("Worker error:", error);
+    this.debug?.onWorkerError?.(error);
     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
@@ -272,11 +347,207 @@ var FetchGuardClient = class {
     return `msg_${++this.messageId}_${Date.now()}`;
   }
   /**
-   * Make API request
+   * 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 = {}) {
-    const { result } = this.fetchWithId(url, options);
-    return result;
+    const { signal, ...restOptions } = options;
+    if (signal?.aborted) {
+      return err(RequestErrors.Cancelled());
+    }
+    const dedupeKey = this.getDedupeKey(url, restOptions);
+    if (dedupeKey) {
+      const inFlight = this.inFlightRequests.get(dedupeKey);
+      if (inFlight) {
+        if (signal) {
+          return this.wrapWithAbortSignal(inFlight, signal, null);
+        }
+        return inFlight;
+      }
+      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;
+        }
+      }
+      const promise = this.fetchWithRetryAndSignal(url, restOptions, signal ?? void 0);
+      this.inFlightRequests.set(dedupeKey, promise);
+      try {
+        const result = await promise;
+        if (window > 0) {
+          this.recentResults.set(dedupeKey, { result, timestamp: Date.now() });
+          setTimeout(() => this.recentResults.delete(dedupeKey), window);
+        }
+        return result;
+      } finally {
+        this.inFlightRequests.delete(dedupeKey);
+      }
+    }
+    return this.fetchWithRetryAndSignal(url, restOptions, signal ?? void 0);
+  }
+  /**
+   * Wrap a promise with AbortSignal support
+   */
+  wrapWithAbortSignal(promise, signal, requestId) {
+    return new Promise((resolve) => {
+      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 ?? 1e3;
+    const backoff = this.retry?.backoff ?? 1;
+    const maxDelay = this.retry?.maxDelay ?? 3e4;
+    const jitter = this.retry?.jitter ?? 0;
+    const shouldRetry = this.retry?.shouldRetry ?? this.defaultShouldRetry;
+    let lastResult = null;
+    let currentDelay = delay;
+    for (let attempt = 0; attempt <= maxAttempts; attempt++) {
+      if (signal?.aborted) {
+        return err(RequestErrors.Cancelled());
+      }
+      const { id, result } = this.fetchWithId(url, options);
+      if (signal) {
+        lastResult = await this.wrapWithAbortSignal(result, signal, id);
+      } else {
+        lastResult = await result;
+      }
+      if (lastResult.ok) {
+        return lastResult;
+      }
+      if (lastResult.errors[0]?.code === "REQUEST_CANCELLED") {
+        return lastResult;
+      }
+      const error = lastResult.errors[0];
+      const errorDetail = {
+        code: error?.code ?? "NETWORK_ERROR",
+        message: error?.message ?? "Unknown error"
+      };
+      if (attempt >= maxAttempts || !shouldRetry(errorDetail)) {
+        return lastResult;
+      }
+      const cappedDelay = Math.min(currentDelay, maxDelay);
+      const jitteredDelay = this.applyJitter(cappedDelay, jitter);
+      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;
+    }
+    if (this.dedupe.keyGenerator) {
+      return this.dedupe.keyGenerator(url, options);
+    }
+    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;
+    const clampedJitter = Math.min(Math.max(jitter, 0), 1);
+    const randomFactor = Math.random() * 2 - 1;
+    return Math.max(0, delay + delay * clampedJitter * randomFactor);
+  }
+  /**
+   * Default retry condition - only retry on NETWORK_ERROR
+   */
+  defaultShouldRetry(error) {
+    return error.code === "NETWORK_ERROR";
+  }
+  /**
+   * Calculate request metrics from timing data
+   */
+  calculateMetrics(timing) {
+    if (!timing) return void 0;
+    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;
+    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
@@ -290,11 +561,18 @@ var FetchGuardClient = class {
         resolve: (response) => resolve(response),
         reject: (error) => reject(error)
       });
+      this.requestUrls.set(id, url);
+      this.requestTimings.set(id, { createdAt: Date.now() });
+      this.debug?.onRequest?.(url, options);
       try {
         let serializedOptions = { ...options };
+        let transferables;
         if (options.body && isFormData(options.body)) {
-          const serializedBody = await serializeFormData(options.body);
-          serializedOptions.body = serializedBody;
+          const { data, transferables: formDataTransferables } = await serializeFormData(options.body);
+          serializedOptions.body = data;
+          if (formDataTransferables.length > 0) {
+            transferables = formDataTransferables;
+          }
         }
         if (options.headers) {
           if (options.headers instanceof Headers) {
@@ -306,11 +584,13 @@ var FetchGuardClient = class {
           }
         }
         const message = { id, type: MSG.FETCH, payload: { url, options: serializedOptions } };
-        await this.sendMessageQueued(message, 3e4);
+        await this.sendMessageQueued(message, 3e4, 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)));
         }
       }
@@ -324,8 +604,16 @@ var FetchGuardClient = class {
   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 });
+      const metrics = this.calculateMetrics(timing);
+      if (this.debug?.onError && url) {
+        this.debug.onError(url, { code: "REQUEST_CANCELLED", message: "Request cancelled" }, metrics);
+      }
       request.reject(new Error("Request cancelled"));
     }
   }
@@ -454,6 +742,37 @@ var FetchGuardClient = class {
   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)
+   * @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' }
+   * })
+   */
+  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
    */
@@ -511,20 +830,28 @@ var FetchGuardClient = class {
   /**
    * 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.queueTimeout) {
+  sendMessageQueued(message, timeoutMs = this.requestTimeout, transferables) {
     return new Promise((resolve, reject) => {
+      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);
-        reject(new Error("Request timeout"));
+        this.requestUrls.delete(message.id);
+        this.requestTimings.delete(message.id);
+        reject(err(RequestErrors.Timeout()));
       }, timeoutMs);
       const queueItem = {
         id: message.id,
         message,
+        transferables,
         resolve,
         reject,
         timeout
@@ -534,29 +861,44 @@ var FetchGuardClient = class {
     });
   }
   /**
-   * Process message queue sequentially
+   * Process message queue with concurrency limit
+   *
+   * Uses semaphore pattern to allow N concurrent requests.
    * Benefits:
-   * - Sequential processing prevents worker overload
+   * - Higher throughput than sequential processing
+   * - Backpressure via maxConcurrent limit
    * - Better error isolation (one failure doesn't affect others)
-   * - 50ms delay between requests for backpressure
    */
-  async processQueue() {
-    if (this.isProcessingQueue || this.requestQueue.length === 0) {
-      return;
-    }
-    this.isProcessingQueue = true;
-    while (this.requestQueue.length > 0) {
+  processQueue() {
+    while (this.requestQueue.length > 0 && this.activeRequests < this.maxConcurrent) {
       const item = this.requestQueue.shift();
       if (!item) continue;
+      this.activeRequests++;
+      const timing = this.requestTimings.get(item.id);
+      if (timing) {
+        timing.sentAt = Date.now();
+      }
       try {
-        this.worker.postMessage(item.message);
-        await new Promise((resolve) => setTimeout(resolve, 50));
+        if (item.transferables && item.transferables.length > 0) {
+          this.worker.postMessage(item.message, item.transferables);
+        } else {
+          this.worker.postMessage(item.message);
+        }
       } catch (error) {
+        this.activeRequests--;
         clearTimeout(item.timeout);
         item.reject(error instanceof Error ? error : new Error(String(error)));
+        this.processQueue();
       }
     }
-    this.isProcessingQueue = false;
+  }
+  /**
+   * 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
@@ -564,6 +906,8 @@ var FetchGuardClient = class {
   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"));
@@ -619,7 +963,7 @@ function createProvider(config) {
         const response = await config.strategy.refresh(currentRefreshToken);
         if (!response.ok) {
           const body = await response.text().catch(() => "");
-          return err2(AuthErrors.TokenRefreshFailed(), { body }, response.status);
+          return err2(AuthErrors.TokenRefreshFailed(), { params: { body, status: response.status } });
         }
         const tokenInfo = await config.parser.parse(response);
         if (!tokenInfo.token) {
@@ -638,7 +982,7 @@ function createProvider(config) {
         const response = await config.strategy.login(payload, url);
         if (!response.ok) {
           const body = await response.text().catch(() => "");
-          return err2(AuthErrors.LoginFailed(), { body }, response.status);
+          return err2(AuthErrors.LoginFailed(), { params: { body, status: response.status } });
         }
         const tokenInfo = await config.parser.parse(response);
         if (!tokenInfo.token) {
@@ -657,7 +1001,7 @@ function createProvider(config) {
         const response = await config.strategy.logout(payload);
         if (!response.ok) {
           const body = await response.text().catch(() => "");
-          return err2(AuthErrors.LogoutFailed(), { body }, response.status);
+          return err2(AuthErrors.LogoutFailed(), { params: { body, status: response.status } });
         }
         if (config.refreshStorage) {
           await config.refreshStorage.set(null);
@@ -672,6 +1016,37 @@ function createProvider(config) {
       } catch (error) {
         return err2(RequestErrors.NetworkError({ message: String(error) }));
       }
+    },
+    async exchangeToken(accessToken, url, options = {}) {
+      const { method = "POST", payload } = options;
+      if (!accessToken) {
+        return err2(AuthErrors.NotAuthenticated());
+      }
+      try {
+        const response = await fetch(url, {
+          method,
+          headers: {
+            "Content-Type": "application/json",
+            "Authorization": `Bearer ${accessToken}`
+          },
+          body: payload ? JSON.stringify(payload) : void 0,
+          credentials: "include"
+        });
+        if (!response.ok) {
+          const body = await response.text().catch(() => "");
+          return err2(AuthErrors.TokenExchangeFailed(), { params: { body, status: response.status } });
+        }
+        const tokenInfo = await config.parser.parse(response);
+        if (!tokenInfo.token) {
+          return err2(AuthErrors.TokenExchangeFailed({ message: "No access token in response" }));
+        }
+        if (config.refreshStorage && tokenInfo.refreshToken) {
+          await config.refreshStorage.set(tokenInfo.refreshToken);
+        }
+        return ok2(tokenInfo);
+      } catch (error) {
+        return err2(RequestErrors.NetworkError({ message: String(error) }));
+      }
     }
   };
   if (config.customMethods) {
@@ -684,7 +1059,13 @@ function createProvider(config) {
 }
 
 // src/provider/storage/indexeddb.ts
-function createIndexedDBStorage(dbName = "FetchGuardDB", refreshTokenKey = "refreshToken") {
+function createIndexedDBStorage(options = "FetchGuardDB", legacyRefreshTokenKey) {
+  const config = typeof options === "string" ? { dbName: options, refreshTokenKey: legacyRefreshTokenKey ?? "refreshToken", onError: void 0 } : {
+    dbName: options.dbName ?? "FetchGuardDB",
+    refreshTokenKey: options.refreshTokenKey ?? "refreshToken",
+    onError: options.onError
+  };
+  const { dbName, refreshTokenKey, onError } = config;
   const storeName = "tokens";
   const openDB = () => {
     return new Promise((resolve, reject) => {
@@ -715,7 +1096,7 @@ function createIndexedDBStorage(dbName = "FetchGuardDB", refreshTokenKey = "refr
         const result = await promisifyRequest(store.get(refreshTokenKey));
         return result?.value || null;
       } catch (error) {
-        console.warn("Failed to get refresh token from IndexedDB:", error);
+        onError?.(error, "get");
         return null;
       }
     },
@@ -730,7 +1111,7 @@ function createIndexedDBStorage(dbName = "FetchGuardDB", refreshTokenKey = "refr
           await promisifyRequest(store.delete(refreshTokenKey));
         }
       } catch (error) {
-        console.warn("Failed to save refresh token to IndexedDB:", error);
+        onError?.(error, token ? "set" : "delete");
       }
     }
   };
@@ -891,9 +1272,76 @@ function isBinaryContentType(contentType) {
   if (normalized.includes("html")) return false;
   return true;
 }
+
+// src/helpers.ts
+function isNetworkError(result) {
+  return !result.ok;
+}
+function isSuccess(result) {
+  return result.ok && result.data.status >= 200 && result.data.status < 300;
+}
+function isClientError(result) {
+  return result.ok && result.data.status >= 400 && result.data.status < 500;
+}
+function isServerError(result) {
+  return result.ok && result.data.status >= 500;
+}
+function parseJson(result) {
+  if (!result.ok) return null;
+  try {
+    return JSON.parse(result.data.body);
+  } catch {
+    return null;
+  }
+}
+function getErrorMessage(result) {
+  if (result.ok) {
+    try {
+      const body = JSON.parse(result.data.body);
+      return body.message || body.error || `HTTP ${result.data.status}`;
+    } catch {
+      return `HTTP ${result.data.status}`;
+    }
+  }
+  return result.errors[0]?.message || "Unknown error";
+}
+function getErrorBody(result) {
+  if (!result.ok) return null;
+  if (result.data.status >= 400) {
+    try {
+      return JSON.parse(result.data.body);
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+function getStatus(result) {
+  return result.ok ? result.data.status : null;
+}
+function hasStatus(result, status) {
+  return result.ok && result.data.status === status;
+}
+function matchResult(result, handlers) {
+  if (!result.ok) {
+    return handlers.networkError?.(result.errors);
+  }
+  const status = result.data.status;
+  if (status >= 200 && status < 300) {
+    return handlers.success?.(result.data);
+  }
+  if (status >= 400 && status < 500) {
+    return handlers.clientError?.(result.data);
+  }
+  if (status >= 500) {
+    return handlers.serverError?.(result.data);
+  }
+  return void 0;
+}
 export {
   AuthErrors,
   DomainErrors,
+  ERROR_CODES,
   FetchGuardClient,
   GeneralErrors,
   InitErrors,
@@ -913,12 +1361,22 @@ export {
   createIndexedDBStorage,
   createProvider,
   deserializeFormData,
+  getErrorBody,
+  getErrorMessage,
   getProvider,
+  getStatus,
   hasProvider,
+  hasStatus,
   isBinaryContentType,
+  isClientError,
   isFormData,
+  isNetworkError,
   isSerializedFormData,
+  isServerError,
+  isSuccess,
   listProviders,
+  matchResult,
+  parseJson,
   registerProvider,
   serializeFormData,
   unregisterProvider