llm-retry-kit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 llm-retry contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,152 @@
+# llm-retry-kit
+
+Smart retry wrapper for LLM APIs. It handles transient failures, rate limits,
+fallback calls, exponential backoff, and simple token-cost tracking.
+
+## Install
+
+```bash
+npm install llm-retry-kit
+```
+
+## Quick Start
+
+```ts
+import { llmRetry } from 'llm-retry-kit'
+import OpenAI from 'openai'
+
+const openai = new OpenAI()
+
+const result = await llmRetry({
+  fn: async () => {
+    const response = await openai.chat.completions.create({
+      model: 'gpt-4o-mini',
+      messages: [{ role: 'user', content: 'Hello!' }],
+    })
+
+    return {
+      data: response.choices[0]?.message.content ?? '',
+      usage: response.usage
+        ? {
+            promptTokens: response.usage.prompt_tokens,
+            completionTokens: response.usage.completion_tokens,
+            totalTokens: response.usage.total_tokens,
+          }
+        : undefined,
+    }
+  },
+})
+
+console.log(result.data)
+console.log(result.attempts)
+console.log(result.totalCostUSD)
+```
+
+## Fallback Example
+
+```ts
+import { llmRetry } from 'llm-retry-kit'
+
+const result = await llmRetry({
+  fn: async () => callPrimaryModel(),
+  fallback: async () => callFallbackModel(),
+  maxRetries: 3,
+  initialDelayMs: 1000,
+  maxDelayMs: 30000,
+})
+
+if (result.usedFallback) {
+  console.log('Fallback model was used')
+}
+```
+
+## Budget Tracking
+
+`llm-retry-kit` tracks cost from the `usage.totalTokens` value returned by your
+function. It cannot know the exact cost of a future LLM call before that call
+finishes, so the budget guard is best used to stop later retries or fallback
+calls after tracked usage reaches the configured cap.
+
+```ts
+const result = await llmRetry({
+  fn: myLLMCall,
+  maxCostUSD: 0.5,
+  costPer1kTokens: 0.002,
+  onBudgetExceeded: (spent, limit) => {
+    console.warn(`Budget exceeded: $${spent.toFixed(4)} / $${limit}`)
+  },
+})
+```
+
+## Retry Logging
+
+```ts
+const result = await llmRetry({
+  fn: myLLMCall,
+  maxRetries: 4,
+  initialDelayMs: 1000,
+  maxDelayMs: 60000,
+  onRetry: (attempt, error, delayMs) => {
+    console.log(`Attempt ${attempt} failed: ${error.message}`)
+    console.log(`Waiting ${(delayMs / 1000).toFixed(1)}s before retrying`)
+  },
+})
+```
+
+## API
+
+### `llmRetry(options)`
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `fn` | `() => Promise<LLMResponse<T>>` | required | Primary async LLM call. |
+| `fallback` | `() => Promise<LLMResponse<T>>` | optional | Backup async LLM call. |
+| `maxRetries` | `number` | `3` | Number of retries after the first attempt. |
+| `maxCostUSD` | `number` | optional | Maximum tracked cost in USD. |
+| `costPer1kTokens` | `number` | `0.002` | Estimated cost per 1,000 tokens. |
+| `initialDelayMs` | `number` | `1000` | Initial retry delay. |
+| `maxDelayMs` | `number` | `30000` | Maximum retry delay. |
+| `onRetry` | `(attempt, error, delayMs) => void` | optional | Called before each retry wait. |
+| `onBudgetExceeded` | `(spentUSD, limitUSD) => void` | optional | Called when tracked budget is exhausted. |
+
+### `LLMResponse<T>`
+
+```ts
+{
+  data: T
+  usage?: {
+    promptTokens: number
+    completionTokens: number
+    totalTokens: number
+  }
+}
+```
+
+### `RetryResult<T>`
+
+```ts
+{
+  data: T
+  attempts: number
+  usedFallback: boolean
+  totalCostUSD: number
+  totalTokens: number
+}
+```
+
+## Retryable Errors
+
+The package retries common transient failures:
+
+- HTTP `429`
+- HTTP `5xx`
+- timeout errors
+- network connection errors
+- overloaded server errors
+
+Authentication errors, invalid requests, and other non-transient failures are
+not retried.
+
+## License
+
+MIT

