budget-guard 0.1.1 → 0.2.0

package/README.md

@@ -56,10 +56,47 @@ guard(client, opts, { usageOf: (res) => ({ input: res.in, output: res.out }) });
 ```ts
 import { spendReport } from 'budget-guard';
 
-spendReport('my-app');
+await spendReport('my-app'); // async
 // → { chat: 2.41, summarize: 0.88 }   (today, in USD)
 ```
 
+## Shared caps across instances (Redis)
+
+By default the ledger lives in memory (per process) — great for a single script, worker, or agent. Running multiple instances? Pass a shared store so they enforce **one cap together** and survive restarts:
+
+```ts
+import { createClient } from 'redis';
+import { guard, redisStore } from 'budget-guard';
+
+const redis = createClient();
+await redis.connect();
+
+const ai = guard(openai.chat.completions, {
+  project: 'my-app',
+  dailyCapUSD: 50,
+  store: redisStore(redis), // node-redis v4; keys auto-expire (~2 days)
+});
+```
+
+`store` accepts anything implementing the tiny `SpendStore` interface (`add` / `get` / `entries`), so you can back it with whatever you already run.
+
+## Block *before* the call (no overshoot)
+
+By default the cap is enforced on the **next** call after you cross it, so one call can overshoot. Give it an estimator and it blocks the offending call itself:
+
+```ts
+import { encode } from 'gpt-tokenizer'; // or any tokenizer
+
+const ai = guard(openai.chat.completions, {
+  project: 'my-app',
+  dailyCapUSD: 50,
+  estimateUsage: (args) => ({
+    input: args.messages.reduce((n, m) => n + encode(m.content).length, 0),
+    output: args.max_tokens ?? 512,
+  }),
+});
+```
+
 ## Options
 
 ```ts
@@ -67,6 +104,8 @@ guard(client, {
   project: 'my-app',     // groups spend & shares one cap
   dailyCapUSD: 50,       // hard cap per day
   onCap: 'block',        // 'block' (throw) | 'warn' (log only). default 'block'
+  store: myStore,        // optional SpendStore (default: in-memory, per-process)
+  estimateUsage: fn,     // optional: block before a call would exceed the cap
 });
 ```
 
