ai-sdk-rate-limiter 0.9.0 → 0.10.0

package/README.md

@@ -1431,7 +1431,14 @@ import type { StatsDClient } from 'ai-sdk-rate-limiter/statsd'
 
 ## Examples
 
-A full Next.js 15 App Router example is included at [`examples/nextjs/`](./examples/nextjs/). It demonstrates streaming chat with rate limiting, live cost display, and proper error handling for budget and rate limit errors.
+Four runnable examples are included, each with its own README:
+
+| Example | What it shows |
+|---|---|
+| [`examples/nextjs/`](./examples/nextjs/) | Next.js 15 App Router streaming chat — rate limiting, live cost display, budget error handling |
+| [`examples/multi-tenant-express/`](./examples/multi-tenant-express/) | Express API with per-user isolated limits (free/pro tiers), per-user cost reports, circuit breaker |
+| [`examples/batch-processing/`](./examples/batch-processing/) | Classify 30+ items concurrently without 429s — priority queuing, graceful shutdown, live cost tracking |
+| [`examples/budget-alerts/`](./examples/budget-alerts/) | Slack/webhook alerts on budget thresholds — instant `budgetHit` events + periodic spend summaries |
 
 ---
 

package/dist/errors-DcXM0HCM.d.cts

@@ -0,0 +1,68 @@
+/** Base class for all ai-sdk-rate-limiter errors */
+declare class RateLimiterError extends Error {
+    name: string;
+    constructor(message: string);
+}
+/**
+ * Thrown when a request cannot proceed because the rate limit was hit
+ * and the request either timed out waiting in the queue or exhausted all retries.
+ */
+declare class RateLimitExceededError extends RateLimiterError {
+    readonly model: string;
+    readonly limitType: 'rpm' | 'itpm' | 'otpm';
+    readonly limit: number;
+    readonly resetAt: number;
+    constructor(model: string, limitType: 'rpm' | 'itpm' | 'otpm', limit: number, resetAt: number);
+}
+/**
+ * Thrown when a request has waited in the queue longer than the configured timeout.
+ */
+declare class QueueTimeoutError extends RateLimiterError {
+    readonly model: string;
+    readonly waitedMs: number;
+    readonly queueDepth: number;
+    constructor(model: string, waitedMs: number, queueDepth: number);
+}
+/**
+ * Thrown when a new request arrives and the queue is at capacity.
+ */
+declare class QueueFullError extends RateLimiterError {
+    readonly model: string;
+    readonly maxSize: number;
+    constructor(model: string, maxSize: number);
+}
+/**
+ * Thrown when a request would exceed the configured cost budget.
+ */
+declare class BudgetExceededError extends RateLimiterError {
+    readonly model: string;
+    readonly currentCostUsd: number;
+    readonly limitUsd: number;
+    readonly period: 'hourly' | 'daily' | 'monthly';
+    constructor(model: string, currentCostUsd: number, limitUsd: number, period: 'hourly' | 'daily' | 'monthly');
+}
+/**
+ * Thrown when a request is blocked because the circuit breaker is open.
+ */
+declare class CircuitOpenError extends RateLimiterError {
+    readonly model: string;
+    readonly openUntilMs: number;
+    constructor(model: string, openUntilMs: number);
+}
+/**
+ * Thrown when a request arrives after shutdown() has been called.
+ */
+declare class ShutdownError extends RateLimiterError {
+    constructor();
+}
+/**
+ * Thrown when all retry attempts are exhausted.
+ */
+declare class RetryExhaustedError extends RateLimiterError {
+    readonly model: string;
+    readonly attempts: number;
+    readonly cause: unknown;
+    constructor(model: string, attempts: number, cause: unknown);
+}
+
+export { BudgetExceededError as B, CircuitOpenError as C, QueueFullError as Q, RateLimitExceededError as R, ShutdownError as S, QueueTimeoutError as a, RateLimiterError as b, RetryExhaustedError as c };

package/dist/errors-DcXM0HCM.d.ts

@@ -0,0 +1,68 @@
+/** Base class for all ai-sdk-rate-limiter errors */
+declare class RateLimiterError extends Error {
+    name: string;
+    constructor(message: string);
+}
+/**
+ * Thrown when a request cannot proceed because the rate limit was hit
+ * and the request either timed out waiting in the queue or exhausted all retries.
+ */
+declare class RateLimitExceededError extends RateLimiterError {
+    readonly model: string;
+    readonly limitType: 'rpm' | 'itpm' | 'otpm';
+    readonly limit: number;
+    readonly resetAt: number;
+    constructor(model: string, limitType: 'rpm' | 'itpm' | 'otpm', limit: number, resetAt: number);
+}
+/**
+ * Thrown when a request has waited in the queue longer than the configured timeout.
+ */
+declare class QueueTimeoutError extends RateLimiterError {
+    readonly model: string;
+    readonly waitedMs: number;
+    readonly queueDepth: number;
+    constructor(model: string, waitedMs: number, queueDepth: number);
+}
+/**
+ * Thrown when a new request arrives and the queue is at capacity.
+ */
+declare class QueueFullError extends RateLimiterError {
+    readonly model: string;
+    readonly maxSize: number;
+    constructor(model: string, maxSize: number);
+}
+/**
+ * Thrown when a request would exceed the configured cost budget.
+ */
+declare class BudgetExceededError extends RateLimiterError {
+    readonly model: string;
+    readonly currentCostUsd: number;
+    readonly limitUsd: number;
+    readonly period: 'hourly' | 'daily' | 'monthly';
+    constructor(model: string, currentCostUsd: number, limitUsd: number, period: 'hourly' | 'daily' | 'monthly');
+}
+/**
+ * Thrown when a request is blocked because the circuit breaker is open.
+ */
+declare class CircuitOpenError extends RateLimiterError {
+    readonly model: string;
+    readonly openUntilMs: number;
+    constructor(model: string, openUntilMs: number);
+}
+/**
+ * Thrown when a request arrives after shutdown() has been called.
+ */
+declare class ShutdownError extends RateLimiterError {
+    constructor();
+}
+/**
+ * Thrown when all retry attempts are exhausted.
+ */
+declare class RetryExhaustedError extends RateLimiterError {
+    readonly model: string;
+    readonly attempts: number;
+    readonly cause: unknown;
+    constructor(model: string, attempts: number, cause: unknown);
+}
+
+export { BudgetExceededError as B, CircuitOpenError as C, QueueFullError as Q, RateLimitExceededError as R, ShutdownError as S, QueueTimeoutError as a, RateLimiterError as b, RetryExhaustedError as c };

package/dist/index.d.cts

@@ -1,5 +1,6 @@
 import { R as RateLimiterConfig, a as RateLimiter, P as Priority, M as ModelLimitOverride, b as ModelLimits } from './types-CUPpMRPE.cjs';
 export { B as BackoffStrategy, c as BudgetExceededAction, d as BudgetHitEvent, e as BudgetPeriod, C as CircuitBreakerConfig, f as CircuitClosedEvent, g as CircuitOpenEvent, h as CompletedEvent, i as CostConfig, j as CostReport, k as CostStore, D as DequeuedEvent, l as DroppedEvent, E as EventHandler, m as EventHandlers, n as EventMap, L as LimiterStatus, o as LimitsDetectedEvent, p as ModelStatus, q as PerRequestOptions, r as PeriodCostSummary, s as PersistedCostEntry, Q as QueueConfig, t as QueuedEvent, u as RateLimitStore, v as RateLimitedEvent, w as RetryConfig, x as RetryingEvent, S as ScopeConfig } from './types-CUPpMRPE.cjs';
+export { B as BudgetExceededError, C as CircuitOpenError, Q as QueueFullError, a as QueueTimeoutError, R as RateLimitExceededError, b as RateLimiterError, c as RetryExhaustedError, S as ShutdownError } from './errors-DcXM0HCM.cjs';
 
 /**
  * Create a rate limiter instance.
@@ -78,73 +79,6 @@ interface RawSdkProxyOptions {
  */
 declare function rateLimited<T extends object>(client: T, options?: RawSdkProxyOptions): T;
 
-/** Base class for all ai-sdk-rate-limiter errors */
-declare class RateLimiterError extends Error {
-    name: string;
-    constructor(message: string);
-}
-/**
- * Thrown when a request cannot proceed because the rate limit was hit
- * and the request either timed out waiting in the queue or exhausted all retries.
- */
-declare class RateLimitExceededError extends RateLimiterError {
-    readonly model: string;
-    readonly limitType: 'rpm' | 'itpm' | 'otpm';
-    readonly limit: number;
-    readonly resetAt: number;
-    constructor(model: string, limitType: 'rpm' | 'itpm' | 'otpm', limit: number, resetAt: number);
-}
-/**
- * Thrown when a request has waited in the queue longer than the configured timeout.
- */
-declare class QueueTimeoutError extends RateLimiterError {
-    readonly model: string;
-    readonly waitedMs: number;
-    readonly queueDepth: number;
-    constructor(model: string, waitedMs: number, queueDepth: number);
-}
-/**
- * Thrown when a new request arrives and the queue is at capacity.
- */
-declare class QueueFullError extends RateLimiterError {
-    readonly model: string;
-    readonly maxSize: number;
-    constructor(model: string, maxSize: number);
-}
-/**
- * Thrown when a request would exceed the configured cost budget.
- */
-declare class BudgetExceededError extends RateLimiterError {
-    readonly model: string;
-    readonly currentCostUsd: number;
-    readonly limitUsd: number;
-    readonly period: 'hourly' | 'daily' | 'monthly';
-    constructor(model: string, currentCostUsd: number, limitUsd: number, period: 'hourly' | 'daily' | 'monthly');
-}
-/**
- * Thrown when a request is blocked because the circuit breaker is open.
- */
-declare class CircuitOpenError extends RateLimiterError {
-    readonly model: string;
-    readonly openUntilMs: number;
-    constructor(model: string, openUntilMs: number);
-}
-/**
- * Thrown when a request arrives after shutdown() has been called.
- */
-declare class ShutdownError extends RateLimiterError {
-    constructor();
-}
-/**
- * Thrown when all retry attempts are exhausted.
- */
-declare class RetryExhaustedError extends RateLimiterError {
-    readonly model: string;
-    readonly attempts: number;
-    readonly cause: unknown;
-    constructor(model: string, attempts: number, cause: unknown);
-}
-
 /**
  * Look up rate limits and pricing for a model.
  * Resolution order:
@@ -238,4 +172,4 @@ declare const MISTRAL_MODELS: Record<string, ModelLimits>;
  */
 declare const COHERE_MODELS: Record<string, ModelLimits>;
 
