usage-meter-test 0.1.0

package/README.md

@@ -0,0 +1,86 @@
+# usage-meter
+
+A small TypeScript library for **credits + quota + holds + ledger** metering (e.g. AI token billing).
+
+## Core concepts
+
+- **Credits**: integer unit (`bigint`) deducted from a user account.
+- **Hold**: pre-authorize a maximum cost (freeze credits + reserve quota).
+- **Capture**: settle actual cost (deduct balance + release unused hold/quota).
+- **Release**: cancel a hold (unfreeze credits + unreserve quota).
+- **Ledger**: append-only, idempotent charge records.
+
+## Quick start (in-memory)
+
+```ts
+import { DEFAULT_PRICING_CONFIG, InMemoryMeteringPersistence, UsageMeter, bps, credits } from "usage-meter";
+
+const persistence = new InMemoryMeteringPersistence({ quota: true, usage: true });
+
+// Seed credits
+await persistence.accounts.addCredits("u1", credits(10_000));
+
+// Optional: quota policy (daily 5_000 credits)
+persistence.quota?.setPolicy("u1", { policyId: "free-daily", period: "daily", limitCredits: credits(5_000) });
+
+const meter = new UsageMeter(persistence, {
+  pricing: {
+    ...DEFAULT_PRICING_CONFIG,
+    inputTokenCost: credits(1),
+    outputTokenCost: credits(2),
+    minCost: credits(1),
+    defaultModelMultiplierBps: bps(10_000),
+    modelRules: [{ model: "premium", multiplierBps: bps(20_000) }],
+    toolRules: [{ tool: "web_search", unitCost: credits(50) }],
+  },
+});
+
+const estimate = meter.estimate({
+  userId: "u1",
+  requestId: "req-1",
+  model: "premium",
+  tokens: { inputTokens: 100, outputTokens: 200 },
+  maxOutputTokens: 800,
+  tools: [{ tool: "web_search", units: 1 }],
+});
+
+// Hold max possible cost (freeze + reserve quota)
+await meter.hold({
+  userId: "u1",
+  requestId: "req-1",
+  amount: estimate.maxPossibleCost,
+  idempotencyKey: "hold:req-1",
+  expiresAt: new Date(Date.now() + 2 * 60 * 1000),
+});
+
+// Capture actual cost when done
+await meter.capture({
+  userId: "u1",
+  requestId: "req-1",
+  actualCost: estimate.estimatedCost,
+  idempotencyKey: "charge:req-1",
+  usage: {
+    requestId: "req-1",
+    model: "premium",
+    tokens: { inputTokens: 100, outputTokens: 200 },
+    tools: [{ tool: "web_search", units: 1 }],
+  },
+});
+```
+
+## Prisma adapter (route A)
+
+- Add the models/enums from `usage-meter/prisma/schema.prisma.snippet` into your app's `schema.prisma`
+- Run `prisma migrate dev` (or `prisma migrate deploy`)
+
+```ts
+import { createPrismaPersistence, UsageMeter, DEFAULT_PRICING_CONFIG } from "usage-meter";
+import { PrismaClient, Prisma } from "@prisma/client";
+
+const prisma = new PrismaClient();
+const persistence = createPrismaPersistence(prisma, {
+  isolationLevel: Prisma.TransactionIsolationLevel.Serializable,
+});
+
+const meter = new UsageMeter(persistence, { pricing: DEFAULT_PRICING_CONFIG });
+```

package/dist/errors.d.ts

@@ -0,0 +1,24 @@
+export declare class UsageMeterError extends Error {
+    constructor(message?: string);
+}
+export declare class InsufficientCreditsError extends UsageMeterError {
+    constructor(message?: string);
+}
+export declare class QuotaExceededError extends UsageMeterError {
+    constructor(message?: string);
+}
+export declare class HoldNotFoundError extends UsageMeterError {
+    constructor(message?: string);
+}
+export declare class HoldExpiredError extends UsageMeterError {
+    constructor(message?: string);
+}
+export declare class HoldStateError extends UsageMeterError {
+    constructor(message?: string);
+}
+export declare class InvalidCaptureAmountError extends UsageMeterError {
+    constructor(message?: string);
+}
+export declare class IdempotencyConflictError extends UsageMeterError {
+    constructor(message?: string);
+}

