ai-resilience 0.1.0

package/README.md

@@ -0,0 +1,80 @@
+# ai-resilience
+
+Phase 1 of `ai-resilience` is an axios-retry++ foundation for modern AI and backend systems. It keeps axios compatibility while adding configurable retry strategies, advanced jitter, retry conditions, hooks, structured logging, and strong TypeScript types.
+
+## Install
+
+```sh
+npm install ai-resilience axios axios-retry
+```
+
+## Quick start
+
+```ts
+import axios from "axios";
+import { applyAiResilience, ConsoleRetryLogger } from "ai-resilience";
+
+const client = axios.create({ baseURL: "https://api.example.com" });
+
+applyAiResilience(client, {
+  retries: 3,
+  strategy: "exponential",
+  baseDelayMs: 150,
+  maxDelayMs: 10_000,
+  jitter: "full",
+  logger: new ConsoleRetryLogger("info"),
+  hooks: {
+    onRetry: ({ attempt, nextDelayMs }) => {
+      console.log(`retry ${attempt} in ${nextDelayMs}ms`);
+    },
+  },
+});
+```
+
+## Features
+
+- Enhanced retry configuration built on top of `axios-retry`
+- Fixed, linear, and exponential retry strategies
+- None, full, equal, and decorrelated jitter
+- Retry method and status-code controls
+- Async custom retry conditions
+- EventEmitter-based hooks plus direct hook callbacks
+- Structured logger interface and console logger
+- TypeScript-first public API
+
+## API
+
+### `applyAiResilience(instance, config)`
+
+Installs retry behavior on an existing axios instance and returns `{ axios, hooks, config }`.
+
+### `createAiResilienceClient(config)`
+
+Creates a new axios instance with retry behavior already applied.
+
+### Retry config
+
+```ts
+type AiResilienceRetryConfig = {
+  retries?: number;
+  strategy?: "fixed" | "linear" | "exponential";
+  baseDelayMs?: number;
+  maxDelayMs?: number;
+  jitter?: "none" | "full" | "equal" | "decorrelated";
+  retryStatusCodes?: number[];
+  retryMethods?: string[];
+  retryCondition?: (error) => boolean | Promise<boolean>;
+  hooks?: RetryHooks;
+  logger?: RetryLogger;
+  metadata?: Record<string, unknown>;
+};
+```
+
+## Scripts
+
+```sh
+npm run build
+npm test
+npm run lint
+npm run format
+```

package/dist/index.cjs

