tool-call-retry 0.1.0

package/README.md

@@ -0,0 +1,141 @@
+# tool-call-retry
+
+AI-specific retry wrapper with circuit breaker for LLM tool calls. Zero external runtime dependencies.
+
+## Install
+
+```bash
+npm install tool-call-retry
+```
+
+## Quick start — `withRetry`
+
+```typescript
+import { withRetry } from 'tool-call-retry';
+
+const result = await withRetry(
+  () => callMyTool(args),
+  {
+    maxRetries: 3,
+    policy: { strategy: 'exponential', initialDelayMs: 1000, jitter: 'full' },
+    onPermanentFailure: 'return-error',   // returns LLMFormattedError instead of throwing
+    toolName: 'search',
+    hooks: {
+      onRetry: ({ attempt, delayMs, classification }) =>
+        console.log(`Attempt ${attempt} failed (${classification.code}), retrying in ${delayMs}ms`),
+      onSuccess: ({ attempts, totalMs }) =>
+        console.log(`Succeeded after ${attempts} attempt(s) in ${totalMs}ms`),
+    },
+  }
+);
+
+if (result && typeof result === 'object' && result.error === true) {
+  // LLMFormattedError — safe to pass back to the LLM
+  console.log(result.message, result.suggestion);
+} else {
+  // actual result
+}
+```
+
+## `wrapTools`
+
+Wraps an entire tools map so every call goes through retry:
+
+```typescript
+import { wrapTools } from 'tool-call-retry';
+
+const tools = {
+  search: (args) => fetch(...),
+  calculate: (args) => compute(...),
+};
+
+const retryingTools = wrapTools(tools, {
+  maxRetries: 3,
+  onPermanentFailure: 'return-error',
+});
+
+// retryingTools.search / retryingTools.calculate are now retry-wrapped
+```
+
+## Circuit breaker
+
+The circuit breaker is enabled by default (threshold: 5 failures in 60 s, resets after 30 s).
+
+```typescript
+import { withRetry } from 'tool-call-retry';
+
+await withRetry(() => callTool(), {
+  circuitBreaker: {
+    failureThreshold: 3,
+    rollingWindowMs: 30000,
+    resetTimeoutMs: 15000,
+    successThreshold: 1,
+  },
+});
+
+// Disable entirely:
+await withRetry(() => callTool(), { circuitBreaker: false });
+```
+
+You can also create and reuse a circuit breaker instance:
+
+```typescript
+import { createCircuitBreaker } from 'tool-call-retry';
+
+const cb = createCircuitBreaker({ failureThreshold: 5 });
+cb.on('open', () => console.warn('Circuit opened'));
+cb.on('close', () => console.info('Circuit closed'));
+
+console.log(cb.state);           // 'closed' | 'open' | 'half-open'
+console.log(cb.isCallPermitted); // boolean
+cb.recordSuccess();
+cb.recordFailure();
+```
+
+## Error classification
+
+```typescript
+import { classifyError } from 'tool-call-retry';
+
+const c = classifyError(error);
+// c.category: 'retriable' | 'non-retriable' | 'rate-limited' | 'timeout' | 'unknown'
+// c.code: e.g. 'RATE_LIMITED', 'SERVER_ERROR', 'CLIENT_ERROR', 'NETWORK_ERROR', 'TIMEOUT', ...
+// c.retryAfterMs: number | undefined  (populated for 429 responses)
+```
+
+Custom classifier:
+
+```typescript
+await withRetry(() => callTool(), {
+  classifyError: (err) => {
+    if (isMyCustomError(err)) return { category: 'retriable', code: 'MY_ERROR', message: '...' };
+    return null; // fall through to default classification
+  },
+});
+```
+
+## Retry policy options
+
+| Option | Default | Description |
+|---|---|---|
+| `maxRetries` | `3` | Maximum retry attempts |
+| `strategy` | `'exponential'` | `'exponential'` \| `'linear'` \| `'fixed'` |
+| `initialDelayMs` | `1000` | Base delay in ms |
+| `maxDelayMs` | `30000` | Delay cap in ms |
+| `multiplier` | `2` | Exponent base (exponential only) |
+| `jitter` | `'full'` | `'full'` \| `'equal'` \| `'decorrelated'` \| `'none'` |
+| `maxTotalTimeMs` | `60000` | Total time budget before giving up |
+
+## LLMFormattedError shape
+
+```typescript
+{
+  error: true,
+  code: string,        // e.g. 'RATE_LIMITED', 'SERVICE_UNAVAILABLE'
+  message: string,     // sanitized (no stack traces, tokens, passwords)
+  retriable: boolean,
+  suggestion: string,  // human-readable next-step hint
+  tool?: string,       // tool name if provided
+  attemptsMade?: number,
+}
+```