package/dist/backoff.d.ts

@@ -0,0 +1,5 @@
+export declare function calculateBackoff(attempt: number, initialDelayMs: number, maxDelayMs: number): number;
+export declare function sleep(ms: number): Promise<void>;
+export declare function isRetryableError(error: unknown): boolean;
+export declare function extractRetryAfter(error: unknown): number | null;
+//# sourceMappingURL=backoff.d.ts.map

package/dist/backoff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backoff.d.ts","sourceRoot":"","sources":["../src/backoff.ts"],"names":[],"mappings":"AAAA,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,MAAM,GACjB,MAAM,CAMR;AAED,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAiDxD;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAyB/D"}

package/dist/backoff.js

@@ -0,0 +1,96 @@
+export function calculateBackoff(attempt, initialDelayMs, maxDelayMs) {
+    const exponential = initialDelayMs * Math.pow(2, attempt);
+    const jitter = exponential * 0.25 * (Math.random() * 2 - 1);
+    const delay = exponential + jitter;
+    return Math.min(Math.max(delay, initialDelayMs), maxDelayMs);
+}
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export function isRetryableError(error) {
+    if (!(error instanceof Error))
+        return false;
+    const err = error;
+    const status = toNumber(err.status ?? err.statusCode);
+    if (status === 429 || (status !== null && status >= 500 && status <= 599)) {
+        return true;
+    }
+    const code = typeof err.code === 'string' ? err.code.toLowerCase() : '';
+    if ([
+        'etimedout',
+        'econnreset',
+        'econnrefused',
+        'enotfound',
+        'eai_again',
+        'rate_limit_exceeded',
+    ].includes(code)) {
+        return true;
+    }
+    const message = error.message.toLowerCase();
+    const retryablePatterns = [
+        'rate limit',
+        'rate_limit',
+        'too many requests',
+        '429',
+        'server error',
+        '500',
+        '502',
+        '503',
+        '504',
+        'timeout',
+        'timed out',
+        'econnreset',
+        'econnrefused',
+        'network',
+        'socket',
+        'overloaded',
+    ];
+    return retryablePatterns.some((pattern) => message.includes(pattern));
+}
+export function extractRetryAfter(error) {
+    if (!error || typeof error !== 'object')
+        return null;
+    const err = error;
+    const retryAfter = toNumber(err['retryAfter'] ?? err['retry-after']);
+    if (retryAfter !== null) {
+        return retryAfter * 1000;
+    }
+    const headerValue = getHeader(err['headers'], 'retry-after');
+    if (!headerValue) {
+        return null;
+    }
+    const seconds = Number(headerValue);
+    if (Number.isFinite(seconds)) {
+        return seconds * 1000;
+    }
+    const dateMs = Date.parse(headerValue);
+    if (Number.isFinite(dateMs)) {
+        return Math.max(dateMs - Date.now(), 0);
+    }
+    return null;
+}
+function toNumber(value) {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === 'string' && value.trim() !== '') {
+        const parsed = Number(value);
+        return Number.isFinite(parsed) ? parsed : null;
+    }
+    return null;
+}
+function getHeader(headers, name) {
+    if (!headers || typeof headers !== 'object')
+        return null;
+    if ('get' in headers && typeof headers.get === 'function') {
+        const value = headers.get(name);
+        return typeof value === 'string' ? value : null;
+    }
+    const record = headers;
+    const matchedKey = Object.keys(record).find((key) => key.toLowerCase() === name.toLowerCase());
+    if (!matchedKey)
+        return null;
+    const value = record[matchedKey];
+    return typeof value === 'string' ? value : null;
+}
+//# sourceMappingURL=backoff.js.map