@@ -0,0 +1,326 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ConsoleRetryLogger: () => ConsoleRetryLogger,
+  RetryHookEmitter: () => RetryHookEmitter,
+  applyAiResilience: () => applyAiResilience,
+  applyJitter: () => applyJitter,
+  calculateRetryDelay: () => calculateRetryDelay,
+  createAiResilienceClient: () => createAiResilienceClient,
+  createLogEntry: () => createLogEntry,
+  defaultRetryConfig: () => defaultRetryConfig,
+  isRetryableMethod: () => isRetryableMethod,
+  isRetryableStatus: () => isRetryableStatus,
+  normalizeRetryConfig: () => normalizeRetryConfig,
+  resolveRetryStrategy: () => resolveRetryStrategy,
+  retryStrategies: () => retryStrategies,
+  shouldRetry: () => shouldRetry
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/engine.ts
+var import_axios = __toESM(require("axios"), 1);
+var import_axios_retry2 = __toESM(require("axios-retry"), 1);
+
+// src/config.ts
+var import_zod = require("zod");
+var configSchema = import_zod.z.object({
+  retries: import_zod.z.number().int().min(0).optional(),
+  strategy: import_zod.z.enum(["fixed", "linear", "exponential"]).optional(),
+  baseDelayMs: import_zod.z.number().min(0).optional(),
+  maxDelayMs: import_zod.z.number().min(0).optional(),
+  jitter: import_zod.z.enum(["none", "full", "equal", "decorrelated"]).optional(),
+  retryStatusCodes: import_zod.z.array(import_zod.z.number().int().min(100).max(599)).optional(),
+  retryMethods: import_zod.z.array(import_zod.z.string().min(1)).optional(),
+  metadata: import_zod.z.record(import_zod.z.unknown()).optional()
+});
+var defaultRetryConfig = {
+  retries: 3,
+  strategy: "exponential",
+  baseDelayMs: 150,
+  maxDelayMs: 3e4,
+  jitter: "full"
+};
+function normalizeRetryConfig(config = {}) {
+  configSchema.parse(config);
+  return {
+    ...defaultRetryConfig,
+    ...config
+  };
+}
+
+// src/conditions.ts
+var import_axios_retry = __toESM(require("axios-retry"), 1);
+var DEFAULT_RETRY_METHODS = ["delete", "get", "head", "options", "put"];
+var DEFAULT_RETRY_STATUS_CODES = [408, 409, 425, 429, 500, 502, 503, 504];
+function isRetryableMethod(error, retryMethods = DEFAULT_RETRY_METHODS) {
+  const method = error.config?.method?.toLowerCase();
+  return method ? retryMethods.map((item) => item.toLowerCase()).includes(method) : true;
+}
+function isRetryableStatus(error, retryStatusCodes = DEFAULT_RETRY_STATUS_CODES) {
+  const status = error.response?.status;
+  return typeof status === "number" && retryStatusCodes.includes(status);
+}
+async function shouldRetry(error, config = {}) {
+  if (config.retryCondition) {
+    return config.retryCondition(error);
+  }
+  if (!isRetryableMethod(error, config.retryMethods)) {
+    return false;
+  }
+  return import_axios_retry.default.isNetworkOrIdempotentRequestError(error) || isRetryableStatus(error, config.retryStatusCodes);
+}
+
+// src/jitter.ts
+var clamp = (value, max) => Math.min(Math.max(0, value), max);
+function applyJitter(delayMs, options = {}) {
+  const strategy = options.strategy ?? "none";
+  const maxDelayMs = options.maxDelayMs ?? Number.POSITIVE_INFINITY;
+  const random = options.random ?? Math.random;
+  if (strategy === "none") {
+    return clamp(delayMs, maxDelayMs);
+  }
+  if (strategy === "full") {
+    return clamp(random() * delayMs, maxDelayMs);
+  }
+  if (strategy === "equal") {
+    const half = delayMs / 2;
+    return clamp(half + random() * half, maxDelayMs);
+  }
+  const base = options.baseDelayMs ?? delayMs;
+  const previous = options.previousDelayMs ?? base;
+  const next = base + random() * Math.max(base, previous * 3 - base);
+  return clamp(next, maxDelayMs);
+}
+
+// src/delay.ts
+function calculateRetryDelay(config, context) {
+  const baseDelayMs = config.baseDelayMs ?? 100;
+  const maxDelayMs = config.maxDelayMs ?? 3e4;
+  const attempt = Math.max(1, context.attempt);
+  let delayMs;
+  switch (config.strategy ?? "exponential") {
+    case "fixed":
+      delayMs = baseDelayMs;
+      break;
+    case "linear":
+      delayMs = baseDelayMs * attempt;
+      break;
+    case "exponential":
+    default:
+      delayMs = baseDelayMs * 2 ** (attempt - 1);
+      break;
+  }
+  return Math.round(
+    applyJitter(Math.min(delayMs, maxDelayMs), {
+      strategy: config.jitter ?? "full",
+      previousDelayMs: context.previousDelayMs,
+      baseDelayMs,
+      maxDelayMs,
+      random: context.random
+    })
+  );
+}
+
+// src/hooks.ts
+var import_eventemitter3 = __toESM(require("eventemitter3"), 1);
+var RetryHookEmitter = class extends import_eventemitter3.default {
+  constructor(hooks = {}) {
+    super();
+    this.hooks = hooks;
+  }
+  hooks;
+  async emitRetry(context) {
+    this.emit("retry", context);
+    await this.hooks.onRetry?.(context);
+  }
+  async emitSuccess(context) {
+    this.emit("success", context);
+    await this.hooks.onSuccess?.(context);
+  }
+  async emitGiveUp(context) {
+    this.emit("giveUp", context);
+    await this.hooks.onGiveUp?.(context);
+  }
+};
+
+// src/logger.ts
+var ConsoleRetryLogger = class {
+  constructor(minLevel = "info") {
+    this.minLevel = minLevel;
+  }
+  minLevel;
+  log(entry) {
+    if (levelWeight(entry.level) < levelWeight(this.minLevel)) {
+      return;
+    }
+    const payload = {
+      event: entry.event,
+      timestamp: entry.timestamp,
+      ...entry.metadata
+    };
+    console[entry.level === "debug" ? "debug" : entry.level](entry.message, payload);
+  }
+};
+function createLogEntry(level, event, message, metadata) {
+  return {
+    level,
+    event,
+    message,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    metadata
+  };
+}
+function levelWeight(level) {
+  return { debug: 10, info: 20, warn: 30, error: 40 }[level];
+}
+
+// src/engine.ts
+function applyAiResilience(instance, config = {}) {
+  const resolved = normalizeRetryConfig(config);
+  const hooks = new RetryHookEmitter(resolved.hooks);
+  let previousDelayMs;
+  (0, import_axios_retry2.default)(instance, {
+    ...resolved,
+    retries: resolved.retries,
+    retryCondition: (error) => shouldRetry(error, resolved),
+    retryDelay: (retryCount, error) => {
+      const nextDelayMs = calculateRetryDelay(resolved, {
+        attempt: retryCount,
+        previousDelayMs
+      });
+      previousDelayMs = nextDelayMs;
+      const requestConfig = error.config ?? {};
+      void hooks.emitRetry({
+        attempt: retryCount,
+        retries: resolved.retries,
+        error,
+        requestConfig,
+        nextDelayMs
+      });
+      resolved.logger?.log(
+        createLogEntry("warn", "retry.scheduled", "Retry scheduled", {
+          attempt: retryCount,
+          retries: resolved.retries,
+          delayMs: nextDelayMs,
+          method: requestConfig.method,
+          url: requestConfig.url,
+          ...resolved.metadata
+        })
+      );
+      return nextDelayMs;
+    }
+  });
+  instance.interceptors.response.use(
+    async (response) => {
+      await hooks.emitSuccess({
+        attempt: Number(response.config?.["axios-retry"]?.retryCount ?? 0),
+        response,
+        requestConfig: response.config
+      });
+      return response;
+    },
+    async (error) => {
+      const retryState = error.config?.["axios-retry"];
+      const attempts = Number(retryState?.retryCount ?? 0);
+      if (attempts >= resolved.retries) {
+        await hooks.emitGiveUp({
+          attempts,
+          error,
+          requestConfig: error.config ?? {}
+        });
+        resolved.logger?.log(
+          createLogEntry("error", "retry.give_up", "Retry attempts exhausted", {
+            attempts,
+            method: error.config?.method,
+            url: error.config?.url,
+            ...resolved.metadata
+          })
+        );
+      }
+      throw error;
+    }
+  );
+  return {
+    axios: instance,
+    hooks,
+    config: resolved
+  };
+}
+function createAiResilienceClient(config = {}) {
+  return applyAiResilience(import_axios.default.create(), config);
+}
+
+// src/strategies.ts
+var retryStrategies = {
+  conservative: {
+    retries: 2,
+    strategy: "exponential",
+    baseDelayMs: 250,
+    maxDelayMs: 5e3,
+    jitter: "equal"
+  },
+  balanced: {
+    retries: 3,
+    strategy: "exponential",
+    baseDelayMs: 150,
+    maxDelayMs: 15e3,
+    jitter: "full"
+  },
+  aggressive: {
+    retries: 5,
+    strategy: "exponential",
+    baseDelayMs: 100,
+    maxDelayMs: 3e4,
+    jitter: "decorrelated"
+  }
+};
+function resolveRetryStrategy(strategy) {
+  return typeof strategy === "string" ? retryStrategies[strategy] : strategy;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ConsoleRetryLogger,
+  RetryHookEmitter,
+  applyAiResilience,
+  applyJitter,
+  calculateRetryDelay,
+  createAiResilienceClient,
+  createLogEntry,
+  defaultRetryConfig,
+  isRetryableMethod,
+  isRetryableStatus,
+  normalizeRetryConfig,
+  resolveRetryStrategy,
+  retryStrategies,
+  shouldRetry
+});

