@rohan9024/retrykit 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,97 @@
-# 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 ⚡
+
+> Zero-dependency, header-aware retry wrapper tailored for LLM APIs and fetch.
+
+Automatically handles `429 Too Many Requests` by parsing rate-limit headers from OpenAI, Anthropic, and Groq before falling back to exponential backoff with full jitter.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @rohan9024/retrykit
+```
+
+---
+
+## 🚀 Usage
+
+### 1. Drop-in Replacement for `fetch` (`retryFetch`)
+
+`retryFetch` works exactly like standard `fetch`, but automatically handles retries and honors rate-limit headers:
+
+```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: 3,
+  onRetry: (error, attempt, delayMs) => {
+    console.warn(`Retry attempt #${attempt} after ${delayMs}ms delay...`);
+  },
+});
+
+const data = await response.json();
+```
+
+---
+
+### 2. Wrap Official SDKs (`retry`)
+
+Wrap calls from the official OpenAI, Anthropic, or Mistral client libraries:
+
+```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 haiku' }],
+  }),
+  {
+    retries: 4,
+    baseDelayMs: 500,
+  }
+);
+```
+
+---
+
+## 🧠 Provider Header Awareness
+
+`retrykit` inspects and obeys the following provider headers before falling back to exponential backoff:
+
+- `retry-after` (RFC 1123 HTTP Dates or relative seconds)
+- `x-ratelimit-reset-requests` (OpenAI format, e.g., `"15s"`, `"600ms"`)
+- `x-ratelimit-reset-tokens` (Anthropic format)
+
+---
+
+## ⚙️ Options Reference
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `retries` | `number` | `3` | Max retry attempts before failing |
+| `baseDelayMs` | `number` | `500` | Starting backoff delay in ms |
+| `maxDelayMs` | `number` | `30000` | Ceiling delay cap in ms |
+| `retryOnStatus`| `number[]` | `[408, 429, 500, 502, 503, 504]` | HTTP status codes that trigger a retry |
+| `onRetry` | `(err, attempt, delay) => void` | `undefined` | Hook called before every sleep |
+| `signal` | `AbortSignal` | `undefined` | Immediate cancellation controller |
+
+---
+
+## 📄 License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,47 @@
+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;
+    /** HTTP status codes that trigger a retry. Default: [408, 429, 500, 502, 503, 504] */
+    retryOnStatus?: number[];
+    /** Optional callback fired on every retry attempt before sleep */
+    onRetry?: (error: unknown, attempt: number, delayMs: number) => void;
+    /** AbortSignal for immediate cancellation */
+    signal?: AbortSignal;
+}
+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>;
+
+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;
+/**
+ * Inspects rate-limiting headers and extracts sleep delay in milliseconds:
+ * - retry-after (seconds or HTTP date)
+ * - x-ratelimit-reset-requests (OpenAI format)
+ * - x-ratelimit-reset-tokens (Anthropic format)
+ */
+declare function parseRateLimitDelay(headers: HeaderSource): number | null;
+/**
+ * Detects transient network drop errors.
+ */
+declare function isTransientNetworkError(error: unknown): boolean;
+/**
+ * Sleep helper respecting AbortSignal cancellation.
+ */
+declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+
+export { DEFAULT_RETRYABLE_STATUS_CODES, type HeaderSource, type RetryOptions, computeJitterDelay, isTransientNetworkError, parseDurationToMs, parseRateLimitDelay, retry, retryFetch, sleep };

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+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;
+    /** HTTP status codes that trigger a retry. Default: [408, 429, 500, 502, 503, 504] */
+    retryOnStatus?: number[];
+    /** Optional callback fired on every retry attempt before sleep */
+    onRetry?: (error: unknown, attempt: number, delayMs: number) => void;
+    /** AbortSignal for immediate cancellation */
+    signal?: AbortSignal;
+}
+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>;
+
+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;
+/**
+ * Inspects rate-limiting headers and extracts sleep delay in milliseconds:
+ * - retry-after (seconds or HTTP date)
+ * - x-ratelimit-reset-requests (OpenAI format)
+ * - x-ratelimit-reset-tokens (Anthropic format)
+ */
+declare function parseRateLimitDelay(headers: HeaderSource): number | null;
+/**
+ * Detects transient network drop errors.
+ */
+declare function isTransientNetworkError(error: unknown): boolean;
+/**
+ * Sleep helper respecting AbortSignal cancellation.
+ */
+declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+
+export { DEFAULT_RETRYABLE_STATUS_CODES, type HeaderSource, type RetryOptions, computeJitterDelay, isTransientNetworkError, parseDurationToMs, parseRateLimitDelay, retry, retryFetch, sleep };

package/dist/index.js

@@ -0,0 +1,254 @@
+"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, {
+  DEFAULT_RETRYABLE_STATUS_CODES: () => DEFAULT_RETRYABLE_STATUS_CODES,
+  computeJitterDelay: () => computeJitterDelay,
+  isTransientNetworkError: () => isTransientNetworkError,
+  parseDurationToMs: () => parseDurationToMs,
+  parseRateLimitDelay: () => parseRateLimitDelay,
+  retry: () => retry,
+  retryFetch: () => retryFetch,
+  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 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 openaiReset = getHeader(headers, "x-ratelimit-reset-requests");
+  if (openaiReset) {
+    const durationMs = parseDurationToMs(openaiReset);
+    if (durationMs !== null) return durationMs;
+  }
+  const anthropicReset = getHeader(headers, "x-ratelimit-reset-tokens");
+  if (anthropicReset) {
+    const durationMs = parseDurationToMs(anthropicReset);
+    if (durationMs !== null) return durationMs;
+  }
+  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"];
+  if (code && transientCodes.includes(code)) return true;
+  return msg.includes("network error") || msg.includes("socket hang up") || msg.includes("timeout");
+}
+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,
+    retryOnStatus = DEFAULT_RETRYABLE_STATUS_CODES,
+    onRetry,
+    signal
+  } = options;
+  let attempt = 0;
+  while (true) {
+    if (signal?.aborted) {
+      throw signal.reason ?? new DOMException("The operation was aborted.", "AbortError");
+    }
+    try {
+      const response = await fetch(url, {
+        ...init,
+        signal: signal ?? init?.signal
+      });
+      if (retryOnStatus.includes(response.status) && 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 (signal?.aborted || error instanceof Error && error.name === "AbortError") {
+        throw error;
+      }
+      if (isTransientNetworkError(error) && 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,
+    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);
+      if (!isStatusRetryable && !isNetworkRetryable) {
+        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++;
+    }
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_RETRYABLE_STATUS_CODES,
+  computeJitterDelay,
+  isTransientNetworkError,
+  parseDurationToMs,
+  parseRateLimitDelay,
+  retry,
+  retryFetch,
+  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"],"sourcesContent":["export { retryFetch } from './fetch.js';\r\nexport { retry } from './wrap.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 { RetryOptions, HeaderSource } 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, 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  // Native Web API Headers\r\n  if (typeof (headers as Headers).get === 'function') {\r\n    return (headers as Headers).get(target);\r\n  }\r\n\r\n  // Array of tuples\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  // Plain object\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  // Pure numeric string represents seconds\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  // Units match\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 * Inspects rate-limiting headers and extracts sleep delay in milliseconds:\r\n * - retry-after (seconds or HTTP date)\r\n * - x-ratelimit-reset-requests (OpenAI format)\r\n * - x-ratelimit-reset-tokens (Anthropic format)\r\n */\r\nexport function parseRateLimitDelay(headers: HeaderSource): number | null {\r\n  if (!headers) return null;\r\n\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  const openaiReset = getHeader(headers, 'x-ratelimit-reset-requests');\r\n  if (openaiReset) {\r\n    const durationMs = parseDurationToMs(openaiReset);\r\n    if (durationMs !== null) return durationMs;\r\n  }\r\n\r\n  const anthropicReset = getHeader(headers, 'x-ratelimit-reset-tokens');\r\n  if (anthropicReset) {\r\n    const durationMs = parseDurationToMs(anthropicReset);\r\n    if (durationMs !== null) return durationMs;\r\n  }\r\n\r\n  return null;\r\n}\r\n\r\n/**\r\n * Detects transient network drop errors.\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 = ['ECONNRESET', 'ETIMEDOUT', 'ENOTFOUND', 'EAI_AGAIN', 'ECONNREFUSED'];\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('timeout')\r\n  );\r\n}\r\n\r\n/**\r\n * Sleep helper respecting 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    retryOnStatus = DEFAULT_RETRYABLE_STATUS_CODES,\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 response = await fetch(url, {\r\n        ...init,\r\n        signal: signal ?? init?.signal,\r\n      });\r\n\r\n      if (retryOnStatus.includes(response.status) && 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 (signal?.aborted || (error instanceof Error && error.name === 'AbortError')) {\r\n        throw error;\r\n      }\r\n\r\n      if (isTransientNetworkError(error) && 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    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\r\n      if (!isStatusRetryable && !isNetworkRetryable) {\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}"],"mappings":"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","names":[]}

package/dist/index.mjs

@@ -0,0 +1,220 @@
+// 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 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 openaiReset = getHeader(headers, "x-ratelimit-reset-requests");
+  if (openaiReset) {
+    const durationMs = parseDurationToMs(openaiReset);
+    if (durationMs !== null) return durationMs;
+  }
+  const anthropicReset = getHeader(headers, "x-ratelimit-reset-tokens");
+  if (anthropicReset) {
+    const durationMs = parseDurationToMs(anthropicReset);
+    if (durationMs !== null) return durationMs;
+  }
+  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"];
+  if (code && transientCodes.includes(code)) return true;
+  return msg.includes("network error") || msg.includes("socket hang up") || msg.includes("timeout");
+}
+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,
+    retryOnStatus = DEFAULT_RETRYABLE_STATUS_CODES,
+    onRetry,
+    signal
+  } = options;
+  let attempt = 0;
+  while (true) {
+    if (signal?.aborted) {
+      throw signal.reason ?? new DOMException("The operation was aborted.", "AbortError");
+    }
+    try {
+      const response = await fetch(url, {
+        ...init,
+        signal: signal ?? init?.signal
+      });
+      if (retryOnStatus.includes(response.status) && 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 (signal?.aborted || error instanceof Error && error.name === "AbortError") {
+        throw error;
+      }
+      if (isTransientNetworkError(error) && 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,
+    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);
+      if (!isStatusRetryable && !isNetworkRetryable) {
+        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++;
+    }
+  }
+}
+export {
+  DEFAULT_RETRYABLE_STATUS_CODES,
+  computeJitterDelay,
+  isTransientNetworkError,
+  parseDurationToMs,
+  parseRateLimitDelay,
+  retry,
+  retryFetch,
+  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"],"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, 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  // Native Web API Headers\r\n  if (typeof (headers as Headers).get === 'function') {\r\n    return (headers as Headers).get(target);\r\n  }\r\n\r\n  // Array of tuples\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  // Plain object\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  // Pure numeric string represents seconds\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  // Units match\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 * Inspects rate-limiting headers and extracts sleep delay in milliseconds:\r\n * - retry-after (seconds or HTTP date)\r\n * - x-ratelimit-reset-requests (OpenAI format)\r\n * - x-ratelimit-reset-tokens (Anthropic format)\r\n */\r\nexport function parseRateLimitDelay(headers: HeaderSource): number | null {\r\n  if (!headers) return null;\r\n\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  const openaiReset = getHeader(headers, 'x-ratelimit-reset-requests');\r\n  if (openaiReset) {\r\n    const durationMs = parseDurationToMs(openaiReset);\r\n    if (durationMs !== null) return durationMs;\r\n  }\r\n\r\n  const anthropicReset = getHeader(headers, 'x-ratelimit-reset-tokens');\r\n  if (anthropicReset) {\r\n    const durationMs = parseDurationToMs(anthropicReset);\r\n    if (durationMs !== null) return durationMs;\r\n  }\r\n\r\n  return null;\r\n}\r\n\r\n/**\r\n * Detects transient network drop errors.\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 = ['ECONNRESET', 'ETIMEDOUT', 'ENOTFOUND', 'EAI_AGAIN', 'ECONNREFUSED'];\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('timeout')\r\n  );\r\n}\r\n\r\n/**\r\n * Sleep helper respecting 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    retryOnStatus = DEFAULT_RETRYABLE_STATUS_CODES,\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 response = await fetch(url, {\r\n        ...init,\r\n        signal: signal ?? init?.signal,\r\n      });\r\n\r\n      if (retryOnStatus.includes(response.status) && 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 (signal?.aborted || (error instanceof Error && error.name === 'AbortError')) {\r\n        throw error;\r\n      }\r\n\r\n      if (isTransientNetworkError(error) && 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    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\r\n      if (!isStatusRetryable && !isNetworkRetryable) {\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}"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,54 @@
-{
-  "name": "@rohan9024/retrykit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@rohan9024/retrykit",
+  "version": "0.1.0",
+  "description": "Zero-dependency, header-aware network retry library tailored for LLM APIs and fetch.",
+  "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",
+    "fetch",
+    "llm",
+    "openai",
+    "anthropic",
+    "backoff",
+    "jitter",
+    "exponential-backoff",
+    "rate-limit",
+    "retry-after"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^2.1.9"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "directories": {
+    "test": "test"
+  }
+}