package/dist/backoff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backoff.js","sourceRoot":"","sources":["../src/backoff.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,gBAAgB,CAC9B,OAAe,EACf,cAAsB,EACtB,UAAkB;IAElB,MAAM,WAAW,GAAG,cAAc,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,CAAA;IACzD,MAAM,MAAM,GAAG,WAAW,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAA;IAC3D,MAAM,KAAK,GAAG,WAAW,GAAG,MAAM,CAAA;IAElC,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,cAAc,CAAC,EAAE,UAAU,CAAC,CAAA;AAC9D,CAAC;AAED,MAAM,UAAU,KAAK,CAAC,EAAU;IAC9B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAA;AAC1D,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,IAAI,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC;QAAE,OAAO,KAAK,CAAA;IAE3C,MAAM,GAAG,GAAG,KAIX,CAAA;IAED,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,UAAU,CAAC,CAAA;IACrD,IAAI,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,KAAK,IAAI,IAAI,MAAM,IAAI,GAAG,IAAI,MAAM,IAAI,GAAG,CAAC,EAAE,CAAC;QAC1E,OAAO,IAAI,CAAA;IACb,CAAC;IAED,MAAM,IAAI,GAAG,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAA;IACvE,IACE;QACE,WAAW;QACX,YAAY;QACZ,cAAc;QACd,WAAW;QACX,WAAW;QACX,qBAAqB;KACtB,CAAC,QAAQ,CAAC,IAAI,CAAC,EAChB,CAAC;QACD,OAAO,IAAI,CAAA;IACb,CAAC;IAED,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,WAAW,EAAE,CAAA;IAC3C,MAAM,iBAAiB,GAAG;QACxB,YAAY;QACZ,YAAY;QACZ,mBAAmB;QACnB,KAAK;QACL,cAAc;QACd,KAAK;QACL,KAAK;QACL,KAAK;QACL,KAAK;QACL,SAAS;QACT,WAAW;QACX,YAAY;QACZ,cAAc;QACd,SAAS;QACT,QAAQ;QACR,YAAY;KACb,CAAA;IAED,OAAO,iBAAiB,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAA;AACvE,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAA;IAEpD,MAAM,GAAG,GAAG,KAAgC,CAAA;IAC5C,MAAM,UAAU,GAAG,QAAQ,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,GAAG,CAAC,aAAa,CAAC,CAAC,CAAA;IACpE,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;QACxB,OAAO,UAAU,GAAG,IAAI,CAAA;IAC1B,CAAC;IAED,MAAM,WAAW,GAAG,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,aAAa,CAAC,CAAA;IAC5D,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,OAAO,IAAI,CAAA;IACb,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,CAAC,WAAW,CAAC,CAAA;IACnC,IAAI,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QAC7B,OAAO,OAAO,GAAG,IAAI,CAAA;IACvB,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,CAAA;IACtC,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QAC5B,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAA;IACzC,CAAC;IAED,OAAO,IAAI,CAAA;AACb,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACxD,OAAO,KAAK,CAAA;IACd,CAAC;IAED,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACrD,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAA;QAC5B,OAAO,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAA;IAChD,CAAC;IAED,OAAO,IAAI,CAAA;AACb,CAAC;AAED,SAAS,SAAS,CAAC,OAAgB,EAAE,IAAY;IAC/C,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAA;IAExD,IAAI,KAAK,IAAI,OAAO,IAAI,OAAO,OAAO,CAAC,GAAG,KAAK,UAAU,EAAE,CAAC;QAC1D,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QAC/B,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAA;IACjD,CAAC;IAED,MAAM,MAAM,GAAG,OAAkC,CAAA;IACjD,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,CACzC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,WAAW,EAAE,KAAK,IAAI,CAAC,WAAW,EAAE,CAClD,CAAA;IAED,IAAI,CAAC,UAAU;QAAE,OAAO,IAAI,CAAA;IAE5B,MAAM,KAAK,GAAG,MAAM,CAAC,UAAU,CAAC,CAAA;IAChC,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAA;AACjD,CAAC"}

package/dist/budget.d.ts

@@ -0,0 +1,15 @@
+import type { TokenUsage } from './types.js';
+export declare class BudgetTracker {
+    private totalTokens;
+    private totalCostUSD;
+    private readonly costPer1kTokens;
+    private readonly maxCostUSD;
+    constructor(costPer1kTokens: number, maxCostUSD?: number);
+    add(usage: TokenUsage): void;
+    isExceeded(): boolean;
+    get spent(): number;
+    get tokens(): number;
+    get limit(): number | null;
+    summary(): string;
+}
+//# sourceMappingURL=budget.d.ts.map