package/dist/__tests__/backoff.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=backoff.test.d.ts.map

package/dist/__tests__/backoff.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backoff.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/backoff.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/backoff.test.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const backoff_js_1 = require("../backoff.js");
+function makePolicy(overrides) {
+    return {
+        maxRetries: 3,
+        strategy: 'exponential',
+        initialDelayMs: 1000,
+        maxDelayMs: 30000,
+        multiplier: 2,
+        jitter: 'none',
+        maxTotalTimeMs: 60000,
+        ...overrides,
+    };
+}
+(0, vitest_1.describe)('computeDelay', () => {
+    (0, vitest_1.describe)('exponential strategy', () => {
+        (0, vitest_1.it)('returns initialDelayMs on attempt 1', () => {
+            const policy = makePolicy();
+            const delay = (0, backoff_js_1.computeDelay)(1, policy, policy.initialDelayMs);
+            (0, vitest_1.expect)(delay).toBe(1000);
+        });
+        (0, vitest_1.it)('doubles on attempt 2', () => {
+            const policy = makePolicy();
+            const delay = (0, backoff_js_1.computeDelay)(2, policy, 1000);
+            (0, vitest_1.expect)(delay).toBe(2000);
+        });
+        (0, vitest_1.it)('grows to 4x on attempt 3', () => {
+            const policy = makePolicy();
+            const delay = (0, backoff_js_1.computeDelay)(3, policy, 2000);
+            (0, vitest_1.expect)(delay).toBe(4000);
+        });
+        (0, vitest_1.it)('is capped at maxDelayMs', () => {
+            const policy = makePolicy({ maxDelayMs: 3000 });
+            const delay = (0, backoff_js_1.computeDelay)(5, policy, 3000);
+            (0, vitest_1.expect)(delay).toBe(3000);
+        });
+    });
+    (0, vitest_1.describe)('linear strategy', () => {
+        (0, vitest_1.it)('returns 1x initialDelayMs on attempt 1', () => {
+            const policy = makePolicy({ strategy: 'linear' });
+            (0, vitest_1.expect)((0, backoff_js_1.computeDelay)(1, policy, 1000)).toBe(1000);
+        });
+        (0, vitest_1.it)('returns 2x initialDelayMs on attempt 2', () => {
+            const policy = makePolicy({ strategy: 'linear' });
+            (0, vitest_1.expect)((0, backoff_js_1.computeDelay)(2, policy, 1000)).toBe(2000);
+        });
+        (0, vitest_1.it)('is capped at maxDelayMs', () => {
+            const policy = makePolicy({ strategy: 'linear', maxDelayMs: 1500 });
+            (0, vitest_1.expect)((0, backoff_js_1.computeDelay)(3, policy, 1500)).toBe(1500);
+        });
+    });
+    (0, vitest_1.describe)('fixed strategy', () => {
+        (0, vitest_1.it)('always returns initialDelayMs', () => {
+            const policy = makePolicy({ strategy: 'fixed' });
+            (0, vitest_1.expect)((0, backoff_js_1.computeDelay)(1, policy, 0)).toBe(1000);
+            (0, vitest_1.expect)((0, backoff_js_1.computeDelay)(5, policy, 5000)).toBe(1000);
+        });
+    });
+    (0, vitest_1.describe)('jitter', () => {
+        const rng05 = () => 0.5;
+        const rng0 = () => 0;
+        const rng1 = () => 0.9999;
+        (0, vitest_1.it)('full jitter: result is in [0, baseDelay]', () => {
+            const policy = makePolicy({ jitter: 'full', strategy: 'exponential' });
+            for (let i = 0; i < 20; i++) {
+                const delay = (0, backoff_js_1.computeDelay)(1, policy, 1000);
+                (0, vitest_1.expect)(delay).toBeGreaterThanOrEqual(0);
+                (0, vitest_1.expect)(delay).toBeLessThanOrEqual(1000);
+            }
+        });
+        (0, vitest_1.it)('full jitter: scales with rng value', () => {
+            const policy = makePolicy({ jitter: 'full', strategy: 'exponential' });
+            (0, vitest_1.expect)((0, backoff_js_1.computeDelay)(1, policy, 1000, rng05)).toBe(Math.round(0.5 * 1000));
+            (0, vitest_1.expect)((0, backoff_js_1.computeDelay)(1, policy, 1000, rng0)).toBe(0);
+        });
+        (0, vitest_1.it)('equal jitter: result is in [baseDelay/2, baseDelay]', () => {
+            const policy = makePolicy({ jitter: 'equal', strategy: 'exponential' });
+            for (let i = 0; i < 20; i++) {
+                const delay = (0, backoff_js_1.computeDelay)(1, policy, 1000);
+                (0, vitest_1.expect)(delay).toBeGreaterThanOrEqual(500);
+                (0, vitest_1.expect)(delay).toBeLessThanOrEqual(1000);
+            }
+        });
+        (0, vitest_1.it)('equal jitter: lower bound is baseDelay/2 when rng=0', () => {
+            const policy = makePolicy({ jitter: 'equal', strategy: 'exponential' });
+            (0, vitest_1.expect)((0, backoff_js_1.computeDelay)(1, policy, 1000, rng0)).toBe(500);
+        });
+        (0, vitest_1.it)('none jitter: returns exact baseDelay', () => {
+            const policy = makePolicy({ jitter: 'none' });
+            (0, vitest_1.expect)((0, backoff_js_1.computeDelay)(2, policy, 1000)).toBe(2000);
+        });
+        (0, vitest_1.it)('decorrelated: bounded by maxDelayMs', () => {
+            const policy = makePolicy({ jitter: 'decorrelated', strategy: 'exponential', maxDelayMs: 5000 });
+            for (let i = 0; i < 20; i++) {
+                const delay = (0, backoff_js_1.computeDelay)(2, policy, 1000);
+                (0, vitest_1.expect)(delay).toBeLessThanOrEqual(5000);
+            }
+        });
+        (0, vitest_1.it)('decorrelated: uses rng correctly', () => {
+            const policy = makePolicy({ jitter: 'decorrelated', strategy: 'exponential', maxDelayMs: 30000 });
+            // decorrelated = rng * (prev*3 - initial) + initial, prev=1000
+            // = rng * (3000 - 1000) + 1000 = rng * 2000 + 1000
+            const prev = 1000;
+            (0, vitest_1.expect)((0, backoff_js_1.computeDelay)(1, policy, prev, rng0)).toBe(Math.round(0 * 2000 + 1000));
+            (0, vitest_1.expect)((0, backoff_js_1.computeDelay)(1, policy, prev, rng1)).toBe(Math.round(0.9999 * 2000 + 1000));
+        });
+    });
+    (0, vitest_1.describe)('maxDelayMs enforcement', () => {
+        (0, vitest_1.it)('caps exponential at maxDelayMs with none jitter', () => {
+            const policy = makePolicy({ maxDelayMs: 500, strategy: 'exponential', jitter: 'none' });
+            (0, vitest_1.expect)((0, backoff_js_1.computeDelay)(10, policy, 500)).toBe(500);
+        });
+    });
+});
+//# sourceMappingURL=backoff.test.js.map

