@rohan9024/retrykit 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,190 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+
+# @rohan9024/retrykit ⚡
+
+> A zero-dependency, header-aware retry engine and circuit breaker built for reliable LLM API integrations.
+
+[![npm version](https://img.shields.io/npm/v/@rohan9024/retrykit.svg)](https://www.npmjs.com/package/@rohan9024/retrykit)
+[![license](https://img.shields.io/npm/l/@rohan9024/retrykit.svg)](https://github.com/rohan9024/retrykit)
+[![bundle size](https://img.shields.io/bundlephobia/min/@rohan9024/retrykit)](https://bundlephobia.com/package/@rohan9024/retrykit)
+
+**RetryKit** helps developers build resilient applications powered by LLM APIs such as OpenAI, Anthropic, DeepSeek, Groq, and Mistral.
+
+Unlike basic retry libraries such as `p-retry` or `tenacity`, RetryKit understands provider-specific rate-limit headers and uses that information to schedule smarter retries.
+
+### Why RetryKit?
+
+- **Header-aware retries:** Parses provider-specific rate-limit reset headers.
+- **Exponential backoff with jitter:** Prevents synchronized retry storms.
+- **SSE stream resilience:** Handles mid-stream connection interruptions.
+- **Circuit breaker:** Prevents cascading failures during provider outages.
+- **Timeout protection:** Supports per-attempt request timeouts.
+- **Zero dependencies:** Lightweight and dependency-free.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @rohan9024/retrykit
+```
+
+---
+
+## 🚀 Quick Start
+
+### 1. Drop-in Fetch Replacement (`retryFetch`)
+
+Use `retryFetch` just like standard `fetch`, with automatic retries and rate-limit awareness.
+
+```typescript
+import { retryFetch } from '@rohan9024/retrykit';
+
+const response = await retryFetch(
+  'https://api.openai.com/v1/chat/completions',
+  {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      model: 'gpt-4o',
+      messages: [
+        { role: 'user', content: 'Say hello!' }
+      ],
+    }),
+  },
+  {
+    retries: 4,
+    timeoutMs: 15000,
+    onRetry: (error, attempt, delayMs) => {
+      console.warn(
+        `Retry #${attempt}: Waiting ${delayMs}ms...`
+      );
+    },
+  }
+);
+
+const data = await response.json();
+```
+
+### 2. Wrap Official SDKs (`retry`)
+
+Use RetryKit with existing SDKs such as OpenAI, Anthropic, Mistral, or Google.
+
+```typescript
+import OpenAI from 'openai';
+import { retry } from '@rohan9024/retrykit';
+
+const openai = new OpenAI();
+
+const completion = await retry(
+  () =>
+    openai.chat.completions.create({
+      model: 'gpt-4o',
+      messages: [
+        {
+          role: 'user',
+          content: 'Write a poem about resilience',
+        },
+      ],
+    }),
+  {
+    retries: 3,
+    baseDelayMs: 500,
+  }
+);
+```
+
+### 3. Resilient Token Streaming (`retryStream`)
+
+LLM streaming connections can fail midway through generation. `retryStream` helps recover from interrupted streams.
+
+```typescript
+import { retryStream } from '@rohan9024/retrykit';
+
+async function* tokenGenerator() {
+  const stream = await fetchLLMStream();
+
+  for await (const chunk of stream) {
+    yield chunk;
+  }
+}
+
+for await (const chunk of retryStream(() => tokenGenerator())) {
+  process.stdout.write(chunk);
+}
+```
+
+### 4. Circuit Breaker
+
+Protect your application from cascading failures and unnecessary requests when an AI provider experiences an outage.
+
+```typescript
+import { CircuitBreaker } from '@rohan9024/retrykit';
+
+const breaker = new CircuitBreaker({
+  failureThreshold: 3,
+  resetTimeoutMs: 30000,
+
+  onStateChange: (from, to) => {
+    console.log(`Circuit changed: ${from} -> ${to}`);
+  },
+});
+
+// Fails fast when the circuit is open
+const result = await breaker.execute(() => callUnstableAPI());
+```
+
+---
+
+## 🧠 Supported Provider Headers
+
+RetryKit automatically extracts retry timing information from commonly used API rate-limit headers.
+
+| Provider | Supported Headers |
+|---|---|
+| OpenAI | `x-ratelimit-reset-requests`, `x-ratelimit-reset-tokens`, `retry-after` |
+| Anthropic | `anthropic-ratelimit-requests-reset`, `anthropic-ratelimit-tokens-reset`, `retry-after` |
+| Groq / DeepSeek | `x-ratelimit-reset-total`, `retry-after-ms`, `retry-after` |
+| Standard HTTP | `Retry-After` (integer seconds or RFC 1123 HTTP dates) |
+
+---
+
+## ⚙️ Configuration Options
+
+RetryKit provides configurable retry behavior.
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `retries` | `number` | `3` | Maximum retry attempts before failing |
+| `baseDelayMs` | `number` | `500` | Initial backoff delay in milliseconds |
+| `maxDelayMs` | `number` | `30000` | Maximum backoff delay |
+| `timeoutMs` | `number` | `undefined` | Per-attempt timeout in milliseconds |
+| `retryOnStatus` | `number[]` | `[408, 429, 500, 502, 503, 504]` | HTTP status codes that trigger retries |
+| `shouldRetry` | `(err, attempt) => boolean` | `undefined` | Custom retry decision logic |
+| `onRetry` | `(err, attempt, delay) => void` | `undefined` | Callback executed before each retry |
+| `signal` | `AbortSignal` | `undefined` | Abort signal for immediate cancellation |
+
+---
+
+## 🛡️ Designed For
+
+- LLM-powered applications
+- AI agents and autonomous workflows
+- RAG pipelines
+- High-volume API integrations
+- Streaming chat applications
+- Production AI infrastructure
+
+---
+
+## 📄 License
+
+MIT © [rohan9024](https://github.com/rohan9024)
+
+---
+
+<p align="center">
+  Built for developers who want their AI applications to be resilient. ⚡
+</p>

package/dist/index.d.mts

@@ -0,0 +1,90 @@
+interface RetryOptions {
+    /** Maximum number of retry attempts. Default: 3 */
+    retries?: number;
+    /** Base delay in milliseconds for exponential backoff. Default: 500 */
+    baseDelayMs?: number;
+    /** Maximum backoff ceiling delay in milliseconds. Default: 30000 */
+    maxDelayMs?: number;
+    /** Per-request timeout in milliseconds. Default: undefined */
+    timeoutMs?: number;
+    /** HTTP status codes that trigger a retry. Default: [408, 429, 500, 502, 503, 504] */
+    retryOnStatus?: number[];
+    /** Custom condition to decide whether to retry */
+    shouldRetry?: (error: unknown, attempt: number) => boolean;
+    /** Optional callback fired before every retry sleep */
+    onRetry?: (error: unknown, attempt: number, delayMs: number) => void;
+    /** AbortSignal for immediate cancellation */
+    signal?: AbortSignal;
+}
+interface CircuitBreakerOptions {
+    /** Number of consecutive failures before opening the circuit. Default: 5 */
+    failureThreshold?: number;
+    /** Time in milliseconds to wait before attempting recovery (HALF_OPEN). Default: 30000 */
+    resetTimeoutMs?: number;
+    /** Optional callback triggered on circuit state changes */
+    onStateChange?: (from: CircuitState, to: CircuitState) => void;
+}
+type CircuitState = 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+type HeaderSource = Headers | Record<string, string | string[] | undefined> | [string, string][] | undefined;
+
+declare function retryFetch(url: string | URL | Request, init?: RequestInit, options?: RetryOptions): Promise<Response>;
+
+declare function retry<T>(fn: (attempt: number) => Promise<T>, options?: RetryOptions): Promise<T>;
+
+/**
+ * Resilient wrapper for Server-Sent Events / LLM chunk streams.
+ * If the streaming connection drops mid-generation, it retries and resumes.
+ */
+declare function retryStream<T>(streamFactory: (attempt: number) => Promise<AsyncIterable<T>>, options?: RetryOptions): AsyncGenerator<T, void, unknown>;
+
+declare class CircuitBreakerOpenError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Zero-dependency Circuit Breaker implementation to stop cascading failure
+ * cascades when downstream LLM APIs experience total outages.
+ */
+declare class CircuitBreaker {
+    private state;
+    private failureCount;
+    private lastFailureTime;
+    private readonly failureThreshold;
+    private readonly resetTimeoutMs;
+    private readonly onStateChange?;
+    constructor(options?: CircuitBreakerOptions);
+    getState(): CircuitState;
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    private recordSuccess;
+    private recordFailure;
+    private transitionTo;
+    reset(): void;
+}
+
+declare const DEFAULT_RETRYABLE_STATUS_CODES: number[];
+/**
+ * Calculates exponential backoff with full jitter:
+ * sleepMs = min(maxDelayMs, baseDelayMs * 2 ** attempt) * Math.random()
+ */
+declare function computeJitterDelay(attempt: number, baseDelayMs?: number, maxDelayMs?: number): number;
+/**
+ * Parses duration strings returned by LLM APIs (e.g. "600ms", "10s", "2m", "1m30s", "1.5").
+ */
+declare function parseDurationToMs(value: string): number | null;
+/**
+ * Exhaustively checks provider headers across:
+ * - RFC 7231 / RFC 6585 standard `retry-after`
+ * - OpenAI: `x-ratelimit-reset-requests`, `x-ratelimit-reset-tokens`
+ * - Anthropic: `anthropic-ratelimit-requests-reset`, `anthropic-ratelimit-tokens-reset`
+ * - Groq / DeepSeek / Mistral: `x-ratelimit-reset-total`, `retry-after-ms`
+ */
+declare function parseRateLimitDelay(headers: HeaderSource): number | null;
+/**
+ * Detects transient network drop errors across Node, Bun, Deno, and browsers.
+ */
+declare function isTransientNetworkError(error: unknown): boolean;
+/**
+ * Promisified sleep that respects AbortSignal cancellation.
+ */
+declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+
+export { CircuitBreaker, CircuitBreakerOpenError, type CircuitBreakerOptions, type CircuitState, DEFAULT_RETRYABLE_STATUS_CODES, type HeaderSource, type RetryOptions, computeJitterDelay, isTransientNetworkError, parseDurationToMs, parseRateLimitDelay, retry, retryFetch, retryStream, sleep };

package/dist/index.d.ts

@@ -0,0 +1,90 @@
+interface RetryOptions {
+    /** Maximum number of retry attempts. Default: 3 */
+    retries?: number;
+    /** Base delay in milliseconds for exponential backoff. Default: 500 */
+    baseDelayMs?: number;
+    /** Maximum backoff ceiling delay in milliseconds. Default: 30000 */
+    maxDelayMs?: number;
+    /** Per-request timeout in milliseconds. Default: undefined */
+    timeoutMs?: number;
+    /** HTTP status codes that trigger a retry. Default: [408, 429, 500, 502, 503, 504] */
+    retryOnStatus?: number[];
+    /** Custom condition to decide whether to retry */
+    shouldRetry?: (error: unknown, attempt: number) => boolean;
+    /** Optional callback fired before every retry sleep */
+    onRetry?: (error: unknown, attempt: number, delayMs: number) => void;
+    /** AbortSignal for immediate cancellation */
+    signal?: AbortSignal;
+}
+interface CircuitBreakerOptions {
+    /** Number of consecutive failures before opening the circuit. Default: 5 */
+    failureThreshold?: number;
+    /** Time in milliseconds to wait before attempting recovery (HALF_OPEN). Default: 30000 */
+    resetTimeoutMs?: number;
+    /** Optional callback triggered on circuit state changes */
+    onStateChange?: (from: CircuitState, to: CircuitState) => void;
+}
+type CircuitState = 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+type HeaderSource = Headers | Record<string, string | string[] | undefined> | [string, string][] | undefined;
+
+declare function retryFetch(url: string | URL | Request, init?: RequestInit, options?: RetryOptions): Promise<Response>;
+
+declare function retry<T>(fn: (attempt: number) => Promise<T>, options?: RetryOptions): Promise<T>;
+
+/**
+ * Resilient wrapper for Server-Sent Events / LLM chunk streams.
+ * If the streaming connection drops mid-generation, it retries and resumes.
+ */
+declare function retryStream<T>(streamFactory: (attempt: number) => Promise<AsyncIterable<T>>, options?: RetryOptions): AsyncGenerator<T, void, unknown>;
+
+declare class CircuitBreakerOpenError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Zero-dependency Circuit Breaker implementation to stop cascading failure
+ * cascades when downstream LLM APIs experience total outages.
+ */
+declare class CircuitBreaker {
+    private state;
+    private failureCount;
+    private lastFailureTime;
+    private readonly failureThreshold;
+    private readonly resetTimeoutMs;
+    private readonly onStateChange?;
+    constructor(options?: CircuitBreakerOptions);
+    getState(): CircuitState;
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    private recordSuccess;
+    private recordFailure;
+    private transitionTo;
+    reset(): void;
+}
+
+declare const DEFAULT_RETRYABLE_STATUS_CODES: number[];
+/**
+ * Calculates exponential backoff with full jitter:
+ * sleepMs = min(maxDelayMs, baseDelayMs * 2 ** attempt) * Math.random()
+ */
+declare function computeJitterDelay(attempt: number, baseDelayMs?: number, maxDelayMs?: number): number;
+/**
+ * Parses duration strings returned by LLM APIs (e.g. "600ms", "10s", "2m", "1m30s", "1.5").
+ */
+declare function parseDurationToMs(value: string): number | null;
+/**
+ * Exhaustively checks provider headers across:
+ * - RFC 7231 / RFC 6585 standard `retry-after`
+ * - OpenAI: `x-ratelimit-reset-requests`, `x-ratelimit-reset-tokens`
+ * - Anthropic: `anthropic-ratelimit-requests-reset`, `anthropic-ratelimit-tokens-reset`
+ * - Groq / DeepSeek / Mistral: `x-ratelimit-reset-total`, `retry-after-ms`
+ */
+declare function parseRateLimitDelay(headers: HeaderSource): number | null;
+/**
+ * Detects transient network drop errors across Node, Bun, Deno, and browsers.
+ */
+declare function isTransientNetworkError(error: unknown): boolean;
+/**
+ * Promisified sleep that respects AbortSignal cancellation.
+ */
+declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+
+export { CircuitBreaker, CircuitBreakerOpenError, type CircuitBreakerOptions, type CircuitState, DEFAULT_RETRYABLE_STATUS_CODES, type HeaderSource, type RetryOptions, computeJitterDelay, isTransientNetworkError, parseDurationToMs, parseRateLimitDelay, retry, retryFetch, retryStream, sleep };

package/dist/index.js

@@ -0,0 +1,410 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  CircuitBreaker: () => CircuitBreaker,
+  CircuitBreakerOpenError: () => CircuitBreakerOpenError,
+  DEFAULT_RETRYABLE_STATUS_CODES: () => DEFAULT_RETRYABLE_STATUS_CODES,
+  computeJitterDelay: () => computeJitterDelay,
+  isTransientNetworkError: () => isTransientNetworkError,
+  parseDurationToMs: () => parseDurationToMs,
+  parseRateLimitDelay: () => parseRateLimitDelay,
+  retry: () => retry,
+  retryFetch: () => retryFetch,
+  retryStream: () => retryStream,
+  sleep: () => sleep
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/engine.ts
+var DEFAULT_RETRYABLE_STATUS_CODES = [408, 429, 500, 502, 503, 504];
+function computeJitterDelay(attempt, baseDelayMs = 500, maxDelayMs = 3e4) {
+  const exponential = baseDelayMs * Math.pow(2, attempt);
+  const ceiling = Math.min(maxDelayMs, exponential);
+  return Math.floor(ceiling * Math.random());
+}
+function getHeader(headers, name) {
+  if (!headers) return null;
+  const target = name.toLowerCase();
+  if (typeof headers.get === "function") {
+    return headers.get(target);
+  }
+  if (Array.isArray(headers)) {
+    for (const [key, value] of headers) {
+      if (key.toLowerCase() === target) {
+        return value;
+      }
+    }
+    return null;
+  }
+  if (typeof headers === "object") {
+    for (const key of Object.keys(headers)) {
+      if (key.toLowerCase() === target) {
+        const val = headers[key];
+        if (Array.isArray(val)) return val[0] ?? null;
+        return typeof val === "string" ? val : String(val);
+      }
+    }
+  }
+  return null;
+}
+function parseDurationToMs(value) {
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  if (/^\d+(\.\d+)?$/.test(trimmed)) {
+    const sec = parseFloat(trimmed);
+    return isNaN(sec) ? null : Math.max(0, Math.floor(sec * 1e3));
+  }
+  const regex = /(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)/gi;
+  let match;
+  let totalMs = 0;
+  let matched = false;
+  while ((match = regex.exec(trimmed)) !== null) {
+    matched = true;
+    const amount = parseFloat(match[1]);
+    const unit = match[2].toLowerCase();
+    switch (unit) {
+      case "ms":
+        totalMs += amount;
+        break;
+      case "s":
+        totalMs += amount * 1e3;
+        break;
+      case "m":
+        totalMs += amount * 60 * 1e3;
+        break;
+      case "h":
+        totalMs += amount * 60 * 60 * 1e3;
+        break;
+      case "d":
+        totalMs += amount * 24 * 60 * 60 * 1e3;
+        break;
+    }
+  }
+  return matched ? Math.max(0, Math.floor(totalMs)) : null;
+}
+function parseRateLimitDelay(headers) {
+  if (!headers) return null;
+  const retryAfterMs = getHeader(headers, "retry-after-ms");
+  if (retryAfterMs) {
+    const parsed = parseFloat(retryAfterMs);
+    if (!isNaN(parsed)) return Math.max(0, Math.floor(parsed));
+  }
+  const retryAfter = getHeader(headers, "retry-after");
+  if (retryAfter) {
+    if (/^\d+(\.\d+)?$/.test(retryAfter.trim())) {
+      const sec = parseFloat(retryAfter.trim());
+      if (!isNaN(sec)) return Math.max(0, Math.floor(sec * 1e3));
+    }
+    const parsedDate = Date.parse(retryAfter);
+    if (!isNaN(parsedDate)) {
+      return Math.max(0, parsedDate - Date.now());
+    }
+  }
+  const candidateKeys = [
+    "x-ratelimit-reset-requests",
+    "x-ratelimit-reset-tokens",
+    "anthropic-ratelimit-requests-reset",
+    "anthropic-ratelimit-tokens-reset",
+    "x-ratelimit-reset-total"
+  ];
+  for (const key of candidateKeys) {
+    const raw = getHeader(headers, key);
+    if (raw) {
+      const ms = parseDurationToMs(raw);
+      if (ms !== null) return ms;
+      const epochSec = parseFloat(raw);
+      if (!isNaN(epochSec) && epochSec > 1e9) {
+        return Math.max(0, Math.floor(epochSec * 1e3 - Date.now()));
+      }
+    }
+  }
+  return null;
+}
+function isTransientNetworkError(error) {
+  if (!(error instanceof Error)) return false;
+  const msg = error.message.toLowerCase();
+  const code = error.code;
+  if (error.name === "TypeError" && msg.includes("fetch failed")) return true;
+  const transientCodes = [
+    "ECONNRESET",
+    "ETIMEDOUT",
+    "ENOTFOUND",
+    "EAI_AGAIN",
+    "ECONNREFUSED",
+    "UND_ERR_CONNECT_TIMEOUT",
+    "UND_ERR_SOCKET"
+  ];
+  if (code && transientCodes.includes(code)) return true;
+  return msg.includes("network error") || msg.includes("socket hang up") || msg.includes("terminated") || msg.includes("econnreset");
+}
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      return reject(signal.reason ?? new DOMException("The operation was aborted.", "AbortError"));
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    function onAbort() {
+      clearTimeout(timer);
+      reject(signal?.reason ?? new DOMException("The operation was aborted.", "AbortError"));
+    }
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+// src/fetch.ts
+async function retryFetch(url, init, options = {}) {
+  const {
+    retries = 3,
+    baseDelayMs = 500,
+    maxDelayMs = 3e4,
+    timeoutMs,
+    retryOnStatus = DEFAULT_RETRYABLE_STATUS_CODES,
+    shouldRetry,
+    onRetry,
+    signal
+  } = options;
+  let attempt = 0;
+  while (true) {
+    if (signal?.aborted) {
+      throw signal.reason ?? new DOMException("The operation was aborted.", "AbortError");
+    }
+    const attemptController = new AbortController();
+    let timeoutId;
+    if (timeoutMs && timeoutMs > 0) {
+      timeoutId = setTimeout(() => {
+        attemptController.abort(new DOMException(`Request timed out after ${timeoutMs}ms`, "TimeoutError"));
+      }, timeoutMs);
+    }
+    const abortHandler = () => attemptController.abort(signal?.reason);
+    signal?.addEventListener("abort", abortHandler, { once: true });
+    try {
+      const response = await fetch(url, {
+        ...init,
+        signal: attemptController.signal
+      });
+      if (timeoutId) clearTimeout(timeoutId);
+      signal?.removeEventListener("abort", abortHandler);
+      const isStatusRetryable = retryOnStatus.includes(response.status);
+      const customRetry = shouldRetry ? shouldRetry(response, attempt) : isStatusRetryable;
+      if (customRetry && attempt < retries) {
+        const headerDelay = parseRateLimitDelay(response.headers);
+        const backoffDelay = computeJitterDelay(attempt, baseDelayMs, maxDelayMs);
+        const chosenDelay = Math.min(maxDelayMs, headerDelay ?? backoffDelay);
+        onRetry?.(response, attempt + 1, chosenDelay);
+        await sleep(chosenDelay, signal);
+        attempt++;
+        continue;
+      }
+      return response;
+    } catch (error) {
+      if (timeoutId) clearTimeout(timeoutId);
+      signal?.removeEventListener("abort", abortHandler);
+      if (signal?.aborted) {
+        throw signal.reason ?? error;
+      }
+      const isTimeout = error instanceof Error && error.name === "TimeoutError";
+      const isNetworkDrop = isTransientNetworkError(error);
+      const customRetry = shouldRetry ? shouldRetry(error, attempt) : isNetworkDrop || isTimeout;
+      if (customRetry && attempt < retries) {
+        const chosenDelay = computeJitterDelay(attempt, baseDelayMs, maxDelayMs);
+        onRetry?.(error, attempt + 1, chosenDelay);
+        await sleep(chosenDelay, signal);
+        attempt++;
+        continue;
+      }
+      throw error;
+    }
+  }
+}
+
+// src/wrap.ts
+async function retry(fn, options = {}) {
+  const {
+    retries = 3,
+    baseDelayMs = 500,
+    maxDelayMs = 3e4,
+    retryOnStatus = DEFAULT_RETRYABLE_STATUS_CODES,
+    shouldRetry,
+    onRetry,
+    signal
+  } = options;
+  let attempt = 0;
+  while (true) {
+    if (signal?.aborted) {
+      throw signal.reason ?? new DOMException("The operation was aborted.", "AbortError");
+    }
+    try {
+      return await fn(attempt);
+    } catch (error) {
+      if (signal?.aborted || error instanceof Error && error.name === "AbortError") {
+        throw error;
+      }
+      if (attempt >= retries) {
+        throw error;
+      }
+      const err = error;
+      const statusCode = err?.status ?? err?.statusCode ?? err?.response?.status;
+      const headers = err?.headers ?? err?.response?.headers;
+      const isStatusRetryable = statusCode !== void 0 && retryOnStatus.includes(statusCode);
+      const isNetworkRetryable = isTransientNetworkError(error);
+      const customRetry = shouldRetry ? shouldRetry(error, attempt) : isStatusRetryable || isNetworkRetryable;
+      if (!customRetry) {
+        throw error;
+      }
+      let chosenDelay;
+      const headerDelay = headers ? parseRateLimitDelay(headers) : null;
+      if (headerDelay !== null) {
+        chosenDelay = Math.min(maxDelayMs, headerDelay);
+      } else {
+        chosenDelay = computeJitterDelay(attempt, baseDelayMs, maxDelayMs);
+      }
+      onRetry?.(error, attempt + 1, chosenDelay);
+      await sleep(chosenDelay, signal);
+      attempt++;
+    }
+  }
+}
+
+// src/stream.ts
+async function* retryStream(streamFactory, options = {}) {
+  const {
+    retries = 3,
+    baseDelayMs = 500,
+    maxDelayMs = 3e4,
+    onRetry,
+    signal
+  } = options;
+  let attempt = 0;
+  while (true) {
+    if (signal?.aborted) {
+      throw signal.reason ?? new DOMException("The operation was aborted.", "AbortError");
+    }
+    try {
+      const stream = await streamFactory(attempt);
+      for await (const chunk of stream) {
+        if (signal?.aborted) {
+          throw signal.reason ?? new DOMException("The operation was aborted.", "AbortError");
+        }
+        yield chunk;
+      }
+      return;
+    } catch (error) {
+      if (signal?.aborted || error instanceof Error && error.name === "AbortError") {
+        throw error;
+      }
+      if (attempt >= retries) {
+        throw error;
+      }
+      const delay = computeJitterDelay(attempt, baseDelayMs, maxDelayMs);
+      onRetry?.(error, attempt + 1, delay);
+      await sleep(delay, signal);
+      attempt++;
+    }
+  }
+}
+
+// src/circuit-breaker.ts
+var CircuitBreakerOpenError = class extends Error {
+  constructor(message = "Circuit breaker is OPEN. Fast-failing requests.") {
+    super(message);
+    this.name = "CircuitBreakerOpenError";
+  }
+};
+var CircuitBreaker = class {
+  state = "CLOSED";
+  failureCount = 0;
+  lastFailureTime = 0;
+  failureThreshold;
+  resetTimeoutMs;
+  onStateChange;
+  constructor(options = {}) {
+    this.failureThreshold = options.failureThreshold ?? 5;
+    this.resetTimeoutMs = options.resetTimeoutMs ?? 3e4;
+    this.onStateChange = options.onStateChange;
+  }
+  getState() {
+    if (this.state === "OPEN") {
+      const elapsed = Date.now() - this.lastFailureTime;
+      if (elapsed >= this.resetTimeoutMs) {
+        this.transitionTo("HALF_OPEN");
+      }
+    }
+    return this.state;
+  }
+  async execute(fn) {
+    const currentState = this.getState();
+    if (currentState === "OPEN") {
+      throw new CircuitBreakerOpenError();
+    }
+    try {
+      const result = await fn();
+      this.recordSuccess();
+      return result;
+    } catch (error) {
+      this.recordFailure();
+      throw error;
+    }
+  }
+  recordSuccess() {
+    if (this.state === "HALF_OPEN") {
+      this.transitionTo("CLOSED");
+    }
+    this.failureCount = 0;
+  }
+  recordFailure() {
+    this.failureCount++;
+    this.lastFailureTime = Date.now();
+    if (this.state === "HALF_OPEN" || this.failureCount >= this.failureThreshold) {
+      this.transitionTo("OPEN");
+    }
+  }
+  transitionTo(nextState) {
+    const prevState = this.state;
+    if (prevState !== nextState) {
+      this.state = nextState;
+      this.onStateChange?.(prevState, nextState);
+    }
+  }
+  reset() {
+    this.state = "CLOSED";
+    this.failureCount = 0;
+    this.lastFailureTime = 0;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CircuitBreaker,
+  CircuitBreakerOpenError,
+  DEFAULT_RETRYABLE_STATUS_CODES,
+  computeJitterDelay,
+  isTransientNetworkError,
+  parseDurationToMs,
+  parseRateLimitDelay,
+  retry,
+  retryFetch,
+  retryStream,
+  sleep
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/engine.ts","../src/fetch.ts","../src/wrap.ts","../src/stream.ts","../src/circuit-breaker.ts"],"sourcesContent":["export { retryFetch } from './fetch.js';\r\nexport { retry } from './wrap.js';\r\nexport { retryStream } from './stream.js';\r\nexport { CircuitBreaker, CircuitBreakerOpenError } from './circuit-breaker.js';\r\nexport {\r\n  computeJitterDelay,\r\n  parseDurationToMs,\r\n  parseRateLimitDelay,\r\n  isTransientNetworkError,\r\n  sleep,\r\n  DEFAULT_RETRYABLE_STATUS_CODES,\r\n} from './engine.js';\r\nexport type {\r\n  RetryOptions,\r\n  CircuitBreakerOptions,\r\n  CircuitState,\r\n  HeaderSource,\r\n} from './types.js';","import { HeaderSource } from './types.js';\r\n\r\nexport const DEFAULT_RETRYABLE_STATUS_CODES = [408, 429, 500, 502, 503, 504];\r\n\r\n/**\r\n * Calculates exponential backoff with full jitter:\r\n * sleepMs = min(maxDelayMs, baseDelayMs * 2 ** attempt) * Math.random()\r\n */\r\nexport function computeJitterDelay(\r\n  attempt: number,\r\n  baseDelayMs: number = 500,\r\n  maxDelayMs: number = 30000\r\n): number {\r\n  const exponential = baseDelayMs * Math.pow(2, attempt);\r\n  const ceiling = Math.min(maxDelayMs, exponential);\r\n  return Math.floor(ceiling * Math.random());\r\n}\r\n\r\n/**\r\n * Safely extracts a header value case-insensitively across Headers instances, records, or tuples.\r\n */\r\nexport function getHeader(headers: HeaderSource, name: string): string | null {\r\n  if (!headers) return null;\r\n\r\n  const target = name.toLowerCase();\r\n\r\n  if (typeof (headers as Headers).get === 'function') {\r\n    return (headers as Headers).get(target);\r\n  }\r\n\r\n  if (Array.isArray(headers)) {\r\n    for (const [key, value] of headers) {\r\n      if (key.toLowerCase() === target) {\r\n        return value;\r\n      }\r\n    }\r\n    return null;\r\n  }\r\n\r\n  if (typeof headers === 'object') {\r\n    for (const key of Object.keys(headers)) {\r\n      if (key.toLowerCase() === target) {\r\n        const val = (headers as Record<string, unknown>)[key];\r\n        if (Array.isArray(val)) return val[0] ?? null;\r\n        return typeof val === 'string' ? val : String(val);\r\n      }\r\n    }\r\n  }\r\n\r\n  return null;\r\n}\r\n\r\n/**\r\n * Parses duration strings returned by LLM APIs (e.g. \"600ms\", \"10s\", \"2m\", \"1m30s\", \"1.5\").\r\n */\r\nexport function parseDurationToMs(value: string): number | null {\r\n  const trimmed = value.trim();\r\n  if (!trimmed) return null;\r\n\r\n  if (/^\\d+(\\.\\d+)?$/.test(trimmed)) {\r\n    const sec = parseFloat(trimmed);\r\n    return isNaN(sec) ? null : Math.max(0, Math.floor(sec * 1000));\r\n  }\r\n\r\n  const regex = /(\\d+(?:\\.\\d+)?)\\s*(ms|s|m|h|d)/gi;\r\n  let match: RegExpExecArray | null;\r\n  let totalMs = 0;\r\n  let matched = false;\r\n\r\n  while ((match = regex.exec(trimmed)) !== null) {\r\n    matched = true;\r\n    const amount = parseFloat(match[1]);\r\n    const unit = match[2].toLowerCase();\r\n\r\n    switch (unit) {\r\n      case 'ms':\r\n        totalMs += amount;\r\n        break;\r\n      case 's':\r\n        totalMs += amount * 1000;\r\n        break;\r\n      case 'm':\r\n        totalMs += amount * 60 * 1000;\r\n        break;\r\n      case 'h':\r\n        totalMs += amount * 60 * 60 * 1000;\r\n        break;\r\n      case 'd':\r\n        totalMs += amount * 24 * 60 * 60 * 1000;\r\n        break;\r\n    }\r\n  }\r\n\r\n  return matched ? Math.max(0, Math.floor(totalMs)) : null;\r\n}\r\n\r\n/**\r\n * Exhaustively checks provider headers across:\r\n * - RFC 7231 / RFC 6585 standard `retry-after`\r\n * - OpenAI: `x-ratelimit-reset-requests`, `x-ratelimit-reset-tokens`\r\n * - Anthropic: `anthropic-ratelimit-requests-reset`, `anthropic-ratelimit-tokens-reset`\r\n * - Groq / DeepSeek / Mistral: `x-ratelimit-reset-total`, `retry-after-ms`\r\n */\r\nexport function parseRateLimitDelay(headers: HeaderSource): number | null {\r\n  if (!headers) return null;\r\n\r\n  // 1. Direct milliseconds header (Groq, custom proxies)\r\n  const retryAfterMs = getHeader(headers, 'retry-after-ms');\r\n  if (retryAfterMs) {\r\n    const parsed = parseFloat(retryAfterMs);\r\n    if (!isNaN(parsed)) return Math.max(0, Math.floor(parsed));\r\n  }\r\n\r\n  // 2. Standard Retry-After (seconds or RFC 1123 HTTP Date)\r\n  const retryAfter = getHeader(headers, 'retry-after');\r\n  if (retryAfter) {\r\n    if (/^\\d+(\\.\\d+)?$/.test(retryAfter.trim())) {\r\n      const sec = parseFloat(retryAfter.trim());\r\n      if (!isNaN(sec)) return Math.max(0, Math.floor(sec * 1000));\r\n    }\r\n\r\n    const parsedDate = Date.parse(retryAfter);\r\n    if (!isNaN(parsedDate)) {\r\n      return Math.max(0, parsedDate - Date.now());\r\n    }\r\n  }\r\n\r\n  // 3. Provider-specific reset headers\r\n  const candidateKeys = [\r\n    'x-ratelimit-reset-requests',\r\n    'x-ratelimit-reset-tokens',\r\n    'anthropic-ratelimit-requests-reset',\r\n    'anthropic-ratelimit-tokens-reset',\r\n    'x-ratelimit-reset-total',\r\n  ];\r\n\r\n  for (const key of candidateKeys) {\r\n    const raw = getHeader(headers, key);\r\n    if (raw) {\r\n      const ms = parseDurationToMs(raw);\r\n      if (ms !== null) return ms;\r\n\r\n      // Handle epoch timestamp formats\r\n      const epochSec = parseFloat(raw);\r\n      if (!isNaN(epochSec) && epochSec > 1000000000) {\r\n        return Math.max(0, Math.floor(epochSec * 1000 - Date.now()));\r\n      }\r\n    }\r\n  }\r\n\r\n  return null;\r\n}\r\n\r\n/**\r\n * Detects transient network drop errors across Node, Bun, Deno, and browsers.\r\n */\r\nexport function isTransientNetworkError(error: unknown): boolean {\r\n  if (!(error instanceof Error)) return false;\r\n\r\n  const msg = error.message.toLowerCase();\r\n  const code = (error as { code?: string }).code;\r\n\r\n  if (error.name === 'TypeError' && msg.includes('fetch failed')) return true;\r\n\r\n  const transientCodes = [\r\n    'ECONNRESET',\r\n    'ETIMEDOUT',\r\n    'ENOTFOUND',\r\n    'EAI_AGAIN',\r\n    'ECONNREFUSED',\r\n    'UND_ERR_CONNECT_TIMEOUT',\r\n    'UND_ERR_SOCKET',\r\n  ];\r\n  if (code && transientCodes.includes(code)) return true;\r\n\r\n  return (\r\n    msg.includes('network error') ||\r\n    msg.includes('socket hang up') ||\r\n    msg.includes('terminated') ||\r\n    msg.includes('econnreset')\r\n  );\r\n}\r\n\r\n/**\r\n * Promisified sleep that respects AbortSignal cancellation.\r\n */\r\nexport function sleep(ms: number, signal?: AbortSignal): Promise<void> {\r\n  return new Promise((resolve, reject) => {\r\n    if (signal?.aborted) {\r\n      return reject(signal.reason ?? new DOMException('The operation was aborted.', 'AbortError'));\r\n    }\r\n\r\n    const timer = setTimeout(() => {\r\n      signal?.removeEventListener('abort', onAbort);\r\n      resolve();\r\n    }, ms);\r\n\r\n    function onAbort() {\r\n      clearTimeout(timer);\r\n      reject(signal?.reason ?? new DOMException('The operation was aborted.', 'AbortError'));\r\n    }\r\n\r\n    signal?.addEventListener('abort', onAbort, { once: true });\r\n  });\r\n}","import {\r\n  computeJitterDelay,\r\n  DEFAULT_RETRYABLE_STATUS_CODES,\r\n  isTransientNetworkError,\r\n  parseRateLimitDelay,\r\n  sleep,\r\n} from './engine.js';\r\nimport { RetryOptions } from './types.js';\r\n\r\nexport async function retryFetch(\r\n  url: string | URL | Request,\r\n  init?: RequestInit,\r\n  options: RetryOptions = {}\r\n): Promise<Response> {\r\n  const {\r\n    retries = 3,\r\n    baseDelayMs = 500,\r\n    maxDelayMs = 30000,\r\n    timeoutMs,\r\n    retryOnStatus = DEFAULT_RETRYABLE_STATUS_CODES,\r\n    shouldRetry,\r\n    onRetry,\r\n    signal,\r\n  } = options;\r\n\r\n  let attempt = 0;\r\n\r\n  while (true) {\r\n    if (signal?.aborted) {\r\n      throw signal.reason ?? new DOMException('The operation was aborted.', 'AbortError');\r\n    }\r\n\r\n    // Set up per-attempt timeout controller\r\n    const attemptController = new AbortController();\r\n    let timeoutId: ReturnType<typeof setTimeout> | undefined;\r\n\r\n    if (timeoutMs && timeoutMs > 0) {\r\n      timeoutId = setTimeout(() => {\r\n        attemptController.abort(new DOMException(`Request timed out after ${timeoutMs}ms`, 'TimeoutError'));\r\n      }, timeoutMs);\r\n    }\r\n\r\n    const abortHandler = () => attemptController.abort(signal?.reason);\r\n    signal?.addEventListener('abort', abortHandler, { once: true });\r\n\r\n    try {\r\n      const response = await fetch(url, {\r\n        ...init,\r\n        signal: attemptController.signal,\r\n      });\r\n\r\n      if (timeoutId) clearTimeout(timeoutId);\r\n      signal?.removeEventListener('abort', abortHandler);\r\n\r\n      const isStatusRetryable = retryOnStatus.includes(response.status);\r\n      const customRetry = shouldRetry ? shouldRetry(response, attempt) : isStatusRetryable;\r\n\r\n      if (customRetry && attempt < retries) {\r\n        const headerDelay = parseRateLimitDelay(response.headers);\r\n        const backoffDelay = computeJitterDelay(attempt, baseDelayMs, maxDelayMs);\r\n        const chosenDelay = Math.min(maxDelayMs, headerDelay ?? backoffDelay);\r\n\r\n        onRetry?.(response, attempt + 1, chosenDelay);\r\n        await sleep(chosenDelay, signal);\r\n        attempt++;\r\n        continue;\r\n      }\r\n\r\n      return response;\r\n    } catch (error) {\r\n      if (timeoutId) clearTimeout(timeoutId);\r\n      signal?.removeEventListener('abort', abortHandler);\r\n\r\n      // Do not retry intentional outer aborts\r\n      if (signal?.aborted) {\r\n        throw signal.reason ?? error;\r\n      }\r\n\r\n      const isTimeout = error instanceof Error && error.name === 'TimeoutError';\r\n      const isNetworkDrop = isTransientNetworkError(error);\r\n      const customRetry = shouldRetry ? shouldRetry(error, attempt) : (isNetworkDrop || isTimeout);\r\n\r\n      if (customRetry && attempt < retries) {\r\n        const chosenDelay = computeJitterDelay(attempt, baseDelayMs, maxDelayMs);\r\n        onRetry?.(error, attempt + 1, chosenDelay);\r\n        await sleep(chosenDelay, signal);\r\n        attempt++;\r\n        continue;\r\n      }\r\n\r\n      throw error;\r\n    }\r\n  }\r\n}","import {\r\n  computeJitterDelay,\r\n  DEFAULT_RETRYABLE_STATUS_CODES,\r\n  isTransientNetworkError,\r\n  parseRateLimitDelay,\r\n  sleep,\r\n} from './engine.js';\r\nimport { HeaderSource, RetryOptions } from './types.js';\r\n\r\ninterface ErrorWithStatus extends Error {\r\n  status?: number;\r\n  statusCode?: number;\r\n  headers?: HeaderSource;\r\n  response?: {\r\n    status?: number;\r\n    headers?: HeaderSource;\r\n  };\r\n}\r\n\r\nexport async function retry<T>(\r\n  fn: (attempt: number) => Promise<T>,\r\n  options: RetryOptions = {}\r\n): Promise<T> {\r\n  const {\r\n    retries = 3,\r\n    baseDelayMs = 500,\r\n    maxDelayMs = 30000,\r\n    retryOnStatus = DEFAULT_RETRYABLE_STATUS_CODES,\r\n    shouldRetry,\r\n    onRetry,\r\n    signal,\r\n  } = options;\r\n\r\n  let attempt = 0;\r\n\r\n  while (true) {\r\n    if (signal?.aborted) {\r\n      throw signal.reason ?? new DOMException('The operation was aborted.', 'AbortError');\r\n    }\r\n\r\n    try {\r\n      return await fn(attempt);\r\n    } catch (error) {\r\n      if (signal?.aborted || (error instanceof Error && error.name === 'AbortError')) {\r\n        throw error;\r\n      }\r\n\r\n      if (attempt >= retries) {\r\n        throw error;\r\n      }\r\n\r\n      const err = error as ErrorWithStatus;\r\n      const statusCode = err?.status ?? err?.statusCode ?? err?.response?.status;\r\n      const headers = err?.headers ?? err?.response?.headers;\r\n\r\n      const isStatusRetryable = statusCode !== undefined && retryOnStatus.includes(statusCode);\r\n      const isNetworkRetryable = isTransientNetworkError(error);\r\n      const customRetry = shouldRetry\r\n        ? shouldRetry(error, attempt)\r\n        : (isStatusRetryable || isNetworkRetryable);\r\n\r\n      if (!customRetry) {\r\n        throw error;\r\n      }\r\n\r\n      let chosenDelay: number;\r\n      const headerDelay = headers ? parseRateLimitDelay(headers) : null;\r\n\r\n      if (headerDelay !== null) {\r\n        chosenDelay = Math.min(maxDelayMs, headerDelay);\r\n      } else {\r\n        chosenDelay = computeJitterDelay(attempt, baseDelayMs, maxDelayMs);\r\n      }\r\n\r\n      onRetry?.(error, attempt + 1, chosenDelay);\r\n      await sleep(chosenDelay, signal);\r\n      attempt++;\r\n    }\r\n  }\r\n}","import { computeJitterDelay, sleep } from './engine.js';\r\nimport { RetryOptions } from './types.js';\r\n\r\n/**\r\n * Resilient wrapper for Server-Sent Events / LLM chunk streams.\r\n * If the streaming connection drops mid-generation, it retries and resumes.\r\n */\r\nexport async function* retryStream<T>(\r\n  streamFactory: (attempt: number) => Promise<AsyncIterable<T>>,\r\n  options: RetryOptions = {}\r\n): AsyncGenerator<T, void, unknown> {\r\n  const {\r\n    retries = 3,\r\n    baseDelayMs = 500,\r\n    maxDelayMs = 30000,\r\n    onRetry,\r\n    signal,\r\n  } = options;\r\n\r\n  let attempt = 0;\r\n\r\n  while (true) {\r\n    if (signal?.aborted) {\r\n      throw signal.reason ?? new DOMException('The operation was aborted.', 'AbortError');\r\n    }\r\n\r\n    try {\r\n      const stream = await streamFactory(attempt);\r\n      for await (const chunk of stream) {\r\n        if (signal?.aborted) {\r\n          throw signal.reason ?? new DOMException('The operation was aborted.', 'AbortError');\r\n        }\r\n        yield chunk;\r\n      }\r\n      return;\r\n    } catch (error) {\r\n      if (signal?.aborted || (error instanceof Error && error.name === 'AbortError')) {\r\n        throw error;\r\n      }\r\n\r\n      if (attempt >= retries) {\r\n        throw error;\r\n      }\r\n\r\n      const delay = computeJitterDelay(attempt, baseDelayMs, maxDelayMs);\r\n      onRetry?.(error, attempt + 1, delay);\r\n      await sleep(delay, signal);\r\n      attempt++;\r\n    }\r\n  }\r\n}","import { CircuitBreakerOptions, CircuitState } from './types.js';\r\n\r\nexport class CircuitBreakerOpenError extends Error {\r\n  constructor(message: string = 'Circuit breaker is OPEN. Fast-failing requests.') {\r\n    super(message);\r\n    this.name = 'CircuitBreakerOpenError';\r\n  }\r\n}\r\n\r\n/**\r\n * Zero-dependency Circuit Breaker implementation to stop cascading failure\r\n * cascades when downstream LLM APIs experience total outages.\r\n */\r\nexport class CircuitBreaker {\r\n  private state: CircuitState = 'CLOSED';\r\n  private failureCount: number = 0;\r\n  private lastFailureTime: number = 0;\r\n  private readonly failureThreshold: number;\r\n  private readonly resetTimeoutMs: number;\r\n  private readonly onStateChange?: (from: CircuitState, to: CircuitState) => void;\r\n\r\n  constructor(options: CircuitBreakerOptions = {}) {\r\n    this.failureThreshold = options.failureThreshold ?? 5;\r\n    this.resetTimeoutMs = options.resetTimeoutMs ?? 30000;\r\n    this.onStateChange = options.onStateChange;\r\n  }\r\n\r\n  public getState(): CircuitState {\r\n    if (this.state === 'OPEN') {\r\n      const elapsed = Date.now() - this.lastFailureTime;\r\n      if (elapsed >= this.resetTimeoutMs) {\r\n        this.transitionTo('HALF_OPEN');\r\n      }\r\n    }\r\n    return this.state;\r\n  }\r\n\r\n  public async execute<T>(fn: () => Promise<T>): Promise<T> {\r\n    const currentState = this.getState();\r\n\r\n    if (currentState === 'OPEN') {\r\n      throw new CircuitBreakerOpenError();\r\n    }\r\n\r\n    try {\r\n      const result = await fn();\r\n      this.recordSuccess();\r\n      return result;\r\n    } catch (error) {\r\n      this.recordFailure();\r\n      throw error;\r\n    }\r\n  }\r\n\r\n  private recordSuccess(): void {\r\n    if (this.state === 'HALF_OPEN') {\r\n      this.transitionTo('CLOSED');\r\n    }\r\n    this.failureCount = 0;\r\n  }\r\n\r\n  private recordFailure(): void {\r\n    this.failureCount++;\r\n    this.lastFailureTime = Date.now();\r\n\r\n    if (this.state === 'HALF_OPEN' || this.failureCount >= this.failureThreshold) {\r\n      this.transitionTo('OPEN');\r\n    }\r\n  }\r\n\r\n  private transitionTo(nextState: CircuitState): void {\r\n    const prevState = this.state;\r\n    if (prevState !== nextState) {\r\n      this.state = nextState;\r\n      this.onStateChange?.(prevState, nextState);\r\n    }\r\n  }\r\n\r\n  public reset(): void {\r\n    this.state = 'CLOSED';\r\n    this.failureCount = 0;\r\n    this.lastFailureTime = 0;\r\n  }\r\n}"],"mappings":"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","names":[]}

package/dist/index.mjs

@@ -0,0 +1,373 @@
+// src/engine.ts
+var DEFAULT_RETRYABLE_STATUS_CODES = [408, 429, 500, 502, 503, 504];
+function computeJitterDelay(attempt, baseDelayMs = 500, maxDelayMs = 3e4) {
+  const exponential = baseDelayMs * Math.pow(2, attempt);
+  const ceiling = Math.min(maxDelayMs, exponential);
+  return Math.floor(ceiling * Math.random());
+}
+function getHeader(headers, name) {
+  if (!headers) return null;
+  const target = name.toLowerCase();
+  if (typeof headers.get === "function") {
+    return headers.get(target);
+  }
+  if (Array.isArray(headers)) {
+    for (const [key, value] of headers) {
+      if (key.toLowerCase() === target) {
+        return value;
+      }
+    }
+    return null;
+  }
+  if (typeof headers === "object") {
+    for (const key of Object.keys(headers)) {
+      if (key.toLowerCase() === target) {
+        const val = headers[key];
+        if (Array.isArray(val)) return val[0] ?? null;
+        return typeof val === "string" ? val : String(val);
+      }
+    }
+  }
+  return null;
+}
+function parseDurationToMs(value) {
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  if (/^\d+(\.\d+)?$/.test(trimmed)) {
+    const sec = parseFloat(trimmed);
+    return isNaN(sec) ? null : Math.max(0, Math.floor(sec * 1e3));
+  }
+  const regex = /(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)/gi;
+  let match;
+  let totalMs = 0;
+  let matched = false;
+  while ((match = regex.exec(trimmed)) !== null) {
+    matched = true;
+    const amount = parseFloat(match[1]);
+    const unit = match[2].toLowerCase();
+    switch (unit) {
+      case "ms":
+        totalMs += amount;
+        break;
+      case "s":
+        totalMs += amount * 1e3;
+        break;
+      case "m":
+        totalMs += amount * 60 * 1e3;
+        break;
+      case "h":
+        totalMs += amount * 60 * 60 * 1e3;
+        break;
+      case "d":
+        totalMs += amount * 24 * 60 * 60 * 1e3;
+        break;
+    }
+  }
+  return matched ? Math.max(0, Math.floor(totalMs)) : null;
+}
+function parseRateLimitDelay(headers) {
+  if (!headers) return null;
+  const retryAfterMs = getHeader(headers, "retry-after-ms");
+  if (retryAfterMs) {
+    const parsed = parseFloat(retryAfterMs);
+    if (!isNaN(parsed)) return Math.max(0, Math.floor(parsed));
+  }
+  const retryAfter = getHeader(headers, "retry-after");
+  if (retryAfter) {
+    if (/^\d+(\.\d+)?$/.test(retryAfter.trim())) {
+      const sec = parseFloat(retryAfter.trim());
+      if (!isNaN(sec)) return Math.max(0, Math.floor(sec * 1e3));
+    }
+    const parsedDate = Date.parse(retryAfter);
+    if (!isNaN(parsedDate)) {
+      return Math.max(0, parsedDate - Date.now());
+    }
+  }
+  const candidateKeys = [
+    "x-ratelimit-reset-requests",
+    "x-ratelimit-reset-tokens",
+    "anthropic-ratelimit-requests-reset",
+    "anthropic-ratelimit-tokens-reset",
+    "x-ratelimit-reset-total"
+  ];
+  for (const key of candidateKeys) {
+    const raw = getHeader(headers, key);
+    if (raw) {
+      const ms = parseDurationToMs(raw);
+      if (ms !== null) return ms;
+      const epochSec = parseFloat(raw);
+      if (!isNaN(epochSec) && epochSec > 1e9) {
+        return Math.max(0, Math.floor(epochSec * 1e3 - Date.now()));
+      }
+    }
+  }
+  return null;
+}
+function isTransientNetworkError(error) {
+  if (!(error instanceof Error)) return false;
+  const msg = error.message.toLowerCase();
+  const code = error.code;
+  if (error.name === "TypeError" && msg.includes("fetch failed")) return true;
+  const transientCodes = [
+    "ECONNRESET",
+    "ETIMEDOUT",
+    "ENOTFOUND",
+    "EAI_AGAIN",
+    "ECONNREFUSED",
+    "UND_ERR_CONNECT_TIMEOUT",
+    "UND_ERR_SOCKET"
+  ];
+  if (code && transientCodes.includes(code)) return true;
+  return msg.includes("network error") || msg.includes("socket hang up") || msg.includes("terminated") || msg.includes("econnreset");
+}
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      return reject(signal.reason ?? new DOMException("The operation was aborted.", "AbortError"));
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    function onAbort() {
+      clearTimeout(timer);
+      reject(signal?.reason ?? new DOMException("The operation was aborted.", "AbortError"));
+    }
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+// src/fetch.ts
+async function retryFetch(url, init, options = {}) {
+  const {
+    retries = 3,
+    baseDelayMs = 500,
+    maxDelayMs = 3e4,
+    timeoutMs,
+    retryOnStatus = DEFAULT_RETRYABLE_STATUS_CODES,
+    shouldRetry,
+    onRetry,
+    signal
+  } = options;
+  let attempt = 0;
+  while (true) {
+    if (signal?.aborted) {
+      throw signal.reason ?? new DOMException("The operation was aborted.", "AbortError");
+    }
+    const attemptController = new AbortController();
+    let timeoutId;
+    if (timeoutMs && timeoutMs > 0) {
+      timeoutId = setTimeout(() => {
+        attemptController.abort(new DOMException(`Request timed out after ${timeoutMs}ms`, "TimeoutError"));
+      }, timeoutMs);
+    }
+    const abortHandler = () => attemptController.abort(signal?.reason);
+    signal?.addEventListener("abort", abortHandler, { once: true });
+    try {
+      const response = await fetch(url, {
+        ...init,
+        signal: attemptController.signal
+      });
+      if (timeoutId) clearTimeout(timeoutId);
+      signal?.removeEventListener("abort", abortHandler);
+      const isStatusRetryable = retryOnStatus.includes(response.status);
+      const customRetry = shouldRetry ? shouldRetry(response, attempt) : isStatusRetryable;
+      if (customRetry && attempt < retries) {
+        const headerDelay = parseRateLimitDelay(response.headers);
+        const backoffDelay = computeJitterDelay(attempt, baseDelayMs, maxDelayMs);
+        const chosenDelay = Math.min(maxDelayMs, headerDelay ?? backoffDelay);
+        onRetry?.(response, attempt + 1, chosenDelay);
+        await sleep(chosenDelay, signal);
+        attempt++;
+        continue;
+      }
+      return response;
+    } catch (error) {
+      if (timeoutId) clearTimeout(timeoutId);
+      signal?.removeEventListener("abort", abortHandler);
+      if (signal?.aborted) {
+        throw signal.reason ?? error;
+      }
+      const isTimeout = error instanceof Error && error.name === "TimeoutError";
+      const isNetworkDrop = isTransientNetworkError(error);
+      const customRetry = shouldRetry ? shouldRetry(error, attempt) : isNetworkDrop || isTimeout;
+      if (customRetry && attempt < retries) {
+        const chosenDelay = computeJitterDelay(attempt, baseDelayMs, maxDelayMs);
+        onRetry?.(error, attempt + 1, chosenDelay);
+        await sleep(chosenDelay, signal);
+        attempt++;
+        continue;
+      }
+      throw error;
+    }
+  }
+}
+
+// src/wrap.ts
+async function retry(fn, options = {}) {
+  const {
+    retries = 3,
+    baseDelayMs = 500,
+    maxDelayMs = 3e4,
+    retryOnStatus = DEFAULT_RETRYABLE_STATUS_CODES,
+    shouldRetry,
+    onRetry,
+    signal
+  } = options;
+  let attempt = 0;
+  while (true) {
+    if (signal?.aborted) {
+      throw signal.reason ?? new DOMException("The operation was aborted.", "AbortError");
+    }
+    try {
+      return await fn(attempt);
+    } catch (error) {
+      if (signal?.aborted || error instanceof Error && error.name === "AbortError") {
+        throw error;
+      }
+      if (attempt >= retries) {
+        throw error;
+      }
+      const err = error;
+      const statusCode = err?.status ?? err?.statusCode ?? err?.response?.status;
+      const headers = err?.headers ?? err?.response?.headers;
+      const isStatusRetryable = statusCode !== void 0 && retryOnStatus.includes(statusCode);
+      const isNetworkRetryable = isTransientNetworkError(error);
+      const customRetry = shouldRetry ? shouldRetry(error, attempt) : isStatusRetryable || isNetworkRetryable;
+      if (!customRetry) {
+        throw error;
+      }
+      let chosenDelay;
+      const headerDelay = headers ? parseRateLimitDelay(headers) : null;
+      if (headerDelay !== null) {
+        chosenDelay = Math.min(maxDelayMs, headerDelay);
+      } else {
+        chosenDelay = computeJitterDelay(attempt, baseDelayMs, maxDelayMs);
+      }
+      onRetry?.(error, attempt + 1, chosenDelay);
+      await sleep(chosenDelay, signal);
+      attempt++;
+    }
+  }
+}
+
+// src/stream.ts
+async function* retryStream(streamFactory, options = {}) {
+  const {
+    retries = 3,
+    baseDelayMs = 500,
+    maxDelayMs = 3e4,
+    onRetry,
+    signal
+  } = options;
+  let attempt = 0;
+  while (true) {
+    if (signal?.aborted) {
+      throw signal.reason ?? new DOMException("The operation was aborted.", "AbortError");
+    }
+    try {
+      const stream = await streamFactory(attempt);
+      for await (const chunk of stream) {
+        if (signal?.aborted) {
+          throw signal.reason ?? new DOMException("The operation was aborted.", "AbortError");
+        }
+        yield chunk;
+      }
+      return;
+    } catch (error) {
+      if (signal?.aborted || error instanceof Error && error.name === "AbortError") {
+        throw error;
+      }
+      if (attempt >= retries) {
+        throw error;
+      }
+      const delay = computeJitterDelay(attempt, baseDelayMs, maxDelayMs);
+      onRetry?.(error, attempt + 1, delay);
+      await sleep(delay, signal);
+      attempt++;
+    }
+  }
+}
+
+// src/circuit-breaker.ts
+var CircuitBreakerOpenError = class extends Error {
+  constructor(message = "Circuit breaker is OPEN. Fast-failing requests.") {
+    super(message);
+    this.name = "CircuitBreakerOpenError";
+  }
+};
+var CircuitBreaker = class {
+  state = "CLOSED";
+  failureCount = 0;
+  lastFailureTime = 0;
+  failureThreshold;
+  resetTimeoutMs;
+  onStateChange;
+  constructor(options = {}) {
+    this.failureThreshold = options.failureThreshold ?? 5;
+    this.resetTimeoutMs = options.resetTimeoutMs ?? 3e4;
+    this.onStateChange = options.onStateChange;
+  }
+  getState() {
+    if (this.state === "OPEN") {
+      const elapsed = Date.now() - this.lastFailureTime;
+      if (elapsed >= this.resetTimeoutMs) {
+        this.transitionTo("HALF_OPEN");
+      }
+    }
+    return this.state;
+  }
+  async execute(fn) {
+    const currentState = this.getState();
+    if (currentState === "OPEN") {
+      throw new CircuitBreakerOpenError();
+    }
+    try {
+      const result = await fn();
+      this.recordSuccess();
+      return result;
+    } catch (error) {
+      this.recordFailure();
+      throw error;
+    }
+  }
+  recordSuccess() {
+    if (this.state === "HALF_OPEN") {
+      this.transitionTo("CLOSED");
+    }
+    this.failureCount = 0;
+  }
+  recordFailure() {
+    this.failureCount++;
+    this.lastFailureTime = Date.now();
+    if (this.state === "HALF_OPEN" || this.failureCount >= this.failureThreshold) {
+      this.transitionTo("OPEN");
+    }
+  }
+  transitionTo(nextState) {
+    const prevState = this.state;
+    if (prevState !== nextState) {
+      this.state = nextState;
+      this.onStateChange?.(prevState, nextState);
+    }
+  }
+  reset() {
+    this.state = "CLOSED";
+    this.failureCount = 0;
+    this.lastFailureTime = 0;
+  }
+};
+export {
+  CircuitBreaker,
+  CircuitBreakerOpenError,
+  DEFAULT_RETRYABLE_STATUS_CODES,
+  computeJitterDelay,
+  isTransientNetworkError,
+  parseDurationToMs,
+  parseRateLimitDelay,
+  retry,
+  retryFetch,
+  retryStream,
+  sleep
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/engine.ts","../src/fetch.ts","../src/wrap.ts","../src/stream.ts","../src/circuit-breaker.ts"],"sourcesContent":["import { HeaderSource } from './types.js';\r\n\r\nexport const DEFAULT_RETRYABLE_STATUS_CODES = [408, 429, 500, 502, 503, 504];\r\n\r\n/**\r\n * Calculates exponential backoff with full jitter:\r\n * sleepMs = min(maxDelayMs, baseDelayMs * 2 ** attempt) * Math.random()\r\n */\r\nexport function computeJitterDelay(\r\n  attempt: number,\r\n  baseDelayMs: number = 500,\r\n  maxDelayMs: number = 30000\r\n): number {\r\n  const exponential = baseDelayMs * Math.pow(2, attempt);\r\n  const ceiling = Math.min(maxDelayMs, exponential);\r\n  return Math.floor(ceiling * Math.random());\r\n}\r\n\r\n/**\r\n * Safely extracts a header value case-insensitively across Headers instances, records, or tuples.\r\n */\r\nexport function getHeader(headers: HeaderSource, name: string): string | null {\r\n  if (!headers) return null;\r\n\r\n  const target = name.toLowerCase();\r\n\r\n  if (typeof (headers as Headers).get === 'function') {\r\n    return (headers as Headers).get(target);\r\n  }\r\n\r\n  if (Array.isArray(headers)) {\r\n    for (const [key, value] of headers) {\r\n      if (key.toLowerCase() === target) {\r\n        return value;\r\n      }\r\n    }\r\n    return null;\r\n  }\r\n\r\n  if (typeof headers === 'object') {\r\n    for (const key of Object.keys(headers)) {\r\n      if (key.toLowerCase() === target) {\r\n        const val = (headers as Record<string, unknown>)[key];\r\n        if (Array.isArray(val)) return val[0] ?? null;\r\n        return typeof val === 'string' ? val : String(val);\r\n      }\r\n    }\r\n  }\r\n\r\n  return null;\r\n}\r\n\r\n/**\r\n * Parses duration strings returned by LLM APIs (e.g. \"600ms\", \"10s\", \"2m\", \"1m30s\", \"1.5\").\r\n */\r\nexport function parseDurationToMs(value: string): number | null {\r\n  const trimmed = value.trim();\r\n  if (!trimmed) return null;\r\n\r\n  if (/^\\d+(\\.\\d+)?$/.test(trimmed)) {\r\n    const sec = parseFloat(trimmed);\r\n    return isNaN(sec) ? null : Math.max(0, Math.floor(sec * 1000));\r\n  }\r\n\r\n  const regex = /(\\d+(?:\\.\\d+)?)\\s*(ms|s|m|h|d)/gi;\r\n  let match: RegExpExecArray | null;\r\n  let totalMs = 0;\r\n  let matched = false;\r\n\r\n  while ((match = regex.exec(trimmed)) !== null) {\r\n    matched = true;\r\n    const amount = parseFloat(match[1]);\r\n    const unit = match[2].toLowerCase();\r\n\r\n    switch (unit) {\r\n      case 'ms':\r\n        totalMs += amount;\r\n        break;\r\n      case 's':\r\n        totalMs += amount * 1000;\r\n        break;\r\n      case 'm':\r\n        totalMs += amount * 60 * 1000;\r\n        break;\r\n      case 'h':\r\n        totalMs += amount * 60 * 60 * 1000;\r\n        break;\r\n      case 'd':\r\n        totalMs += amount * 24 * 60 * 60 * 1000;\r\n        break;\r\n    }\r\n  }\r\n\r\n  return matched ? Math.max(0, Math.floor(totalMs)) : null;\r\n}\r\n\r\n/**\r\n * Exhaustively checks provider headers across:\r\n * - RFC 7231 / RFC 6585 standard `retry-after`\r\n * - OpenAI: `x-ratelimit-reset-requests`, `x-ratelimit-reset-tokens`\r\n * - Anthropic: `anthropic-ratelimit-requests-reset`, `anthropic-ratelimit-tokens-reset`\r\n * - Groq / DeepSeek / Mistral: `x-ratelimit-reset-total`, `retry-after-ms`\r\n */\r\nexport function parseRateLimitDelay(headers: HeaderSource): number | null {\r\n  if (!headers) return null;\r\n\r\n  // 1. Direct milliseconds header (Groq, custom proxies)\r\n  const retryAfterMs = getHeader(headers, 'retry-after-ms');\r\n  if (retryAfterMs) {\r\n    const parsed = parseFloat(retryAfterMs);\r\n    if (!isNaN(parsed)) return Math.max(0, Math.floor(parsed));\r\n  }\r\n\r\n  // 2. Standard Retry-After (seconds or RFC 1123 HTTP Date)\r\n  const retryAfter = getHeader(headers, 'retry-after');\r\n  if (retryAfter) {\r\n    if (/^\\d+(\\.\\d+)?$/.test(retryAfter.trim())) {\r\n      const sec = parseFloat(retryAfter.trim());\r\n      if (!isNaN(sec)) return Math.max(0, Math.floor(sec * 1000));\r\n    }\r\n\r\n    const parsedDate = Date.parse(retryAfter);\r\n    if (!isNaN(parsedDate)) {\r\n      return Math.max(0, parsedDate - Date.now());\r\n    }\r\n  }\r\n\r\n  // 3. Provider-specific reset headers\r\n  const candidateKeys = [\r\n    'x-ratelimit-reset-requests',\r\n    'x-ratelimit-reset-tokens',\r\n    'anthropic-ratelimit-requests-reset',\r\n    'anthropic-ratelimit-tokens-reset',\r\n    'x-ratelimit-reset-total',\r\n  ];\r\n\r\n  for (const key of candidateKeys) {\r\n    const raw = getHeader(headers, key);\r\n    if (raw) {\r\n      const ms = parseDurationToMs(raw);\r\n      if (ms !== null) return ms;\r\n\r\n      // Handle epoch timestamp formats\r\n      const epochSec = parseFloat(raw);\r\n      if (!isNaN(epochSec) && epochSec > 1000000000) {\r\n        return Math.max(0, Math.floor(epochSec * 1000 - Date.now()));\r\n      }\r\n    }\r\n  }\r\n\r\n  return null;\r\n}\r\n\r\n/**\r\n * Detects transient network drop errors across Node, Bun, Deno, and browsers.\r\n */\r\nexport function isTransientNetworkError(error: unknown): boolean {\r\n  if (!(error instanceof Error)) return false;\r\n\r\n  const msg = error.message.toLowerCase();\r\n  const code = (error as { code?: string }).code;\r\n\r\n  if (error.name === 'TypeError' && msg.includes('fetch failed')) return true;\r\n\r\n  const transientCodes = [\r\n    'ECONNRESET',\r\n    'ETIMEDOUT',\r\n    'ENOTFOUND',\r\n    'EAI_AGAIN',\r\n    'ECONNREFUSED',\r\n    'UND_ERR_CONNECT_TIMEOUT',\r\n    'UND_ERR_SOCKET',\r\n  ];\r\n  if (code && transientCodes.includes(code)) return true;\r\n\r\n  return (\r\n    msg.includes('network error') ||\r\n    msg.includes('socket hang up') ||\r\n    msg.includes('terminated') ||\r\n    msg.includes('econnreset')\r\n  );\r\n}\r\n\r\n/**\r\n * Promisified sleep that respects AbortSignal cancellation.\r\n */\r\nexport function sleep(ms: number, signal?: AbortSignal): Promise<void> {\r\n  return new Promise((resolve, reject) => {\r\n    if (signal?.aborted) {\r\n      return reject(signal.reason ?? new DOMException('The operation was aborted.', 'AbortError'));\r\n    }\r\n\r\n    const timer = setTimeout(() => {\r\n      signal?.removeEventListener('abort', onAbort);\r\n      resolve();\r\n    }, ms);\r\n\r\n    function onAbort() {\r\n      clearTimeout(timer);\r\n      reject(signal?.reason ?? new DOMException('The operation was aborted.', 'AbortError'));\r\n    }\r\n\r\n    signal?.addEventListener('abort', onAbort, { once: true });\r\n  });\r\n}","import {\r\n  computeJitterDelay,\r\n  DEFAULT_RETRYABLE_STATUS_CODES,\r\n  isTransientNetworkError,\r\n  parseRateLimitDelay,\r\n  sleep,\r\n} from './engine.js';\r\nimport { RetryOptions } from './types.js';\r\n\r\nexport async function retryFetch(\r\n  url: string | URL | Request,\r\n  init?: RequestInit,\r\n  options: RetryOptions = {}\r\n): Promise<Response> {\r\n  const {\r\n    retries = 3,\r\n    baseDelayMs = 500,\r\n    maxDelayMs = 30000,\r\n    timeoutMs,\r\n    retryOnStatus = DEFAULT_RETRYABLE_STATUS_CODES,\r\n    shouldRetry,\r\n    onRetry,\r\n    signal,\r\n  } = options;\r\n\r\n  let attempt = 0;\r\n\r\n  while (true) {\r\n    if (signal?.aborted) {\r\n      throw signal.reason ?? new DOMException('The operation was aborted.', 'AbortError');\r\n    }\r\n\r\n    // Set up per-attempt timeout controller\r\n    const attemptController = new AbortController();\r\n    let timeoutId: ReturnType<typeof setTimeout> | undefined;\r\n\r\n    if (timeoutMs && timeoutMs > 0) {\r\n      timeoutId = setTimeout(() => {\r\n        attemptController.abort(new DOMException(`Request timed out after ${timeoutMs}ms`, 'TimeoutError'));\r\n      }, timeoutMs);\r\n    }\r\n\r\n    const abortHandler = () => attemptController.abort(signal?.reason);\r\n    signal?.addEventListener('abort', abortHandler, { once: true });\r\n\r\n    try {\r\n      const response = await fetch(url, {\r\n        ...init,\r\n        signal: attemptController.signal,\r\n      });\r\n\r\n      if (timeoutId) clearTimeout(timeoutId);\r\n      signal?.removeEventListener('abort', abortHandler);\r\n\r\n      const isStatusRetryable = retryOnStatus.includes(response.status);\r\n      const customRetry = shouldRetry ? shouldRetry(response, attempt) : isStatusRetryable;\r\n\r\n      if (customRetry && attempt < retries) {\r\n        const headerDelay = parseRateLimitDelay(response.headers);\r\n        const backoffDelay = computeJitterDelay(attempt, baseDelayMs, maxDelayMs);\r\n        const chosenDelay = Math.min(maxDelayMs, headerDelay ?? backoffDelay);\r\n\r\n        onRetry?.(response, attempt + 1, chosenDelay);\r\n        await sleep(chosenDelay, signal);\r\n        attempt++;\r\n        continue;\r\n      }\r\n\r\n      return response;\r\n    } catch (error) {\r\n      if (timeoutId) clearTimeout(timeoutId);\r\n      signal?.removeEventListener('abort', abortHandler);\r\n\r\n      // Do not retry intentional outer aborts\r\n      if (signal?.aborted) {\r\n        throw signal.reason ?? error;\r\n      }\r\n\r\n      const isTimeout = error instanceof Error && error.name === 'TimeoutError';\r\n      const isNetworkDrop = isTransientNetworkError(error);\r\n      const customRetry = shouldRetry ? shouldRetry(error, attempt) : (isNetworkDrop || isTimeout);\r\n\r\n      if (customRetry && attempt < retries) {\r\n        const chosenDelay = computeJitterDelay(attempt, baseDelayMs, maxDelayMs);\r\n        onRetry?.(error, attempt + 1, chosenDelay);\r\n        await sleep(chosenDelay, signal);\r\n        attempt++;\r\n        continue;\r\n      }\r\n\r\n      throw error;\r\n    }\r\n  }\r\n}","import {\r\n  computeJitterDelay,\r\n  DEFAULT_RETRYABLE_STATUS_CODES,\r\n  isTransientNetworkError,\r\n  parseRateLimitDelay,\r\n  sleep,\r\n} from './engine.js';\r\nimport { HeaderSource, RetryOptions } from './types.js';\r\n\r\ninterface ErrorWithStatus extends Error {\r\n  status?: number;\r\n  statusCode?: number;\r\n  headers?: HeaderSource;\r\n  response?: {\r\n    status?: number;\r\n    headers?: HeaderSource;\r\n  };\r\n}\r\n\r\nexport async function retry<T>(\r\n  fn: (attempt: number) => Promise<T>,\r\n  options: RetryOptions = {}\r\n): Promise<T> {\r\n  const {\r\n    retries = 3,\r\n    baseDelayMs = 500,\r\n    maxDelayMs = 30000,\r\n    retryOnStatus = DEFAULT_RETRYABLE_STATUS_CODES,\r\n    shouldRetry,\r\n    onRetry,\r\n    signal,\r\n  } = options;\r\n\r\n  let attempt = 0;\r\n\r\n  while (true) {\r\n    if (signal?.aborted) {\r\n      throw signal.reason ?? new DOMException('The operation was aborted.', 'AbortError');\r\n    }\r\n\r\n    try {\r\n      return await fn(attempt);\r\n    } catch (error) {\r\n      if (signal?.aborted || (error instanceof Error && error.name === 'AbortError')) {\r\n        throw error;\r\n      }\r\n\r\n      if (attempt >= retries) {\r\n        throw error;\r\n      }\r\n\r\n      const err = error as ErrorWithStatus;\r\n      const statusCode = err?.status ?? err?.statusCode ?? err?.response?.status;\r\n      const headers = err?.headers ?? err?.response?.headers;\r\n\r\n      const isStatusRetryable = statusCode !== undefined && retryOnStatus.includes(statusCode);\r\n      const isNetworkRetryable = isTransientNetworkError(error);\r\n      const customRetry = shouldRetry\r\n        ? shouldRetry(error, attempt)\r\n        : (isStatusRetryable || isNetworkRetryable);\r\n\r\n      if (!customRetry) {\r\n        throw error;\r\n      }\r\n\r\n      let chosenDelay: number;\r\n      const headerDelay = headers ? parseRateLimitDelay(headers) : null;\r\n\r\n      if (headerDelay !== null) {\r\n        chosenDelay = Math.min(maxDelayMs, headerDelay);\r\n      } else {\r\n        chosenDelay = computeJitterDelay(attempt, baseDelayMs, maxDelayMs);\r\n      }\r\n\r\n      onRetry?.(error, attempt + 1, chosenDelay);\r\n      await sleep(chosenDelay, signal);\r\n      attempt++;\r\n    }\r\n  }\r\n}","import { computeJitterDelay, sleep } from './engine.js';\r\nimport { RetryOptions } from './types.js';\r\n\r\n/**\r\n * Resilient wrapper for Server-Sent Events / LLM chunk streams.\r\n * If the streaming connection drops mid-generation, it retries and resumes.\r\n */\r\nexport async function* retryStream<T>(\r\n  streamFactory: (attempt: number) => Promise<AsyncIterable<T>>,\r\n  options: RetryOptions = {}\r\n): AsyncGenerator<T, void, unknown> {\r\n  const {\r\n    retries = 3,\r\n    baseDelayMs = 500,\r\n    maxDelayMs = 30000,\r\n    onRetry,\r\n    signal,\r\n  } = options;\r\n\r\n  let attempt = 0;\r\n\r\n  while (true) {\r\n    if (signal?.aborted) {\r\n      throw signal.reason ?? new DOMException('The operation was aborted.', 'AbortError');\r\n    }\r\n\r\n    try {\r\n      const stream = await streamFactory(attempt);\r\n      for await (const chunk of stream) {\r\n        if (signal?.aborted) {\r\n          throw signal.reason ?? new DOMException('The operation was aborted.', 'AbortError');\r\n        }\r\n        yield chunk;\r\n      }\r\n      return;\r\n    } catch (error) {\r\n      if (signal?.aborted || (error instanceof Error && error.name === 'AbortError')) {\r\n        throw error;\r\n      }\r\n\r\n      if (attempt >= retries) {\r\n        throw error;\r\n      }\r\n\r\n      const delay = computeJitterDelay(attempt, baseDelayMs, maxDelayMs);\r\n      onRetry?.(error, attempt + 1, delay);\r\n      await sleep(delay, signal);\r\n      attempt++;\r\n    }\r\n  }\r\n}","import { CircuitBreakerOptions, CircuitState } from './types.js';\r\n\r\nexport class CircuitBreakerOpenError extends Error {\r\n  constructor(message: string = 'Circuit breaker is OPEN. Fast-failing requests.') {\r\n    super(message);\r\n    this.name = 'CircuitBreakerOpenError';\r\n  }\r\n}\r\n\r\n/**\r\n * Zero-dependency Circuit Breaker implementation to stop cascading failure\r\n * cascades when downstream LLM APIs experience total outages.\r\n */\r\nexport class CircuitBreaker {\r\n  private state: CircuitState = 'CLOSED';\r\n  private failureCount: number = 0;\r\n  private lastFailureTime: number = 0;\r\n  private readonly failureThreshold: number;\r\n  private readonly resetTimeoutMs: number;\r\n  private readonly onStateChange?: (from: CircuitState, to: CircuitState) => void;\r\n\r\n  constructor(options: CircuitBreakerOptions = {}) {\r\n    this.failureThreshold = options.failureThreshold ?? 5;\r\n    this.resetTimeoutMs = options.resetTimeoutMs ?? 30000;\r\n    this.onStateChange = options.onStateChange;\r\n  }\r\n\r\n  public getState(): CircuitState {\r\n    if (this.state === 'OPEN') {\r\n      const elapsed = Date.now() - this.lastFailureTime;\r\n      if (elapsed >= this.resetTimeoutMs) {\r\n        this.transitionTo('HALF_OPEN');\r\n      }\r\n    }\r\n    return this.state;\r\n  }\r\n\r\n  public async execute<T>(fn: () => Promise<T>): Promise<T> {\r\n    const currentState = this.getState();\r\n\r\n    if (currentState === 'OPEN') {\r\n      throw new CircuitBreakerOpenError();\r\n    }\r\n\r\n    try {\r\n      const result = await fn();\r\n      this.recordSuccess();\r\n      return result;\r\n    } catch (error) {\r\n      this.recordFailure();\r\n      throw error;\r\n    }\r\n  }\r\n\r\n  private recordSuccess(): void {\r\n    if (this.state === 'HALF_OPEN') {\r\n      this.transitionTo('CLOSED');\r\n    }\r\n    this.failureCount = 0;\r\n  }\r\n\r\n  private recordFailure(): void {\r\n    this.failureCount++;\r\n    this.lastFailureTime = Date.now();\r\n\r\n    if (this.state === 'HALF_OPEN' || this.failureCount >= this.failureThreshold) {\r\n      this.transitionTo('OPEN');\r\n    }\r\n  }\r\n\r\n  private transitionTo(nextState: CircuitState): void {\r\n    const prevState = this.state;\r\n    if (prevState !== nextState) {\r\n      this.state = nextState;\r\n      this.onStateChange?.(prevState, nextState);\r\n    }\r\n  }\r\n\r\n  public reset(): void {\r\n    this.state = 'CLOSED';\r\n    this.failureCount = 0;\r\n    this.lastFailureTime = 0;\r\n  }\r\n}"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,53 @@
-{
-  "name": "@rohan9024/retrykit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+{
+  "name": "@rohan9024/retrykit",
+  "version": "0.2.0",
+  "description": "The ultimate zero-dependency, header-aware retry engine and circuit breaker for LLM APIs (OpenAI, Anthropic, DeepSeek, Groq).",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "llms.txt",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run test && npm run build"
+  },
+  "keywords": [
+    "retry",
+    "llm",
+    "openai",
+    "anthropic",
+    "deepseek",
+    "groq",
+    "fetch",
+    "circuit-breaker",
+    "streaming",
+    "rate-limit",
+    "backoff",
+    "jitter"
+  ],
+  "author": "rohan9024",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
 }