package/dist/errors.js

@@ -0,0 +1,48 @@
+export class UsageMeterError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "UsageMeterError";
+    }
+}
+export class InsufficientCreditsError extends UsageMeterError {
+    constructor(message = "Insufficient credits") {
+        super(message);
+        this.name = "InsufficientCreditsError";
+    }
+}
+export class QuotaExceededError extends UsageMeterError {
+    constructor(message = "Quota exceeded") {
+        super(message);
+        this.name = "QuotaExceededError";
+    }
+}
+export class HoldNotFoundError extends UsageMeterError {
+    constructor(message = "Hold not found") {
+        super(message);
+        this.name = "HoldNotFoundError";
+    }
+}
+export class HoldExpiredError extends UsageMeterError {
+    constructor(message = "Hold expired") {
+        super(message);
+        this.name = "HoldExpiredError";
+    }
+}
+export class HoldStateError extends UsageMeterError {
+    constructor(message = "Invalid hold state") {
+        super(message);
+        this.name = "HoldStateError";
+    }
+}
+export class InvalidCaptureAmountError extends UsageMeterError {
+    constructor(message = "Invalid capture amount") {
+        super(message);
+        this.name = "InvalidCaptureAmountError";
+    }
+}
+export class IdempotencyConflictError extends UsageMeterError {
+    constructor(message = "Idempotency conflict") {
+        super(message);
+        this.name = "IdempotencyConflictError";
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./errors.js";
+export * from "./math.js";
+export * from "./pricing.js";
+export * from "./types.js";
+export * from "./usageMeter.js";
+export * from "./providers/inMemoryProvider.js";
+export * from "./providers/prismaProvider.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+export * from "./errors.js";
+export * from "./math.js";
+export * from "./pricing.js";
+export * from "./types.js";
+export * from "./usageMeter.js";
+export * from "./providers/inMemoryProvider.js";
+export * from "./providers/prismaProvider.js";

package/dist/math.d.ts

@@ -0,0 +1,7 @@
+import type { Bps, Credits } from "./types.js";
+export declare function credits(value: number | string | bigint): Credits;
+export declare function bps(value: number | string | bigint): Bps;
+export declare function ceilDiv(numerator: bigint, denominator: bigint): bigint;
+export declare function mulBps(amount: Credits, multiplierBps: Bps): Credits;
+export declare function maxBigint(a: bigint, b: bigint): bigint;
+export declare function clampNonNegative(value: bigint, label: string): bigint;

package/dist/math.js

@@ -0,0 +1,37 @@
+export function credits(value) {
+    if (typeof value === "bigint")
+        return value;
+    if (typeof value === "number") {
+        if (!Number.isSafeInteger(value)) {
+            throw new Error(`credits(number) must be a safe integer, got: ${value}`);
+        }
+        return BigInt(value);
+    }
+    if (typeof value === "string")
+        return BigInt(value);
+    throw new Error(`Unsupported credits input: ${String(value)}`);
+}
+export function bps(value) {
+    return credits(value);
+}
+export function ceilDiv(numerator, denominator) {
+    if (denominator === 0n)
+        throw new Error("Division by zero");
+    if (numerator === 0n)
+        return 0n;
+    if (numerator > 0n && denominator > 0n)
+        return (numerator + denominator - 1n) / denominator;
+    return numerator / denominator;
+}
+export function mulBps(amount, multiplierBps) {
+    // ceil(amount * bps / 10_000)
+    return ceilDiv(amount * multiplierBps, 10000n);
+}
+export function maxBigint(a, b) {
+    return a >= b ? a : b;
+}
+export function clampNonNegative(value, label) {
+    if (value < 0n)
+        throw new Error(`${label} must be >= 0`);
+    return value;
+}

package/dist/pricing.d.ts

@@ -0,0 +1,32 @@
+import type { Bps, Credits, PriceBreakdown, ToolUsage, UsageTokens } from "./types.js";
+export interface ModelPricingRule {
+    model: string;
+    multiplierBps: Bps;
+}
+export interface ToolPricingRule {
+    tool: string;
+    unitCost: Credits;
+}
+export interface PricingConfig {
+    inputTokenCost: Credits;
+    outputTokenCost: Credits;
+    minCost: Credits;
+    defaultModelMultiplierBps: Bps;
+    modelRules?: ModelPricingRule[];
+    toolRules?: ToolPricingRule[];
+}
+export declare function resolveModelMultiplierBps(config: PricingConfig, model: string): Bps;
+export declare function resolveToolUnitCost(config: PricingConfig, tool: string): Credits;
+export declare function estimateToolCost(config: PricingConfig, tools: ToolUsage[] | undefined): Credits;
+export declare function estimateCost(params: {
+    config: PricingConfig;
+    model: string;
+    tokens: UsageTokens;
+    tools?: ToolUsage[];
+    riskMultiplierBps?: Bps;
+    overrideModelMultiplierBps?: Bps;
+}): {
+    cost: Credits;
+    breakdown: PriceBreakdown;
+};
+export declare const DEFAULT_PRICING_CONFIG: PricingConfig;

package/dist/pricing.js

@@ -0,0 +1,57 @@
+import { bps, credits, maxBigint, mulBps } from "./math.js";
+export function resolveModelMultiplierBps(config, model) {
+    const rule = config.modelRules?.find((r) => r.model === model);
+    return rule?.multiplierBps ?? config.defaultModelMultiplierBps;
+}
+export function resolveToolUnitCost(config, tool) {
+    const rule = config.toolRules?.find((r) => r.tool === tool);
+    return rule?.unitCost ?? 0n;
+}
+export function estimateToolCost(config, tools) {
+    if (!tools?.length)
+        return 0n;
+    let total = 0n;
+    for (const t of tools) {
+        if (!Number.isFinite(t.units) || t.units < 0)
+            throw new Error(`Invalid tool units for ${t.tool}: ${t.units}`);
+        total += resolveToolUnitCost(config, t.tool) * BigInt(Math.floor(t.units));
+    }
+    return total;
+}
+export function estimateCost(params) {
+    const { config, model, tokens, tools } = params;
+    const riskMultiplierBps = params.riskMultiplierBps ?? 10000n;
+    const modelMultiplierBps = params.overrideModelMultiplierBps ?? resolveModelMultiplierBps(config, model);
+    if (!Number.isFinite(tokens.inputTokens) || tokens.inputTokens < 0)
+        throw new Error("inputTokens must be >= 0");
+    if (!Number.isFinite(tokens.outputTokens) || tokens.outputTokens < 0)
+        throw new Error("outputTokens must be >= 0");
+    const inputCost = config.inputTokenCost * BigInt(Math.floor(tokens.inputTokens));
+    const outputCost = config.outputTokenCost * BigInt(Math.floor(tokens.outputTokens));
+    const toolCost = estimateToolCost(config, tools);
+    const totalBeforeMultipliers = inputCost + outputCost + toolCost;
+    const afterModel = mulBps(totalBeforeMultipliers, modelMultiplierBps);
+    const totalAfterMultipliers = mulBps(afterModel, riskMultiplierBps);
+    const totalFinal = maxBigint(config.minCost, totalAfterMultipliers);
+    const breakdown = {
+        model,
+        inputCost,
+        outputCost,
+        toolCost,
+        minCostApplied: totalFinal !== totalAfterMultipliers,
+        modelMultiplierBps,
+        riskMultiplierBps: riskMultiplierBps,
+        totalBeforeMultipliers,
+        totalAfterMultipliers,
+        totalFinal,
+    };
+    return { cost: totalFinal, breakdown };
+}
+export const DEFAULT_PRICING_CONFIG = {
+    inputTokenCost: credits(1),
+    outputTokenCost: credits(2),
+    minCost: credits(1),
+    defaultModelMultiplierBps: bps(10_000),
+    modelRules: [],
+    toolRules: [],
+};

package/dist/providers/inMemoryProvider.d.ts

@@ -0,0 +1,66 @@
+import type { CreditAccount, CreditAccountStore, CreditHold, CreditHoldStore, CreditLedgerStore, IdempotencyKey, LedgerEntry, MeteringPersistence, MeteringTransaction, QuotaBucket, QuotaPolicy, QuotaStore, UsageFacts, UsageStore, UserId } from "../types.js";
+export declare class InMemoryUsageStore implements UsageStore {
+    readonly rows: Array<{
+        userId: UserId;
+        usage: UsageFacts;
+        estimatedCost: bigint;
+        actualCost?: bigint;
+    }>;
+    recordUsage(row: {
+        userId: UserId;
+        usage: UsageFacts;
+        estimatedCost: bigint;
+        actualCost?: bigint;
+    }): Promise<void>;
+}
+export declare class InMemoryCreditAccountStore implements CreditAccountStore {
+    private readonly accounts;
+    private readonly now;
+    constructor(now: () => Date);
+    getOrCreate(userId: UserId): Promise<CreditAccount>;
+    update(userId: UserId, patch: Partial<Pick<CreditAccount, "balance" | "frozen">>): Promise<CreditAccount>;
+    addCredits(userId: UserId, amount: bigint): Promise<CreditAccount>;
+}
+export declare class InMemoryCreditHoldStore implements CreditHoldStore {
+    private readonly holds;
+    private readonly now;
+    constructor(now: () => Date);
+    getByRequestId(userId: UserId, requestId: string): Promise<CreditHold | null>;
+    create(hold: CreditHold): Promise<CreditHold>;
+    update(userId: UserId, requestId: string, patch: Partial<Pick<CreditHold, "status" | "expiresAt">>): Promise<CreditHold>;
+    lockCapture(userId: UserId, requestId: string, capturedIdempotencyKey: string, now: Date): Promise<CreditHold>;
+    finalizeCapture(userId: UserId, requestId: string, capturedIdempotencyKey: string): Promise<CreditHold>;
+}
+export declare class InMemoryCreditLedgerStore implements CreditLedgerStore {
+    private readonly entries;
+    private readonly byIdempotency;
+    getByIdempotencyKey(userId: UserId, idempotencyKey: IdempotencyKey): Promise<LedgerEntry | null>;
+    append(entry: LedgerEntry): Promise<LedgerEntry>;
+    list(): LedgerEntry[];
+}
+export declare class InMemoryQuotaStore implements QuotaStore {
+    private readonly now;
+    private readonly policyByUser;
+    private readonly buckets;
+    constructor(now: () => Date);
+    setPolicy(userId: UserId, policy: QuotaPolicy | null): void;
+    getActivePolicy(userId: UserId): Promise<QuotaPolicy | null>;
+    getOrCreateBucket(userId: UserId, policy: QuotaPolicy, now: Date): Promise<QuotaBucket>;
+    updateBucket(userId: UserId, policyId: string, periodStart: Date, patch: Partial<Pick<QuotaBucket, "usedCredits" | "reservedCredits" | "usedRequests" | "reservedRequests">>): Promise<QuotaBucket>;
+    private computePeriod;
+}
+export declare class InMemoryMeteringPersistence implements MeteringPersistence {
+    private readonly clock;
+    readonly accounts: InMemoryCreditAccountStore;
+    readonly holds: InMemoryCreditHoldStore;
+    readonly ledger: InMemoryCreditLedgerStore;
+    readonly quota: InMemoryQuotaStore | undefined;
+    readonly usage: InMemoryUsageStore | undefined;
+    constructor(params?: {
+        now?: () => Date;
+        quota?: boolean;
+        usage?: boolean;
+    });
+    now(): Date;
+    withTransaction<T>(fn: (tx: MeteringTransaction) => Promise<T>): Promise<T>;
+}

package/dist/providers/inMemoryProvider.js

@@ -0,0 +1,198 @@
+function key(userId, requestId) {
+    return `${userId}::${requestId}`;
+}
+export class InMemoryUsageStore {
+    rows = [];
+    async recordUsage(row) {
+        this.rows.push(row);
+    }
+}
+export class InMemoryCreditAccountStore {
+    accounts = new Map();
+    now;
+    constructor(now) {
+        this.now = now;
+    }
+    async getOrCreate(userId) {
+        const existing = this.accounts.get(userId);
+        if (existing)
+            return existing;
+        const created = { userId, balance: 0n, frozen: 0n, updatedAt: this.now() };
+        this.accounts.set(userId, created);
+        return created;
+    }
+    async update(userId, patch) {
+        const existing = await this.getOrCreate(userId);
+        const updated = {
+            ...existing,
+            balance: patch.balance ?? existing.balance,
+            frozen: patch.frozen ?? existing.frozen,
+            updatedAt: this.now(),
+        };
+        this.accounts.set(userId, updated);
+        return updated;
+    }
+    // Convenience for demos/tests.
+    async addCredits(userId, amount) {
+        const acc = await this.getOrCreate(userId);
+        return this.update(userId, { balance: acc.balance + amount });
+    }
+}
+export class InMemoryCreditHoldStore {
+    holds = new Map();
+    now;
+    constructor(now) {
+        this.now = now;
+    }
+    async getByRequestId(userId, requestId) {
+        return this.holds.get(key(userId, requestId)) ?? null;
+    }
+    async create(hold) {
+        this.holds.set(key(hold.userId, hold.requestId), { ...hold, updatedAt: this.now() });
+        return (await this.getByRequestId(hold.userId, hold.requestId));
+    }
+    async update(userId, requestId, patch) {
+        const existing = await this.getByRequestId(userId, requestId);
+        if (!existing)
+            throw new Error("Hold not found");
+        const updated = { ...existing, ...patch, updatedAt: this.now() };
+        this.holds.set(key(userId, requestId), updated);
+        return updated;
+    }
+    async lockCapture(userId, requestId, capturedIdempotencyKey, now) {
+        const existing = await this.getByRequestId(userId, requestId);
+        if (!existing)
+            throw new Error("Hold not found");
+        if (existing.expiresAt.getTime() <= now.getTime())
+            return existing;
+        if (existing.capturedIdempotencyKey && existing.capturedIdempotencyKey !== capturedIdempotencyKey)
+            return existing;
+        if (existing.capturedIdempotencyKey === capturedIdempotencyKey)
+            return existing;
+        const updated = { ...existing, capturedIdempotencyKey, updatedAt: this.now() };
+        this.holds.set(key(userId, requestId), updated);
+        return updated;
+    }
+    async finalizeCapture(userId, requestId, capturedIdempotencyKey) {
+        const existing = await this.getByRequestId(userId, requestId);
+        if (!existing)
+            throw new Error("Hold not found");
+        if (existing.capturedIdempotencyKey !== capturedIdempotencyKey)
+            return existing;
+        if (existing.status === "captured")
+            return existing;
+        const updated = { ...existing, status: "captured", updatedAt: this.now() };
+        this.holds.set(key(userId, requestId), updated);
+        return updated;
+    }
+}
+export class InMemoryCreditLedgerStore {
+    entries = [];
+    byIdempotency = new Map();
+    async getByIdempotencyKey(userId, idempotencyKey) {
+        return this.byIdempotency.get(key(userId, idempotencyKey)) ?? null;
+    }
+    async append(entry) {
+        const k = key(entry.userId, entry.idempotencyKey);
+        const existing = this.byIdempotency.get(k);
+        if (existing)
+            return existing;
+        this.entries.push(entry);
+        this.byIdempotency.set(k, entry);
+        return entry;
+    }
+    list() {
+        return [...this.entries];
+    }
+}
+export class InMemoryQuotaStore {
+    now;
+    policyByUser = new Map();
+    buckets = new Map();
+    constructor(now) {
+        this.now = now;
+    }
+    setPolicy(userId, policy) {
+        this.policyByUser.set(userId, policy);
+    }
+    async getActivePolicy(userId) {
+        return this.policyByUser.get(userId) ?? null;
+    }
+    async getOrCreateBucket(userId, policy, now) {
+        const { start, end } = this.computePeriod(policy.period, now);
+        const bucketKey = `${userId}::${policy.policyId}::${start.toISOString()}`;
+        const existing = this.buckets.get(bucketKey);
+        if (existing)
+            return existing;
+        const created = {
+            userId,
+            policyId: policy.policyId,
+            periodStart: start,
+            periodEnd: end,
+            usedCredits: 0n,
+            reservedCredits: 0n,
+            usedRequests: 0,
+            reservedRequests: 0,
+            updatedAt: this.now(),
+        };
+        this.buckets.set(bucketKey, created);
+        return created;
+    }
+    async updateBucket(userId, policyId, periodStart, patch) {
+        const bucketKey = `${userId}::${policyId}::${periodStart.toISOString()}`;
+        const existing = this.buckets.get(bucketKey);
+        if (!existing)
+            throw new Error("Quota bucket not found");
+        const updated = {
+            ...existing,
+            usedCredits: patch.usedCredits ?? existing.usedCredits,
+            reservedCredits: patch.reservedCredits ?? existing.reservedCredits,
+            usedRequests: patch.usedRequests ?? existing.usedRequests,
+            reservedRequests: patch.reservedRequests ?? existing.reservedRequests,
+            updatedAt: this.now(),
+        };
+        this.buckets.set(bucketKey, updated);
+        return updated;
+    }
+    computePeriod(period, now) {
+        const d = new Date(now);
+        if (period === "daily") {
+            const start = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate(), 0, 0, 0, 0));
+            const end = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate() + 1, 0, 0, 0, 0));
+            return { start, end };
+        }
+        // monthly
+        const start = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), 1, 0, 0, 0, 0));
+        const end = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + 1, 1, 0, 0, 0, 0));
+        return { start, end };
+    }
+}
+export class InMemoryMeteringPersistence {
+    clock;
+    accounts;
+    holds;
+    ledger;
+    quota;
+    usage;
+    constructor(params) {
+        this.clock = params?.now ?? (() => new Date());
+        this.accounts = new InMemoryCreditAccountStore(this.clock);
+        this.holds = new InMemoryCreditHoldStore(this.clock);
+        this.ledger = new InMemoryCreditLedgerStore();
+        this.quota = params?.quota ? new InMemoryQuotaStore(this.clock) : undefined;
+        this.usage = params?.usage ? new InMemoryUsageStore() : undefined;
+    }
+    now() {
+        return this.clock();
+    }
+    async withTransaction(fn) {
+        // In-memory: operations are already single-threaded; treat as a "transaction".
+        return fn({
+            accounts: this.accounts,
+            holds: this.holds,
+            ledger: this.ledger,
+            ...(this.quota ? { quota: this.quota } : {}),
+            ...(this.usage ? { usage: this.usage } : {}),
+        });
+    }
+}

