feat: Implement comprehensive web request handling with caching, retry, and interceptors

- Added cache strategies: NetworkFirst, CacheFirst, StaleWhileRevalidate, NetworkOnly, and CacheOnly.
- Introduced InterceptorManager for managing request, response, and error interceptors.
- Developed RetryManager for handling request retries with customizable backoff strategies.
- Implemented RequestDeduplicator to prevent simultaneous identical requests.
- Created timeout utilities for handling request timeouts.
- Enhanced WebrequestClient to support global interceptors, caching, and retry logic.
- Added convenience methods for common HTTP methods (GET, POST, PUT, DELETE) with JSON handling.
- Established a fetch-compatible webrequest function for seamless integration.
- Defined core type structures for caching, retry options, interceptors, and web request configurations.

ts/webrequest.types.ts

@@ -0,0 +1,143 @@
+/**
+ * Core type definitions for @push.rocks/webrequest v4
+ */
+
+// ==================
+// Cache Types
+// ==================
+
+export type TCacheStrategy =
+  | 'network-first'
+  | 'cache-first'
+  | 'stale-while-revalidate'
+  | 'network-only'
+  | 'cache-only';
+
+export type TStandardCacheMode =
+  | 'default'
+  | 'no-store'
+  | 'reload'
+  | 'no-cache'
+  | 'force-cache'
+  | 'only-if-cached';
+
+export interface ICacheEntry {
+  response: ArrayBuffer;
+  headers: Record<string, string>;
+  timestamp: number;
+  etag?: string;
+  lastModified?: string;
+  maxAge?: number;
+  url: string;
+  status: number;
+  statusText: string;
+}
+
+export interface ICacheOptions {
+  /** Standard cache mode (fetch API compatible) */
+  cache?: TStandardCacheMode;
+  /** Advanced cache strategy */
+  cacheStrategy?: TCacheStrategy;
+  /** Maximum age in milliseconds */
+  cacheMaxAge?: number;
+  /** Custom cache key generator */
+  cacheKey?: string | ((request: Request) => string);
+  /** Force revalidation even if cached */
+  revalidate?: boolean;
+}
+
+// ==================
+// Retry Types
+// ==================
+
+export type TBackoffStrategy = 'exponential' | 'linear' | 'constant';
+
+export interface IRetryOptions {
+  /** Maximum number of retry attempts (default: 3) */
+  maxAttempts?: number;
+  /** Backoff strategy (default: 'exponential') */
+  backoff?: TBackoffStrategy;
+  /** Initial delay in milliseconds (default: 1000) */
+  initialDelay?: number;
+  /** Maximum delay in milliseconds (default: 30000) */
+  maxDelay?: number;
+  /** Status codes or function to determine if retry should occur */
+  retryOn?: number[] | ((response: Response, error?: Error) => boolean);
+  /** Callback on each retry attempt */
+  onRetry?: (attempt: number, error: Error, nextDelay: number) => void;
+}
+
+// ==================
+// Interceptor Types
+// ==================
+
+export type TRequestInterceptor = (
+  request: Request,
+) => Request | Promise<Request>;
+export type TResponseInterceptor = (
+  response: Response,
+) => Response | Promise<Response>;
+
+export interface IInterceptors {
+  request?: TRequestInterceptor[];
+  response?: TResponseInterceptor[];
+}
+
+// ==================
+// Main Options
+// ==================
+
+export interface IWebrequestOptions extends Omit<RequestInit, 'cache'> {
+  // Caching
+  cache?: TStandardCacheMode;
+  cacheStrategy?: TCacheStrategy;
+  cacheMaxAge?: number;
+  cacheKey?: string | ((request: Request) => string);
+  revalidate?: boolean;
+
+  // Retry & Fault Tolerance
+  retry?: boolean | IRetryOptions;
+  fallbackUrls?: string[];
+  timeout?: number;
+
+  // Interceptors
+  interceptors?: IInterceptors;
+
+  // Deduplication
+  deduplicate?: boolean;
+
+  // Logging
+  logging?: boolean;
+}
+
+// ==================
+// Result Types
+// ==================
+
+export interface IWebrequestSuccess<T> {
+  ok: true;
+  data: T;
+  response: Response;
+}
+
+export interface IWebrequestError {
+  ok: false;
+  error: Error;
+  response?: Response;
+}
+
+export type TWebrequestResult<T> = IWebrequestSuccess<T> | IWebrequestError;
+
+// ==================
+// Internal Types
+// ==================
+
+export interface ICacheMetadata {
+  maxAge: number;
+  etag?: string;
+  lastModified?: string;
+  immutable: boolean;
+  noCache: boolean;
+  noStore: boolean;
+  mustRevalidate: boolean;
+}