API reference ​

function createClient(options?: ClientOptions): Client

interface ClientOptions {
  baseURL?: string;
  headers?: Record<string, string>;
  cache?: CacheOptions;
  retry?: RetryOptions;
  timeout?: number;
  fetch?: typeof fetch;
  intelligence?: IntelligenceOptions;
  circuitBreaker?: CircuitBreakerOptions;
  scheduler?: SchedulerOptions;
  adaptive?: AdaptiveOptions;
}

interface Client {
  request<T>(method: HttpMethod, url: string, options?: RequestOptions): CancellablePromise<ApiResponse<T>>;
  get<T>(url: string, options?: RequestOptions): CancellablePromise<ApiResponse<T>>;
  post<T>(url: string, body?: unknown, options?: RequestOptions): CancellablePromise<ApiResponse<T>>;
  put<T>(url: string, body?: unknown, options?: RequestOptions): CancellablePromise<ApiResponse<T>>;
  patch<T>(url: string, body?: unknown, options?: RequestOptions): CancellablePromise<ApiResponse<T>>;
  delete<T>(url: string, options?: RequestOptions): CancellablePromise<ApiResponse<T>>;
  head<T>(url: string, options?: RequestOptions): CancellablePromise<ApiResponse<T>>;
  options<T>(url: string, options?: RequestOptions): CancellablePromise<ApiResponse<T>>;

  on<K extends keyof ClientEvents>(event: K, listener: (payload: ClientEvents[K]) => void): () => void;
  subscribe<T>(matcher: (key: string) => boolean, listener: CacheSubscriber<T>): () => void;
  invalidate(target: InvalidateTarget, options?: { refetch?: boolean }): string[];
  cancelAll(): void;
  clearCache(): void;
  intelligence(): IntelligenceController;
  circuitBreaker(): CircuitBreakerController;
  scheduler(): SchedulerController;
  adaptive(): AdaptiveController;
  cancelGroup(group: string): void;
}

interface CircuitBreakerOptions {
  enabled?: boolean;              // default true
  failureThreshold?: number;      // default 5 — consecutive countable failures to trip open
  resetTimeout?: number;          // default 10_000 ms — how long a circuit stays open
}

interface CircuitBreakerController {
  status(method: HttpMethod, path: string): CircuitStatus;  // read (and lazily create) a circuit
  statuses(): CircuitStatus[];                              // every circuit ever observed
  reset(method?: HttpMethod, path?: string): void;          // force back to closed (all if args omitted)
}

type CircuitState = "closed" | "open" | "halfOpen";

interface CircuitStatus {
  endpoint: string;                 // "METHOD pathname"
  state: CircuitState;
  consecutiveFailures: number;      // counted failures since the last success
  openedAt?: number;                // when the circuit last opened (resetTimeout measured from here)
  probing: boolean;                 // a half-open probe is currently in flight
}

interface SchedulerOptions {
  enabled?: boolean;            // default true — the option's presence enables the scheduler
  concurrency?: number;         // max simultaneous network attempts; default 8
  priority?: boolean;           // enable high/normal/low lanes; default false (single FIFO queue)
  hosts?: Record<string, number>;   // per-host concurrency caps (hostname → max)
  rateLimit?: SchedulerRateLimitOptions;
}

interface SchedulerRateLimitOptions {
  requests: number;   // max network attempts per window
  interval: number;   // window length in ms
}

interface SchedulerController {
  stats(): SchedulerStats;              // lived counters (below)
  pauseGroup(group: string): void;      // freeze queued work in a group (running requests finish)
  resumeGroup(group: string): void;     // re-admit a paused group
  cancelGroup(group: string): void;     // drop every queued/parked/running request in a group
  prioritize(selector: string, priority: Priority): number; // move matching queued jobs to a lane
}

type Priority = "high" | "normal" | "low";

interface SchedulerStats {
  active: number;       // holding a network slot right now
  queued: number;       // waiting in the priority lanes
  delayed: number;      // parked until a future moment
  completed: number;    // finished their full lifecycle
  rejected: number;     // dropped by the scheduler (group/all cancellation)
  lanes: Record<Priority, number>;
}