-export { ANTHROPIC_MODELS, BudgetExceededError, COHERE_MODELS, CircuitOpenError, GOOGLE_MODELS, GROQ_MODELS, MISTRAL_MODELS, ModelLimitOverride, ModelLimits, OPENAI_MODELS, Priority, QueueFullError, QueueTimeoutError, RateLimitExceededError, RateLimiter, RateLimiterConfig, RateLimiterError, type RawSdkProxyOptions, RetryExhaustedError, ShutdownError, createRateLimiter, isKnownModel, rateLimited, resolveModelLimits };
+export { ANTHROPIC_MODELS, COHERE_MODELS, GOOGLE_MODELS, GROQ_MODELS, MISTRAL_MODELS, ModelLimitOverride, ModelLimits, OPENAI_MODELS, Priority, RateLimiter, RateLimiterConfig, type RawSdkProxyOptions, createRateLimiter, isKnownModel, rateLimited, resolveModelLimits };

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { R as RateLimiterConfig, a as RateLimiter, P as Priority, M as ModelLimitOverride, b as ModelLimits } from './types-CUPpMRPE.js';
 export { B as BackoffStrategy, c as BudgetExceededAction, d as BudgetHitEvent, e as BudgetPeriod, C as CircuitBreakerConfig, f as CircuitClosedEvent, g as CircuitOpenEvent, h as CompletedEvent, i as CostConfig, j as CostReport, k as CostStore, D as DequeuedEvent, l as DroppedEvent, E as EventHandler, m as EventHandlers, n as EventMap, L as LimiterStatus, o as LimitsDetectedEvent, p as ModelStatus, q as PerRequestOptions, r as PeriodCostSummary, s as PersistedCostEntry, Q as QueueConfig, t as QueuedEvent, u as RateLimitStore, v as RateLimitedEvent, w as RetryConfig, x as RetryingEvent, S as ScopeConfig } from './types-CUPpMRPE.js';
+export { B as BudgetExceededError, C as CircuitOpenError, Q as QueueFullError, a as QueueTimeoutError, R as RateLimitExceededError, b as RateLimiterError, c as RetryExhaustedError, S as ShutdownError } from './errors-DcXM0HCM.js';
 
 /**
  * Create a rate limiter instance.
@@ -78,73 +79,6 @@ interface RawSdkProxyOptions {
  */
 declare function rateLimited<T extends object>(client: T, options?: RawSdkProxyOptions): T;
 
-/** Base class for all ai-sdk-rate-limiter errors */
-declare class RateLimiterError extends Error {
-    name: string;
-    constructor(message: string);
-}
-/**
- * Thrown when a request cannot proceed because the rate limit was hit
- * and the request either timed out waiting in the queue or exhausted all retries.
- */
-declare class RateLimitExceededError extends RateLimiterError {
-    readonly model: string;
-    readonly limitType: 'rpm' | 'itpm' | 'otpm';
-    readonly limit: number;
-    readonly resetAt: number;
-    constructor(model: string, limitType: 'rpm' | 'itpm' | 'otpm', limit: number, resetAt: number);
-}
-/**
- * Thrown when a request has waited in the queue longer than the configured timeout.
- */
-declare class QueueTimeoutError extends RateLimiterError {
-    readonly model: string;
-    readonly waitedMs: number;
-    readonly queueDepth: number;
-    constructor(model: string, waitedMs: number, queueDepth: number);
-}
-/**
- * Thrown when a new request arrives and the queue is at capacity.
- */
-declare class QueueFullError extends RateLimiterError {
-    readonly model: string;
-    readonly maxSize: number;
-    constructor(model: string, maxSize: number);
-}
-/**
- * Thrown when a request would exceed the configured cost budget.
- */
-declare class BudgetExceededError extends RateLimiterError {
-    readonly model: string;
-    readonly currentCostUsd: number;
-    readonly limitUsd: number;
-    readonly period: 'hourly' | 'daily' | 'monthly';
-    constructor(model: string, currentCostUsd: number, limitUsd: number, period: 'hourly' | 'daily' | 'monthly');
-}
-/**
- * Thrown when a request is blocked because the circuit breaker is open.
- */
-declare class CircuitOpenError extends RateLimiterError {
-    readonly model: string;
-    readonly openUntilMs: number;
-    constructor(model: string, openUntilMs: number);
-}
-/**
- * Thrown when a request arrives after shutdown() has been called.
- */
-declare class ShutdownError extends RateLimiterError {
-    constructor();
-}
-/**
- * Thrown when all retry attempts are exhausted.
- */
-declare class RetryExhaustedError extends RateLimiterError {
-    readonly model: string;
-    readonly attempts: number;
-    readonly cause: unknown;
-    constructor(model: string, attempts: number, cause: unknown);
-}
-
 /**
  * Look up rate limits and pricing for a model.
  * Resolution order:
@@ -238,4 +172,4 @@ declare const MISTRAL_MODELS: Record<string, ModelLimits>;
  */
 declare const COHERE_MODELS: Record<string, ModelLimits>;
 
-export { ANTHROPIC_MODELS, BudgetExceededError, COHERE_MODELS, CircuitOpenError, GOOGLE_MODELS, GROQ_MODELS, MISTRAL_MODELS, ModelLimitOverride, ModelLimits, OPENAI_MODELS, Priority, QueueFullError, QueueTimeoutError, RateLimitExceededError, RateLimiter, RateLimiterConfig, RateLimiterError, type RawSdkProxyOptions, RetryExhaustedError, ShutdownError, createRateLimiter, isKnownModel, rateLimited, resolveModelLimits };
+export { ANTHROPIC_MODELS, COHERE_MODELS, GOOGLE_MODELS, GROQ_MODELS, MISTRAL_MODELS, ModelLimitOverride, ModelLimits, OPENAI_MODELS, Priority, RateLimiter, RateLimiterConfig, type RawSdkProxyOptions, createRateLimiter, isKnownModel, rateLimited, resolveModelLimits };

package/dist/middleware.cjs

@@ -0,0 +1,228 @@
+'use strict';
+
+// src/errors.ts
+var RateLimiterError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "RateLimiterError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var QueueTimeoutError = class extends RateLimiterError {
+  constructor(model, waitedMs, queueDepth) {
+    super(
+      `Request for model "${model}" timed out after waiting ${waitedMs}ms in the queue (current queue depth: ${queueDepth}).`
+    );
+    this.model = model;
+    this.waitedMs = waitedMs;
+    this.queueDepth = queueDepth;
+    this.name = "QueueTimeoutError";
+  }
+};
+var QueueFullError = class extends RateLimiterError {
+  constructor(model, maxSize) {
+    super(
+      `Queue for model "${model}" is full (maxSize: ${maxSize}). Increase queue.maxSize or reduce request rate.`
+    );
+    this.model = model;
+    this.maxSize = maxSize;
+    this.name = "QueueFullError";
+  }
+};
+var BudgetExceededError = class extends RateLimiterError {
+  constructor(model, currentCostUsd, limitUsd, period) {
+    super(
+      `Cost budget exceeded for model "${model}": $${currentCostUsd.toFixed(4)} used of $${limitUsd.toFixed(2)} ${period} budget.`
+    );
+    this.model = model;
+    this.currentCostUsd = currentCostUsd;
+    this.limitUsd = limitUsd;
+    this.period = period;
+    this.name = "BudgetExceededError";
+  }
+};
+var CircuitOpenError = class extends RateLimiterError {
+  constructor(model, openUntilMs) {
+    super(
+      `Circuit breaker for model "${model}" is open due to repeated failures. Requests are blocked until ${new Date(openUntilMs).toISOString()}.`
+    );
+    this.model = model;
+    this.openUntilMs = openUntilMs;
+    this.name = "CircuitOpenError";
+  }
+};
+var ShutdownError = class extends RateLimiterError {
+  constructor() {
+    super("Rate limiter is shutting down \u2014 new requests are not accepted.");
+    this.name = "ShutdownError";
+  }
+};
+
+// src/middleware.ts
+function createRateLimiterMiddleware(limiter, options = {}) {
+  const middleware = (req, res, next) => {
+    const scope = options.scope?.(req);
+    const priority = typeof options.priority === "function" ? options.priority(req) : options.priority;
+    const ctx = {
+      ...scope !== void 0 && { scope },
+      ...priority !== void 0 && { priority }
+    };
+    req["rateLimiter"] = ctx;
+    if (options.injectHeaders && !res.headersSent) {
+      const modelId = typeof options.injectHeaders === "function" ? options.injectHeaders(req) : options.injectHeaders;
+      const status = limiter.getStatus();
+      const modelStat = status.models.find((m) => m.modelId === modelId);
+      if (modelStat) {
+        res.setHeader("X-RateLimit-Model", modelId);
+        res.setHeader("X-RateLimit-Queue-Depth", modelStat.queueDepth);
+        res.setHeader("X-RateLimit-Requests-Window", modelStat.requestsInWindow);
+        if (modelStat.estimatedWaitMs > 0) {
+          res.setHeader("X-RateLimit-Estimated-Wait-Ms", modelStat.estimatedWaitMs);
+        }
+      }
+    }
+    next();
+  };
+  const errorHandler = (err, _req, res, next) => {
+    if (!(err instanceof RateLimiterError)) {
+      next(err);
+      return;
+    }
+    if (res.headersSent) {
+      next(err);
+      return;
+    }
+    const { status, body } = mapErrorToResponse(err);
+    res.status(status).json(body);
+  };
+  return { middleware, errorHandler };
+}
+function createRateLimiterErrorHandler(options = {}) {
+  return (err, _req, res, next) => {
+    if (!(err instanceof RateLimiterError)) {
+      next(err);
+      return;
+    }
+    if (res.headersSent) {
+      next(err);
+      return;
+    }
+    if (options.format) {
+      const custom = options.format(err);
+      if (custom == null) {
+        next(err);
+        return;
+      }
+      res.status(custom.status).json(custom.body);
+      return;
+    }
+    const { status, body } = mapErrorToResponse(err, options.includeDetails);
+    res.status(status).json(body);
+  };
+}
+function createHonoMiddleware(limiter, options = {}) {
+  return async (c, next) => {
+    const scope = options.scope?.(c);
+    const priority = typeof options.priority === "function" ? options.priority(c) : options.priority;
+    const ctx = {
+      ...scope !== void 0 && { scope },
+      ...priority !== void 0 && { priority }
+    };
+    c.set("rateLimiter", ctx);
+    if (options.injectHeaders) {
+      const modelId = typeof options.injectHeaders === "function" ? options.injectHeaders(c) : options.injectHeaders;
+      const status = limiter.getStatus();
+      const modelStat = status.models.find((m) => m.modelId === modelId);
+      if (modelStat) {
+        c.header("X-RateLimit-Model", modelId);
+        c.header("X-RateLimit-Queue-Depth", String(modelStat.queueDepth));
+        c.header("X-RateLimit-Requests-Window", String(modelStat.requestsInWindow));
+        if (modelStat.estimatedWaitMs > 0) {
+          c.header("X-RateLimit-Estimated-Wait-Ms", String(modelStat.estimatedWaitMs));
+        }
+      }
+    }
+    try {
+      await next();
+    } catch (err) {
+      if (err instanceof RateLimiterError) {
+        const { status, body } = mapErrorToResponse(err);
+        return c.json(body, status);
+      }
+      throw err;
+    }
+  };
+}
+function mapErrorToResponse(err, includeDetails = true) {
+  if (err instanceof QueueTimeoutError) {
+    return {
+      status: 503,
+      body: {
+        error: "Request queued too long. Try again shortly.",
+        code: "QUEUE_TIMEOUT",
+        ...includeDetails && {
+          retryAfterMs: 5e3,
+          queueDepth: err.queueDepth
+        }
+      }
+    };
+  }
+  if (err instanceof QueueFullError) {
+    return {
+      status: 503,
+      body: {
+        error: "Server is busy. Try again in a moment.",
+        code: "QUEUE_FULL"
+      }
+    };
+  }
+  if (err instanceof BudgetExceededError) {
+    return {
+      status: 402,
+      body: {
+        error: "AI usage budget exceeded.",
+        code: "BUDGET_EXCEEDED",
+        ...includeDetails && {
+          period: err.period,
+          limitUsd: err.limitUsd,
+          currentCostUsd: err.currentCostUsd
+        }
+      }
+    };
+  }
+  if (err instanceof CircuitOpenError) {
+    return {
+      status: 503,
+      body: {
+        error: "AI provider temporarily unavailable.",
+        code: "CIRCUIT_OPEN",
+        ...includeDetails && {
+          retryAfter: Math.max(0, Math.ceil((err.openUntilMs - Date.now()) / 1e3))
+        }
+      }
+    };
+  }
+  if (err instanceof ShutdownError) {
+    return {
+      status: 503,
+      body: {
+        error: "Service is shutting down.",
+        code: "SHUTDOWN"
+      }
+    };
+  }
+  return {
+    status: 429,
+    body: {
+      error: "Rate limit exceeded.",
+      code: "RATE_LIMITED"
+    }
+  };
+}
+
+exports.createHonoMiddleware = createHonoMiddleware;
+exports.createRateLimiterErrorHandler = createRateLimiterErrorHandler;
+exports.createRateLimiterMiddleware = createRateLimiterMiddleware;
+exports.mapErrorToResponse = mapErrorToResponse;
+//# sourceMappingURL=middleware.cjs.map
+//# sourceMappingURL=middleware.cjs.map

