llmbrake 0.0.0-stage → 0.1.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,177 @@
-# 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.**
+
+[![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
+```
+
+`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.
+
+## 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.
+
+## 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. |
+
+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.** The budget is checked before a call and the cost is recorded after it. Several in-flight calls for the same customer can each pass the check, so the cap can be overshot by roughly the cost of those concurrent calls. Keep a margin in your budgets if this matters.
+- **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.
+
+## Hosted dashboard (coming)
+
+The library is free and stays MIT licensed. We're building an optional hosted dashboard on top of it: cost per customer, feature and model, shared counters, alerts near and at caps, and AI cost vs. Stripe revenue per customer. It is **not available yet**; join the waitlist at [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,69 @@
+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;
+}
+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;
+    }>;
+    status: (ctx: CallContext) => Promise<{
+        period: string;
+        spentUsd: number;
+        budgetUsd: number;
+        remainingUsd: number;
+    }>;
+};
+export {};

package/dist/guard.js

@@ -0,0 +1,136 @@
+import { BudgetExceededError, UnknownModelPriceError } from "./errors.js";
+import { DEFAULT_PRICES, computeCostUsd } from "./prices.js";
+import { MemoryStore } from "./store.js";
+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 };
+    }
+    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 (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 = await check(ctx, requestedModel);
+            const finalParams = { ...params, model: d.model };
+            if (params.stream) {
+                finalParams.stream_options = { ...(params.stream_options ?? {}), include_usage: true };
+                const stream = (await createFn(finalParams, ...rest));
+                return wrapStream(stream, (model, usage) => record(ctx, d, requestedModel, model, usage));
+            }
+            const res = await createFn(finalParams, ...rest);
+            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/index.d.ts

@@ -0,0 +1,7 @@
+export { createGuard, periodOf } from "./guard.js";
+export type { GuardOptions, CallContext, UsageEvent } from "./guard.js";
+export { MemoryStore } from "./store.js";
+export type { UsageStore } from "./store.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,4 @@
+export { createGuard, periodOf } from "./guard.js";
+export { MemoryStore } from "./store.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,22 @@
+/** 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>;
+}
+/** 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,22 @@
+/** 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.1.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"
+  }
+}