interface AdaptiveOptions {
  enabled?: boolean;                    // master switch; default false
  concurrency?: boolean;                // per-endpoint scheduler ceiling (default false)
  retry?: boolean;                      // scale retry backoff while throttled (default false)
  rateLimit?: boolean;                  // 429 throttling / release (default false)
  staleWhileRevalidate?: boolean;       // SWR reads for degraded endpoints (default false)
  highLatencyMs?: number;               // p95 ≥ this → pressured; default 2000
  lowLatencyMs?: number;                // p95 < this → healthy; default 1000 (deadband between)
  degradeSamples?: number;              // multiplied bad windows before a reduction; default 3
  recoverySamples?: number;             // clean windows before a +1 recovery / throttle release; default 3
  changeCooldown?: number;              // min windows between two decisions per endpoint; default 2
  minConcurrency?: number;              // floor for the effective ceiling; default 1
  rateLimitRatio?: number;              // 429 share flagging throttling pressure; default 0.2
  errorRatio?: number;                  // error share flagging pressure; default 0.1
  backoffFactor?: number;               // retry backoff multiplier while throttled; default 2
  maxBackoffMs?: number;                // cap for the adapted base delay; default 10_000
  swrLatencyMs?: number;                // p95 ≥ this flips reads to SWR; default 1500
  latencyWindow?: number;               // latency ring size (min 4); default 64
  outcomeWindow?: number;               // outcome ring size (min 2); default 32
}

interface AdaptiveController {
  snapshot(): { enabled: boolean; endpoints: Record<string, EndpointAdaptiveState> };
  endpoint(method: HttpMethod, path: string): EndpointAdaptiveState | undefined;
  metrics(): AdaptiveMetrics;           // rolled-up counters
  reset(): void;                        // forget every learned profile
}

type AdaptiveHealth = "good" | "recovering" | "degraded" | "throttled";

interface EndpointAdaptiveState {
  endpoint: string;                     // "METHOD pathname"
  configured: number;                   // the scheduler's original ceiling
  effective: number;                    // ceiling applied right now
  mode: "nominal" | "reducing" | "recovering";
  health: AdaptiveHealth;
  reason: string;                       // explainable decision
  retryMultiplier: number;              // backoff multiplier while throttled
  retryMode: "nominal" | "throttled";
  retryReason: string;
  strategy?: CacheStrategy;             // "stale-while-revalidate" once engaged
  strategyReason: string;
  signals: {
    avg: number; p50: number; p95: number; samples: number;
    errorRatio: number; rateLimitRatio: number; active: number;
  };
  degradedSince?: number;
  counters: AdaptiveMetrics;
}

interface AdaptiveMetrics {
  decisions: number;                    // reductions + recoveries + throttles
  concurrencyReductions: number;
  concurrencyRecoveries: number;
  throttles: number;                    // endpoints entered throttled mode
  retryChanges: number;                 // retry multiplier changes
}

interface IntelligenceOptions {
  enabled?: boolean;                  // default true
  adaptiveTimeout?: boolean;          // default false
  adaptiveStaleWhileRevalidate?: boolean; // default false
}

interface IntelligenceController {
  snapshot(): IntelligenceSnapshot;                    // summary + all endpoints
  endpoint(method: string, pathname: string): EndpointStats | undefined;
  reset(): void;                                       // clears observation history
}

interface IntelligenceSummary {
  totalRequests; cacheHits; cacheMisses; deduplicated;
  retriesPerformed; retriesRecovered; failures; rateLimited; timeouts; cancels;
  activeRequests; cacheHitRate;         // cacheHits / totalRequests (0 if none)
  dedupRate; retryRate; failureRate; rateLimitRate;
  adaptive: AdaptiveMetrics;            // rolled-up adaptive counters
}

interface IntelligenceSnapshot {
  summary: IntelligenceSummary;
  endpoints: EndpointStats[];
}

interface EndpointStats {
  method; path;
  requests; successes; failures; cacheHits; cacheMisses; dedupPrevented;
  retriesPerformed; retriesRecovered; rateLimited; timeouts; cancels;
  latency: { avg: number; p50: number; p95: number; samples: number };
}