@@ -77,11 +116,17 @@ const ai = guard(openai.chat.completions, { project: 'my-app', dailyCapUSD: 50,
 // over cap → logs a warning, still calls. Good for easing in.
 ```
 
-## Notes (v0.1)
+## Notes (v0.2)
 
-- Caps are accounted **after each call** and enforced on the **next** one (no pre-call token estimation yet).
-- The ledger is in-memory per process. Persistence + a hosted dashboard are on the roadmap.
+- **Multi-instance + persistence** via a pluggable `SpendStore` (in-memory default, Redis adapter included, or bring your own).
+- **No-overshoot mode** when you supply `estimateUsage`; otherwise the cap is enforced on the next call after you cross it.
+- `spendReport()` is async.
 - Prices live in `PRICES` (USD per 1K tokens) — PRs to keep them current are welcome.
+- Roadmap: streaming usage, more providers, a hosted dashboard. See ROADMAP.
+
+## Migrating from 0.1
+
+`spendReport()` is now `async` — add `await`. Everything else is backward compatible (no `store` = same in-process behavior).
 
 ## License
 

package/dist/guard.d.ts

@@ -1,3 +1,4 @@
+import type { SpendStore } from './store.js';
 import type { GuardOptions, Usage } from './types.js';
 /** 호출별 비용 이벤트 (대시보드/로그용). */
 export interface SpendEvent {
@@ -22,6 +23,8 @@ export declare class BudgetExceededError extends Error {
     capUsd: number;
     constructor(project: string, spentUsd: number, capUsd: number);
 }
+/** 테스트 전용: 기본 메모리 저장소 초기화. */
+export declare function __resetDefaultStore(): void;
 type CreateArgs = {
     model: string;
     [k: string]: unknown;
@@ -41,8 +44,6 @@ export declare function guard<R extends object>(client: {
         feature?: string;
     }): Promise<R>;
 };
-/** 특정 프로젝트의 그날 기능별 비용 내역을 돌려준다. */
-export declare function spendReport(project: string, day?: string): Record<string, number>;
-/** 테스트 전용: 장부 초기화. */
-export declare function _resetLedger(): void;
+/** 특정 프로젝트의 그날 기능별 비용 내역을 돌려준다. (기본 저장소 또는 넘긴 store 기준) */
+export declare function spendReport(project: string, day?: string, store?: SpendStore): Promise<Record<string, number>>;
 export {};

package/dist/guard.js

@@ -1,5 +1,6 @@
 import { cost } from './cost.js';
 import { normalizeUsage } from './usage.js';
+import { MemoryStore } from './store.js';
 /** 캡 초과로 호출이 차단될 때 던지는 에러. */
 export class BudgetExceededError extends Error {
     project;
@@ -13,11 +14,14 @@ export class BudgetExceededError extends Error {
         this.name = 'BudgetExceededError';
     }
 }
-// 앱 전역 장부: "project|feature|YYYY-MM-DD" -> 누적 USD.
-// (한 프로젝트의 캡은 호출 위치와 무관하게 합산되어야 하므로 모듈 전역)
-const ledger = {};
 const SEP = '|';
 const TOTAL = '__total__';
+// 기본 저장소: 프로세스 전역 단일 인스턴스 → 같은 프로세스 안에서는 project별 캡이 공유된다.
+const defaultStore = new MemoryStore();
+/** 테스트 전용: 기본 메모리 저장소 초기화. */
+export function __resetDefaultStore() {
+    defaultStore.clear();
+}
 function dayKey(d) {
     return d.toISOString().slice(0, 10);
 }
@@ -32,15 +36,22 @@ function dayKey(d) {
 export function guard(client, opts, internals = {}) {
     const now = internals.now ?? (() => new Date());
     const onCap = opts.onCap ?? 'block';
+    const store = opts.store ?? defaultStore;
     const extract = internals.usageOf ?? ((res) => normalizeUsage(res.usage));
     return {
         async create(args, tags = {}) {
             const day = dayKey(now());
             const feature = tags.feature ?? 'default';
             const totalKey = `${opts.project}${SEP}${TOTAL}${SEP}${day}`;
-            const spentToday = ledger[totalKey] ?? 0;
-            // --- 하드 캡: 돈 나가는 호출 "전에" 차단 ---
-            if (spentToday >= opts.dailyCapUSD) {
+            const spentToday = await store.get(totalKey);
+            // --- 하드 캡 (호출 전) ---
+            // estimateUsage가 있으면 "이 호출이 넘길지"를 미리 보고 그 호출을 차단(overshoot 방지).
+            // 없으면 이미 캡을 넘긴 경우 다음 호출을 차단.
+            const projected = opts.estimateUsage
+                ? spentToday + cost(args.model, opts.estimateUsage(args))
+                : spentToday;
+            const over = opts.estimateUsage ? projected > opts.dailyCapUSD : spentToday >= opts.dailyCapUSD;
+            if (over) {
                 const err = new BudgetExceededError(opts.project, spentToday, opts.dailyCapUSD);
                 if (onCap === 'block')
                     throw err;
@@ -50,26 +61,19 @@ export function guard(client, opts, internals = {}) {
             const res = await client.create(args);
             // --- 비용 적립 + 기능별 귀속 ---
             const usd = cost(args.model, extract(res));
-            ledger[totalKey] = spentToday + usd;
-            const featKey = `${opts.project}${SEP}${feature}${SEP}${day}`;
-            ledger[featKey] = (ledger[featKey] ?? 0) + usd;
-            internals.onSpend?.({
-                project: opts.project,
-                feature,
-                model: args.model,
-                usd,
-                dayTotalUsd: ledger[totalKey],
-            });
+            const dayTotalUsd = await store.add(totalKey, usd);
+            await store.add(`${opts.project}${SEP}${feature}${SEP}${day}`, usd);
+            internals.onSpend?.({ project: opts.project, feature, model: args.model, usd, dayTotalUsd });
             return res;
         },
     };
 }
-/** 특정 프로젝트의 그날 기능별 비용 내역을 돌려준다. */
-export function spendReport(project, day = dayKey(new Date())) {
+/** 특정 프로젝트의 그날 기능별 비용 내역을 돌려준다. (기본 저장소 또는 넘긴 store 기준) */
+export async function spendReport(project, day = dayKey(new Date()), store = defaultStore) {
     const prefix = `${project}${SEP}`;
     const suffix = `${SEP}${day}`;
     const out = {};
-    for (const [k, v] of Object.entries(ledger)) {
+    for (const [k, v] of await store.entries(prefix)) {
         if (k.startsWith(prefix) && k.endsWith(suffix)) {
             const feature = k.slice(prefix.length, k.length - suffix.length);
             if (feature !== TOTAL)
@@ -78,8 +82,3 @@ export function spendReport(project, day = dayKey(new Date())) {
     }
     return out;
 }
-/** 테스트 전용: 장부 초기화. */
-export function _resetLedger() {
-    for (const k of Object.keys(ledger))
-        delete ledger[k];
-}

package/dist/index.d.ts

@@ -2,5 +2,7 @@ export { guard, spendReport, BudgetExceededError } from './guard.js';
 export { cost } from './cost.js';
 export { normalizeUsage } from './usage.js';
 export { PRICES } from './pricing.js';
+export { MemoryStore, redisStore } from './store.js';
 export type { Usage, GuardOptions } from './types.js';
 export type { SpendEvent } from './guard.js';
+export type { SpendStore, RedisLike } from './store.js';

package/dist/index.js

@@ -2,3 +2,4 @@ export { guard, spendReport, BudgetExceededError } from './guard.js';
 export { cost } from './cost.js';
 export { normalizeUsage } from './usage.js';
 export { PRICES } from './pricing.js';
+export { MemoryStore, redisStore } from './store.js';

package/dist/store.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 지출 누적 저장소. 기본은 프로세스 내 메모리(MemoryStore).
+ * 여러 인스턴스가 캡을 공유하려면 redisStore 등 공유 저장소를 넘긴다.
+ * 모든 메서드는 동기/비동기 둘 다 허용(guard가 await로 흡수).
+ */
+export interface SpendStore {
+    /** key의 누적값에 amount(USD)를 더하고 새 누적값을 돌려준다. 공유 저장소면 원자적이어야 함. */
+    add(key: string, amountUSD: number): number | Promise<number>;
+    /** key의 현재 누적값(없으면 0). */
+    get(key: string): number | Promise<number>;
+    /** prefix로 시작하는 모든 [key, total] 쌍 (spendReport용). */
+    entries(prefix: string): Array<[string, number]> | Promise<Array<[string, number]>>;
+}
+/** 기본 저장소: 프로세스 내 메모리. 단일 프로세스 앱/스크립트/에이전트에 적합. */
+export declare class MemoryStore implements SpendStore {
+    private m;
+    add(key: string, amountUSD: number): number;
+    get(key: string): number;
+    entries(prefix: string): Array<[string, number]>;
+    /** 테스트/리셋용. */
+    clear(): void;
+}
+/** redisStore가 기대하는 최소 redis 클라이언트 형태 (node-redis v4 호환). */
+export interface RedisLike {
+    incrByFloat(key: string, amount: number): Promise<string | number>;
+    get(key: string): Promise<string | null>;
+    expire(key: string, seconds: number): Promise<unknown>;
+    scan(cursor: number, opts: {
+        MATCH: string;
+        COUNT: number;
+    }): Promise<{
+        cursor: number | string;
+        keys: string[];
+    }>;
+}
+/**
+ * 여러 인스턴스가 캡을 공유하는 Redis 백엔드 저장소. (BYO 클라이언트 — redis를 의존성으로 안 가짐)
+ * node-redis v4 기준: `redisStore(createClient())`. 키는 ttlSeconds(기본 2일) 후 만료되어 자연 일일 리셋.
+ */
+export declare function redisStore(client: RedisLike, opts?: {
+    ttlSeconds?: number;
+    keyPrefix?: string;
+}): SpendStore;

package/dist/store.js

@@ -0,0 +1,57 @@
+/** 기본 저장소: 프로세스 내 메모리. 단일 프로세스 앱/스크립트/에이전트에 적합. */
+export class MemoryStore {
+    m = new Map();
+    add(key, amountUSD) {
+        const n = (this.m.get(key) ?? 0) + amountUSD;
+        this.m.set(key, n);
+        return n;
+    }
+    get(key) {
+        return this.m.get(key) ?? 0;
+    }
+    entries(prefix) {
+        const out = [];
+        for (const [k, v] of this.m)
+            if (k.startsWith(prefix))
+                out.push([k, v]);
+        return out;
+    }
+    /** 테스트/리셋용. */
+    clear() {
+        this.m.clear();
+    }
+}
+/**
+ * 여러 인스턴스가 캡을 공유하는 Redis 백엔드 저장소. (BYO 클라이언트 — redis를 의존성으로 안 가짐)
+ * node-redis v4 기준: `redisStore(createClient())`. 키는 ttlSeconds(기본 2일) 후 만료되어 자연 일일 리셋.
+ */
+export function redisStore(client, opts = {}) {
+    const ttl = opts.ttlSeconds ?? 172800; // 2일
+    const pre = opts.keyPrefix ?? 'bg:';
+    const num = (v) => v == null ? 0 : typeof v === 'number' ? v : parseFloat(v);
+    return {
+        async add(key, amountUSD) {
+            const k = pre + key;
+            const n = await client.incrByFloat(k, amountUSD);
+            await client.expire(k, ttl);
+            return num(n);
+        },
+        async get(key) {
+            return num(await client.get(pre + key));
+        },
+        async entries(prefix) {
+            const out = [];
+            let cursor = 0;
+            do {
+                const res = await client.scan(cursor, { MATCH: pre + prefix + '*', COUNT: 200 });
+                cursor = Number(res.cursor);
+                for (const fullKey of res.keys) {
+                    const v = await client.get(fullKey);
+                    if (v != null)
+                        out.push([fullKey.slice(pre.length), num(v)]);
+                }
+            } while (cursor !== 0);
+            return out;
+        },
+    };
+}

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import type { SpendStore } from './store.js';
 /** 한 번의 LLM 호출이 쓴 토큰 수. 제공자가 응답의 usage로 알려준다. */
 export interface Usage {
     input: number;
@@ -7,8 +8,21 @@ export interface Usage {
 export interface GuardOptions {
     /** 비용을 묶는 단위(예: 'agent-worker'). */
     project: string;
-    /** 하루 하드 캡(USD). 초과하면 다음 호출을 막는다. */
+    /** 하루 하드 캡(USD). 초과하면 호출을 막는다. */
     dailyCapUSD: number;
     /** 캡 초과 시 동작. 기본 'block'(throw) / 'warn'(경고만). */
     onCap?: 'block' | 'warn';
+    /**
+     * 지출 저장소. 기본은 프로세스 공유 MemoryStore.
+     * 여러 인스턴스가 캡을 공유하려면 redisStore 등을 넘긴다.
+     */
+    store?: SpendStore;
+    /**
+     * (선택) 호출 전 usage 추정기. 주면 "이 호출이 캡을 넘길지"를 호출 전에 판단해
+     * 넘기는 호출 자체를 차단(overshoot 방지). 없으면 캡 초과 후 '다음' 호출을 차단.
+     */
+    estimateUsage?: (args: {
+        model: string;
+        [k: string]: unknown;
+    }) => Usage;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "budget-guard",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "A circuit breaker for your LLM API bill — hard budget caps + per-feature cost attribution for the OpenAI & Anthropic APIs.",
   "type": "module",
   "main": "dist/index.js",
@@ -9,7 +9,8 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "files": ["dist", "README.md"],
   "scripts": {