llmbrake 0.0.0-stage → 0.2.0

package/LICENSE

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

package/README.md

@@ -1,3 +1,221 @@
-# Temporary Holding Version
+# llmbrake
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Per-customer cost caps for AI apps: put a monthly dollar budget on every customer, switch them to a cheaper model near the cap, and block them at the cap.**
+
+[![npm version](https://img.shields.io/npm/v/llmbrake.svg)](https://www.npmjs.com/package/llmbrake)
+[![CI](https://github.com/llmbrake/llmbrake/actions/workflows/ci.yml/badge.svg)](https://github.com/llmbrake/llmbrake/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+`llmbrake` is a small TypeScript library that wraps your OpenAI-compatible `chat.completions.create` call. It prices every call in USD from the token usage the provider returns and keeps a running monthly total per customer. Near a customer's budget it swaps in a cheaper model; at the budget it throws a typed `BudgetExceededError` before the request ever reaches the provider.
+
+- **Not a proxy.** It runs inside your app and calls your provider directly with your own keys.
+- **Metadata only.** It never reads or stores prompts or completions, only customer ID, plan, feature tag, model, token counts, cost and timestamps.
+- **Zero runtime dependencies.** ESM, Node 18+, MIT licensed.
+
+Status: `0.1.0`, early. Website: [llmbrake.com](https://llmbrake.com)
+
+## Install
+
+```bash
+npm install llmbrake
+```
+
+Published on npm as [`llmbrake`](https://www.npmjs.com/package/llmbrake). To try the latest `main` instead, run `npm install github:llmbrake/llmbrake` (it builds on install).
+
+`llmbrake` is ESM-only (`import`, not `require`).
+
+## 30-second quickstart
+
+```ts
+import OpenAI from "openai";
+import { createGuard, isBudgetExceededError } from "llmbrake";
+
+const openai = new OpenAI();
+
+const guard = createGuard({
+  budgetUsd: (ctx) => (ctx.plan === "pro" ? 20 : 2), // USD per customer per calendar month (UTC)
+  downgradeAt: 0.8,                                   // at 80% of the budget...
+  downgradeMap: { "gpt-5.5": "gpt-5.4-mini" },        // ...send gpt-5.5 requests to gpt-5.4-mini
+});
+
+const chat = openai.chat.completions;
+const create = guard.wrap(chat.create.bind(chat));
+
+try {
+  const res = await create(
+    { model: "gpt-5.5", messages: [{ role: "user", content: "Hello" }] },
+    { customerId: user.id, plan: user.plan, feature: "chat" },
+  );
+} catch (e) {
+  if (isBudgetExceededError(e)) {
+    // e.customerId, e.spentUsd, e.budgetUsd, e.period
+    return showUpgradePrompt();
+  }
+  throw e;
+}
+
+await guard.status({ customerId: user.id, plan: user.plan });
+// → { period: "2026-10", spentUsd: …, budgetUsd: 20, remainingUsd: … }
+```
+
+## How it works
+
+Every wrapped call goes through three steps:
+
+1. **Check (before the call).** `llmbrake` resolves the customer's budget (a number, or your `(ctx) => number` function, e.g. by plan) and reads their spend for the current period, a calendar month in UTC such as `2026-10`.
+2. **Decide.**
+   - **Block:** if `spent >= budget`, it throws `BudgetExceededError` (`code: "LLMBRAKE_BUDGET_EXCEEDED"`) and **the provider is never called**. Catch it to show an upgrade prompt.
+   - **Downgrade:** if `spent >= budget × downgradeAt` and the requested model has an entry in `downgradeMap`, the request is sent with the cheaper model instead. The usage event reports `downgraded: true` and the original `requestedModel`.
+   - Otherwise the request goes through unchanged.
+3. **Record (after the call).** The cost is computed from the response's `usage` (uncached input, cached input and output tokens) and your price table, then added to the customer's total. The `onUsage` hook receives a usage event:
+
+```ts
+{
+  customerId: "cus_123", plan: "pro", feature: "chat", period: "2026-10",
+  requestedModel: "gpt-5.5", model: "gpt-5.4-mini", downgraded: true,
+  promptTokens: 1102, completionTokens: 182, cachedTokens: 640,
+  costUsd: 0.0012, spentUsd: 16.41, budgetUsd: 20, timestamp: "2026-10-11T20:00:00.000Z"
+}
+```
+
+`guard.check(ctx, model)` runs steps 1–2 without making a call, which is handy for disabling a button before the user clicks it.
+
+### Streaming
+
+With `stream: true`, `llmbrake` sets `stream_options.include_usage = true` and records the cost when the stream ends, including when your code stops reading early (whatever usage was received by then is recorded).
+
+### Other OpenAI-compatible endpoints
+
+Any `create(params)` function that accepts `{ model, ... }` and returns `{ model, usage: { prompt_tokens, completion_tokens } }` works, for example OpenRouter, Anthropic's OpenAI-compatible endpoint and local gateways. Add their model IDs to the price table.
+
+## Examples: Vercel AI SDK, OpenRouter, LangChain
+
+Tested integrations live in [`examples/`](examples/):
+
+- **[Vercel AI SDK](examples/vercel-ai-sdk/)**: `guard.check()` before `generateText` / `streamText`, then charge from `result.usage` (cached tokens included). Also has a Next.js route handler sketch.
+- **[OpenRouter](examples/openrouter/)**: `guard.wrap()` on the OpenAI SDK pointed at OpenRouter, with OpenRouter model IDs in the price table.
+- **[LangChain.js](examples/langchain/)**: `guard.check()` before `invoke()`, then charge from `AIMessage.usage_metadata`.
+
+CI runs them against mock providers (no API keys).
+
+## Storage (Redis example)
+
+The default `MemoryStore` keeps totals in process memory: fine for one server, tests and demos, but lost on restart and not shared between instances. For multiple instances or serverless, implement the two-method `UsageStore` interface. With [ioredis](https://github.com/redis/ioredis):
+
+```ts
+import Redis from "ioredis";
+import { createGuard, type UsageStore } from "llmbrake";
+
+const redis = new Redis(process.env.REDIS_URL!);
+const key = (customerId: string, period: string) => `llmbrake:${period}:${customerId}`;
+
+const redisStore: UsageStore = {
+  async getSpend(customerId, period) {
+    return Number((await redis.get(key(customerId, period))) ?? 0);
+  },
+  async addSpend(customerId, period, usd) {
+    const k = key(customerId, period);
+    const res = await redis
+      .multi()
+      .incrbyfloat(k, usd)
+      .expire(k, 60 * 60 * 24 * 40) // keep ~40 days, then let old months expire
+      .exec();
+    const [err, total] = res?.[0] ?? [new Error("Redis transaction failed"), null];
+    if (err) throw err;
+    return Number(total);
+  },
+};
+
+const guard = createGuard({ budgetUsd: 5, store: redisStore });
+```
+
+`INCRBYFLOAT` is atomic, so totals stay correct across instances. If the store throws (or returns a non-numeric value), calls **fail open** by default so your product keeps working; set `failOpen: false` to fail closed instead.
+
+## Shared budgets across servers (`HostedStore`)
+
+`HostedStore` keeps the counters in LLMBrake Cloud, so every server and serverless instance using your project's API key shares one counter per customer, and budgets you edit in the dashboard apply on the next call, with no Redis to run:
+
+```ts
+import { createGuard, HostedStore } from "llmbrake";
+
+const guard = createGuard({
+  budgetUsd: 5, // default; a budget set in the dashboard for a customer wins
+  downgradeMap: { "gpt-5.5": "gpt-5.4-mini" },
+  store: new HostedStore({ apiKey: process.env.LLMBRAKE_API_KEY! }),
+});
+```
+
+It also closes the concurrent-overshoot gap: before each call the guard **reserves** an estimate of the call's cost (prompt size plus `max_tokens`, or `estimateUsd`), and the reservation only succeeds if spend plus other in-flight reservations is under the budget, in one atomic step on the server. After the call it **settles** the real cost and releases the hold (failed provider calls release it at $0). Parallel calls can then overshoot by at most about one call, instead of by everything in flight. If the API is unreachable the guard follows `failOpen` (default: let the call through).
+
+Any store can opt in to this by implementing `reserve` and `settle` (the `ReservingStore` interface).
+
+## Options
+
+`createGuard(options)` returns `{ wrap, check, status }`.
+
+| Option | Default | Description |
+|---|---|---|
+| `budgetUsd` | required | Monthly USD budget: a number, or `(ctx) => number \| Promise<number>`. Must be `>= 0`; use `Infinity` for unlimited. |
+| `store` | `new MemoryStore()` | Where spend is kept. Any `UsageStore` (`getSpend`, `addSpend`). |
+| `prices` | `DEFAULT_PRICES` | Model → `{ inputPerMTok, outputPerMTok, cachedInputPerMTok?, source? }`, USD per 1M tokens. |
+| `downgradeAt` | `0.8` | Fraction of the budget (0–1) at which `downgradeMap` applies. `1` disables downgrading. |
+| `downgradeMap` | `{}` | `{ "expensive-model": "cheaper-model" }`. |
+| `onUsage` | none | `(event) => void \| Promise<void>`, called after each metered call. Errors in it are swallowed. |
+| `unknownModel` | `"throw"` | Model missing from `prices`: `"throw"` an `UnknownModelPriceError` before the call, or `"allow"` it and record `costUsd: null`. |
+| `failOpen` | `true` | If the store errors: `true` lets calls through, `false` rethrows. |
+| `now` | `() => new Date()` | Clock override, mainly for tests. |
+| `estimateUsd` | estimated | Reserving stores only (`HostedStore`): USD to hold while a call is in flight, a number or `(ctx, params) => number`. Default: prompt length / 4 tokens plus `max_completion_tokens`/`max_tokens` (or 1,000) at the requested model's price. |
+
+The call context passed as the second argument to the wrapped function is `{ customerId: string; plan?: string; feature?: string }`.
+
+## Model prices: verify before relying on them
+
+`DEFAULT_PRICES` covers a few common OpenAI and Anthropic models in USD per 1M tokens (standard tier), read on 2026-10-09 from:
+
+- OpenAI: https://developers.openai.com/api/docs/pricing
+- Anthropic: https://docs.anthropic.com/en/docs/about-claude/pricing
+
+**Provider prices change often, and these values are not guaranteed current.** Check them against the pages above before using them for billing decisions. Each entry carries a `source` field. Override or extend the table:
+
+```ts
+import { createGuard, DEFAULT_PRICES } from "llmbrake";
+
+createGuard({
+  budgetUsd: 5,
+  prices: { ...DEFAULT_PRICES, "my-model": { inputPerMTok: 1, outputPerMTok: 3 } },
+});
+```
+
+Dated snapshot IDs such as `gpt-5.4-mini-2026-03-17` fall back to the undated entry.
+
+## Known limitations
+
+- **Concurrent overshoot.** With `MemoryStore` or a plain `UsageStore`, the budget is checked before a call and the cost is recorded after it, so several in-flight calls for the same customer can each pass the check and overshoot the cap by roughly their combined cost. `HostedStore` (or any `ReservingStore`) reserves before each call, which bounds the overshoot to about one call.
+- **Prices need verification.** See above. Long-context tiers, batch discounts, regional or data-residency uplifts and priority tiers are not modeled, and the Anthropic IDs in the default table may differ from what your endpoint accepts.
+- **Chat completions only.** Only chat-completions-style token usage is metered: no images, audio, embeddings or tool fees yet.
+- **Streaming needs usage.** If a provider ignores `include_usage`, or a stream is abandoned before the usage chunk arrives, that call is recorded with zero cost.
+- **UTC calendar months.** Budget periods reset at 00:00 UTC on the 1st.
+
+## Python
+
+A Python port with the same behavior lives in [`python/`](python/README.md): sync and async `openai` clients, streaming, pluggable stores (in-memory, Redis), zero required dependencies, Python 3.9+.
+
+`pip install llmbrake` is coming soon to PyPI. For now, install from GitHub:
+
+```bash
+pip install "git+https://github.com/llmbrake/llmbrake#subdirectory=python"
+```
+
+See [python/README.md](python/README.md) for the quickstart.
+
+## Hosted dashboard (LLMBrake Cloud)
+
+The library is free and stays MIT licensed. LLMBrake Cloud is the optional paid layer on top: shared counters (`HostedStore`), a dashboard with spend, budget and status per customer (edit budgets live), Slack/webhook alerts at 80% and 100%, and AI cost vs. Stripe revenue per customer. See [llmbrake.com](https://llmbrake.com).
+
+## Contributing
+
+Issues and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md). Security issues: see [SECURITY.md](SECURITY.md).
+
+## License
+
+[MIT](LICENSE)

package/dist/errors.d.ts

@@ -0,0 +1,14 @@
+export declare class BudgetExceededError extends Error {
+    readonly customerId: string;
+    readonly spentUsd: number;
+    readonly budgetUsd: number;
+    readonly period: string;
+    readonly code: "LLMBRAKE_BUDGET_EXCEEDED";
+    constructor(customerId: string, spentUsd: number, budgetUsd: number, period: string);
+}
+export declare class UnknownModelPriceError extends Error {
+    readonly model: string;
+    readonly code: "LLMBRAKE_UNKNOWN_MODEL";
+    constructor(model: string);
+}
+export declare function isBudgetExceededError(e: unknown): e is BudgetExceededError;

package/dist/errors.js

@@ -0,0 +1,27 @@
+export class BudgetExceededError extends Error {
+    customerId;
+    spentUsd;
+    budgetUsd;
+    period;
+    code = "LLMBRAKE_BUDGET_EXCEEDED";
+    constructor(customerId, spentUsd, budgetUsd, period) {
+        super(`Customer ${customerId} has used $${spentUsd.toFixed(4)} of a $${budgetUsd.toFixed(2)} AI budget for ${period}.`);
+        this.customerId = customerId;
+        this.spentUsd = spentUsd;
+        this.budgetUsd = budgetUsd;
+        this.period = period;
+        this.name = "BudgetExceededError";
+    }
+}
+export class UnknownModelPriceError extends Error {
+    model;
+    code = "LLMBRAKE_UNKNOWN_MODEL";
+    constructor(model) {
+        super(`No price configured for model "${model}". Add it to the price table.`);
+        this.model = model;
+        this.name = "UnknownModelPriceError";
+    }
+}
+export function isBudgetExceededError(e) {
+    return e instanceof BudgetExceededError;
+}

package/dist/guard.d.ts

@@ -0,0 +1,78 @@
+import { PriceTable } from "./prices.js";
+import { UsageStore } from "./store.js";
+export interface CallContext {
+    customerId: string;
+    /** Optional plan name, passed to your budget function. */
+    plan?: string;
+    /** Optional feature tag for analytics, e.g. "summarize". */
+    feature?: string;
+}
+export interface UsageEvent {
+    customerId: string;
+    plan?: string;
+    feature?: string;
+    period: string;
+    requestedModel: string;
+    model: string;
+    downgraded: boolean;
+    promptTokens: number;
+    completionTokens: number;
+    cachedTokens: number;
+    /** null when the model had no price configured */
+    costUsd: number | null;
+    spentUsd: number;
+    budgetUsd: number;
+    timestamp: string;
+}
+export interface GuardOptions {
+    /** Monthly USD budget for a customer (number or lookup). Return Infinity for unlimited. */
+    budgetUsd: number | ((ctx: CallContext) => number | Promise<number>);
+    store?: UsageStore;
+    prices?: PriceTable;
+    /** Fraction of budget (0–1) at which to switch to a cheaper model. Default 0.8. Set to 1 to disable. */
+    downgradeAt?: number;
+    /** Map of expensive model -> cheaper model to use once past `downgradeAt`. */
+    downgradeMap?: Record<string, string>;
+    /** Called after each successful, metered call. Errors thrown here are swallowed. */
+    onUsage?: (e: UsageEvent) => void | Promise<void>;
+    /** What to do when a model has no price: "throw" before calling, or "allow" and record cost null. Default "throw". */
+    unknownModel?: "throw" | "allow";
+    /** If the store fails, let the call through (true, default) or rethrow (false). */
+    failOpen?: boolean;
+    /** Clock override for tests. */
+    now?: () => Date;
+    /**
+     * Only used with a reserving store (e.g. HostedStore): the cost to hold while a call is in flight.
+     * Default: estimated from the prompt size (~4 chars/token) plus `max_completion_tokens`/`max_tokens`
+     * (or 1,000 output tokens) at the requested model's price.
+     */
+    estimateUsd?: number | ((ctx: CallContext, params: Record<string, unknown>) => number);
+}
+/** Rough upper-ish estimate of a call's cost, used only to size reservations. */
+export declare function estimateCallUsd(model: string, params: Record<string, unknown>, prices?: PriceTable): number;
+type ChatParams = {
+    model: string;
+    stream?: boolean | null;
+    stream_options?: Record<string, unknown> | null;
+    [k: string]: unknown;
+};
+type CreateFn<P, R> = (params: P, ...rest: any[]) => Promise<R>;
+export declare function periodOf(d: Date): string;
+export declare function createGuard(opts: GuardOptions): {
+    wrap: <P extends ChatParams, R>(createFn: CreateFn<P, R>) => (params: P, ctx: CallContext, ...rest: any[]) => Promise<R>;
+    check: (ctx: CallContext, model: string) => Promise<{
+        period: string;
+        budget: number;
+        spent: number;
+        model: string;
+        downgraded: boolean;
+        holdId: string | null;
+    }>;
+    status: (ctx: CallContext) => Promise<{
+        period: string;
+        spentUsd: number;
+        budgetUsd: number;
+        remainingUsd: number;
+    }>;
+};
+export {};

package/dist/guard.js

@@ -0,0 +1,226 @@
+import { BudgetExceededError, UnknownModelPriceError } from "./errors.js";
+import { DEFAULT_PRICES, computeCostUsd } from "./prices.js";
+import { MemoryStore, isReservingStore } from "./store.js";
+/** Rough upper-ish estimate of a call's cost, used only to size reservations. */
+export function estimateCallUsd(model, params, prices = DEFAULT_PRICES) {
+    let chars = 0;
+    try {
+        chars = JSON.stringify(params.messages ?? params.input ?? params.prompt ?? "").length;
+    }
+    catch { /* circular: ignore */ }
+    const maxOut = Number(params.max_completion_tokens ?? params.max_tokens ?? 1000);
+    const cost = computeCostUsd(model, { prompt_tokens: Math.ceil(chars / 4), completion_tokens: Number.isFinite(maxOut) && maxOut > 0 ? maxOut : 1000 }, prices);
+    return cost ?? 0;
+}
+export function periodOf(d) {
+    return `${d.getUTCFullYear()}-${String(d.getUTCMonth() + 1).padStart(2, "0")}`;
+}
+export function createGuard(opts) {
+    const store = opts.store ?? new MemoryStore();
+    const prices = opts.prices ?? DEFAULT_PRICES;
+    const downgradeAt = opts.downgradeAt ?? 0.8;
+    const downgradeMap = opts.downgradeMap ?? {};
+    const unknownModel = opts.unknownModel ?? "throw";
+    const failOpen = opts.failOpen ?? true;
+    const now = opts.now ?? (() => new Date());
+    if (typeof downgradeAt !== "number" || !(downgradeAt >= 0 && downgradeAt <= 1)) {
+        throw new RangeError(`llmbrake: downgradeAt must be a number between 0 and 1, got ${String(downgradeAt)}`);
+    }
+    async function budgetFor(ctx) {
+        const b = typeof opts.budgetUsd === "function" ? await opts.budgetUsd(ctx) : opts.budgetUsd;
+        // NaN or a negative budget would silently disable the cap (spent >= NaN is always false), so reject it.
+        if (typeof b !== "number" || Number.isNaN(b) || b < 0) {
+            throw new TypeError(`llmbrake: budgetUsd for customer ${ctx.customerId} must be a number >= 0 (or Infinity), got ${String(b)}`);
+        }
+        return b;
+    }
+    async function safeGetSpend(c, p) {
+        try {
+            const spent = await store.getSpend(c, p);
+            // A store returning NaN/garbage would also silently disable the cap; treat it as a store failure.
+            if (typeof spent !== "number" || !Number.isFinite(spent))
+                throw new TypeError(`llmbrake: store.getSpend returned a non-numeric value (${String(spent)})`);
+            return spent;
+        }
+        catch (e) {
+            if (failOpen)
+                return 0;
+            throw e;
+        }
+    }
+    /** Decide whether a call may proceed, and with which model. Throws BudgetExceededError at the cap. */
+    async function check(ctx, model) {
+        const period = periodOf(now());
+        const budget = await budgetFor(ctx);
+        const spent = await safeGetSpend(ctx.customerId, period);
+        if (spent >= budget)
+            throw new BudgetExceededError(ctx.customerId, spent, budget, period);
+        let effective = model;
+        if (budget !== Infinity && spent >= budget * downgradeAt && downgradeMap[model])
+            effective = downgradeMap[model];
+        if (unknownModel === "throw" && computeCostUsd(effective, {}, prices) === null)
+            throw new UnknownModelPriceError(effective);
+        return { period, budget, spent, model: effective, downgraded: effective !== model, holdId: null };
+    }
+    function decide(ctx, model, period, budget, spent) {
+        if (spent >= budget)
+            throw new BudgetExceededError(ctx.customerId, spent, budget, period);
+        let effective = model;
+        if (budget !== Infinity && spent >= budget * downgradeAt && downgradeMap[model])
+            effective = downgradeMap[model];
+        if (unknownModel === "throw" && computeCostUsd(effective, {}, prices) === null)
+            throw new UnknownModelPriceError(effective);
+        return { period, budget, spent, model: effective, downgraded: effective !== model, holdId: null };
+    }
+    /** Reserving stores: atomic check-and-reserve before the call (see ReservingStore). */
+    async function reserveCheck(ctx, params) {
+        const period = periodOf(now());
+        const budget = await budgetFor(ctx);
+        if (!isReservingStore(store))
+            throw new Error("unreachable");
+        let holdUsd = 0;
+        try {
+            holdUsd = typeof opts.estimateUsd === "function" ? opts.estimateUsd(ctx, params) : opts.estimateUsd ?? estimateCallUsd(params.model, params, prices);
+            if (!Number.isFinite(holdUsd) || holdUsd < 0)
+                holdUsd = 0;
+        }
+        catch {
+            holdUsd = 0;
+        }
+        let r;
+        try {
+            r = await store.reserve({ customerId: ctx.customerId, period, holdUsd, budgetUsd: budget, downgradeAt, stream: !!params.stream });
+            if (typeof r?.spentUsd !== "number" || !Number.isFinite(r.spentUsd))
+                throw new TypeError("llmbrake: store.reserve returned a non-numeric spentUsd");
+        }
+        catch (e) {
+            if (!failOpen)
+                throw e;
+            return decide(ctx, params.model, period, budget, 0);
+        }
+        const effBudget = typeof r.budgetUsd === "number" && !Number.isNaN(r.budgetUsd) ? r.budgetUsd : budget;
+        if (!r.allowed)
+            throw new BudgetExceededError(ctx.customerId, r.spentUsd, effBudget, period);
+        // The server already admitted the call; only the downgrade and unknown-model rules apply here.
+        const model = params.model;
+        const effective = effBudget !== Infinity && r.spentUsd >= effBudget * downgradeAt && downgradeMap[model] ? downgradeMap[model] : model;
+        if (unknownModel === "throw" && computeCostUsd(effective, {}, prices) === null) {
+            await release(ctx, period, r.holdId);
+            throw new UnknownModelPriceError(effective);
+        }
+        return { period, budget: effBudget, spent: r.spentUsd, model: effective, downgraded: effective !== model, holdId: r.holdId };
+    }
+    async function release(ctx, period, holdId) {
+        if (!holdId || !isReservingStore(store))
+            return;
+        try {
+            await store.settle({ holdId, customerId: ctx.customerId, period, costUsd: 0, downgraded: false });
+        }
+        catch { /* hold expires on its own */ }
+    }
+    async function record(ctx, d, requestedModel, respModel, usage) {
+        const u = usage ?? {};
+        // Price by the model the provider reports (dated snapshots resolve via lookupPrice); fall back to the model we sent.
+        const priceModel = respModel && computeCostUsd(respModel, {}, prices) !== null ? respModel : d.model;
+        const cost = computeCostUsd(priceModel, u, prices);
+        let spent = d.spent;
+        if (d.holdId && isReservingStore(store)) {
+            try {
+                spent = await store.settle({ holdId: d.holdId, customerId: ctx.customerId, period: d.period, costUsd: cost ?? 0, downgraded: d.downgraded });
+            }
+            catch (e) {
+                if (!failOpen)
+                    throw e;
+            }
+        }
+        else if (cost !== null && cost > 0) {
+            try {
+                spent = await store.addSpend(ctx.customerId, d.period, cost);
+            }
+            catch (e) {
+                if (!failOpen)
+                    throw e;
+            }
+        }
+        const event = {
+            customerId: ctx.customerId, plan: ctx.plan, feature: ctx.feature, period: d.period,
+            requestedModel, model: d.model, downgraded: d.downgraded,
+            promptTokens: u.prompt_tokens ?? 0, completionTokens: u.completion_tokens ?? 0,
+            cachedTokens: u.prompt_tokens_details?.cached_tokens ?? 0,
+            costUsd: cost, spentUsd: spent, budgetUsd: d.budget, timestamp: now().toISOString(),
+        };
+        if (opts.onUsage) {
+            try {
+                await opts.onUsage(event);
+            }
+            catch { /* never break the caller */ }
+        }
+        return event;
+    }
+    /**
+     * Wrap an OpenAI-compatible `chat.completions.create` function.
+     *   const create = guard.wrap(openai.chat.completions.create.bind(openai.chat.completions));
+     *   await create({ model, messages }, { customerId: "cus_123" });
+     */
+    function wrap(createFn) {
+        return async function guardedCreate(params, ctx, ...rest) {
+            if (!ctx?.customerId)
+                throw new TypeError("llmbrake: ctx.customerId is required");
+            const requestedModel = params.model;
+            const d = isReservingStore(store) ? await reserveCheck(ctx, params) : await check(ctx, requestedModel);
+            const finalParams = { ...params, model: d.model };
+            if (params.stream) {
+                finalParams.stream_options = { ...(params.stream_options ?? {}), include_usage: true };
+                let stream;
+                try {
+                    stream = (await createFn(finalParams, ...rest));
+                }
+                catch (e) {
+                    await release(ctx, d.period, d.holdId);
+                    throw e;
+                }
+                return wrapStream(stream, (model, usage) => record(ctx, d, requestedModel, model, usage));
+            }
+            let res;
+            try {
+                res = await createFn(finalParams, ...rest);
+            }
+            catch (e) {
+                await release(ctx, d.period, d.holdId);
+                throw e;
+            }
+            await record(ctx, d, requestedModel, res?.model, res?.usage);
+            return res;
+        };
+    }
+    /** Current spend/budget for a customer this period. */
+    async function status(ctx) {
+        const period = periodOf(now());
+        const budget = await budgetFor(ctx);
+        const spent = await safeGetSpend(ctx.customerId, period);
+        return { period, spentUsd: spent, budgetUsd: budget, remainingUsd: Math.max(0, budget - spent) };
+    }
+    return { wrap, check, status };
+}
+function wrapStream(stream, onDone) {
+    const proxy = {
+        async *[Symbol.asyncIterator]() {
+            let usage;
+            let model;
+            try {
+                for await (const chunk of stream) {
+                    if (chunk?.usage)
+                        usage = chunk.usage;
+                    if (chunk?.model)
+                        model = chunk.model;
+                    yield chunk;
+                }
+            }
+            finally {
+                await onDone(model, usage);
+            }
+        },
+    };
+    // Preserve other properties (e.g. controller) of SDK stream objects.
+    return Object.assign(Object.create(Object.getPrototypeOf(stream) ?? null), stream, { [Symbol.asyncIterator]: proxy[Symbol.asyncIterator] });
+}

package/dist/hosted.d.ts

@@ -0,0 +1,42 @@
+import type { Reservation, ReserveRequest, ReservingStore, SettleRequest } from "./store.js";
+export declare const DEFAULT_HOSTED_URL = "https://app.llmbrake.com";
+export interface HostedStoreOptions {
+    /** Your project's SDK API key (lbsk_...). */
+    apiKey: string;
+    /** API base URL. Default https://app.llmbrake.com */
+    baseUrl?: string;
+    /** Per-request timeout in ms. Default 3000. On timeout the guard follows `failOpen`. */
+    timeoutMs?: number;
+    /** fetch implementation (defaults to global fetch; Node 18+). */
+    fetch?: typeof fetch;
+}
+export declare class HostedStoreError extends Error {
+    readonly status?: number | undefined;
+    constructor(message: string, status?: number | undefined);
+}
+/**
+ * Shared, hosted spend counters (LLMBrake Cloud). One counter per customer per month across every
+ * server using the same API key; budgets edited in the dashboard override the guard's `budgetUsd`.
+ *
+ *   const guard = createGuard({ budgetUsd: 5, store: new HostedStore({ apiKey: process.env.LLMBRAKE_API_KEY! }) });
+ */
+export declare class HostedStore implements ReservingStore {
+    private readonly base;
+    private readonly key;
+    private readonly timeoutMs;
+    private readonly f;
+    constructor(opts: HostedStoreOptions);
+    private call;
+    getSpend(customerId: string, period: string): Promise<number>;
+    addSpend(customerId: string, period: string, usd: number): Promise<number>;
+    reserve(req: ReserveRequest): Promise<Reservation>;
+    settle(req: SettleRequest): Promise<number>;
+    /** Server view of a customer this period (spend, in-flight holds, effective budget, status). */
+    customer(customerId: string, period: string): Promise<{
+        spentUsd: number;
+        pendingUsd: number;
+        budgetUsd: number | null;
+        budgetSource: string;
+        status: string;
+    }>;
+}

package/dist/hosted.js

@@ -0,0 +1,79 @@
+export const DEFAULT_HOSTED_URL = "https://app.llmbrake.com";
+export class HostedStoreError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = "HostedStoreError";
+    }
+}
+/**
+ * Shared, hosted spend counters (LLMBrake Cloud). One counter per customer per month across every
+ * server using the same API key; budgets edited in the dashboard override the guard's `budgetUsd`.
+ *
+ *   const guard = createGuard({ budgetUsd: 5, store: new HostedStore({ apiKey: process.env.LLMBRAKE_API_KEY! }) });
+ */
+export class HostedStore {
+    base;
+    key;
+    timeoutMs;
+    f;
+    constructor(opts) {
+        if (!opts?.apiKey)
+            throw new TypeError("llmbrake: HostedStore needs an apiKey");
+        this.key = opts.apiKey;
+        this.base = (opts.baseUrl ?? DEFAULT_HOSTED_URL).replace(/\/+$/, "");
+        this.timeoutMs = opts.timeoutMs ?? 3000;
+        const f = opts.fetch ?? globalThis.fetch;
+        if (!f)
+            throw new TypeError("llmbrake: HostedStore needs fetch (Node 18+), or pass opts.fetch");
+        this.f = f;
+    }
+    async call(method, path, body) {
+        const ctl = new AbortController();
+        const t = setTimeout(() => ctl.abort(), this.timeoutMs);
+        try {
+            const r = await this.f(this.base + path, {
+                method,
+                headers: { authorization: `Bearer ${this.key}`, "content-type": "application/json", "user-agent": "llmbrake-js" },
+                body: body === undefined ? undefined : JSON.stringify(body),
+                signal: ctl.signal,
+            });
+            const data = await r.json().catch(() => ({}));
+            if (!r.ok)
+                throw new HostedStoreError(`llmbrake: hosted API ${r.status} ${data?.error ?? ""}`.trim(), r.status);
+            return data;
+        }
+        catch (e) {
+            if (e instanceof HostedStoreError)
+                throw e;
+            throw new HostedStoreError(`llmbrake: hosted API unreachable (${e?.name === "AbortError" ? `timeout after ${this.timeoutMs}ms` : String(e?.message ?? e)})`);
+        }
+        finally {
+            clearTimeout(t);
+        }
+    }
+    async getSpend(customerId, period) {
+        const q = new URLSearchParams({ customerId, period });
+        return (await this.call("GET", `/v1/spend?${q}`)).spentUsd;
+    }
+    async addSpend(customerId, period, usd) {
+        return (await this.call("POST", "/v1/spend/add", { customerId, period, usd })).spentUsd;
+    }
+    async reserve(req) {
+        const r = await this.call("POST", "/v1/reserve", {
+            customerId: req.customerId, period: req.period, holdUsd: req.holdUsd,
+            budgetUsd: Number.isFinite(req.budgetUsd) ? req.budgetUsd : null,
+            downgradeAt: req.downgradeAt, ttlSec: req.stream ? 900 : 120,
+        });
+        return { allowed: !!r.allowed, spentUsd: r.spentUsd, budgetUsd: r.budgetUsd === null ? Infinity : r.budgetUsd, holdId: r.holdId ?? null };
+    }
+    async settle(req) {
+        return (await this.call("POST", "/v1/settle", req)).spentUsd;
+    }
+    /** Server view of a customer this period (spend, in-flight holds, effective budget, status). */
+    async customer(customerId, period) {
+        const q = new URLSearchParams({ customerId, period });
+        return this.call("GET", `/v1/spend?${q}`);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { createGuard, periodOf, estimateCallUsd } from "./guard.js";
+export type { GuardOptions, CallContext, UsageEvent } from "./guard.js";
+export { MemoryStore, isReservingStore } from "./store.js";
+export type { UsageStore, ReservingStore, Reservation, ReserveRequest, SettleRequest } from "./store.js";
+export { HostedStore, HostedStoreError, DEFAULT_HOSTED_URL } from "./hosted.js";
+export type { HostedStoreOptions } from "./hosted.js";
+export { DEFAULT_PRICES, computeCostUsd, lookupPrice } from "./prices.js";
+export type { ModelPrice, PriceTable, ChatUsage } from "./prices.js";
+export { BudgetExceededError, UnknownModelPriceError, isBudgetExceededError } from "./errors.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { createGuard, periodOf, estimateCallUsd } from "./guard.js";
+export { MemoryStore, isReservingStore } from "./store.js";
+export { HostedStore, HostedStoreError, DEFAULT_HOSTED_URL } from "./hosted.js";
+export { DEFAULT_PRICES, computeCostUsd, lookupPrice } from "./prices.js";
+export { BudgetExceededError, UnknownModelPriceError, isBudgetExceededError } from "./errors.js";

package/dist/prices.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Default price table, USD per 1M tokens, standard (non-batch, short-context) tier.
+ *
+ * ⚠️ NEEDS VERIFICATION before production use. Provider prices change often.
+ * Values were read on 2026-10-09 from:
+ *   - OpenAI:    https://developers.openai.com/api/docs/pricing
+ *   - Anthropic: https://docs.anthropic.com/en/docs/about-claude/pricing
+ * Anthropic model IDs below are illustrative; confirm the exact IDs your endpoint accepts.
+ * Long-context, batch, regional/data-residency uplifts and fast/priority tiers are NOT modeled.
+ * Override or extend via `createGuard({ prices: { ...DEFAULT_PRICES, ...yours } })`.
+ */
+export interface ModelPrice {
+    /** USD per 1M uncached input tokens */
+    inputPerMTok: number;
+    /** USD per 1M output tokens */
+    outputPerMTok: number;
+    /** USD per 1M cached input tokens (defaults to inputPerMTok if omitted) */
+    cachedInputPerMTok?: number;
+    /** Where the number came from */
+    source?: string;
+}
+export type PriceTable = Record<string, ModelPrice>;
+export declare const DEFAULT_PRICES: PriceTable;
+/** OpenAI-compatible usage object (chat.completions). */
+export interface ChatUsage {
+    prompt_tokens?: number;
+    completion_tokens?: number;
+    prompt_tokens_details?: {
+        cached_tokens?: number;
+    } | null;
+}
+/** Returns USD cost, or null if the model is not in the table. */
+export declare function computeCostUsd(model: string, usage: ChatUsage, prices: PriceTable): number | null;
+/** Exact match first, then strips a trailing date snapshot like "-2025-04-14". */
+export declare function lookupPrice(model: string, prices: PriceTable): ModelPrice | undefined;

package/dist/prices.js

@@ -0,0 +1,34 @@
+const OPENAI = "https://developers.openai.com/api/docs/pricing (read 2026-10-09, verify)";
+const ANTHROPIC = "https://docs.anthropic.com/en/docs/about-claude/pricing (read 2026-10-09, verify)";
+export const DEFAULT_PRICES = {
+    "gpt-6.1-sol": { inputPerMTok: 2.0, cachedInputPerMTok: 0.1, outputPerMTok: 10.0, source: OPENAI },
+    "gpt-6-luna": { inputPerMTok: 0.1, cachedInputPerMTok: 0.01, outputPerMTok: 0.5, source: OPENAI },
+    "gpt-5.5": { inputPerMTok: 5.0, cachedInputPerMTok: 0.5, outputPerMTok: 30.0, source: OPENAI },
+    "gpt-5.4": { inputPerMTok: 2.5, cachedInputPerMTok: 0.25, outputPerMTok: 15.0, source: OPENAI },
+    "gpt-5.4-mini": { inputPerMTok: 0.75, cachedInputPerMTok: 0.075, outputPerMTok: 4.5, source: OPENAI },
+    "gpt-5.4-nano": { inputPerMTok: 0.2, cachedInputPerMTok: 0.02, outputPerMTok: 1.25, source: OPENAI },
+    "gpt-4.1-mini": { inputPerMTok: 0.4, cachedInputPerMTok: 0.1, outputPerMTok: 1.6, source: OPENAI },
+    "gpt-4o-mini": { inputPerMTok: 0.15, cachedInputPerMTok: 0.075, outputPerMTok: 0.6, source: OPENAI },
+    "claude-opus-4-8": { inputPerMTok: 5.0, cachedInputPerMTok: 0.5, outputPerMTok: 25.0, source: ANTHROPIC },
+    "claude-sonnet-5": { inputPerMTok: 2.0, cachedInputPerMTok: 0.2, outputPerMTok: 10.0, source: ANTHROPIC },
+    "claude-haiku-4-5": { inputPerMTok: 1.0, cachedInputPerMTok: 0.1, outputPerMTok: 5.0, source: ANTHROPIC },
+};
+/** Returns USD cost, or null if the model is not in the table. */
+export function computeCostUsd(model, usage, prices) {
+    const p = lookupPrice(model, prices);
+    if (!p)
+        return null;
+    const prompt = usage.prompt_tokens ?? 0;
+    const cached = Math.min(usage.prompt_tokens_details?.cached_tokens ?? 0, prompt);
+    const uncached = prompt - cached;
+    const out = usage.completion_tokens ?? 0;
+    const cachedRate = p.cachedInputPerMTok ?? p.inputPerMTok;
+    return (uncached * p.inputPerMTok + cached * cachedRate + out * p.outputPerMTok) / 1_000_000;
+}
+/** Exact match first, then strips a trailing date snapshot like "-2025-04-14". */
+export function lookupPrice(model, prices) {
+    if (prices[model])
+        return prices[model];
+    const base = model.replace(/-\d{4}-\d{2}-\d{2}$/, "");
+    return prices[base];
+}

package/dist/store.d.ts

@@ -0,0 +1,62 @@
+/** Pluggable spend storage. Implement this with Redis/Postgres/etc. for multi-instance apps. */
+export interface UsageStore {
+    /** Current spend in USD for a customer in a period (e.g. "2026-10"). */
+    getSpend(customerId: string, period: string): Promise<number>;
+    /** Atomically add USD and return the new total. */
+    addSpend(customerId: string, period: string, usd: number): Promise<number>;
+}
+/** What a {@link ReservingStore} answers before a call. */
+export interface Reservation {
+    /** false = the customer is at/over budget (counting other in-flight calls); the call must not be made. */
+    allowed: boolean;
+    /** Settled spend this period (USD). */
+    spentUsd: number;
+    /** Effective budget (USD). Infinity = unlimited. May differ from the one you sent if a dashboard override is set. */
+    budgetUsd: number;
+    /** Pass back to `settle`. null when not allowed (or when the store failed open). */
+    holdId: string | null;
+}
+export interface ReserveRequest {
+    customerId: string;
+    period: string;
+    /** Estimated cost of the call, held until it settles. */
+    holdUsd: number;
+    /** Budget from your guard config. Infinity = unlimited. */
+    budgetUsd: number;
+    downgradeAt: number;
+    /** Streams get a longer hold before it expires on its own. */
+    stream: boolean;
+}
+export interface SettleRequest {
+    holdId: string | null;
+    customerId: string;
+    period: string;
+    /** Actual cost; 0 releases the hold without charging (e.g. the provider call failed). */
+    costUsd: number;
+    downgraded: boolean;
+}
+/**
+ * Optional extension of {@link UsageStore} for shared stores (e.g. {@link HostedStore}).
+ * When the guard's store implements it, wrapped calls *check-and-reserve* atomically before the
+ * provider call and *settle* after it, so parallel calls across servers can't overshoot the cap together.
+ */
+export interface ReservingStore extends UsageStore {
+    reserve(req: ReserveRequest): Promise<Reservation>;
+    settle(req: SettleRequest): Promise<number>;
+}
+export declare function isReservingStore(s: UsageStore): s is ReservingStore;
+/** In-memory store. Fine for a single process, tests and demos; state is lost on restart. */
+export declare class MemoryStore implements UsageStore {
+    private data;
+    private key;
+    getSpend(customerId: string, period: string): Promise<number>;
+    addSpend(customerId: string, period: string, usd: number): Promise<number>;
+}
+/**
+ * Example Redis adapter shape (not bundled, to keep zero runtime deps):
+ *
+ *   const redisStore: UsageStore = {
+ *     async getSpend(c, p) { return Number(await redis.get(`llmbrake:${p}:${c}`) ?? 0); },
+ *     async addSpend(c, p, usd) { return Number(await redis.incrbyfloat(`llmbrake:${p}:${c}`, usd)); },
+ *   };
+ */

package/dist/store.js

@@ -0,0 +1,25 @@
+export function isReservingStore(s) {
+    return typeof s.reserve === "function" && typeof s.settle === "function";
+}
+/** In-memory store. Fine for a single process, tests and demos; state is lost on restart. */
+export class MemoryStore {
+    data = new Map();
+    key(c, p) { return `${p}:${c}`; }
+    async getSpend(customerId, period) {
+        return this.data.get(this.key(customerId, period)) ?? 0;
+    }
+    async addSpend(customerId, period, usd) {
+        const k = this.key(customerId, period);
+        const next = (this.data.get(k) ?? 0) + usd;
+        this.data.set(k, next);
+        return next;
+    }
+}
+/**
+ * Example Redis adapter shape (not bundled, to keep zero runtime deps):
+ *
+ *   const redisStore: UsageStore = {
+ *     async getSpend(c, p) { return Number(await redis.get(`llmbrake:${p}:${c}`) ?? 0); },
+ *     async addSpend(c, p, usd) { return Number(await redis.incrbyfloat(`llmbrake:${p}:${c}`, usd)); },
+ *   };
+ */

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "llmbrake",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Per-customer monthly USD budgets for OpenAI-compatible chat calls: track cost, auto-downgrade near the cap, block at the cap.",
+  "license": "MIT",
+  "author": "LLMBrake contributors",
+  "homepage": "https://llmbrake.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/llmbrake/llmbrake.git"
+  },
+  "bugs": {
+    "url": "https://github.com/llmbrake/llmbrake/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "clean": "node -e \"for (const d of ['dist','build-test']) require('node:fs').rmSync(d, { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "test": "npm run build && tsc -p tsconfig.test.json && node --test build-test/test/*.test.js",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "openai",
+    "anthropic",
+    "llm",
+    "ai",
+    "cost",
+    "budget",
+    "usage",
+    "quota",
+    "rate-limit",
+    "saas"
+  ],
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.6.0"
+  }
+}