package/dist/budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.d.ts","sourceRoot":"","sources":["../src/budget.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE5C,qBAAa,aAAa;IACxB,OAAO,CAAC,WAAW,CAAI;IACvB,OAAO,CAAC,YAAY,CAAI;IACxB,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAQ;IACxC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAe;gBAE9B,eAAe,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM;IAaxD,GAAG,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAK5B,UAAU,IAAI,OAAO;IAKrB,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,IAAI,KAAK,IAAI,MAAM,GAAG,IAAI,CAEzB;IAED,OAAO,IAAI,MAAM;CAKlB"}

package/dist/budget.js

@@ -0,0 +1,40 @@
+export class BudgetTracker {
+    totalTokens = 0;
+    totalCostUSD = 0;
+    costPer1kTokens;
+    maxCostUSD;
+    constructor(costPer1kTokens, maxCostUSD) {
+        if (costPer1kTokens < 0) {
+            throw new Error('costPer1kTokens must be greater than or equal to 0');
+        }
+        if (maxCostUSD !== undefined && maxCostUSD < 0) {
+            throw new Error('maxCostUSD must be greater than or equal to 0');
+        }
+        this.costPer1kTokens = costPer1kTokens;
+        this.maxCostUSD = maxCostUSD ?? null;
+    }
+    add(usage) {
+        this.totalTokens += usage.totalTokens;
+        this.totalCostUSD += (usage.totalTokens / 1000) * this.costPer1kTokens;
+    }
+    isExceeded() {
+        if (this.maxCostUSD === null)
+            return false;
+        return this.totalCostUSD >= this.maxCostUSD;
+    }
+    get spent() {
+        return this.totalCostUSD;
+    }
+    get tokens() {
+        return this.totalTokens;
+    }
+    get limit() {
+        return this.maxCostUSD;
+    }
+    summary() {
+        const cost = this.totalCostUSD.toFixed(4);
+        const limit = this.maxCostUSD !== null ? `/ $${this.maxCostUSD}` : '';
+        return `$${cost}${limit} (${this.totalTokens.toLocaleString()} tokens)`;
+    }
+}
+//# sourceMappingURL=budget.js.map