package/dist/middleware.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/middleware.ts"],"names":[],"mappings":"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","file":"middleware.cjs","sourcesContent":["/** Base class for all ai-sdk-rate-limiter errors */\nexport class RateLimiterError extends Error {\n  // Declared as mutable string so subclasses can assign in constructors\n  declare name: string\n\n  constructor(message: string) {\n    super(message)\n    this.name = 'RateLimiterError'\n    // Restore prototype chain (needed when extending built-ins in TS)\n    Object.setPrototypeOf(this, new.target.prototype)\n  }\n}\n\n/**\n * Thrown when a request cannot proceed because the rate limit was hit\n * and the request either timed out waiting in the queue or exhausted all retries.\n */\nexport class RateLimitExceededError extends RateLimiterError {\n  constructor(\n    public readonly model: string,\n    public readonly limitType: 'rpm' | 'itpm' | 'otpm',\n    public readonly limit: number,\n    public readonly resetAt: number,\n  ) {\n    super(\n      `Rate limit exceeded for model \"${model}\": ${limitType.toUpperCase()} limit of ${limit} hit. ` +\n        `Resets at ${new Date(resetAt).toISOString()}.`,\n    )\n    this.name = 'RateLimitExceededError'\n  }\n}\n\n/**\n * Thrown when a request has waited in the queue longer than the configured timeout.\n */\nexport class QueueTimeoutError extends RateLimiterError {\n  constructor(\n    public readonly model: string,\n    public readonly waitedMs: number,\n    public readonly queueDepth: number,\n  ) {\n    super(\n      `Request for model \"${model}\" timed out after waiting ${waitedMs}ms in the queue ` +\n        `(current queue depth: ${queueDepth}).`,\n    )\n    this.name = 'QueueTimeoutError'\n  }\n}\n\n/**\n * Thrown when a new request arrives and the queue is at capacity.\n */\nexport class QueueFullError extends RateLimiterError {\n  constructor(\n    public readonly model: string,\n    public readonly maxSize: number,\n  ) {\n    super(\n      `Queue for model \"${model}\" is full (maxSize: ${maxSize}). ` +\n        `Increase queue.maxSize or reduce request rate.`,\n    )\n    this.name = 'QueueFullError'\n  }\n}\n\n/**\n * Thrown when a request would exceed the configured cost budget.\n */\nexport class BudgetExceededError extends RateLimiterError {\n  constructor(\n    public readonly model: string,\n    public readonly currentCostUsd: number,\n    public readonly limitUsd: number,\n    public readonly period: 'hourly' | 'daily' | 'monthly',\n  ) {\n    super(\n      `Cost budget exceeded for model \"${model}\": ` +\n        `$${currentCostUsd.toFixed(4)} used of $${limitUsd.toFixed(2)} ${period} budget.`,\n    )\n    this.name = 'BudgetExceededError'\n  }\n}\n\n/**\n * Thrown when a request is blocked because the circuit breaker is open.\n */\nexport class CircuitOpenError extends RateLimiterError {\n  constructor(\n    public readonly model: string,\n    public readonly openUntilMs: number,\n  ) {\n    super(\n      `Circuit breaker for model \"${model}\" is open due to repeated failures. ` +\n        `Requests are blocked until ${new Date(openUntilMs).toISOString()}.`,\n    )\n    this.name = 'CircuitOpenError'\n  }\n}\n\n/**\n * Thrown when a request arrives after shutdown() has been called.\n */\nexport class ShutdownError extends RateLimiterError {\n  constructor() {\n    super('Rate limiter is shutting down — new requests are not accepted.')\n    this.name = 'ShutdownError'\n  }\n}\n\n/**\n * Thrown when all retry attempts are exhausted.\n */\nexport class RetryExhaustedError extends RateLimiterError {\n  constructor(\n    public readonly model: string,\n    public readonly attempts: number,\n    public readonly cause: unknown,\n  ) {\n    super(\n      `All ${attempts} retry attempts exhausted for model \"${model}\". ` +\n        `Last error: ${cause instanceof Error ? cause.message : String(cause)}`,\n    )\n    this.name = 'RetryExhaustedError'\n    if (cause instanceof Error) {\n      this.stack = `${this.stack}\\nCaused by: ${cause.stack}`\n    }\n  }\n}\n","/**\n * ai-sdk-rate-limiter/middleware\n *\n * Framework-agnostic middleware helpers. Reduces per-route boilerplate to zero:\n * scope extraction, priority assignment, and rate-limiter error handling are\n * all handled at the middleware layer.\n *\n * @example Express\n * ```typescript\n * import { createRateLimiterMiddleware } from 'ai-sdk-rate-limiter/middleware'\n *\n * const { middleware, errorHandler } = createRateLimiterMiddleware(limiter, {\n *   scope: (req) => `user:${req.headers['x-user-id']}`,\n * })\n *\n * app.use(middleware)        // BEFORE routes — attaches req.rateLimiter\n *\n * app.post('/chat', async (req, res) => {\n *   await generateText({\n *     model,\n *     providerOptions: { rateLimiter: req.rateLimiter }, // just pass it through\n *   })\n * })\n *\n * app.use(errorHandler)      // AFTER routes — converts errors to proper HTTP responses\n * ```\n *\n * @example Hono\n * ```typescript\n * import { createHonoMiddleware } from 'ai-sdk-rate-limiter/middleware'\n *\n * app.use(createHonoMiddleware(limiter, {\n *   scope: (c) => c.req.header('x-user-id'),\n * }))\n *\n * app.post('/chat', async (c) => {\n *   await generateText({\n *     model,\n *     providerOptions: { rateLimiter: c.var.rateLimiter },\n *   })\n * })\n * ```\n */\n\nimport type { RateLimiter, Priority } from './types.js'\nimport {\n  RateLimiterError,\n  QueueTimeoutError,\n  QueueFullError,\n  BudgetExceededError,\n  CircuitOpenError,\n  ShutdownError,\n} from './errors.js'\n\n// ---------------------------------------------------------------------------\n// Shared request context\n//\n// Stored on req.rateLimiter (Express) or c.var.rateLimiter (Hono).\n// Pass directly to providerOptions.rateLimiter in route handlers.\n// ---------------------------------------------------------------------------\n\nexport interface RateLimiterRequestContext {\n  /** Scope key for per-user/org isolated rate limiting */\n  scope?: string\n  /** Queue priority for this request. Default: 'normal' */\n  priority?: Priority\n}\n\n// Augment Node.js http.IncomingMessage so TypeScript knows about req.rateLimiter\n// without requiring users to install @types/express separately.\ndeclare module 'http' {\n  interface IncomingMessage {\n    /**\n     * Populated by createRateLimiterMiddleware(). Pass directly to providerOptions:\n     * ```typescript\n     * providerOptions: { rateLimiter: req.rateLimiter }\n     * ```\n     */\n    rateLimiter?: RateLimiterRequestContext\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Minimal structural types — no runtime dep on express / hono / fastify\n// ---------------------------------------------------------------------------\n\ninterface MinReq {\n  headers: Record<string, string | string[] | undefined>\n  [key: string]: unknown\n}\n\ninterface MinRes {\n  setHeader(name: string, value: string | number): void\n  status(code: number): MinRes\n  json(body: unknown): void\n  readonly headersSent: boolean\n  [key: string]: unknown\n}\n\ntype NextFn = (err?: unknown) => void\n\n// ---------------------------------------------------------------------------\n// Options — Express\n// ---------------------------------------------------------------------------\n\nexport interface RateLimiterMiddlewareOptions {\n  /**\n   * Extract the per-request scope from the incoming request.\n   * Stored in req.rateLimiter.scope.\n   *\n   * @example (req) => req.headers['x-user-id'] as string\n   * @example (req) => `user:${(req as any).user.id}`\n   */\n  scope?: (req: MinReq) => string | undefined\n\n  /**\n   * Default queue priority, or derive it per-request.\n   * Stored in req.rateLimiter.priority. Default: 'normal'\n   *\n   * @example (req) => req.headers['x-priority'] === 'high' ? 'high' : 'normal'\n   */\n  priority?: Priority | ((req: MinReq) => Priority)\n\n  /**\n   * Inject X-RateLimit-* informational headers into every response.\n   * Pass the model ID to inspect, or a function to derive it per-request.\n   *\n   * @example 'gpt-4o'\n   * @example (req) => req.headers['x-ai-model'] as string ?? 'gpt-4o-mini'\n   */\n  injectHeaders?: string | ((req: MinReq) => string)\n}\n\nexport interface ErrorHandlerOptions {\n  /**\n   * Include structured details (retryAfter, period, limitUsd…) in the\n   * response body. Default: true\n   */\n  includeDetails?: boolean\n\n  /**\n   * Override the default error → HTTP mapping.\n   * Return null/undefined to fall through to the next error handler.\n   */\n  format?: (err: RateLimiterError) => { status: number; body: unknown } | null | undefined\n}\n\n// ---------------------------------------------------------------------------\n// Express: createRateLimiterMiddleware\n// ---------------------------------------------------------------------------\n\n/**\n * Returns a middleware + error handler pair for Express (or any Node.js\n * framework that uses the `(req, res, next)` calling convention).\n *\n * **middleware** — place BEFORE routes. Attaches req.rateLimiter.\n * **errorHandler** — place AFTER routes. Converts RateLimiterErrors to HTTP.\n */\nexport function createRateLimiterMiddleware(\n  limiter: RateLimiter,\n  options: RateLimiterMiddlewareOptions = {},\n): {\n  middleware:   (req: MinReq, res: MinRes, next: NextFn) => void\n  errorHandler: (err: unknown, req: MinReq, res: MinRes, next: NextFn) => void\n} {\n  const middleware = (req: MinReq, res: MinRes, next: NextFn): void => {\n    const scope    = options.scope?.(req)\n    const priority = typeof options.priority === 'function'\n      ? options.priority(req)\n      : options.priority\n\n    const ctx: RateLimiterRequestContext = {\n      ...(scope    !== undefined && { scope }),\n      ...(priority !== undefined && { priority }),\n    }\n    ;(req as Record<string, unknown>)['rateLimiter'] = ctx\n\n    if (options.injectHeaders && !res.headersSent) {\n      const modelId   = typeof options.injectHeaders === 'function'\n        ? options.injectHeaders(req)\n        : options.injectHeaders\n      const status    = limiter.getStatus()\n      const modelStat = status.models.find(m => m.modelId === modelId)\n\n      if (modelStat) {\n        res.setHeader('X-RateLimit-Model',           modelId)\n        res.setHeader('X-RateLimit-Queue-Depth',     modelStat.queueDepth)\n        res.setHeader('X-RateLimit-Requests-Window', modelStat.requestsInWindow)\n        if (modelStat.estimatedWaitMs > 0) {\n          res.setHeader('X-RateLimit-Estimated-Wait-Ms', modelStat.estimatedWaitMs)\n        }\n      }\n    }\n\n    next()\n  }\n\n  const errorHandler = (err: unknown, _req: MinReq, res: MinRes, next: NextFn): void => {\n    if (!(err instanceof RateLimiterError)) { next(err); return }\n    if (res.headersSent)                    { next(err); return }\n    const { status, body } = mapErrorToResponse(err)\n    res.status(status).json(body)\n  }\n\n  return { middleware, errorHandler }\n}\n\n/**\n * Standalone Express 4-argument error handler.\n * Use this when you only need error handling and not scope injection.\n *\n * @example\n * ```typescript\n * app.use(createRateLimiterErrorHandler({ includeDetails: false }))\n * ```\n */\nexport function createRateLimiterErrorHandler(\n  options: ErrorHandlerOptions = {},\n): (err: unknown, req: MinReq, res: MinRes, next: NextFn) => void {\n  return (err, _req, res, next) => {\n    if (!(err instanceof RateLimiterError)) { next(err); return }\n    if (res.headersSent)                    { next(err); return }\n\n    if (options.format) {\n      const custom = options.format(err)\n      if (custom == null) { next(err); return }\n      res.status(custom.status).json(custom.body)\n      return\n    }\n\n    const { status, body } = mapErrorToResponse(err, options.includeDetails)\n    res.status(status).json(body)\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Hono middleware\n// ---------------------------------------------------------------------------\n\n/**\n * Minimal Hono Context interface — structural typing, no hard `hono` dep.\n */\nexport interface HonoContext {\n  req: {\n    raw: Request\n    header(name: string): string | undefined\n  }\n  set(key: string, value: unknown): void\n  json(body: unknown, status?: number): Response\n  header(name: string, value: string): void\n  var: Record<string, unknown>\n}\n\ntype HonoNext = () => Promise<Response | void>\n\n/** Hono middleware handler signature */\nexport type HonoMiddlewareHandler = (c: HonoContext, next: HonoNext) => Promise<Response | void>\n\nexport interface HonoMiddlewareOptions {\n  /**\n   * Extract scope from the Hono context. Stored in c.var.rateLimiter.scope.\n   *\n   * @example (c) => c.req.header('x-user-id')\n   * @example (c) => c.var.user?.id ? `user:${c.var.user.id}` : undefined\n   */\n  scope?: (c: HonoContext) => string | undefined\n\n  /** Default queue priority, or derive it per-request. */\n  priority?: Priority | ((c: HonoContext) => Priority)\n\n  /** Inject X-RateLimit-* headers. Pass model ID or function. */\n  injectHeaders?: string | ((c: HonoContext) => string)\n}\n\n/**\n * Hono middleware that attaches rateLimiter context and catches RateLimiterErrors.\n *\n * Access the context in route handlers via `c.var.rateLimiter`.\n */\nexport function createHonoMiddleware(\n  limiter: RateLimiter,\n  options: HonoMiddlewareOptions = {},\n): HonoMiddlewareHandler {\n  return async (c, next) => {\n    const scope    = options.scope?.(c)\n    const priority = typeof options.priority === 'function'\n      ? options.priority(c)\n      : options.priority\n\n    const ctx: RateLimiterRequestContext = {\n      ...(scope    !== undefined && { scope }),\n      ...(priority !== undefined && { priority }),\n    }\n    c.set('rateLimiter', ctx)\n\n    if (options.injectHeaders) {\n      const modelId   = typeof options.injectHeaders === 'function'\n        ? options.injectHeaders(c)\n        : options.injectHeaders\n      const status    = limiter.getStatus()\n      const modelStat = status.models.find(m => m.modelId === modelId)\n\n      if (modelStat) {\n        c.header('X-RateLimit-Model',           modelId)\n        c.header('X-RateLimit-Queue-Depth',     String(modelStat.queueDepth))\n        c.header('X-RateLimit-Requests-Window', String(modelStat.requestsInWindow))\n        if (modelStat.estimatedWaitMs > 0) {\n          c.header('X-RateLimit-Estimated-Wait-Ms', String(modelStat.estimatedWaitMs))\n        }\n      }\n    }\n\n    try {\n      await next()\n    } catch (err) {\n      if (err instanceof RateLimiterError) {\n        const { status, body } = mapErrorToResponse(err)\n        return c.json(body, status as Parameters<typeof c.json>[1])\n      }\n      throw err\n    }\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Shared: error → HTTP response\n// ---------------------------------------------------------------------------\n\n/**\n * Map any RateLimiterError to an HTTP status code + JSON body.\n *\n * Exported so you can use it in custom error handlers, non-Express frameworks,\n * or API gateway integrations.\n *\n * @example\n * ```typescript\n * import { mapErrorToResponse } from 'ai-sdk-rate-limiter/middleware'\n *\n * // Fastify onError hook\n * fastify.setErrorHandler((err, request, reply) => {\n *   if (err instanceof RateLimiterError) {\n *     const { status, body } = mapErrorToResponse(err)\n *     return reply.status(status).send(body)\n *   }\n *   reply.send(err)\n * })\n * ```\n */\nexport function mapErrorToResponse(\n  err: RateLimiterError,\n  includeDetails = true,\n): { status: number; body: Record<string, unknown> } {\n  if (err instanceof QueueTimeoutError) {\n    return {\n      status: 503,\n      body: {\n        error: 'Request queued too long. Try again shortly.',\n        code:  'QUEUE_TIMEOUT',\n        ...(includeDetails && {\n          retryAfterMs: 5_000,\n          queueDepth:   err.queueDepth,\n        }),\n      },\n    }\n  }\n\n  if (err instanceof QueueFullError) {\n    return {\n      status: 503,\n      body: {\n        error: 'Server is busy. Try again in a moment.',\n        code:  'QUEUE_FULL',\n      },\n    }\n  }\n\n  if (err instanceof BudgetExceededError) {\n    return {\n      status: 402,\n      body: {\n        error: 'AI usage budget exceeded.',\n        code:  'BUDGET_EXCEEDED',\n        ...(includeDetails && {\n          period:         err.period,\n          limitUsd:       err.limitUsd,\n          currentCostUsd: err.currentCostUsd,\n        }),\n      },\n    }\n  }\n\n  if (err instanceof CircuitOpenError) {\n    return {\n      status: 503,\n      body: {\n        error: 'AI provider temporarily unavailable.',\n        code:  'CIRCUIT_OPEN',\n        ...(includeDetails && {\n          retryAfter: Math.max(0, Math.ceil((err.openUntilMs - Date.now()) / 1000)),\n        }),\n      },\n    }\n  }\n\n  if (err instanceof ShutdownError) {\n    return {\n      status: 503,\n      body: {\n        error: 'Service is shutting down.',\n        code:  'SHUTDOWN',\n      },\n    }\n  }\n\n  return {\n    status: 429,\n    body: {\n      error: 'Rate limit exceeded.',\n      code:  'RATE_LIMITED',\n    },\n  }\n}\n"]}

package/dist/middleware.d.cts

@@ -0,0 +1,198 @@
+import { P as Priority, a as RateLimiter } from './types-CUPpMRPE.cjs';
+import { b as RateLimiterError } from './errors-DcXM0HCM.cjs';
+
+/**
+ * ai-sdk-rate-limiter/middleware
+ *
+ * Framework-agnostic middleware helpers. Reduces per-route boilerplate to zero:
+ * scope extraction, priority assignment, and rate-limiter error handling are
+ * all handled at the middleware layer.
+ *
+ * @example Express
+ * ```typescript
+ * import { createRateLimiterMiddleware } from 'ai-sdk-rate-limiter/middleware'
+ *
+ * const { middleware, errorHandler } = createRateLimiterMiddleware(limiter, {
+ *   scope: (req) => `user:${req.headers['x-user-id']}`,
+ * })
+ *
+ * app.use(middleware)        // BEFORE routes — attaches req.rateLimiter
+ *
+ * app.post('/chat', async (req, res) => {
+ *   await generateText({
+ *     model,
+ *     providerOptions: { rateLimiter: req.rateLimiter }, // just pass it through
+ *   })
+ * })
+ *
+ * app.use(errorHandler)      // AFTER routes — converts errors to proper HTTP responses
+ * ```
+ *
+ * @example Hono
+ * ```typescript
+ * import { createHonoMiddleware } from 'ai-sdk-rate-limiter/middleware'
+ *
+ * app.use(createHonoMiddleware(limiter, {
+ *   scope: (c) => c.req.header('x-user-id'),
+ * }))
+ *
+ * app.post('/chat', async (c) => {
+ *   await generateText({
+ *     model,
+ *     providerOptions: { rateLimiter: c.var.rateLimiter },
+ *   })
+ * })
+ * ```
+ */
+
+interface RateLimiterRequestContext {
+    /** Scope key for per-user/org isolated rate limiting */
+    scope?: string;
+    /** Queue priority for this request. Default: 'normal' */
+    priority?: Priority;
+}
+declare module 'http' {
+    interface IncomingMessage {
+        /**
+         * Populated by createRateLimiterMiddleware(). Pass directly to providerOptions:
+         * ```typescript
+         * providerOptions: { rateLimiter: req.rateLimiter }
+         * ```
+         */
+        rateLimiter?: RateLimiterRequestContext;
+    }
+}
+interface MinReq {
+    headers: Record<string, string | string[] | undefined>;
+    [key: string]: unknown;
+}
+interface MinRes {
+    setHeader(name: string, value: string | number): void;
+    status(code: number): MinRes;
+    json(body: unknown): void;
+    readonly headersSent: boolean;
+    [key: string]: unknown;
+}
+type NextFn = (err?: unknown) => void;
+interface RateLimiterMiddlewareOptions {
+    /**
+     * Extract the per-request scope from the incoming request.
+     * Stored in req.rateLimiter.scope.
+     *
+     * @example (req) => req.headers['x-user-id'] as string
+     * @example (req) => `user:${(req as any).user.id}`
+     */
+    scope?: (req: MinReq) => string | undefined;
+    /**
+     * Default queue priority, or derive it per-request.
+     * Stored in req.rateLimiter.priority. Default: 'normal'
+     *
+     * @example (req) => req.headers['x-priority'] === 'high' ? 'high' : 'normal'
+     */
+    priority?: Priority | ((req: MinReq) => Priority);
+    /**
+     * Inject X-RateLimit-* informational headers into every response.
+     * Pass the model ID to inspect, or a function to derive it per-request.
+     *
+     * @example 'gpt-4o'
+     * @example (req) => req.headers['x-ai-model'] as string ?? 'gpt-4o-mini'
+     */
+    injectHeaders?: string | ((req: MinReq) => string);
+}
+interface ErrorHandlerOptions {
+    /**
+     * Include structured details (retryAfter, period, limitUsd…) in the
+     * response body. Default: true
+     */
+    includeDetails?: boolean;
+    /**
+     * Override the default error → HTTP mapping.
+     * Return null/undefined to fall through to the next error handler.
+     */
+    format?: (err: RateLimiterError) => {
+        status: number;
+        body: unknown;
+    } | null | undefined;
+}
+/**
+ * Returns a middleware + error handler pair for Express (or any Node.js
+ * framework that uses the `(req, res, next)` calling convention).
+ *
+ * **middleware** — place BEFORE routes. Attaches req.rateLimiter.
+ * **errorHandler** — place AFTER routes. Converts RateLimiterErrors to HTTP.
+ */
+declare function createRateLimiterMiddleware(limiter: RateLimiter, options?: RateLimiterMiddlewareOptions): {
+    middleware: (req: MinReq, res: MinRes, next: NextFn) => void;
+    errorHandler: (err: unknown, req: MinReq, res: MinRes, next: NextFn) => void;
+};
+/**
+ * Standalone Express 4-argument error handler.
+ * Use this when you only need error handling and not scope injection.
+ *
+ * @example
+ * ```typescript
+ * app.use(createRateLimiterErrorHandler({ includeDetails: false }))
+ * ```
+ */
+declare function createRateLimiterErrorHandler(options?: ErrorHandlerOptions): (err: unknown, req: MinReq, res: MinRes, next: NextFn) => void;
+/**
+ * Minimal Hono Context interface — structural typing, no hard `hono` dep.
+ */
+interface HonoContext {
+    req: {
+        raw: Request;
+        header(name: string): string | undefined;
+    };
+    set(key: string, value: unknown): void;
+    json(body: unknown, status?: number): Response;
+    header(name: string, value: string): void;
+    var: Record<string, unknown>;
+}
+type HonoNext = () => Promise<Response | void>;
+/** Hono middleware handler signature */
+type HonoMiddlewareHandler = (c: HonoContext, next: HonoNext) => Promise<Response | void>;
+interface HonoMiddlewareOptions {
+    /**
+     * Extract scope from the Hono context. Stored in c.var.rateLimiter.scope.
+     *
+     * @example (c) => c.req.header('x-user-id')
+     * @example (c) => c.var.user?.id ? `user:${c.var.user.id}` : undefined
+     */
+    scope?: (c: HonoContext) => string | undefined;
+    /** Default queue priority, or derive it per-request. */
+    priority?: Priority | ((c: HonoContext) => Priority);
+    /** Inject X-RateLimit-* headers. Pass model ID or function. */
+    injectHeaders?: string | ((c: HonoContext) => string);
+}
+/**
+ * Hono middleware that attaches rateLimiter context and catches RateLimiterErrors.
+ *
+ * Access the context in route handlers via `c.var.rateLimiter`.
+ */
+declare function createHonoMiddleware(limiter: RateLimiter, options?: HonoMiddlewareOptions): HonoMiddlewareHandler;
+/**
+ * Map any RateLimiterError to an HTTP status code + JSON body.
+ *
+ * Exported so you can use it in custom error handlers, non-Express frameworks,
+ * or API gateway integrations.
+ *
+ * @example
+ * ```typescript
+ * import { mapErrorToResponse } from 'ai-sdk-rate-limiter/middleware'
+ *
+ * // Fastify onError hook
+ * fastify.setErrorHandler((err, request, reply) => {
+ *   if (err instanceof RateLimiterError) {
+ *     const { status, body } = mapErrorToResponse(err)
+ *     return reply.status(status).send(body)
+ *   }
+ *   reply.send(err)
+ * })
+ * ```
+ */
+declare function mapErrorToResponse(err: RateLimiterError, includeDetails?: boolean): {
+    status: number;
+    body: Record<string, unknown>;
+};
+
+export { type ErrorHandlerOptions, type HonoContext, type HonoMiddlewareHandler, type HonoMiddlewareOptions, type RateLimiterMiddlewareOptions, type RateLimiterRequestContext, createHonoMiddleware, createRateLimiterErrorHandler, createRateLimiterMiddleware, mapErrorToResponse };

package/dist/middleware.d.ts

@@ -0,0 +1,198 @@
+import { P as Priority, a as RateLimiter } from './types-CUPpMRPE.js';
+import { b as RateLimiterError } from './errors-DcXM0HCM.js';
+
+/**
+ * ai-sdk-rate-limiter/middleware
+ *
+ * Framework-agnostic middleware helpers. Reduces per-route boilerplate to zero:
+ * scope extraction, priority assignment, and rate-limiter error handling are
+ * all handled at the middleware layer.
+ *
+ * @example Express
+ * ```typescript
+ * import { createRateLimiterMiddleware } from 'ai-sdk-rate-limiter/middleware'
+ *
+ * const { middleware, errorHandler } = createRateLimiterMiddleware(limiter, {
+ *   scope: (req) => `user:${req.headers['x-user-id']}`,
+ * })
+ *
+ * app.use(middleware)        // BEFORE routes — attaches req.rateLimiter
+ *
+ * app.post('/chat', async (req, res) => {
+ *   await generateText({
+ *     model,
+ *     providerOptions: { rateLimiter: req.rateLimiter }, // just pass it through
+ *   })
+ * })
+ *
+ * app.use(errorHandler)      // AFTER routes — converts errors to proper HTTP responses
+ * ```
+ *
+ * @example Hono
+ * ```typescript
+ * import { createHonoMiddleware } from 'ai-sdk-rate-limiter/middleware'
+ *
+ * app.use(createHonoMiddleware(limiter, {
+ *   scope: (c) => c.req.header('x-user-id'),
+ * }))
+ *
+ * app.post('/chat', async (c) => {
+ *   await generateText({
+ *     model,
+ *     providerOptions: { rateLimiter: c.var.rateLimiter },
+ *   })
+ * })
+ * ```
+ */
+
+interface RateLimiterRequestContext {
+    /** Scope key for per-user/org isolated rate limiting */
+    scope?: string;
+    /** Queue priority for this request. Default: 'normal' */
+    priority?: Priority;
+}
+declare module 'http' {
+    interface IncomingMessage {
+        /**
+         * Populated by createRateLimiterMiddleware(). Pass directly to providerOptions:
+         * ```typescript
+         * providerOptions: { rateLimiter: req.rateLimiter }
+         * ```
+         */
+        rateLimiter?: RateLimiterRequestContext;
+    }
+}
+interface MinReq {
+    headers: Record<string, string | string[] | undefined>;
+    [key: string]: unknown;
+}
+interface MinRes {
+    setHeader(name: string, value: string | number): void;
+    status(code: number): MinRes;
+    json(body: unknown): void;
+    readonly headersSent: boolean;
+    [key: string]: unknown;
+}
+type NextFn = (err?: unknown) => void;
+interface RateLimiterMiddlewareOptions {
+    /**
+     * Extract the per-request scope from the incoming request.
+     * Stored in req.rateLimiter.scope.
+     *
+     * @example (req) => req.headers['x-user-id'] as string
+     * @example (req) => `user:${(req as any).user.id}`
+     */
+    scope?: (req: MinReq) => string | undefined;
+    /**
+     * Default queue priority, or derive it per-request.
+     * Stored in req.rateLimiter.priority. Default: 'normal'
+     *
+     * @example (req) => req.headers['x-priority'] === 'high' ? 'high' : 'normal'
+     */
+    priority?: Priority | ((req: MinReq) => Priority);
+    /**
+     * Inject X-RateLimit-* informational headers into every response.
+     * Pass the model ID to inspect, or a function to derive it per-request.
+     *
+     * @example 'gpt-4o'
+     * @example (req) => req.headers['x-ai-model'] as string ?? 'gpt-4o-mini'
+     */
+    injectHeaders?: string | ((req: MinReq) => string);
+}
+interface ErrorHandlerOptions {
+    /**
+     * Include structured details (retryAfter, period, limitUsd…) in the
+     * response body. Default: true
+     */
+    includeDetails?: boolean;
+    /**
+     * Override the default error → HTTP mapping.
+     * Return null/undefined to fall through to the next error handler.
+     */
+    format?: (err: RateLimiterError) => {
+        status: number;
+        body: unknown;
+    } | null | undefined;
+}
+/**
+ * Returns a middleware + error handler pair for Express (or any Node.js
+ * framework that uses the `(req, res, next)` calling convention).
+ *
+ * **middleware** — place BEFORE routes. Attaches req.rateLimiter.
+ * **errorHandler** — place AFTER routes. Converts RateLimiterErrors to HTTP.
+ */
+declare function createRateLimiterMiddleware(limiter: RateLimiter, options?: RateLimiterMiddlewareOptions): {
+    middleware: (req: MinReq, res: MinRes, next: NextFn) => void;
+    errorHandler: (err: unknown, req: MinReq, res: MinRes, next: NextFn) => void;
+};
+/**
+ * Standalone Express 4-argument error handler.
+ * Use this when you only need error handling and not scope injection.
+ *
+ * @example
+ * ```typescript
+ * app.use(createRateLimiterErrorHandler({ includeDetails: false }))
+ * ```
+ */
+declare function createRateLimiterErrorHandler(options?: ErrorHandlerOptions): (err: unknown, req: MinReq, res: MinRes, next: NextFn) => void;
+/**
+ * Minimal Hono Context interface — structural typing, no hard `hono` dep.
+ */
+interface HonoContext {
+    req: {
+        raw: Request;
+        header(name: string): string | undefined;
+    };
+    set(key: string, value: unknown): void;
+    json(body: unknown, status?: number): Response;
+    header(name: string, value: string): void;
+    var: Record<string, unknown>;
+}
+type HonoNext = () => Promise<Response | void>;
+/** Hono middleware handler signature */
+type HonoMiddlewareHandler = (c: HonoContext, next: HonoNext) => Promise<Response | void>;
+interface HonoMiddlewareOptions {
+    /**
+     * Extract scope from the Hono context. Stored in c.var.rateLimiter.scope.
+     *
+     * @example (c) => c.req.header('x-user-id')
+     * @example (c) => c.var.user?.id ? `user:${c.var.user.id}` : undefined
+     */
+    scope?: (c: HonoContext) => string | undefined;
+    /** Default queue priority, or derive it per-request. */
+    priority?: Priority | ((c: HonoContext) => Priority);
+    /** Inject X-RateLimit-* headers. Pass model ID or function. */
+    injectHeaders?: string | ((c: HonoContext) => string);
+}
+/**
+ * Hono middleware that attaches rateLimiter context and catches RateLimiterErrors.
+ *
+ * Access the context in route handlers via `c.var.rateLimiter`.
+ */
+declare function createHonoMiddleware(limiter: RateLimiter, options?: HonoMiddlewareOptions): HonoMiddlewareHandler;
+/**
+ * Map any RateLimiterError to an HTTP status code + JSON body.
+ *
+ * Exported so you can use it in custom error handlers, non-Express frameworks,
+ * or API gateway integrations.
+ *
+ * @example
+ * ```typescript
+ * import { mapErrorToResponse } from 'ai-sdk-rate-limiter/middleware'
+ *
+ * // Fastify onError hook
+ * fastify.setErrorHandler((err, request, reply) => {
+ *   if (err instanceof RateLimiterError) {
+ *     const { status, body } = mapErrorToResponse(err)
+ *     return reply.status(status).send(body)
+ *   }
+ *   reply.send(err)
+ * })
+ * ```
+ */
+declare function mapErrorToResponse(err: RateLimiterError, includeDetails?: boolean): {
+    status: number;
+    body: Record<string, unknown>;
+};
+
+export { type ErrorHandlerOptions, type HonoContext, type HonoMiddlewareHandler, type HonoMiddlewareOptions, type RateLimiterMiddlewareOptions, type RateLimiterRequestContext, createHonoMiddleware, createRateLimiterErrorHandler, createRateLimiterMiddleware, mapErrorToResponse };

package/dist/middleware.js

@@ -0,0 +1,223 @@
+// src/errors.ts
+var RateLimiterError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "RateLimiterError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var QueueTimeoutError = class extends RateLimiterError {
+  constructor(model, waitedMs, queueDepth) {
+    super(
+      `Request for model "${model}" timed out after waiting ${waitedMs}ms in the queue (current queue depth: ${queueDepth}).`
+    );
+    this.model = model;
+    this.waitedMs = waitedMs;
+    this.queueDepth = queueDepth;
+    this.name = "QueueTimeoutError";
+  }
+};
+var QueueFullError = class extends RateLimiterError {
+  constructor(model, maxSize) {
+    super(
+      `Queue for model "${model}" is full (maxSize: ${maxSize}). Increase queue.maxSize or reduce request rate.`
+    );
+    this.model = model;
+    this.maxSize = maxSize;
+    this.name = "QueueFullError";
+  }
+};
+var BudgetExceededError = class extends RateLimiterError {
+  constructor(model, currentCostUsd, limitUsd, period) {
+    super(
+      `Cost budget exceeded for model "${model}": $${currentCostUsd.toFixed(4)} used of $${limitUsd.toFixed(2)} ${period} budget.`
+    );
+    this.model = model;
+    this.currentCostUsd = currentCostUsd;
+    this.limitUsd = limitUsd;
+    this.period = period;
+    this.name = "BudgetExceededError";
+  }
+};
+var CircuitOpenError = class extends RateLimiterError {
+  constructor(model, openUntilMs) {
+    super(
+      `Circuit breaker for model "${model}" is open due to repeated failures. Requests are blocked until ${new Date(openUntilMs).toISOString()}.`
+    );
+    this.model = model;
+    this.openUntilMs = openUntilMs;
+    this.name = "CircuitOpenError";
+  }
+};
+var ShutdownError = class extends RateLimiterError {
+  constructor() {
+    super("Rate limiter is shutting down \u2014 new requests are not accepted.");
+    this.name = "ShutdownError";
+  }
+};
+
+// src/middleware.ts
+function createRateLimiterMiddleware(limiter, options = {}) {
+  const middleware = (req, res, next) => {
+    const scope = options.scope?.(req);
+    const priority = typeof options.priority === "function" ? options.priority(req) : options.priority;
+    const ctx = {
+      ...scope !== void 0 && { scope },
+      ...priority !== void 0 && { priority }
+    };
+    req["rateLimiter"] = ctx;
+    if (options.injectHeaders && !res.headersSent) {
+      const modelId = typeof options.injectHeaders === "function" ? options.injectHeaders(req) : options.injectHeaders;
+      const status = limiter.getStatus();
+      const modelStat = status.models.find((m) => m.modelId === modelId);
+      if (modelStat) {
+        res.setHeader("X-RateLimit-Model", modelId);
+        res.setHeader("X-RateLimit-Queue-Depth", modelStat.queueDepth);
+        res.setHeader("X-RateLimit-Requests-Window", modelStat.requestsInWindow);
+        if (modelStat.estimatedWaitMs > 0) {
+          res.setHeader("X-RateLimit-Estimated-Wait-Ms", modelStat.estimatedWaitMs);
+        }
+      }
+    }
+    next();
+  };
+  const errorHandler = (err, _req, res, next) => {
+    if (!(err instanceof RateLimiterError)) {
+      next(err);
+      return;
+    }
+    if (res.headersSent) {
+      next(err);
+      return;
+    }
+    const { status, body } = mapErrorToResponse(err);
+    res.status(status).json(body);
+  };
+  return { middleware, errorHandler };
+}
+function createRateLimiterErrorHandler(options = {}) {
+  return (err, _req, res, next) => {
+    if (!(err instanceof RateLimiterError)) {
+      next(err);
+      return;
+    }
+    if (res.headersSent) {
+      next(err);
+      return;
+    }
+    if (options.format) {
+      const custom = options.format(err);
+      if (custom == null) {
+        next(err);
+        return;
+      }
+      res.status(custom.status).json(custom.body);
+      return;
+    }
+    const { status, body } = mapErrorToResponse(err, options.includeDetails);
+    res.status(status).json(body);
+  };
+}
+function createHonoMiddleware(limiter, options = {}) {
+  return async (c, next) => {
+    const scope = options.scope?.(c);
+    const priority = typeof options.priority === "function" ? options.priority(c) : options.priority;
+    const ctx = {
+      ...scope !== void 0 && { scope },
+      ...priority !== void 0 && { priority }
+    };
+    c.set("rateLimiter", ctx);
+    if (options.injectHeaders) {
+      const modelId = typeof options.injectHeaders === "function" ? options.injectHeaders(c) : options.injectHeaders;
+      const status = limiter.getStatus();
+      const modelStat = status.models.find((m) => m.modelId === modelId);
+      if (modelStat) {
+        c.header("X-RateLimit-Model", modelId);
+        c.header("X-RateLimit-Queue-Depth", String(modelStat.queueDepth));
+        c.header("X-RateLimit-Requests-Window", String(modelStat.requestsInWindow));
+        if (modelStat.estimatedWaitMs > 0) {
+          c.header("X-RateLimit-Estimated-Wait-Ms", String(modelStat.estimatedWaitMs));
+        }
+      }
+    }
+    try {
+      await next();
+    } catch (err) {
+      if (err instanceof RateLimiterError) {
+        const { status, body } = mapErrorToResponse(err);
+        return c.json(body, status);
+      }
+      throw err;
+    }
+  };
+}
+function mapErrorToResponse(err, includeDetails = true) {
+  if (err instanceof QueueTimeoutError) {
+    return {
+      status: 503,
+      body: {
+        error: "Request queued too long. Try again shortly.",
+        code: "QUEUE_TIMEOUT",
+        ...includeDetails && {
+          retryAfterMs: 5e3,
+          queueDepth: err.queueDepth
+        }
+      }
+    };
+  }
+  if (err instanceof QueueFullError) {
+    return {
+      status: 503,
+      body: {
+        error: "Server is busy. Try again in a moment.",
+        code: "QUEUE_FULL"
+      }
+    };
+  }
+  if (err instanceof BudgetExceededError) {
+    return {
+      status: 402,
+      body: {
+        error: "AI usage budget exceeded.",
+        code: "BUDGET_EXCEEDED",
+        ...includeDetails && {
+          period: err.period,
+          limitUsd: err.limitUsd,
+          currentCostUsd: err.currentCostUsd
+        }
+      }
+    };
+  }
+  if (err instanceof CircuitOpenError) {
+    return {
+      status: 503,
+      body: {
+        error: "AI provider temporarily unavailable.",
+        code: "CIRCUIT_OPEN",
+        ...includeDetails && {
+          retryAfter: Math.max(0, Math.ceil((err.openUntilMs - Date.now()) / 1e3))
+        }
+      }
+    };
+  }
+  if (err instanceof ShutdownError) {
+    return {
+      status: 503,
+      body: {
+        error: "Service is shutting down.",
+        code: "SHUTDOWN"
+      }
+    };
+  }
+  return {
+    status: 429,
+    body: {
+      error: "Rate limit exceeded.",
+      code: "RATE_LIMITED"
+    }
+  };
+}
+
+export { createHonoMiddleware, createRateLimiterErrorHandler, createRateLimiterMiddleware, mapErrorToResponse };
+//# sourceMappingURL=middleware.js.map
+//# sourceMappingURL=middleware.js.map