package/dist/index.d.cts

@@ -0,0 +1,144 @@
+import { AxiosInstance, AxiosError, AxiosRequestConfig, AxiosResponse } from 'axios';
+import EventEmitter from 'eventemitter3';
+import { IAxiosRetryConfig } from 'axios-retry';
+
+type RetryHookEvents<T = unknown> = {
+    retry: (context: RetryAttemptContext<T>) => void;
+    success: (context: RetrySuccessContext<T>) => void;
+    giveUp: (context: RetryGiveUpContext<T>) => void;
+};
+declare class RetryHookEmitter<T = unknown> extends EventEmitter<RetryHookEvents<T>> {
+    private readonly hooks;
+    constructor(hooks?: RetryHooks<T>);
+    emitRetry(context: RetryAttemptContext<T>): Promise<void>;
+    emitSuccess(context: RetrySuccessContext<T>): Promise<void>;
+    emitGiveUp(context: RetryGiveUpContext<T>): Promise<void>;
+}
+
+type RetryStrategy = "fixed" | "linear" | "exponential";
+type JitterStrategy = "none" | "full" | "equal" | "decorrelated";
+type LogLevel = "debug" | "info" | "warn" | "error";
+interface RetryAttemptContext<T = unknown> {
+    attempt: number;
+    retries: number;
+    error: AxiosError<T>;
+    requestConfig: AxiosRequestConfig;
+    nextDelayMs: number;
+}
+interface RetrySuccessContext<T = unknown> {
+    attempt: number;
+    response: AxiosResponse<T>;
+    requestConfig: AxiosRequestConfig;
+}
+interface RetryGiveUpContext<T = unknown> {
+    attempts: number;
+    error: AxiosError<T>;
+    requestConfig: AxiosRequestConfig;
+}
+interface RetryHooks<T = unknown> {
+    onRetry?: (context: RetryAttemptContext<T>) => void | Promise<void>;
+    onSuccess?: (context: RetrySuccessContext<T>) => void | Promise<void>;
+    onGiveUp?: (context: RetryGiveUpContext<T>) => void | Promise<void>;
+}
+interface StructuredLogEntry {
+    level: LogLevel;
+    event: string;
+    message: string;
+    timestamp: string;
+    metadata?: Record<string, unknown>;
+}
+interface RetryLogger {
+    log(entry: StructuredLogEntry): void;
+}
+interface AiResilienceRetryConfig<T = unknown> extends Omit<IAxiosRetryConfig, "retries" | "retryDelay" | "retryCondition" | "onRetry"> {
+    retries?: number;
+    strategy?: RetryStrategy;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    jitter?: JitterStrategy;
+    retryStatusCodes?: number[];
+    retryMethods?: string[];
+    retryCondition?: (error: AxiosError<T>) => boolean | Promise<boolean>;
+    hooks?: RetryHooks<T>;
+    logger?: RetryLogger;
+    metadata?: Record<string, unknown>;
+}
+interface NormalizedAiResilienceRetryConfig<T = unknown> extends AiResilienceRetryConfig<T> {
+    retries: number;
+    strategy: RetryStrategy;
+    baseDelayMs: number;
+    maxDelayMs: number;
+    jitter: JitterStrategy;
+}
+interface AiResilienceClient<T = unknown> {
+    axios: AxiosInstance;
+    hooks: RetryHookEmitter<T>;
+    config: NormalizedAiResilienceRetryConfig<T>;
+}
+
+declare function applyAiResilience<T = unknown>(instance: AxiosInstance, config?: AiResilienceRetryConfig<T>): AiResilienceClient<T>;
+declare function createAiResilienceClient<T = unknown>(config?: AiResilienceRetryConfig<T>): AiResilienceClient<T>;
+
+interface DelayContext {
+    attempt: number;
+    previousDelayMs?: number;
+    random?: () => number;
+}
+declare function calculateRetryDelay<T = unknown>(config: AiResilienceRetryConfig<T>, context: DelayContext): number;
+
+interface JitterOptions {
+    strategy?: JitterStrategy;
+    previousDelayMs?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    random?: () => number;
+}
+declare function applyJitter(delayMs: number, options?: JitterOptions): number;
+
+declare function isRetryableMethod(error: AxiosError, retryMethods?: string[]): boolean;
+declare function isRetryableStatus(error: AxiosError, retryStatusCodes?: number[]): boolean;
+declare function shouldRetry<T = unknown>(error: AxiosError<T>, config?: AiResilienceRetryConfig<T>): Promise<boolean>;
+
+declare class ConsoleRetryLogger implements RetryLogger {
+    private readonly minLevel;
+    constructor(minLevel?: LogLevel);
+    log(entry: StructuredLogEntry): void;
+}
+declare function createLogEntry(level: LogLevel, event: string, message: string, metadata?: Record<string, unknown>): StructuredLogEntry;
+
+declare const defaultRetryConfig: {
+    readonly retries: 3;
+    readonly strategy: "exponential";
+    readonly baseDelayMs: 150;
+    readonly maxDelayMs: 30000;
+    readonly jitter: "full";
+};
+declare function normalizeRetryConfig<T = unknown>(config?: AiResilienceRetryConfig<T>): NormalizedAiResilienceRetryConfig<T>;
+
+declare const retryStrategies: {
+    readonly conservative: {
+        readonly retries: 2;
+        readonly strategy: "exponential";
+        readonly baseDelayMs: 250;
+        readonly maxDelayMs: 5000;
+        readonly jitter: "equal";
+    };
+    readonly balanced: {
+        readonly retries: 3;
+        readonly strategy: "exponential";
+        readonly baseDelayMs: 150;
+        readonly maxDelayMs: 15000;
+        readonly jitter: "full";
+    };
+    readonly aggressive: {
+        readonly retries: 5;
+        readonly strategy: "exponential";
+        readonly baseDelayMs: 100;
+        readonly maxDelayMs: 30000;
+        readonly jitter: "decorrelated";
+    };
+};
+type NamedRetryStrategy = keyof typeof retryStrategies;
+declare function resolveRetryStrategy(strategy: NamedRetryStrategy | AiResilienceRetryConfig): AiResilienceRetryConfig;
+
+export { type AiResilienceClient, type AiResilienceRetryConfig, ConsoleRetryLogger, type JitterStrategy, type LogLevel, type RetryAttemptContext, type RetryGiveUpContext, RetryHookEmitter, type RetryHooks, type RetryLogger, type RetryStrategy, type RetrySuccessContext, type StructuredLogEntry, applyAiResilience, applyJitter, calculateRetryDelay, createAiResilienceClient, createLogEntry, defaultRetryConfig, isRetryableMethod, isRetryableStatus, normalizeRetryConfig, resolveRetryStrategy, retryStrategies, shouldRetry };