package/dist/__tests__/backoff.test.js.map

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

package/dist/__tests__/circuit-breaker.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=circuit-breaker.test.d.ts.map

package/dist/__tests__/circuit-breaker.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/circuit-breaker.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/circuit-breaker.test.js

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const circuit_breaker_js_1 = require("../circuit-breaker.js");
+(0, vitest_1.describe)('createCircuitBreaker', () => {
+    (0, vitest_1.beforeEach)(() => {
+        vitest_1.vi.useFakeTimers();
+    });
+    (0, vitest_1.afterEach)(() => {
+        vitest_1.vi.useRealTimers();
+    });
+    (0, vitest_1.it)('starts in closed state', () => {
+        const cb = (0, circuit_breaker_js_1.createCircuitBreaker)({ failureThreshold: 3 });
+        (0, vitest_1.expect)(cb.state).toBe('closed');
+        (0, vitest_1.expect)(cb.isCallPermitted).toBe(true);
+    });
+    (0, vitest_1.it)('remains closed below failure threshold', () => {
+        const cb = (0, circuit_breaker_js_1.createCircuitBreaker)({ failureThreshold: 3 });
+        cb.recordFailure();
+        cb.recordFailure();
+        (0, vitest_1.expect)(cb.state).toBe('closed');
+        (0, vitest_1.expect)(cb.isCallPermitted).toBe(true);
+    });
+    (0, vitest_1.it)('opens after reaching failure threshold', () => {
+        const cb = (0, circuit_breaker_js_1.createCircuitBreaker)({ failureThreshold: 3 });
+        cb.recordFailure();
+        cb.recordFailure();
+        cb.recordFailure();
+        (0, vitest_1.expect)(cb.state).toBe('open');
+        (0, vitest_1.expect)(cb.isCallPermitted).toBe(false);
+    });
+    (0, vitest_1.it)('emits "open" event when transitioning to open', () => {
+        const cb = (0, circuit_breaker_js_1.createCircuitBreaker)({ failureThreshold: 2 });
+        const handler = vitest_1.vi.fn();
+        cb.on('open', handler);
+        cb.recordFailure();
+        cb.recordFailure();
+        (0, vitest_1.expect)(handler).toHaveBeenCalledTimes(1);
+    });
+    (0, vitest_1.it)('transitions to half-open after resetTimeoutMs', () => {
+        const cb = (0, circuit_breaker_js_1.createCircuitBreaker)({ failureThreshold: 2, resetTimeoutMs: 5000 });
+        cb.recordFailure();
+        cb.recordFailure();
+        (0, vitest_1.expect)(cb.state).toBe('open');
+        vitest_1.vi.advanceTimersByTime(5000);
+        (0, vitest_1.expect)(cb.state).toBe('half-open');
+        (0, vitest_1.expect)(cb.isCallPermitted).toBe(true);
+    });
+    (0, vitest_1.it)('emits "half-open" event on transition', () => {
+        const cb = (0, circuit_breaker_js_1.createCircuitBreaker)({ failureThreshold: 2, resetTimeoutMs: 5000 });
+        const handler = vitest_1.vi.fn();
+        cb.on('half-open', handler);
+        cb.recordFailure();
+        cb.recordFailure();
+        vitest_1.vi.advanceTimersByTime(5000);
+        // Accessing state triggers the checkHalfOpen transition
+        (0, vitest_1.expect)(cb.state).toBe('half-open');
+        (0, vitest_1.expect)(handler).toHaveBeenCalledTimes(1);
+    });
+    (0, vitest_1.it)('closes after success in half-open state', () => {
+        const cb = (0, circuit_breaker_js_1.createCircuitBreaker)({ failureThreshold: 2, resetTimeoutMs: 5000, successThreshold: 1 });
+        cb.recordFailure();
+        cb.recordFailure();
+        vitest_1.vi.advanceTimersByTime(5000);
+        (0, vitest_1.expect)(cb.state).toBe('half-open');
+        cb.recordSuccess();
+        (0, vitest_1.expect)(cb.state).toBe('closed');
+        (0, vitest_1.expect)(cb.isCallPermitted).toBe(true);
+    });
+    (0, vitest_1.it)('emits "close" event when closing from half-open', () => {
+        const cb = (0, circuit_breaker_js_1.createCircuitBreaker)({ failureThreshold: 2, resetTimeoutMs: 5000 });
+        const handler = vitest_1.vi.fn();
+        cb.on('close', handler);
+        cb.recordFailure();
+        cb.recordFailure();
+        vitest_1.vi.advanceTimersByTime(5000);
+        void cb.state; // trigger half-open
+        cb.recordSuccess();
+        (0, vitest_1.expect)(handler).toHaveBeenCalledTimes(1);
+    });
+    (0, vitest_1.it)('goes back to open on failure in half-open state', () => {
+        const cb = (0, circuit_breaker_js_1.createCircuitBreaker)({ failureThreshold: 2, resetTimeoutMs: 5000 });
+        cb.recordFailure();
+        cb.recordFailure();
+        vitest_1.vi.advanceTimersByTime(5000);
+        (0, vitest_1.expect)(cb.state).toBe('half-open');
+        cb.recordFailure();
+        (0, vitest_1.expect)(cb.state).toBe('open');
+        (0, vitest_1.expect)(cb.isCallPermitted).toBe(false);
+    });
+    (0, vitest_1.it)('resets failure count after closing', () => {
+        const cb = (0, circuit_breaker_js_1.createCircuitBreaker)({ failureThreshold: 3, resetTimeoutMs: 1000 });
+        cb.recordFailure();
+        cb.recordFailure();
+        cb.recordFailure(); // open
+        vitest_1.vi.advanceTimersByTime(1000);
+        void cb.state; // half-open
+        cb.recordSuccess(); // close
+        // Should need 3 new failures to open again
+        cb.recordFailure();
+        cb.recordFailure();
+        (0, vitest_1.expect)(cb.state).toBe('closed');
+        cb.recordFailure();
+        (0, vitest_1.expect)(cb.state).toBe('open');
+    });
+    (0, vitest_1.it)('removes listener when unsubscribe function is called', () => {
+        const cb = (0, circuit_breaker_js_1.createCircuitBreaker)({ failureThreshold: 2 });
+        const handler = vitest_1.vi.fn();
+        const unsubscribe = cb.on('open', handler);
+        unsubscribe();
+        cb.recordFailure();
+        cb.recordFailure();
+        (0, vitest_1.expect)(handler).not.toHaveBeenCalled();
+    });
+    (0, vitest_1.it)('does not count failures outside rolling window', () => {
+        const cb = (0, circuit_breaker_js_1.createCircuitBreaker)({
+            failureThreshold: 3,
+            rollingWindowMs: 5000,
+        });
+        cb.recordFailure();
+        cb.recordFailure();
+        // Advance past rolling window
+        vitest_1.vi.advanceTimersByTime(6000);
+        // This failure is within the window, the previous two are not
+        cb.recordFailure();
+        (0, vitest_1.expect)(cb.state).toBe('closed');
+    });
+});
+//# sourceMappingURL=circuit-breaker.test.js.map