interface RequestOptions {
  method: HttpMethod;
  url: string;
  baseURL?: string;
  headers?: Record<string, string>;
  params?: Record<string, ParamValue | ParamValue[]>;
  body?: unknown;
  signal?: AbortSignal;
  timeout?: number;
  cache?: boolean | CacheOptions;
  retry?: boolean | RetryOptions;
  tags?: string[];
  priority?: Priority;                    // "high" | "normal" | "low" (used when scheduler.priority is true)
  scheduler?: { group: string };          // queue group for pause/resume/cancel/prioritize
}

type ParamValue = string | number | boolean | null | undefined;

interface CacheOptions {
  enabled?: boolean;   // default false at type level, client enables by default
  ttl?: number;        // ms; default 30_000
  strategy?: CacheStrategy; // "cache-first" | "stale-while-revalidate"
}

interface RetryOptions {
  attempts?: number;              // total attempts incl. first; default 3
  baseDelay?: number;             // ms; default 1000
  maxDelay?: number;              // ms; default 30_000
  backoff?: "exponential" | "fixed";
  jitter?: boolean;               // default true
  retryOn?: (status: number | undefined) => boolean;
  respectRetryAfter?: boolean;    // default true
}

interface ApiResponse<T = unknown> {
  data: T;
  status: number;
  statusText: string;
  headers: Headers;
}

interface CancellablePromise<T> extends Promise<T> {
  cancel: () => void;   // rejects with CancelledError
}

interface ClientEvents {
  request:     { key: string; method: HttpMethod; url: string; tracker: Tracker };
  success:     { key: string; tracker: Tracker; response: ApiResponse };
  error:       { key: string; tracker: Tracker; error: unknown };
  retry:       { key: string; tracker: Tracker; attempts: number; delay: number; error: HttpError };
  cancel:      { key: string; tracker: Tracker };
  dedup:       { key: string; method: HttpMethod; url: string; consumers: number };
  "cache-hit": { key: string; tracker: Tracker };
  "cache-write": { key: string; response: ApiResponse };
  invalidate:  { keys: string[]; target: InvalidateTarget };
  revalidate:  { key: string; response: ApiResponse };
  "circuit-open": { endpoint: string; method: HttpMethod; path: string };
  "circuit-half-open": { endpoint: string; method: HttpMethod; path: string };
  "circuit-closed": { endpoint: string; method: HttpMethod; path: string };
  "circuit-rejected": { endpoint: string; method: HttpMethod; path: string; error: CircuitOpenError };
  "request-queued": { id: number; key: string; method: HttpMethod; url: string; priority: Priority; position: number };
  "request-dequeued": { id: number; key: string; method: HttpMethod; url: string; priority: Priority };
  "request-started": { id: number; key: string; method: HttpMethod; url: string; priority: Priority };
  "request-delayed": { id: number; key: string; method: HttpMethod; url: string; priority: Priority; reason: ParkReason; delay: number };
  "request-scheduled": { id: number; key: string; method: HttpMethod; url: string; priority: Priority };
  "request-prioritized": { id: number; key: string; method: HttpMethod; url: string; priority: Priority; from: Priority; to: Priority };
  "request-rejected": { id: number; key: string; method: HttpMethod; url: string; priority: Priority; reason: "cancelled" };
  "queue-paused": { group?: string };
  "queue-resumed": { group?: string };
}

type CacheSubscriber<T> = (update: CacheUpdate<T>) => void;

interface CacheUpdate<T = unknown> {
  type: "write" | "revalidate" | "invalidate";
  key: string;
  response?: ApiResponse<T>;   // absent for "invalidate"
}

client.subscribe<T>(matcher: (key: string) => boolean, listener: CacheSubscriber<T>): () => void

type InvalidateTarget = string | string[] | ((entry: CacheMeta) => boolean);

interface CacheMeta {
  key: string;
  tags: string[];
  storedAt: number;
  expiresAt: number;
}

client.invalidate(target: InvalidateTarget, options?: { refetch?: boolean }): string[];

class HttpError extends Error {
  status?: number;
  statusText?: string;
  headers?: Headers;
}
class TimeoutError extends Error {}
class CancelledError extends Error {}
class CircuitOpenError extends Error {
  endpoint: string;   // "METHOD pathname" for which the circuit is open
}
function isAbortError(err: unknown): boolean;