package/dist/index.d.ts

@@ -0,0 +1,144 @@
+import { AxiosInstance, AxiosError, AxiosRequestConfig, AxiosResponse } from 'axios';
+import EventEmitter from 'eventemitter3';
+import { IAxiosRetryConfig } from 'axios-retry';
+
+type RetryHookEvents<T = unknown> = {
+    retry: (context: RetryAttemptContext<T>) => void;
+    success: (context: RetrySuccessContext<T>) => void;
+    giveUp: (context: RetryGiveUpContext<T>) => void;
+};
+declare class RetryHookEmitter<T = unknown> extends EventEmitter<RetryHookEvents<T>> {
+    private readonly hooks;
+    constructor(hooks?: RetryHooks<T>);
+    emitRetry(context: RetryAttemptContext<T>): Promise<void>;
+    emitSuccess(context: RetrySuccessContext<T>): Promise<void>;
+    emitGiveUp(context: RetryGiveUpContext<T>): Promise<void>;
+}
+
+type RetryStrategy = "fixed" | "linear" | "exponential";
+type JitterStrategy = "none" | "full" | "equal" | "decorrelated";
+type LogLevel = "debug" | "info" | "warn" | "error";
+interface RetryAttemptContext<T = unknown> {
+    attempt: number;
+    retries: number;
+    error: AxiosError<T>;
+    requestConfig: AxiosRequestConfig;
+    nextDelayMs: number;
+}
+interface RetrySuccessContext<T = unknown> {
+    attempt: number;
+    response: AxiosResponse<T>;
+    requestConfig: AxiosRequestConfig;
+}
+interface RetryGiveUpContext<T = unknown> {
+    attempts: number;
+    error: AxiosError<T>;
+    requestConfig: AxiosRequestConfig;
+}
+interface RetryHooks<T = unknown> {
+    onRetry?: (context: RetryAttemptContext<T>) => void | Promise<void>;
+    onSuccess?: (context: RetrySuccessContext<T>) => void | Promise<void>;
+    onGiveUp?: (context: RetryGiveUpContext<T>) => void | Promise<void>;
+}
+interface StructuredLogEntry {
+    level: LogLevel;
+    event: string;
+    message: string;
+    timestamp: string;
+    metadata?: Record<string, unknown>;
+}
+interface RetryLogger {
+    log(entry: StructuredLogEntry): void;
+}
+interface AiResilienceRetryConfig<T = unknown> extends Omit<IAxiosRetryConfig, "retries" | "retryDelay" | "retryCondition" | "onRetry"> {
+    retries?: number;
+    strategy?: RetryStrategy;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    jitter?: JitterStrategy;
+    retryStatusCodes?: number[];
+    retryMethods?: string[];
+    retryCondition?: (error: AxiosError<T>) => boolean | Promise<boolean>;
+    hooks?: RetryHooks<T>;
+    logger?: RetryLogger;
+    metadata?: Record<string, unknown>;
+}
+interface NormalizedAiResilienceRetryConfig<T = unknown> extends AiResilienceRetryConfig<T> {
+    retries: number;
+    strategy: RetryStrategy;
+    baseDelayMs: number;
+    maxDelayMs: number;
+    jitter: JitterStrategy;
+}
+interface AiResilienceClient<T = unknown> {
+    axios: AxiosInstance;
+    hooks: RetryHookEmitter<T>;
+    config: NormalizedAiResilienceRetryConfig<T>;
+}
+
+declare function applyAiResilience<T = unknown>(instance: AxiosInstance, config?: AiResilienceRetryConfig<T>): AiResilienceClient<T>;
+declare function createAiResilienceClient<T = unknown>(config?: AiResilienceRetryConfig<T>): AiResilienceClient<T>;
+
+interface DelayContext {
+    attempt: number;
+    previousDelayMs?: number;
+    random?: () => number;
+}
+declare function calculateRetryDelay<T = unknown>(config: AiResilienceRetryConfig<T>, context: DelayContext): number;
+
+interface JitterOptions {
+    strategy?: JitterStrategy;
+    previousDelayMs?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    random?: () => number;
+}
+declare function applyJitter(delayMs: number, options?: JitterOptions): number;
+
+declare function isRetryableMethod(error: AxiosError, retryMethods?: string[]): boolean;
+declare function isRetryableStatus(error: AxiosError, retryStatusCodes?: number[]): boolean;
+declare function shouldRetry<T = unknown>(error: AxiosError<T>, config?: AiResilienceRetryConfig<T>): Promise<boolean>;
+
+declare class ConsoleRetryLogger implements RetryLogger {
+    private readonly minLevel;
+    constructor(minLevel?: LogLevel);
+    log(entry: StructuredLogEntry): void;
+}
+declare function createLogEntry(level: LogLevel, event: string, message: string, metadata?: Record<string, unknown>): StructuredLogEntry;
+
+declare const defaultRetryConfig: {
+    readonly retries: 3;
+    readonly strategy: "exponential";
+    readonly baseDelayMs: 150;
+    readonly maxDelayMs: 30000;
+    readonly jitter: "full";
+};
+declare function normalizeRetryConfig<T = unknown>(config?: AiResilienceRetryConfig<T>): NormalizedAiResilienceRetryConfig<T>;
+
+declare const retryStrategies: {
+    readonly conservative: {
+        readonly retries: 2;
+        readonly strategy: "exponential";
+        readonly baseDelayMs: 250;
+        readonly maxDelayMs: 5000;
+        readonly jitter: "equal";
+    };
+    readonly balanced: {
+        readonly retries: 3;
+        readonly strategy: "exponential";
+        readonly baseDelayMs: 150;
+        readonly maxDelayMs: 15000;
+        readonly jitter: "full";
+    };
+    readonly aggressive: {
+        readonly retries: 5;
+        readonly strategy: "exponential";
+        readonly baseDelayMs: 100;
+        readonly maxDelayMs: 30000;
+        readonly jitter: "decorrelated";
+    };
+};
+type NamedRetryStrategy = keyof typeof retryStrategies;
+declare function resolveRetryStrategy(strategy: NamedRetryStrategy | AiResilienceRetryConfig): AiResilienceRetryConfig;
+
+export { type AiResilienceClient, type AiResilienceRetryConfig, ConsoleRetryLogger, type JitterStrategy, type LogLevel, type RetryAttemptContext, type RetryGiveUpContext, RetryHookEmitter, type RetryHooks, type RetryLogger, type RetryStrategy, type RetrySuccessContext, type StructuredLogEntry, applyAiResilience, applyJitter, calculateRetryDelay, createAiResilienceClient, createLogEntry, defaultRetryConfig, isRetryableMethod, isRetryableStatus, normalizeRetryConfig, resolveRetryStrategy, retryStrategies, shouldRetry };