package/dist/__tests__/circuit-breaker.test.js.map

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

package/dist/__tests__/classify.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=classify.test.d.ts.map

package/dist/__tests__/classify.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classify.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/classify.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/classify.test.js

@@ -0,0 +1,139 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const classify_js_1 = require("../classify.js");
+(0, vitest_1.describe)('classifyError', () => {
+    (0, vitest_1.it)('classifies HTTP 429 as rate-limited', () => {
+        const err = Object.assign(new Error('Too Many Requests'), { status: 429 });
+        const result = (0, classify_js_1.classifyError)(err);
+        (0, vitest_1.expect)(result.category).toBe('rate-limited');
+        (0, vitest_1.expect)(result.code).toBe('RATE_LIMITED');
+        (0, vitest_1.expect)(result.statusCode).toBe(429);
+    });
+    (0, vitest_1.it)('extracts retryAfterMs from headers', () => {
+        const err = Object.assign(new Error('Rate limited'), {
+            status: 429,
+            headers: { 'retry-after': '5' },
+        });
+        const result = (0, classify_js_1.classifyError)(err);
+        (0, vitest_1.expect)(result.retryAfterMs).toBe(5000);
+    });
+    (0, vitest_1.it)('extracts retryAfterMs from retryAfter property', () => {
+        const err = Object.assign(new Error('Rate limited'), {
+            status: 429,
+            retryAfter: 10000,
+        });
+        const result = (0, classify_js_1.classifyError)(err);
+        (0, vitest_1.expect)(result.retryAfterMs).toBe(10000);
+    });
+    (0, vitest_1.it)('classifies HTTP 404 as non-retriable', () => {
+        const err = Object.assign(new Error('Not Found'), { status: 404 });
+        const result = (0, classify_js_1.classifyError)(err);
+        (0, vitest_1.expect)(result.category).toBe('non-retriable');
+        (0, vitest_1.expect)(result.code).toBe('CLIENT_ERROR');
+        (0, vitest_1.expect)(result.statusCode).toBe(404);
+    });
+    (0, vitest_1.it)('classifies HTTP 401 as non-retriable', () => {
+        const err = Object.assign(new Error('Unauthorized'), { status: 401 });
+        const result = (0, classify_js_1.classifyError)(err);
+        (0, vitest_1.expect)(result.category).toBe('non-retriable');
+        (0, vitest_1.expect)(result.statusCode).toBe(401);
+    });
+    (0, vitest_1.it)('classifies HTTP 422 as non-retriable', () => {
+        const err = Object.assign(new Error('Unprocessable'), { status: 422 });
+        const result = (0, classify_js_1.classifyError)(err);
+        (0, vitest_1.expect)(result.category).toBe('non-retriable');
+        (0, vitest_1.expect)(result.statusCode).toBe(422);
+    });
+    (0, vitest_1.it)('classifies HTTP 503 as retriable', () => {
+        const err = Object.assign(new Error('Service Unavailable'), { status: 503 });
+        const result = (0, classify_js_1.classifyError)(err);
+        (0, vitest_1.expect)(result.category).toBe('retriable');
+        (0, vitest_1.expect)(result.code).toBe('SERVER_ERROR');
+        (0, vitest_1.expect)(result.statusCode).toBe(503);
+    });
+    (0, vitest_1.it)('classifies HTTP 500 as retriable', () => {
+        const err = Object.assign(new Error('Internal Server Error'), { status: 500 });
+        const result = (0, classify_js_1.classifyError)(err);
+        (0, vitest_1.expect)(result.category).toBe('retriable');
+    });
+    (0, vitest_1.it)('classifies HTTP 502 as retriable', () => {
+        const err = Object.assign(new Error('Bad Gateway'), { statusCode: 502 });
+        const result = (0, classify_js_1.classifyError)(err);
+        (0, vitest_1.expect)(result.category).toBe('retriable');
+    });
+    (0, vitest_1.it)('classifies ECONNREFUSED as retriable', () => {
+        const err = Object.assign(new Error('connection refused'), { code: 'ECONNREFUSED' });
+        const result = (0, classify_js_1.classifyError)(err);
+        (0, vitest_1.expect)(result.category).toBe('retriable');
+        (0, vitest_1.expect)(result.code).toBe('NETWORK_ERROR');
+    });
+    (0, vitest_1.it)('classifies ECONNRESET as retriable', () => {
+        const err = Object.assign(new Error('socket hang up'), { code: 'ECONNRESET' });
+        const result = (0, classify_js_1.classifyError)(err);
+        (0, vitest_1.expect)(result.category).toBe('retriable');
+        (0, vitest_1.expect)(result.code).toBe('NETWORK_ERROR');
+    });
+    (0, vitest_1.it)('classifies EPIPE as retriable', () => {
+        const err = Object.assign(new Error('broken pipe'), { code: 'EPIPE' });
+        const result = (0, classify_js_1.classifyError)(err);
+        (0, vitest_1.expect)(result.category).toBe('retriable');
+        (0, vitest_1.expect)(result.code).toBe('NETWORK_ERROR');
+    });
+    (0, vitest_1.it)('classifies ETIMEDOUT as timeout', () => {
+        const err = Object.assign(new Error('timed out'), { code: 'ETIMEDOUT' });
+        const result = (0, classify_js_1.classifyError)(err);
+        (0, vitest_1.expect)(result.category).toBe('timeout');
+        (0, vitest_1.expect)(result.code).toBe('TIMEOUT');
+    });
+    (0, vitest_1.it)('classifies ENOTFOUND as retriable DNS error', () => {
+        const err = Object.assign(new Error('getaddrinfo ENOTFOUND'), { code: 'ENOTFOUND' });
+        const result = (0, classify_js_1.classifyError)(err);
+        (0, vitest_1.expect)(result.category).toBe('retriable');
+        (0, vitest_1.expect)(result.code).toBe('DNS_ERROR');
+    });
+    (0, vitest_1.it)('classifies EAI_AGAIN as retriable DNS error', () => {
+        const err = Object.assign(new Error('DNS lookup failed'), { code: 'EAI_AGAIN' });
+        const result = (0, classify_js_1.classifyError)(err);
+        (0, vitest_1.expect)(result.category).toBe('retriable');
+        (0, vitest_1.expect)(result.code).toBe('DNS_ERROR');
+    });
+    (0, vitest_1.it)('classifies message containing "timeout" as timeout', () => {
+        const err = new Error('Request timeout exceeded');
+        const result = (0, classify_js_1.classifyError)(err);
+        (0, vitest_1.expect)(result.category).toBe('timeout');
+        (0, vitest_1.expect)(result.code).toBe('TIMEOUT');
+    });
+    (0, vitest_1.it)('classifies AbortError as non-retriable', () => {
+        const err = new Error('Aborted');
+        err.name = 'AbortError';
+        const result = (0, classify_js_1.classifyError)(err);
+        (0, vitest_1.expect)(result.category).toBe('non-retriable');
+        (0, vitest_1.expect)(result.code).toBe('ABORTED');
+    });
+    (0, vitest_1.it)('falls back to unknown for unrecognized errors', () => {
+        const err = new Error('Something weird happened');
+        const result = (0, classify_js_1.classifyError)(err);
+        (0, vitest_1.expect)(result.category).toBe('unknown');
+        (0, vitest_1.expect)(result.code).toBe('UNKNOWN_ERROR');
+    });
+    (0, vitest_1.it)('uses custom classifier when provided and returns non-null', () => {
+        const err = new Error('custom error');
+        const custom = () => ({
+            category: 'retriable',
+            code: 'CUSTOM',
+            message: 'custom',
+        });
+        const result = (0, classify_js_1.classifyError)(err, custom);
+        (0, vitest_1.expect)(result.code).toBe('CUSTOM');
+        (0, vitest_1.expect)(result.category).toBe('retriable');
+    });
+    (0, vitest_1.it)('falls through to default classification when custom classifier returns null', () => {
+        const err = Object.assign(new Error('Service Unavailable'), { status: 503 });
+        const custom = () => null;
+        const result = (0, classify_js_1.classifyError)(err, custom);
+        (0, vitest_1.expect)(result.category).toBe('retriable');
+        (0, vitest_1.expect)(result.code).toBe('SERVER_ERROR');
+    });
+});
+//# sourceMappingURL=classify.test.js.map

package/dist/__tests__/classify.test.js.map

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

package/dist/__tests__/retry.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=retry.test.d.ts.map

package/dist/__tests__/retry.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/retry.test.ts"],"names":[],"mappings":""}