@lunora/ratelimit 1.0.0-alpha.4 → 1.0.0-alpha.41

package/LICENSE.md

@@ -103,3 +103,9 @@ Unless required by applicable law or agreed to in writing, software distributed
 under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
 CONDITIONS OF ANY KIND, either express or implied. See the License for the
 specific language governing permissions and limitations under the License.
+
+<!-- DEPENDENCIES -->
+<!-- /DEPENDENCIES -->
+
+<!-- TYPE_DEPENDENCIES -->
+<!-- /TYPE_DEPENDENCIES -->

package/README.md

@@ -59,37 +59,63 @@ to a procedure's `.use(...)` chain. The procedure builders (`mutation`, …) com
 from your app's generated `_generated/server` module, not from a package.
 
 ```ts
-import { RateLimiter, rateLimit } from "@lunora/ratelimit";
+import { dbRateLimit } from "@lunora/ratelimit";
 
 import { mutation } from "./_generated/server";
 
-const limiter = new RateLimiter({
-    config: {
-        login: { kind: "fixed window", period: 60_000, rate: 5 },
-        send: { kind: "token bucket", period: 1_000, rate: 10 },
-    },
-});
-
+const config = {
+    login: { kind: "fixed window", period: 60_000, rate: 5 },
+    send: { kind: "token bucket", period: 1_000, rate: 10 },
+};
+
+// `dbRateLimit` builds the limiter per call, backed by a Lunora table via
+// `ctx.db`, so the count is durable. A `RateLimiter` built with no explicit
+// `store` falls back to `createMemoryStore` (a per-instance in-memory Map) —
+// fine for a limit that only ever needs to hold within one Durable Object
+// instance, but a limiter like `login` needs a durable store or it stops
+// enforcing the configured rate the moment the DO instance is sharded,
+// replicated, or recreated.
 // As procedure middleware — throws a structural LunoraError (429/403) on rejection.
-export const send = mutation.use(rateLimit(limiter, "send", { key: (ctx) => ctx.auth.userId })).mutation(async ({ ctx }) => {
+// `key` must resolve to a string — a resolver returning `undefined` throws
+// rather than silently sharing one bucket across every keyless caller.
+export const send = mutation.use(dbRateLimit(config, "send", { key: (ctx) => ctx.auth.userId ?? "anonymous" })).mutation(async ({ ctx }) => {
     // …
 });
 ```
 
-Or call the limiter directly:
+Or call the limiter directly, inside a mutation/action so `ctx.db` is available.
+A login limiter belongs in an **action**: a mutation's `ctx.db` writes ride its
+storage transaction, so a handler that throws (a wrong password) rolls the
+consumed unit back and every failed attempt is free. An action's writes commit
+on their own, so the charge stays whether or not the handler throws.
 
 ```ts
-const status = await limiter.limit("send", { key: userId });
+import { RateLimiter, RateLimitError, createDbStore } from "@lunora/ratelimit";
+
+import { action } from "./_generated/server";
 
-if (!status.ok) {
-    // status.retryAfter is milliseconds until the request would succeed.
-    // status.reason is "rate" or "deny".
-}
+export const login = action.action(async ({ ctx, args }) => {
+    const limiter = new RateLimiter({ config, store: createDbStore({ db: ctx.db }) });
+    const status = await limiter.limit("login", { key: args.email });
+
+    if (!status.ok) {
+        // Stop here — `limit` returns a failing status by default rather than
+        // throwing, so falling through authenticates the rejected attempt.
+        // status.retryAfter is milliseconds until the request would succeed.
+        // status.reason is "rate" or "deny".
+        throw new RateLimitError(status);
+    }
+
+    await authenticate(args);
+});
 ```
 
 For durable per-DO state inside a procedure, back the limiter with a Lunora
 table via `dbRateLimit(config, name, options)`, or supply a `store`