package/dist/providers/prismaProvider.d.ts

@@ -0,0 +1,36 @@
+import type { MeteringPersistence, UserId } from "../types.js";
+interface PrismaDelegate<T> {
+    findUnique(args: any): Promise<T | null>;
+    findFirst(args: any): Promise<T | null>;
+    create(args: any): Promise<T>;
+    update(args: any): Promise<T>;
+    upsert(args: any): Promise<T>;
+}
+interface PrismaClientTx {
+    creditAccount: PrismaDelegate<any>;
+    creditHold: PrismaDelegate<any>;
+    creditLedger: PrismaDelegate<any>;
+    planQuotaPolicy: PrismaDelegate<any>;
+    quotaBucket: PrismaDelegate<any>;
+    user?: PrismaDelegate<any>;
+    creditAccountUpdateMany?: (args: any) => Promise<{
+        count: number;
+    }>;
+    quotaBucketUpdateMany?: (args: any) => Promise<{
+        count: number;
+    }>;
+    creditHoldUpdateMany?: (args: any) => Promise<{
+        count: number;
+    }>;
+}
+export interface PrismaClientLike {
+    $transaction<T>(fn: (tx: PrismaClientTx) => Promise<T>, options?: any): Promise<T>;
+}
+export interface PrismaPersistenceOptions {
+    isolationLevel?: any;
+    maxRetries?: number;
+    now?: () => Date;
+    resolvePlanKey?: (userId: UserId, tx: PrismaClientTx) => Promise<string>;
+}
+export declare function createPrismaPersistence(prisma: PrismaClientLike, options?: PrismaPersistenceOptions): MeteringPersistence;
+export {};