package/dist/budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.js","sourceRoot":"","sources":["../src/budget.ts"],"names":[],"mappings":"AAEA,MAAM,OAAO,aAAa;IAChB,WAAW,GAAG,CAAC,CAAA;IACf,YAAY,GAAG,CAAC,CAAA;IACP,eAAe,CAAQ;IACvB,UAAU,CAAe;IAE1C,YAAY,eAAuB,EAAE,UAAmB;QACtD,IAAI,eAAe,GAAG,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAA;QACvE,CAAC;QAED,IAAI,UAAU,KAAK,SAAS,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC;YAC/C,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAA;QAClE,CAAC;QAED,IAAI,CAAC,eAAe,GAAG,eAAe,CAAA;QACtC,IAAI,CAAC,UAAU,GAAG,UAAU,IAAI,IAAI,CAAA;IACtC,CAAC;IAED,GAAG,CAAC,KAAiB;QACnB,IAAI,CAAC,WAAW,IAAI,KAAK,CAAC,WAAW,CAAA;QACrC,IAAI,CAAC,YAAY,IAAI,CAAC,KAAK,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,eAAe,CAAA;IACxE,CAAC;IAED,UAAU;QACR,IAAI,IAAI,CAAC,UAAU,KAAK,IAAI;YAAE,OAAO,KAAK,CAAA;QAC1C,OAAO,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,UAAU,CAAA;IAC7C,CAAC;IAED,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,YAAY,CAAA;IAC1B,CAAC;IAED,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,WAAW,CAAA;IACzB,CAAC;IAED,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,UAAU,CAAA;IACxB,CAAC;IAED,OAAO;QACL,MAAM,IAAI,GAAG,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,CAAA;QACzC,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAA;QACrE,OAAO,IAAI,IAAI,GAAG,KAAK,KAAK,IAAI,CAAC,WAAW,CAAC,cAAc,EAAE,UAAU,CAAA;IACzE,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { llmRetry, LLMRetryError } from './retry.js';
+export { BudgetTracker } from './budget.js';
+export { calculateBackoff, isRetryableError } from './backoff.js';
+export type { RetryOptions, RetryResult, TokenUsage, LLMResponse, RetryableError, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AACjE,YAAY,EACV,YAAY,EACZ,WAAW,EACX,UAAU,EACV,WAAW,EACX,cAAc,GACf,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { llmRetry, LLMRetryError } from './retry.js';
+export { BudgetTracker } from './budget.js';
+export { calculateBackoff, isRetryableError } from './backoff.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA"}

package/dist/retry.d.ts

@@ -0,0 +1,10 @@
+import type { RetryOptions, RetryResult } from './types.js';
+export declare function llmRetry<T>(options: RetryOptions<T>): Promise<RetryResult<T>>;
+export declare class LLMRetryError extends Error {
+    readonly primaryError: Error | null;
+    readonly fallbackError: Error | null;
+    readonly totalCostUSD: number;
+    readonly totalTokens: number;
+    constructor(message: string, primaryError: Error | null, fallbackError: Error | null, totalCostUSD: number, totalTokens: number);
+}
+//# sourceMappingURL=retry.d.ts.map

package/dist/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAE3D,wBAAsB,QAAQ,CAAC,CAAC,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAgHnF;AAeD,qBAAa,aAAc,SAAQ,KAAK;aAGpB,YAAY,EAAE,KAAK,GAAG,IAAI;aAC1B,aAAa,EAAE,KAAK,GAAG,IAAI;aAC3B,YAAY,EAAE,MAAM;aACpB,WAAW,EAAE,MAAM;gBAJnC,OAAO,EAAE,MAAM,EACC,YAAY,EAAE,KAAK,GAAG,IAAI,EAC1B,aAAa,EAAE,KAAK,GAAG,IAAI,EAC3B,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM;CAKtC"}

package/dist/retry.js

@@ -0,0 +1,103 @@
+import { calculateBackoff, extractRetryAfter, isRetryableError, sleep } from './backoff.js';
+import { BudgetTracker } from './budget.js';
+export async function llmRetry(options) {
+    const { fn, fallback, maxRetries = 3, maxCostUSD, costPer1kTokens = 0.002, initialDelayMs = 1000, maxDelayMs = 30000, onRetry, onBudgetExceeded, } = options;
+    validateOptions({ maxRetries, initialDelayMs, maxDelayMs });
+    const budget = new BudgetTracker(costPer1kTokens, maxCostUSD);
+    let lastError = null;
+    let attempts = 0;
+    let budgetExceededNotified = false;
+    for (let retryIndex = 0; retryIndex <= maxRetries; retryIndex++) {
+        if (budget.isExceeded()) {
+            budgetExceededNotified = notifyBudgetExceeded(budget.spent, budget.limit, onBudgetExceeded, budgetExceededNotified);
+            break;
+        }
+        attempts += 1;
+        try {
+            const response = await fn();
+            if (response.usage) {
+                budget.add(response.usage);
+            }
+            return {
+                data: response.data,
+                attempts,
+                usedFallback: false,
+                totalCostUSD: budget.spent,
+                totalTokens: budget.tokens,
+            };
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            lastError = err;
+            const isLastAttempt = retryIndex === maxRetries;
+            if (isLastAttempt || !isRetryableError(err)) {
+                break;
+            }
+            const serverDelay = extractRetryAfter(error);
+            const delay = serverDelay ?? calculateBackoff(retryIndex, initialDelayMs, maxDelayMs);
+            onRetry?.(attempts, err, delay);
+            await sleep(delay);
+        }
+    }
+    if (fallback && !budget.isExceeded()) {
+        attempts += 1;
+        try {
+            const response = await fallback();
+            if (response.usage) {
+                budget.add(response.usage);
+            }
+            return {
+                data: response.data,
+                attempts,
+                usedFallback: true,
+                totalCostUSD: budget.spent,
+                totalTokens: budget.tokens,
+            };
+        }
+        catch (fallbackError) {
+            const err = fallbackError instanceof Error
+                ? fallbackError
+                : new Error(String(fallbackError));
+            throw new LLMRetryError(`Both primary and fallback failed. Primary: ${lastError?.message ?? 'unknown error'}. Fallback: ${err.message}`, lastError, err, budget.spent, budget.tokens);
+        }
+    }
+    if (budget.isExceeded()) {
+        notifyBudgetExceeded(budget.spent, budget.limit, onBudgetExceeded, budgetExceededNotified);
+    }
+    throw new LLMRetryError(`LLM call failed after ${attempts} attempt${attempts === 1 ? '' : 's'}: ${lastError?.message ?? 'budget exceeded'}`, lastError, null, budget.spent, budget.tokens);
+}
+function notifyBudgetExceeded(spentUSD, limitUSD, callback, alreadyNotified) {
+    if (!alreadyNotified && limitUSD !== null) {
+        callback?.(spentUSD, limitUSD);
+    }
+    return true;
+}
+export class LLMRetryError extends Error {
+    primaryError;
+    fallbackError;
+    totalCostUSD;
+    totalTokens;
+    constructor(message, primaryError, fallbackError, totalCostUSD, totalTokens) {
+        super(message);
+        this.primaryError = primaryError;
+        this.fallbackError = fallbackError;
+        this.totalCostUSD = totalCostUSD;
+        this.totalTokens = totalTokens;
+        this.name = 'LLMRetryError';
+    }
+}
+function validateOptions(options) {
+    if (!Number.isInteger(options.maxRetries) || options.maxRetries < 0) {
+        throw new Error('maxRetries must be a non-negative integer');
+    }
+    if (options.initialDelayMs < 0) {
+        throw new Error('initialDelayMs must be greater than or equal to 0');
+    }
+    if (options.maxDelayMs < 0) {
+        throw new Error('maxDelayMs must be greater than or equal to 0');
+    }
+    if (options.maxDelayMs < options.initialDelayMs) {
+        throw new Error('maxDelayMs must be greater than or equal to initialDelayMs');
+    }
+}
+//# sourceMappingURL=retry.js.map

package/dist/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,29 @@
+export interface TokenUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+export interface LLMResponse<T = unknown> {
+    data: T;
+    usage?: TokenUsage;
+}
+export interface RetryOptions<T = unknown> {
+    fn: () => Promise<LLMResponse<T>>;
+    fallback?: () => Promise<LLMResponse<T>>;
+    maxRetries?: number;
+    maxCostUSD?: number;
+    costPer1kTokens?: number;
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+    onRetry?: (attempt: number, error: Error, delayMs: number) => void;
+    onBudgetExceeded?: (spentUSD: number, limitUSD: number) => void;
+}
+export interface RetryResult<T = unknown> {
+    data: T;
+    attempts: number;
+    usedFallback: boolean;
+    totalCostUSD: number;
+    totalTokens: number;
+}
+export type RetryableError = 'rate_limit' | 'server_error' | 'timeout' | 'network_error';
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IACzB,YAAY,EAAE,MAAM,CAAA;IACpB,gBAAgB,EAAE,MAAM,CAAA;IACxB,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,WAAW,CAAC,CAAC,GAAG,OAAO;IACtC,IAAI,EAAE,CAAC,CAAA;IACP,KAAK,CAAC,EAAE,UAAU,CAAA;CACnB;AAED,MAAM,WAAW,YAAY,CAAC,CAAC,GAAG,OAAO;IACvC,EAAE,EAAE,MAAM,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAA;IACjC,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAA;IACxC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;IAClE,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAA;CAChE;AAED,MAAM,WAAW,WAAW,CAAC,CAAC,GAAG,OAAO;IACtC,IAAI,EAAE,CAAC,CAAA;IACP,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,EAAE,OAAO,CAAA;IACrB,YAAY,EAAE,MAAM,CAAA;IACpB,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,MAAM,cAAc,GACtB,YAAY,GACZ,cAAc,GACd,SAAS,GACT,eAAe,CAAA"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "llm-retry-kit",
+  "version": "0.1.0",
+  "description": "Smart retry wrapper for LLM APIs with fallback, budget tracking, and exponential backoff.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "clean": "node -e \"fs.rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm test && npm run typecheck"
+  },
+  "keywords": [
+    "llm",
+    "openai",
+    "anthropic",
+    "retry",
+    "rate-limit",
+    "fallback",
+    "backoff",
+    "ai",
+    "gpt",
+    "claude"
+  ],
+  "author": "llm-retry contributors",
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "vitest": "^4.1.8"
+  }
+}