package/dist/middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/middleware.ts"],"names":[],"mappings":"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","file":"middleware.js","sourcesContent":["/** Base class for all ai-sdk-rate-limiter errors */\nexport class RateLimiterError extends Error {\n  // Declared as mutable string so subclasses can assign in constructors\n  declare name: string\n\n  constructor(message: string) {\n    super(message)\n    this.name = 'RateLimiterError'\n    // Restore prototype chain (needed when extending built-ins in TS)\n    Object.setPrototypeOf(this, new.target.prototype)\n  }\n}\n\n/**\n * Thrown when a request cannot proceed because the rate limit was hit\n * and the request either timed out waiting in the queue or exhausted all retries.\n */\nexport class RateLimitExceededError extends RateLimiterError {\n  constructor(\n    public readonly model: string,\n    public readonly limitType: 'rpm' | 'itpm' | 'otpm',\n    public readonly limit: number,\n    public readonly resetAt: number,\n  ) {\n    super(\n      `Rate limit exceeded for model \"${model}\": ${limitType.toUpperCase()} limit of ${limit} hit. ` +\n        `Resets at ${new Date(resetAt).toISOString()}.`,\n    )\n    this.name = 'RateLimitExceededError'\n  }\n}\n\n/**\n * Thrown when a request has waited in the queue longer than the configured timeout.\n */\nexport class QueueTimeoutError extends RateLimiterError {\n  constructor(\n    public readonly model: string,\n    public readonly waitedMs: number,\n    public readonly queueDepth: number,\n  ) {\n    super(\n      `Request for model \"${model}\" timed out after waiting ${waitedMs}ms in the queue ` +\n        `(current queue depth: ${queueDepth}).`,\n    )\n    this.name = 'QueueTimeoutError'\n  }\n}\n\n/**\n * Thrown when a new request arrives and the queue is at capacity.\n */\nexport class QueueFullError extends RateLimiterError {\n  constructor(\n    public readonly model: string,\n    public readonly maxSize: number,\n  ) {\n    super(\n      `Queue for model \"${model}\" is full (maxSize: ${maxSize}). ` +\n        `Increase queue.maxSize or reduce request rate.`,\n    )\n    this.name = 'QueueFullError'\n  }\n}\n\n/**\n * Thrown when a request would exceed the configured cost budget.\n */\nexport class BudgetExceededError extends RateLimiterError {\n  constructor(\n    public readonly model: string,\n    public readonly currentCostUsd: number,\n    public readonly limitUsd: number,\n    public readonly period: 'hourly' | 'daily' | 'monthly',\n  ) {\n    super(\n      `Cost budget exceeded for model \"${model}\": ` +\n        `$${currentCostUsd.toFixed(4)} used of $${limitUsd.toFixed(2)} ${period} budget.`,\n    )\n    this.name = 'BudgetExceededError'\n  }\n}\n\n/**\n * Thrown when a request is blocked because the circuit breaker is open.\n */\nexport class CircuitOpenError extends RateLimiterError {\n  constructor(\n    public readonly model: string,\n    public readonly openUntilMs: number,\n  ) {\n    super(\n      `Circuit breaker for model \"${model}\" is open due to repeated failures. ` +\n        `Requests are blocked until ${new Date(openUntilMs).toISOString()}.`,\n    )\n    this.name = 'CircuitOpenError'\n  }\n}\n\n/**\n * Thrown when a request arrives after shutdown() has been called.\n */\nexport class ShutdownError extends RateLimiterError {\n  constructor() {\n    super('Rate limiter is shutting down — new requests are not accepted.')\n    this.name = 'ShutdownError'\n  }\n}\n\n/**\n * Thrown when all retry attempts are exhausted.\n */\nexport class RetryExhaustedError extends RateLimiterError {\n  constructor(\n    public readonly model: string,\n    public readonly attempts: number,\n    public readonly cause: unknown,\n  ) {\n    super(\n      `All ${attempts} retry attempts exhausted for model \"${model}\". ` +\n        `Last error: ${cause instanceof Error ? cause.message : String(cause)}`,\n    )\n    this.name = 'RetryExhaustedError'\n    if (cause instanceof Error) {\n      this.stack = `${this.stack}\\nCaused by: ${cause.stack}`\n    }\n  }\n}\n","/**\n * ai-sdk-rate-limiter/middleware\n *\n * Framework-agnostic middleware helpers. Reduces per-route boilerplate to zero:\n * scope extraction, priority assignment, and rate-limiter error handling are\n * all handled at the middleware layer.\n *\n * @example Express\n * ```typescript\n * import { createRateLimiterMiddleware } from 'ai-sdk-rate-limiter/middleware'\n *\n * const { middleware, errorHandler } = createRateLimiterMiddleware(limiter, {\n *   scope: (req) => `user:${req.headers['x-user-id']}`,\n * })\n *\n * app.use(middleware)        // BEFORE routes — attaches req.rateLimiter\n *\n * app.post('/chat', async (req, res) => {\n *   await generateText({\n *     model,\n *     providerOptions: { rateLimiter: req.rateLimiter }, // just pass it through\n *   })\n * })\n *\n * app.use(errorHandler)      // AFTER routes — converts errors to proper HTTP responses\n * ```\n *\n * @example Hono\n * ```typescript\n * import { createHonoMiddleware } from 'ai-sdk-rate-limiter/middleware'\n *\n * app.use(createHonoMiddleware(limiter, {\n *   scope: (c) => c.req.header('x-user-id'),\n * }))\n *\n * app.post('/chat', async (c) => {\n *   await generateText({\n *     model,\n *     providerOptions: { rateLimiter: c.var.rateLimiter },\n *   })\n * })\n * ```\n */\n\nimport type { RateLimiter, Priority } from './types.js'\nimport {\n  RateLimiterError,\n  QueueTimeoutError,\n  QueueFullError,\n  BudgetExceededError,\n  CircuitOpenError,\n  ShutdownError,\n} from './errors.js'\n\n// ---------------------------------------------------------------------------\n// Shared request context\n//\n// Stored on req.rateLimiter (Express) or c.var.rateLimiter (Hono).\n// Pass directly to providerOptions.rateLimiter in route handlers.\n// ---------------------------------------------------------------------------\n\nexport interface RateLimiterRequestContext {\n  /** Scope key for per-user/org isolated rate limiting */\n  scope?: string\n  /** Queue priority for this request. Default: 'normal' */\n  priority?: Priority\n}\n\n// Augment Node.js http.IncomingMessage so TypeScript knows about req.rateLimiter\n// without requiring users to install @types/express separately.\ndeclare module 'http' {\n  interface IncomingMessage {\n    /**\n     * Populated by createRateLimiterMiddleware(). Pass directly to providerOptions:\n     * ```typescript\n     * providerOptions: { rateLimiter: req.rateLimiter }\n     * ```\n     */\n    rateLimiter?: RateLimiterRequestContext\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Minimal structural types — no runtime dep on express / hono / fastify\n// ---------------------------------------------------------------------------\n\ninterface MinReq {\n  headers: Record<string, string | string[] | undefined>\n  [key: string]: unknown\n}\n\ninterface MinRes {\n  setHeader(name: string, value: string | number): void\n  status(code: number): MinRes\n  json(body: unknown): void\n  readonly headersSent: boolean\n  [key: string]: unknown\n}\n\ntype NextFn = (err?: unknown) => void\n\n// ---------------------------------------------------------------------------\n// Options — Express\n// ---------------------------------------------------------------------------\n\nexport interface RateLimiterMiddlewareOptions {\n  /**\n   * Extract the per-request scope from the incoming request.\n   * Stored in req.rateLimiter.scope.\n   *\n   * @example (req) => req.headers['x-user-id'] as string\n   * @example (req) => `user:${(req as any).user.id}`\n   */\n  scope?: (req: MinReq) => string | undefined\n\n  /**\n   * Default queue priority, or derive it per-request.\n   * Stored in req.rateLimiter.priority. Default: 'normal'\n   *\n   * @example (req) => req.headers['x-priority'] === 'high' ? 'high' : 'normal'\n   */\n  priority?: Priority | ((req: MinReq) => Priority)\n\n  /**\n   * Inject X-RateLimit-* informational headers into every response.\n   * Pass the model ID to inspect, or a function to derive it per-request.\n   *\n   * @example 'gpt-4o'\n   * @example (req) => req.headers['x-ai-model'] as string ?? 'gpt-4o-mini'\n   */\n  injectHeaders?: string | ((req: MinReq) => string)\n}\n\nexport interface ErrorHandlerOptions {\n  /**\n   * Include structured details (retryAfter, period, limitUsd…) in the\n   * response body. Default: true\n   */\n  includeDetails?: boolean\n\n  /**\n   * Override the default error → HTTP mapping.\n   * Return null/undefined to fall through to the next error handler.\n   */\n  format?: (err: RateLimiterError) => { status: number; body: unknown } | null | undefined\n}\n\n// ---------------------------------------------------------------------------\n// Express: createRateLimiterMiddleware\n// ---------------------------------------------------------------------------\n\n/**\n * Returns a middleware + error handler pair for Express (or any Node.js\n * framework that uses the `(req, res, next)` calling convention).\n *\n * **middleware** — place BEFORE routes. Attaches req.rateLimiter.\n * **errorHandler** — place AFTER routes. Converts RateLimiterErrors to HTTP.\n */\nexport function createRateLimiterMiddleware(\n  limiter: RateLimiter,\n  options: RateLimiterMiddlewareOptions = {},\n): {\n  middleware:   (req: MinReq, res: MinRes, next: NextFn) => void\n  errorHandler: (err: unknown, req: MinReq, res: MinRes, next: NextFn) => void\n} {\n  const middleware = (req: MinReq, res: MinRes, next: NextFn): void => {\n    const scope    = options.scope?.(req)\n    const priority = typeof options.priority === 'function'\n      ? options.priority(req)\n      : options.priority\n\n    const ctx: RateLimiterRequestContext = {\n      ...(scope    !== undefined && { scope }),\n      ...(priority !== undefined && { priority }),\n    }\n    ;(req as Record<string, unknown>)['rateLimiter'] = ctx\n\n    if (options.injectHeaders && !res.headersSent) {\n      const modelId   = typeof options.injectHeaders === 'function'\n        ? options.injectHeaders(req)\n        : options.injectHeaders\n      const status    = limiter.getStatus()\n      const modelStat = status.models.find(m => m.modelId === modelId)\n\n      if (modelStat) {\n        res.setHeader('X-RateLimit-Model',           modelId)\n        res.setHeader('X-RateLimit-Queue-Depth',     modelStat.queueDepth)\n        res.setHeader('X-RateLimit-Requests-Window', modelStat.requestsInWindow)\n        if (modelStat.estimatedWaitMs > 0) {\n          res.setHeader('X-RateLimit-Estimated-Wait-Ms', modelStat.estimatedWaitMs)\n        }\n      }\n    }\n\n    next()\n  }\n\n  const errorHandler = (err: unknown, _req: MinReq, res: MinRes, next: NextFn): void => {\n    if (!(err instanceof RateLimiterError)) { next(err); return }\n    if (res.headersSent)                    { next(err); return }\n    const { status, body } = mapErrorToResponse(err)\n    res.status(status).json(body)\n  }\n\n  return { middleware, errorHandler }\n}\n\n/**\n * Standalone Express 4-argument error handler.\n * Use this when you only need error handling and not scope injection.\n *\n * @example\n * ```typescript\n * app.use(createRateLimiterErrorHandler({ includeDetails: false }))\n * ```\n */\nexport function createRateLimiterErrorHandler(\n  options: ErrorHandlerOptions = {},\n): (err: unknown, req: MinReq, res: MinRes, next: NextFn) => void {\n  return (err, _req, res, next) => {\n    if (!(err instanceof RateLimiterError)) { next(err); return }\n    if (res.headersSent)                    { next(err); return }\n\n    if (options.format) {\n      const custom = options.format(err)\n      if (custom == null) { next(err); return }\n      res.status(custom.status).json(custom.body)\n      return\n    }\n\n    const { status, body } = mapErrorToResponse(err, options.includeDetails)\n    res.status(status).json(body)\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Hono middleware\n// ---------------------------------------------------------------------------\n\n/**\n * Minimal Hono Context interface — structural typing, no hard `hono` dep.\n */\nexport interface HonoContext {\n  req: {\n    raw: Request\n    header(name: string): string | undefined\n  }\n  set(key: string, value: unknown): void\n  json(body: unknown, status?: number): Response\n  header(name: string, value: string): void\n  var: Record<string, unknown>\n}\n\ntype HonoNext = () => Promise<Response | void>\n\n/** Hono middleware handler signature */\nexport type HonoMiddlewareHandler = (c: HonoContext, next: HonoNext) => Promise<Response | void>\n\nexport interface HonoMiddlewareOptions {\n  /**\n   * Extract scope from the Hono context. Stored in c.var.rateLimiter.scope.\n   *\n   * @example (c) => c.req.header('x-user-id')\n   * @example (c) => c.var.user?.id ? `user:${c.var.user.id}` : undefined\n   */\n  scope?: (c: HonoContext) => string | undefined\n\n  /** Default queue priority, or derive it per-request. */\n  priority?: Priority | ((c: HonoContext) => Priority)\n\n  /** Inject X-RateLimit-* headers. Pass model ID or function. */\n  injectHeaders?: string | ((c: HonoContext) => string)\n}\n\n/**\n * Hono middleware that attaches rateLimiter context and catches RateLimiterErrors.\n *\n * Access the context in route handlers via `c.var.rateLimiter`.\n */\nexport function createHonoMiddleware(\n  limiter: RateLimiter,\n  options: HonoMiddlewareOptions = {},\n): HonoMiddlewareHandler {\n  return async (c, next) => {\n    const scope    = options.scope?.(c)\n    const priority = typeof options.priority === 'function'\n      ? options.priority(c)\n      : options.priority\n\n    const ctx: RateLimiterRequestContext = {\n      ...(scope    !== undefined && { scope }),\n      ...(priority !== undefined && { priority }),\n    }\n    c.set('rateLimiter', ctx)\n\n    if (options.injectHeaders) {\n      const modelId   = typeof options.injectHeaders === 'function'\n        ? options.injectHeaders(c)\n        : options.injectHeaders\n      const status    = limiter.getStatus()\n      const modelStat = status.models.find(m => m.modelId === modelId)\n\n      if (modelStat) {\n        c.header('X-RateLimit-Model',           modelId)\n        c.header('X-RateLimit-Queue-Depth',     String(modelStat.queueDepth))\n        c.header('X-RateLimit-Requests-Window', String(modelStat.requestsInWindow))\n        if (modelStat.estimatedWaitMs > 0) {\n          c.header('X-RateLimit-Estimated-Wait-Ms', String(modelStat.estimatedWaitMs))\n        }\n      }\n    }\n\n    try {\n      await next()\n    } catch (err) {\n      if (err instanceof RateLimiterError) {\n        const { status, body } = mapErrorToResponse(err)\n        return c.json(body, status as Parameters<typeof c.json>[1])\n      }\n      throw err\n    }\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Shared: error → HTTP response\n// ---------------------------------------------------------------------------\n\n/**\n * Map any RateLimiterError to an HTTP status code + JSON body.\n *\n * Exported so you can use it in custom error handlers, non-Express frameworks,\n * or API gateway integrations.\n *\n * @example\n * ```typescript\n * import { mapErrorToResponse } from 'ai-sdk-rate-limiter/middleware'\n *\n * // Fastify onError hook\n * fastify.setErrorHandler((err, request, reply) => {\n *   if (err instanceof RateLimiterError) {\n *     const { status, body } = mapErrorToResponse(err)\n *     return reply.status(status).send(body)\n *   }\n *   reply.send(err)\n * })\n * ```\n */\nexport function mapErrorToResponse(\n  err: RateLimiterError,\n  includeDetails = true,\n): { status: number; body: Record<string, unknown> } {\n  if (err instanceof QueueTimeoutError) {\n    return {\n      status: 503,\n      body: {\n        error: 'Request queued too long. Try again shortly.',\n        code:  'QUEUE_TIMEOUT',\n        ...(includeDetails && {\n          retryAfterMs: 5_000,\n          queueDepth:   err.queueDepth,\n        }),\n      },\n    }\n  }\n\n  if (err instanceof QueueFullError) {\n    return {\n      status: 503,\n      body: {\n        error: 'Server is busy. Try again in a moment.',\n        code:  'QUEUE_FULL',\n      },\n    }\n  }\n\n  if (err instanceof BudgetExceededError) {\n    return {\n      status: 402,\n      body: {\n        error: 'AI usage budget exceeded.',\n        code:  'BUDGET_EXCEEDED',\n        ...(includeDetails && {\n          period:         err.period,\n          limitUsd:       err.limitUsd,\n          currentCostUsd: err.currentCostUsd,\n        }),\n      },\n    }\n  }\n\n  if (err instanceof CircuitOpenError) {\n    return {\n      status: 503,\n      body: {\n        error: 'AI provider temporarily unavailable.',\n        code:  'CIRCUIT_OPEN',\n        ...(includeDetails && {\n          retryAfter: Math.max(0, Math.ceil((err.openUntilMs - Date.now()) / 1000)),\n        }),\n      },\n    }\n  }\n\n  if (err instanceof ShutdownError) {\n    return {\n      status: 503,\n      body: {\n        error: 'Service is shutting down.',\n        code:  'SHUTDOWN',\n      },\n    }\n  }\n\n  return {\n    status: 429,\n    body: {\n      error: 'Rate limit exceeded.',\n      code:  'RATE_LIMITED',\n    },\n  }\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-sdk-rate-limiter",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Smart rate limiting, queuing, and cost tracking middleware for AI SDK calls. Works across providers.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -66,6 +66,16 @@
         "types": "./dist/statsd.d.cts",
         "default": "./dist/statsd.cjs"
       }
+    },
+    "./middleware": {
+      "import": {
+        "types": "./dist/middleware.d.ts",
+        "default": "./dist/middleware.js"
+      },
+      "require": {
+        "types": "./dist/middleware.d.cts",
+        "default": "./dist/middleware.cjs"
+      }
     }
   },
   "bin": {
@@ -97,6 +107,7 @@
   "license": "MIT",
   "devDependencies": {
     "@ai-sdk/provider": "^3.0.8",
+    "@types/node": "^22.19.15",
     "ai": "^6.0.0",
     "tsup": "^8.5.0",
     "typescript": "^5.8.0",
@@ -104,8 +115,8 @@
   },
   "peerDependencies": {
     "@ai-sdk/provider": ">=1.0.0",
-    "ioredis": ">=4.0.0",
-    "@opentelemetry/api": ">=1.0.0"
+    "@opentelemetry/api": ">=1.0.0",
+    "ioredis": ">=4.0.0"
   },
   "peerDependenciesMeta": {
     "@ai-sdk/provider": {