package/dist/index.js

@@ -0,0 +1,276 @@
+// src/engine.ts
+import axios from "axios";
+import axiosRetry2 from "axios-retry";
+
+// src/config.ts
+import { z } from "zod";
+var configSchema = z.object({
+  retries: z.number().int().min(0).optional(),
+  strategy: z.enum(["fixed", "linear", "exponential"]).optional(),
+  baseDelayMs: z.number().min(0).optional(),
+  maxDelayMs: z.number().min(0).optional(),
+  jitter: z.enum(["none", "full", "equal", "decorrelated"]).optional(),
+  retryStatusCodes: z.array(z.number().int().min(100).max(599)).optional(),
+  retryMethods: z.array(z.string().min(1)).optional(),
+  metadata: z.record(z.unknown()).optional()
+});
+var defaultRetryConfig = {
+  retries: 3,
+  strategy: "exponential",
+  baseDelayMs: 150,
+  maxDelayMs: 3e4,
+  jitter: "full"
+};
+function normalizeRetryConfig(config = {}) {
+  configSchema.parse(config);
+  return {
+    ...defaultRetryConfig,
+    ...config
+  };
+}
+
+// src/conditions.ts
+import axiosRetry from "axios-retry";
+var DEFAULT_RETRY_METHODS = ["delete", "get", "head", "options", "put"];
+var DEFAULT_RETRY_STATUS_CODES = [408, 409, 425, 429, 500, 502, 503, 504];
+function isRetryableMethod(error, retryMethods = DEFAULT_RETRY_METHODS) {
+  const method = error.config?.method?.toLowerCase();
+  return method ? retryMethods.map((item) => item.toLowerCase()).includes(method) : true;
+}
+function isRetryableStatus(error, retryStatusCodes = DEFAULT_RETRY_STATUS_CODES) {
+  const status = error.response?.status;
+  return typeof status === "number" && retryStatusCodes.includes(status);
+}
+async function shouldRetry(error, config = {}) {
+  if (config.retryCondition) {
+    return config.retryCondition(error);
+  }
+  if (!isRetryableMethod(error, config.retryMethods)) {
+    return false;
+  }
+  return axiosRetry.isNetworkOrIdempotentRequestError(error) || isRetryableStatus(error, config.retryStatusCodes);
+}
+
+// src/jitter.ts
+var clamp = (value, max) => Math.min(Math.max(0, value), max);
+function applyJitter(delayMs, options = {}) {
+  const strategy = options.strategy ?? "none";
+  const maxDelayMs = options.maxDelayMs ?? Number.POSITIVE_INFINITY;
+  const random = options.random ?? Math.random;
+  if (strategy === "none") {
+    return clamp(delayMs, maxDelayMs);
+  }
+  if (strategy === "full") {
+    return clamp(random() * delayMs, maxDelayMs);
+  }
+  if (strategy === "equal") {
+    const half = delayMs / 2;
+    return clamp(half + random() * half, maxDelayMs);
+  }
+  const base = options.baseDelayMs ?? delayMs;
+  const previous = options.previousDelayMs ?? base;
+  const next = base + random() * Math.max(base, previous * 3 - base);
+  return clamp(next, maxDelayMs);
+}
+
+// src/delay.ts
+function calculateRetryDelay(config, context) {
+  const baseDelayMs = config.baseDelayMs ?? 100;
+  const maxDelayMs = config.maxDelayMs ?? 3e4;
+  const attempt = Math.max(1, context.attempt);
+  let delayMs;
+  switch (config.strategy ?? "exponential") {
+    case "fixed":
+      delayMs = baseDelayMs;
+      break;
+    case "linear":
+      delayMs = baseDelayMs * attempt;
+      break;
+    case "exponential":
+    default:
+      delayMs = baseDelayMs * 2 ** (attempt - 1);
+      break;
+  }
+  return Math.round(
+    applyJitter(Math.min(delayMs, maxDelayMs), {
+      strategy: config.jitter ?? "full",
+      previousDelayMs: context.previousDelayMs,
+      baseDelayMs,
+      maxDelayMs,
+      random: context.random
+    })
+  );
+}
+
+// src/hooks.ts
+import EventEmitter from "eventemitter3";
+var RetryHookEmitter = class extends EventEmitter {
+  constructor(hooks = {}) {
+    super();
+    this.hooks = hooks;
+  }
+  hooks;
+  async emitRetry(context) {
+    this.emit("retry", context);
+    await this.hooks.onRetry?.(context);
+  }
+  async emitSuccess(context) {
+    this.emit("success", context);
+    await this.hooks.onSuccess?.(context);
+  }
+  async emitGiveUp(context) {
+    this.emit("giveUp", context);
+    await this.hooks.onGiveUp?.(context);
+  }
+};
+
+// src/logger.ts
+var ConsoleRetryLogger = class {
+  constructor(minLevel = "info") {
+    this.minLevel = minLevel;
+  }
+  minLevel;
+  log(entry) {
+    if (levelWeight(entry.level) < levelWeight(this.minLevel)) {
+      return;
+    }
+    const payload = {
+      event: entry.event,
+      timestamp: entry.timestamp,
+      ...entry.metadata
+    };
+    console[entry.level === "debug" ? "debug" : entry.level](entry.message, payload);
+  }
+};
+function createLogEntry(level, event, message, metadata) {
+  return {
+    level,
+    event,
+    message,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    metadata
+  };
+}
+function levelWeight(level) {
+  return { debug: 10, info: 20, warn: 30, error: 40 }[level];
+}
+
+// src/engine.ts
+function applyAiResilience(instance, config = {}) {
+  const resolved = normalizeRetryConfig(config);
+  const hooks = new RetryHookEmitter(resolved.hooks);
+  let previousDelayMs;
+  axiosRetry2(instance, {
+    ...resolved,
+    retries: resolved.retries,
+    retryCondition: (error) => shouldRetry(error, resolved),
+    retryDelay: (retryCount, error) => {
+      const nextDelayMs = calculateRetryDelay(resolved, {
+        attempt: retryCount,
+        previousDelayMs
+      });
+      previousDelayMs = nextDelayMs;
+      const requestConfig = error.config ?? {};
+      void hooks.emitRetry({
+        attempt: retryCount,
+        retries: resolved.retries,
+        error,
+        requestConfig,
+        nextDelayMs
+      });
+      resolved.logger?.log(
+        createLogEntry("warn", "retry.scheduled", "Retry scheduled", {
+          attempt: retryCount,
+          retries: resolved.retries,
+          delayMs: nextDelayMs,
+          method: requestConfig.method,
+          url: requestConfig.url,
+          ...resolved.metadata
+        })
+      );
+      return nextDelayMs;
+    }
+  });
+  instance.interceptors.response.use(
+    async (response) => {
+      await hooks.emitSuccess({
+        attempt: Number(response.config?.["axios-retry"]?.retryCount ?? 0),
+        response,
+        requestConfig: response.config
+      });
+      return response;
+    },
+    async (error) => {
+      const retryState = error.config?.["axios-retry"];
+      const attempts = Number(retryState?.retryCount ?? 0);
+      if (attempts >= resolved.retries) {
+        await hooks.emitGiveUp({
+          attempts,
+          error,
+          requestConfig: error.config ?? {}
+        });
+        resolved.logger?.log(
+          createLogEntry("error", "retry.give_up", "Retry attempts exhausted", {
+            attempts,
+            method: error.config?.method,
+            url: error.config?.url,
+            ...resolved.metadata
+          })
+        );
+      }
+      throw error;
+    }
+  );
+  return {
+    axios: instance,
+    hooks,
+    config: resolved
+  };
+}
+function createAiResilienceClient(config = {}) {
+  return applyAiResilience(axios.create(), config);
+}
+
+// src/strategies.ts
+var retryStrategies = {
+  conservative: {
+    retries: 2,
+    strategy: "exponential",
+    baseDelayMs: 250,
+    maxDelayMs: 5e3,
+    jitter: "equal"
+  },
+  balanced: {
+    retries: 3,
+    strategy: "exponential",
+    baseDelayMs: 150,
+    maxDelayMs: 15e3,
+    jitter: "full"
+  },
+  aggressive: {
+    retries: 5,
+    strategy: "exponential",
+    baseDelayMs: 100,
+    maxDelayMs: 3e4,
+    jitter: "decorrelated"
+  }
+};
+function resolveRetryStrategy(strategy) {
+  return typeof strategy === "string" ? retryStrategies[strategy] : strategy;
+}
+export {
+  ConsoleRetryLogger,
+  RetryHookEmitter,
+  applyAiResilience,
+  applyJitter,
+  calculateRetryDelay,
+  createAiResilienceClient,
+  createLogEntry,
+  defaultRetryConfig,
+  isRetryableMethod,
+  isRetryableStatus,
+  normalizeRetryConfig,
+  resolveRetryStrategy,
+  retryStrategies,
+  shouldRetry
+};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "ai-resilience",
+  "version": "0.1.0",
+  "description": "Axios retry++ primitives for resilient AI and backend systems.",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint . --ext .ts",
+    "format": "prettier --write ."
+  },
+  "keywords": [
+    "axios",
+    "retry",
+    "axios-retry",
+    "resilience",
+    "ai"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "axios": "^1.7.9",
+    "axios-retry": "^4.5.0",
+    "eventemitter3": "^5.0.1",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "@typescript-eslint/eslint-plugin": "^8.18.2",
+    "@typescript-eslint/parser": "^8.18.2",
+    "eslint": "^9.17.0",
+    "prettier": "^3.4.2",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}