-(`createMemoryStore` / `createSqlStore` / `createDbStore`).
+(`createSqlStore` / `createDbStore`). `createMemoryStore` stays the default —
+correct inside a single Durable Object — but constructing a `RateLimiter` with
+no explicit `store` now warns once so that choice is visible instead of
+silent.
 
 > This README covers the basics. For the full API, options, and guides, see the **[documentation](https://lunora.sh/docs)**.
 

package/dist/index.d.mts

@@ -1,61 +1,158 @@
 import { Middleware, Plugin } from '@lunora/server';
 import { Id } from '@lunora/values';
 import { LunoraError } from '@lunora/errors';
+/** Rate-limit algorithm. */
 type RateLimitKind = "fixed window" | "sliding window" | "token bucket";
+/** Why a request was denied. */
 type RateLimitReason = "deny" | "rate";
+/** Definition of a single named rate limit. */
 interface RateLimitConfig {
+  /**
+   * Maximum tokens that can accumulate (the rollover ceiling). Defaults to
+   * `rate`: for a token bucket that caps a burst at one period's worth of
+   * tokens, and for a fixed window it disables cross-window rollover. Ignored
+   * by sliding windows, which always cap at `rate` per `period`.
+   */
   capacity?: number;
   kind: RateLimitKind;
+  /** Window/refill period in milliseconds. */
   period: number;
+  /** Tokens granted per `period`. */
   rate: number;
+  /**
+   * Split a hot limit across N independent sub-buckets to avoid a single
+   * contended key/Durable Object. Each shard enforces `rate / shards` (and
+   * `capacity / shards`); a request is routed to a shard via a deterministic
+   * hash of `(name, key)`, so the same key always lands on the same shard and
+   * a single key's effective throughput is exactly `rate / shards`. Aggregate
+   * throughput across many distinct keys approaches `rate` as keys spread
+   * uniformly across shards. Reserve it for high-volume limits where
+   * contention bites; leave unset (one bucket) otherwise. Must be a positive
+   * integer — `1` is equivalent to unset.
+   */
   shards?: number;
+  /**
+   * Phase offset in epoch milliseconds for windowed algorithms — windows
+   * align to `start + n * period`. Ignored by token buckets. Defaults to `0`.
+   */
   start?: number;
 }
+/** A map of limit name to its config, used to construct a `RateLimiter`. */
 type RateLimitConfigMap<Names extends string = string> = Record<Names, RateLimitConfig>;
+/** Persisted accounting state for one `(name, key)` pair. */
 interface RateLimitValue {
+  /**
+   * Sliding window only: request count from the previous window, used to
+   * weight the current estimate. Unset for token-bucket / fixed-window.
+   */
   prev?: number;
+  /**
+   * Token-bucket: timestamp of the last refill. Fixed/sliding window: start of
+   * the window the value belongs to.
+   */
   ts: number;
+  /**
+   * Tokens available (token bucket), tokens remaining in the window (fixed
+   * window), or requests made in the current window (sliding window).
+   * Fractional for token buckets; negative when reserved ahead.
+   */
   value: number;
 }
+/** Outcome of a `RateLimiter.limit` / `RateLimiter.check` call. */
 interface RateLimitStatus {
+  /** Whether the request is permitted. */
   ok: boolean;
+  /** Why the request was denied. Absent when `ok`. */
   reason?: RateLimitReason;
+  /** Milliseconds until the request would succeed. `0` when `ok` without reservation. */
   retryAfter: number;
 }
+/** Per-call options for `RateLimiter.limit`. */
 interface RateLimitArgs {
+  /** Units to consume. Defaults to `1`. */
   count?: number;
+  /** Sub-key isolating the limit (per user/team/IP). Omit for a global limit. */
   key?: string;
+  /**
+   * Permit the request even when capacity is insufficient, reserving future
+   * capacity (the stored value goes negative). `retryAfter` then reports when
+   * the debt clears. Rejected only when `count` exceeds the bucket capacity.
+   */
   reserve?: boolean;
+  /** Throw `RateLimitError` instead of returning a failing status. */
   throws?: boolean;
 }
+/**
+ * Pluggable persistence. Reads and writes are keyed by an opaque storage key
+ * the limiter derives from the limit name and `key`. Implementations may be
+ * synchronous (in-memory) or asynchronous (SQLite/KV); the limiter awaits
+ * either.
+ */
 interface RateLimitStore {
   delete: (storageKey: string) => Promise<void> | void;
   get: (storageKey: string) => Promise<RateLimitValue | undefined> | RateLimitValue | undefined;
   set: (storageKey: string, value: RateLimitValue) => Promise<void> | void;
 }
+/** Inputs to {@link evaluate}. */
 interface EvaluateOptions {
+  /** When `false`, compute status without consuming (a `check`). */
   consume: boolean;
+  /** Units requested. */
   count: number;
+  /** Current time in epoch milliseconds. */
   now: number;
+  /** Permit a deficit by reserving future capacity (token bucket / within-window). */
   reserve: boolean;
 }
+/** Result of evaluating a limit against its prior state. */
 interface EvaluateResult {
   status: RateLimitStatus;
+  /** Next value to persist, or `undefined` when the call must not mutate state. */
   value: RateLimitValue | undefined;
 }
+/**
+ * Project a limit's stored state forward to `now` without consuming: how many
+ * units could be admitted right now. Token bucket → the refilled token count;
+ * fixed window → tokens left in the current (possibly rolled-over) window;
+ * sliding window → `rate` minus the weighted estimate, floored at zero. Pure,
+ * like {@link evaluate}, and shares its per-algorithm projection helpers so the
+ * two never diverge. Backs `RateLimiter.getValue` so it reports a live figure
+ * rather than the last value that happened to be persisted.
+ */
 declare const availableAt: (config: RateLimitConfig, prior: RateLimitValue | undefined, now: number) => {
   ts: number;
   value: number;
 };
+/**
+ * Evaluate a request against a limit's prior state. Pure: it never reads a
+ * clock or persists — the caller supplies `now` and writes back `value` when
+ * it is not `undefined`.
+ */
 declare const evaluate: (config: RateLimitConfig, prior: RateLimitValue | undefined, options: EvaluateOptions) => EvaluateResult;
 interface RateLimiterOptions<Names extends string> {
   config: RateLimitConfigMap<Names>;
+  /** Keys that are always denied, regardless of limit state. */
   denyList?: Iterable<string>;
+  /**
+   * Optional key normalizer applied to every incoming `args.key` (the
+   * deny-list check, the storage key, and downstream shard selection all see
+   * the normalized form). Use for case-folding, trimming, or canonicalizing
+   * IPs/emails so equivalent inputs share a single bucket. The deny-list
+   * itself is consulted as-is; normalize the deny-list entries up front to
+   * match.
+   */
   normalize?: (key: string) => string;
+  /** Clock injection for tests. Defaults to `Date.now`. */
   now?: () => number;
-  random?: () => number;
+  /** Persistence. Defaults to a per-instance in-memory store. */
   store?: RateLimitStore;
 }
+/**
+ * Enforces named rate limits over a pluggable store. Construct one per app with
+ * a config map; call {@link RateLimiter.limit} to consume and
+ * {@link RateLimiter.check} to peek. Framework-agnostic — the `@lunora/ratelimit`
+ * middleware wraps it for procedures.
+ */
 declare class RateLimiter<Names extends string = string> {
   private readonly config;
   private readonly denyList;
@@ -63,7 +160,16 @@ declare class RateLimiter<Names extends string = string> {
   private readonly now;
   private readonly store;
   constructor(options: RateLimiterOptions<Names>);
+  /** Peek at whether a request would be permitted without consuming. */
   check(name: Names, args?: Omit<RateLimitArgs, "reserve" | "throws">): Promise<RateLimitStatus>;
+  /**
+   * Read the current config and the units admittable right now for a
+   * `(name, key)` pair. The value is projected forward to the current clock
+   * (token-bucket refill, fixed-window rollover, sliding-window decay), not
+   * the last persisted figure. For a sharded limit it reads only the single
+   * shard `limit()`/`run()` would route this key to — the sibling shards are
+   * never touched by this key, so summing them would over-report.
+   */
   getValue(name: Names, args?: {
     key?: string;
   }): Promise<{
@@ -71,22 +177,74 @@ declare class RateLimiter<Names extends string = string> {
     ts: number;
     value: number;
   }>;
+  /** Consume capacity. Returns the outcome, or throws when `args.throws` is set. */
   limit(name: Names, args?: RateLimitArgs): Promise<RateLimitStatus>;
+  /** Clear accounting for a `(name, key)` pair (e.g. on successful login). */
   reset(name: Names, args?: {
     key?: string;
   }): Promise<void>;
+  private normalizeKey;
   private resolve;
   private run;
 }
+/**
+ * Either a fixed {@link RateLimiter} or a function that derives one from `ctx`
+ * — the latter lets a procedure bind a durable, ORM-backed limiter at call time
+ * (e.g. `(ctx) => new RateLimiter({ config, store: createDbStore({ db: ctx.db }) })`).
+ */
 type LimiterResolver<Context> = ((context: Context) => Promise<RateLimiter> | RateLimiter) | RateLimiter;
 interface RateLimitMiddlewareOptions<Context> {
+  /** Units to consume per call. Defaults to `1`. */
   count?: number;
+  /**
+   * Behavior when the limiter itself throws (store unavailable, etc).
+   * Defaults to `false` (fail closed: deny the request with a 503). Set to
+   * `true` only when degraded availability is preferable to denying traffic
+   * — note that a failing limiter then permits every request through.
+   */
   failOpen?: boolean;
+  /**
+   * Sub-key derived from `ctx` (per-user/IP). Omit for a global limit.
+   *
+   * A resolver that returns `undefined` is a config bug, not a global limit:
+   * the middleware throws `INTERNAL` rather than silently pooling every
+   * keyless caller (e.g. every anonymous user) into one shared bucket. Fold
+   * the absent case yourself — `ctx.auth.userId ?? "anonymous"` — so the
+   * shared bucket is a visible choice.
+   */
   key?: (context: Context) => string | undefined;
+  /** Override the error message thrown on rejection. */
   message?: string;
 }
+/**
+ * Procedure middleware that enforces a named rate limit before the handler
+ * runs. Attach it with `.use()`. On rejection it throws a structural
+ * `LunoraError` (`TOO_MANY_REQUESTS`/429, or `FORBIDDEN`/403 for deny-list
+ * hits) carrying `data.retryAfterMs` — the runtime maps it to the
+ * matching RPC/HTTP status without any import of `@lunora/server` at runtime.
+ *
+ * **Failure policy:** if resolving or invoking the limiter throws for a genuine
+ * availability reason (e.g. the persistence store is unavailable), the
+ * middleware **fails closed by default**: it logs via `console.error` and
+ * rejects the request with `503`. This is the safer default for
+ * security-sensitive limits (auth, account creation). Pass `failOpen: true` to
+ * swallow the error and admit the request instead — appropriate only when
+ * degraded availability is preferable to refusal. Deterministic caller misuse
+ * (an unconfigured limit name, a non-positive count, or a count that exceeds
+ * capacity) throws an `INTERNAL` `LunoraError` that is re-thrown as-is under
+ * **both** policies — a config bug is never masked as a 503 or silently admitted.
+ */
 declare const rateLimit: <Context>(limiter: LimiterResolver<Context>, name: string, options?: RateLimitMiddlewareOptions<Context>) => Middleware<Context, Context>;
+/**
+ * In-memory store. State lives for the lifetime of the process (or, inside a
+ * Durable Object, the instance) — adequate for single-DO limits but not shared
+ * across instances. Use {@link createSqlStore} for durable per-DO state.
+ */
 declare const createMemoryStore: () => RateLimitStore;
+/**
+ * Minimal projection of `state.storage.sql` (workerd's `SqlStorage`, also
+ * satisfied by `node:sqlite`). Only the `exec` overload is required.
+ */
 interface SqlLike {
   exec: <Row = Record<string, unknown>>(query: string, ...params: unknown[]) => {
     toArray: () => Row[];
@@ -94,9 +252,29 @@ interface SqlLike {
 }
 interface SqlStoreOptions {
   sql: SqlLike;
+  /** Table name. Created if missing. Defaults to `_lunora_rate_limits`. */
   table?: string;
 }
+/**
+ * SQLite-backed store for durable, per-DO rate-limit state. Persists each
+ * `(name, key)` pair as one row so limits survive hibernation and eviction.
+ *
+ * **Atomicity:** the store does not wrap individual operations in an explicit
+ * SQL transaction. Inside a Durable Object the DO's input gate serializes
+ * every RPC call against the storage, so the limiter's read-modify-write
+ * sequence runs to completion without interleaving — this is the same
+ * guarantee the surrounding `evaluate()` step depends on. **Outside a DO**
+ * (e.g. driving `createSqlStore` from a long-lived `node:sqlite` connection in
+ * tests or a custom host) the caller is responsible for serialization; the
+ * SQL surface used here (`exec`) is not a substitute for transactional
+ * isolation across concurrent invocations.
+ */
 declare const createSqlStore: (options: SqlStoreOptions) => RateLimitStore;
+/**
+ * The slice of an index-range builder the store uses. Mirrors `@lunora/server`'s
+ * `IndexRangeBuilder` field-for-field so the real `ctx.db` query builder is
+ * assignable; only `eq` is exercised.
+ */
 interface RateLimitDatabaseIndexRange {
   eq: (field: string, value: unknown) => RateLimitDatabaseIndexRange;
   gt: (field: string, value: unknown) => RateLimitDatabaseIndexRange;
@@ -104,33 +282,146 @@ interface RateLimitDatabaseIndexRange {
   lt: (field: string, value: unknown) => RateLimitDatabaseIndexRange;
   lte: (field: string, value: unknown) => RateLimitDatabaseIndexRange;
 }
+/** The slice of a `ctx.db` table query the store relies on. */
 interface RateLimitDatabaseQuery {
   first: () => Promise<Record<string, unknown> | null>;
   withIndex: (indexName: string, range: (q: RateLimitDatabaseIndexRange) => RateLimitDatabaseIndexRange) => RateLimitDatabaseQuery;
 }
-interface RateLimitDatabase {
+/**
+ * The READ slice — everything the store needs to answer `RateLimiter.getValue`
+ * and `check`, which the docs describe as projecting the stored value forward to
+ * the current clock. A `QueryCtx`'s `ctx.db` is a reader and satisfies this.
+ *
+ * Split out because requiring the writer for a pure read meant "how many
+ * requests does this user have left" could not be answered from a query context
+ * at all — every remaining-quota display had to cast, and a cast that appears
+ * often enough stops carrying information. The distinction was already in the
+ * methods: `getValue`/`check` read, `limit`/`reset` write.
+ */
+interface RateLimitDatabaseReader {
+  query: (table: string) => RateLimitDatabaseQuery;
+}
+/**
+ * The slice of the Lunora ORM writer (`ctx.db` on a mutation/action) the store
+ * needs. The real `DatabaseWriter` is structurally assignable, so pass `ctx.db`
+ * directly — declared here (rather than imported) to keep `@lunora/ratelimit`
+ * free of a runtime dependency on `@lunora/server`.
+ */
+interface RateLimitDatabase extends RateLimitDatabaseReader {
   delete: <T extends string>(id: Id<T>) => Promise<void>;
   insert: <T extends string>(table: T, document: Record<string, unknown>) => Promise<Id<T>>;
   patch: <T extends string>(id: Id<T>, patch: Record<string, unknown>) => Promise<void>;
-  query: (table: string) => RateLimitDatabaseQuery;
 }
-interface DatabaseStoreOptions {
-  db: RateLimitDatabase;
+/** The table/column/index knobs shared by the read-only and read-write stores. */
+interface DatabaseStoreLocation {
+  /** Index that resolves a row by its key column. Defaults to `by_key`. */
   index?: string;
+  /** Column storing the opaque key. Defaults to `key`. */
   keyField?: string;
+  /** Table holding one row per `(name, key)` pair. Defaults to `rateLimits`. */
   table?: string;
 }
+interface DatabaseStoreOptions extends DatabaseStoreLocation {
+  /** The Lunora ORM writer — `ctx.db` inside a mutation or action. */
+  db: RateLimitDatabase;
+}
+interface ReadOnlyDatabaseStoreOptions extends DatabaseStoreLocation {
+  /** The Lunora ORM reader — `ctx.db` inside a query. */
+  db: RateLimitDatabaseReader;
+}
+/**
+ * Store backed by a Lunora table through `ctx.db`, for durable per-DO limits
+ * inside a procedure (the procedure context exposes no raw SQL). Declare a
+ * table with the key column and its index, e.g.
+ *
+ * ```ts
+ * rateLimits: defineTable({
+ *     key: v.string(),
+ *     ts: v.number(),
+ *     value: v.number(),
+ *     prev: v.optional(v.number()),
+ * }).index("by_key", ["key"])
+ * ```
+ *
+ * Each operation is a read-then-write; inside a mutation/action that pair runs
+ * under the DO's input gate, so it is atomic against concurrent calls.
+ *
+ * **Consumption commits with the procedure.** A mutation's `ctx.db` writes ride
+ * its storage transaction, so a handler that throws after `limit()` rolls the
+ * consumed unit back with everything else — inside a mutation this store counts
+ * successful calls, not attempts. To charge every attempt (a login limiter),
+ * consume from an action, where each write commits on its own, or return a
+ * failure value from the mutation instead of throwing.
+ */
 declare const createDatabaseStore: (options: DatabaseStoreOptions) => RateLimitStore;
+/**
+ * Read-only counterpart to {@link createDatabaseStore}, for a query context.
+ *
+ * `get` behaves identically — same table, index and key column — so
+ * `RateLimiter.getValue` / `check` report exactly what the writing store would.
+ * `set` and `delete` are the only difference: they throw rather than silently
+ * doing nothing, because a limiter that appears to consume budget and does not
+ * is worse than one that refuses.
+ *
+ * This mirrors the split Lunora already makes for `ctx.storage`, which is a
+ * `ReadOnlyStorage` in a query and a full `Storage` in an action — the
+ * capability difference is visible in the type instead of discovered at runtime.
+ */
+declare const createReadOnlyDatabaseStore: (options: ReadOnlyDatabaseStoreOptions) => RateLimitStore;
+/**
+ * DB-backed rate-limit middleware sugar. Collapses the common
+ *
+ * ```ts
+ * rateLimit((ctx) => new RateLimiter({ config, store: createDbStore({ db: ctx.db }) }), name, opts)
+ * ```
+ *
+ * into `dbRateLimit(config, name, opts)`: it builds a per-call {@link RateLimiter}
+ * whose accounting lives in a Lunora table via `ctx.db` (so the bucket is durable
+ * on the DO the procedure runs on). Every query/mutation/action ctx exposes a
+ * compatible `db`, so it slots straight into a `.use(...)` chain.
+ *
+ * Pass `options.store` to point at a non-default backing table/index/key column
+ * (defaults: table `rateLimits`, index `by_key`, key column `key`); the rest of
+ * `options` (`key`, `count`, `failOpen`, `message`) is forwarded to
+ * {@link rateLimit} unchanged. When `config` is precisely typed, `name`
+ * autocompletes to its declared limit names.
+ *
+ * On a mutation the consumed unit commits with the handler: a handler that
+ * throws rolls it back, so a failed call costs nothing. Attach it to an action
+ * (whose writes commit independently) when failed attempts must count — see
+ * {@link createDatabaseStore}.
+ *
+ * Re-exported as `dbRateLimit` from the package root.
+ *
+ * ```ts
+ * const limits = { send: { kind: "token bucket", period: 60_000, rate: 30 } } satisfies RateLimitConfigMap;
+ *
+ * export const send = mutation
+ *   .input({ text: v.string() })
+ *   .use(dbRateLimit(limits, "send", { key: (ctx) => ctx.auth.userId ?? "anonymous" }))
+ *   .mutation(async ({ ctx, args }) => ...);
+ * ```
+ */
 declare const databaseRateLimit: <Context extends {
   db: RateLimitDatabase;
 }, Names extends string = string>(config: RateLimitConfigMap<Names>, name: Names, options?: RateLimitMiddlewareOptions<Context> & {
   store?: Omit<DatabaseStoreOptions, "db">;
 }) => Middleware<Context, Context>;
+/**
+ * Thrown by `RateLimiter.limit` when called with `{ throws: true }`. A
+ * `LunoraError` subclass whose code/status track `status.reason`: a rate
+ * rejection is `TOO_MANY_REQUESTS`/429, a deny-list hit is `FORBIDDEN`/403 —
+ * the same mapping the middleware applies, so both entry points surface the
+ * identical wire code (a permanent deny is never a retryable 429). The
+ * middleware itself throws a bare structural `LunoraError`, so this is for
+ * direct callers that prefer exceptions. Keeps `reason`/`retryAfter`.
+ */
 declare class RateLimitError extends LunoraError {
   readonly reason: RateLimitReason | undefined;
   readonly retryAfter: number;
   constructor(status: RateLimitStatus, message?: string);
 }
+/** Context shape the plugin middleware widens to: a `ratelimit` limiter on `ctx.api`. */
 interface RatelimitApiContext<Context> {
   api: (Context extends {
     api: infer A;
@@ -138,6 +429,81 @@ interface RatelimitApiContext<Context> {
     ratelimit: RateLimiter;
   };
 }
+/**
+ * Package `@lunora/ratelimit` as a first-party {@link Plugin}, the dogfooded
+ * form of the plugin contract: instead of (or alongside) the enforcing
+ * `rateLimit(...)` middleware, this exposes the resolved {@link RateLimiter}
+ * under `ctx.api.ratelimit` so a handler can `limit()`/`check()`/`reset()`
+ * programmatically.
+ *
+ * Install the middleware with one `.use(...)` (or fold it in with
+ * `composePluginMiddleware([...])`):
+ *
+ * ```ts
+ * const limiter = new RateLimiter({ config: { send: { kind: "token bucket", rate: 5, period: 60_000, capacity: 5 } } });
+ * const c = initLunora.dataModel<DataModel>().create();
+ * export const send = c.mutation
+ *     .use(ratelimitPlugin(limiter).middleware!)
+ *     .mutation(async ({ ctx, args }) => {
+ *         const status = await ctx.api.ratelimit.limit("send", { key: ctx.userId });
+ *         if (!status.ok) throw new Error("slow down");
+ *         // …
+ *     });
+ * ```
+ *
+ * The plugin ships no schema extension — the limiter's persistence is whatever
+ * store the resolved {@link RateLimiter} was built with — so it is a
+ * middleware-only plugin and is skipped by `installPlugins(...)`'s schema fold.
+ *
+ * Built as a plain {@link Plugin} literal (the key is the fixed string
+ * `"ratelimit"`, so the `definePlugin` validation adds nothing) — this keeps
+ * `@lunora/server` a type-only dependency of `@lunora/ratelimit`.
+ */
 declare const ratelimitPlugin: <Context = unknown>(limiter: LimiterResolver<Context>) => Plugin<Record<never, never>, Context, Context & RatelimitApiContext<Context>>;
+/** A budget bound to one named limit — check before the call, record after it. */
+interface TokenBudget {
+  /**
+   * Peek at the budget before spending. `ok: false` means it is exhausted:
+   * refuse the call, and `retryAfter` says when it refills. Consumes nothing.
+   */
+  check: (key: string) => Promise<RateLimitStatus>;
+  /**
+   * Charge the tokens a call actually used. Always call it, including when the
+   * call THREW — a failed generation that consumed input tokens still has to be
+   * paid for. `tokens` of `0` is a no-op, so a call that spent nothing costs
+   * nothing.
+   *
+   * The charge is a reservation, so it may take the bucket negative: the tokens
+   * are already spent, and refusing to record them would let a single oversized
+   * call escape the budget entirely.
+   */
+  record: (key: string, tokens: number) => Promise<RateLimitStatus>;
+}
+/**
+ * Bind a {@link TokenBudget} to one of a limiter's named limits.
+ *
+ * ```ts
+ * const budget = tokenBudget(limiter, "tokens");
+ * const allowed = await budget.check(userId);
+ *
+ * if (!allowed.ok) {
+ *     throw new LunoraError("RATE_LIMITED", `token budget exhausted; retry in ${String(allowed.retryAfter)}ms`);
+ * }
+ *
+ * try {
+ *     const { text, usage } = await generateText({ model: ctx.ai.model(), prompt });
+ *
+ *     await budget.record(userId, usage?.totalTokens ?? 0);
+ *
+ *     return text;
+ * } catch (error) {
+ *     // The prompt was still sent — charge what is known, then rethrow.
+ *     await budget.record(userId, estimatedInputTokens);
+ *
+ *     throw error;
+ * }
+ * ```
+ */
+declare const tokenBudget: <Names extends string>(limiter: RateLimiter<Names>, name: Names) => TokenBudget;
 declare const VERSION = "0.0.0";
-export { type DatabaseStoreOptions as DbStoreOptions, type EvaluateOptions, type EvaluateResult, type LimiterResolver, type RateLimitArgs, type RateLimitConfig, type RateLimitConfigMap, type RateLimitDatabase as RateLimitDb, type RateLimitDatabaseIndexRange as RateLimitDbIndexRange, type RateLimitDatabaseQuery as RateLimitDbQuery, RateLimitError, type RateLimitKind, type RateLimitMiddlewareOptions, type RateLimitReason, type RateLimitStatus, type RateLimitStore, type RateLimitValue, RateLimiter, type RateLimiterOptions, type RatelimitApiContext, type SqlLike, type SqlStoreOptions, VERSION, availableAt, createDatabaseStore as createDbStore, createMemoryStore, createSqlStore, databaseRateLimit as dbRateLimit, evaluate, rateLimit, ratelimitPlugin };
+export { type DatabaseStoreOptions as DbStoreOptions, type EvaluateOptions, type EvaluateResult, type LimiterResolver, type RateLimitArgs, type RateLimitConfig, type RateLimitConfigMap, type RateLimitDatabase as RateLimitDb, type RateLimitDatabaseIndexRange as RateLimitDbIndexRange, type RateLimitDatabaseQuery as RateLimitDbQuery, type RateLimitDatabaseReader as RateLimitDbReader, RateLimitError, type RateLimitKind, type RateLimitMiddlewareOptions, type RateLimitReason, type RateLimitStatus, type RateLimitStore, type RateLimitValue, RateLimiter, type RateLimiterOptions, type RatelimitApiContext, type ReadOnlyDatabaseStoreOptions as ReadOnlyDbStoreOptions, type SqlLike, type SqlStoreOptions, type TokenBudget, VERSION, availableAt, createDatabaseStore as createDbStore, createMemoryStore, createReadOnlyDatabaseStore as createReadOnlyDbStore, createSqlStore, databaseRateLimit as dbRateLimit, evaluate, rateLimit, ratelimitPlugin, tokenBudget };