usage-meter-test 0.1.0

package/dist/usageMeter.js

@@ -0,0 +1,320 @@
+import { HoldExpiredError, HoldNotFoundError, HoldStateError, IdempotencyConflictError, InsufficientCreditsError, InvalidCaptureAmountError, QuotaExceededError, } from "./errors.js";
+import { clampNonNegative } from "./math.js";
+import { estimateCost, resolveModelMultiplierBps } from "./pricing.js";
+export class UsageMeter {
+    pricing;
+    persistence;
+    constructor(persistence, options) {
+        this.persistence = persistence;
+        this.pricing = options.pricing;
+    }
+    estimate(req) {
+        const estimated = estimateCost({
+            config: this.pricing,
+            model: req.model,
+            tokens: req.tokens,
+            ...(req.tools ? { tools: req.tools } : {}),
+            ...(req.riskBps ? { riskMultiplierBps: req.riskBps } : {}),
+        });
+        const maxTokens = { inputTokens: req.tokens.inputTokens, outputTokens: req.maxOutputTokens };
+        const maxPossible = estimateCost({
+            config: this.pricing,
+            model: req.model,
+            tokens: maxTokens,
+            ...(req.tools ? { tools: req.tools } : {}),
+            ...(req.riskBps ? { riskMultiplierBps: req.riskBps } : {}),
+        });
+        return {
+            estimatedCost: estimated.cost,
+            maxPossibleCost: maxPossible.cost,
+            breakdown: {
+                ...estimated.breakdown,
+                // keep the breakdown aligned with the estimate (not maxPossible)
+                modelMultiplierBps: resolveModelMultiplierBps(this.pricing, req.model),
+            },
+        };
+    }
+    async hold(req) {
+        if (req.amount <= 0n)
+            throw new Error("Hold amount must be > 0");
+        return this.persistence.withTransaction(async (tx) => {
+            const now = this.persistence.now();
+            if (req.expiresAt.getTime() <= now.getTime())
+                throw new HoldExpiredError("expiresAt must be in the future");
+            const existingHold = await tx.holds.getByRequestId(req.userId, req.requestId);
+            if (existingHold) {
+                // idempotency for holds is based on requestId (since clients may not have a stable key for hold itself)
+                if (existingHold.amount !== req.amount) {
+                    throw new IdempotencyConflictError("Existing hold has different amount");
+                }
+                if (existingHold.idempotencyKey !== req.idempotencyKey) {
+                    throw new IdempotencyConflictError("Existing hold has different idempotencyKey");
+                }
+                const base = {
+                    hold: existingHold,
+                    account: await tx.accounts.getOrCreate(req.userId),
+                };
+                if (tx.quota) {
+                    const quotaBucket = await this.tryGetBucket(tx, req.userId, now);
+                    if (quotaBucket)
+                        return { ...base, quotaBucket };
+                }
+                return {
+                    ...base,
+                };
+            }
+            const account = await tx.accounts.getOrCreate(req.userId);
+            const available = account.balance - account.frozen;
+            if (available < req.amount) {
+                throw new InsufficientCreditsError(`Insufficient credits: available=${available.toString()} need=${req.amount.toString()}`);
+            }
+            let quotaBucket = undefined;
+            if (tx.quota) {
+                quotaBucket = await this.reserveQuota(tx, req.userId, now, req.amount, 1);
+            }
+            const updatedAccount = await tx.accounts.update(req.userId, { frozen: account.frozen + req.amount });
+            const hold = await tx.holds.create({
+                userId: req.userId,
+                requestId: req.requestId,
+                idempotencyKey: req.idempotencyKey,
+                amount: req.amount,
+                status: "held",
+                expiresAt: req.expiresAt,
+                createdAt: now,
+                updatedAt: now,
+            });
+            if (tx.usage) {
+                await tx.usage.recordUsage({
+                    userId: req.userId,
+                    usage: {
+                        requestId: req.requestId,
+                        model: "unknown",
+                        tokens: { inputTokens: 0, outputTokens: 0 },
+                        ...(req.meta ? { meta: req.meta } : {}),
+                    },
+                    estimatedCost: req.amount,
+                });
+            }
+            const result = { hold, account: updatedAccount };
+            if (quotaBucket)
+                return { ...result, quotaBucket };
+            return result;
+        });
+    }
+    async capture(req) {
+        clampNonNegative(req.actualCost, "actualCost");
+        if (req.actualCost === 0n)
+            throw new InvalidCaptureAmountError("actualCost must be > 0");
+        return this.persistence.withTransaction(async (tx) => {
+            const now = this.persistence.now();
+            const prior = await tx.ledger.getByIdempotencyKey(req.userId, req.idempotencyKey);
+            if (prior) {
+                if (prior.referenceId != null && prior.referenceId !== req.requestId) {
+                    throw new IdempotencyConflictError("Idempotency key already used for a different requestId");
+                }
+                const hold = await tx.holds.getByRequestId(req.userId, req.requestId);
+                if (!hold)
+                    throw new HoldNotFoundError();
+                const base = {
+                    charged: prior.amount < 0n ? -prior.amount : prior.amount,
+                    hold,
+                    account: await tx.accounts.getOrCreate(req.userId),
+                    ledgerEntry: prior,
+                };
+                if (tx.quota) {
+                    const quotaBucket = await this.tryGetBucket(tx, req.userId, now);
+                    if (quotaBucket)
+                        return { ...base, quotaBucket };
+                }
+                return base;
+            }
+            const hold = await tx.holds.getByRequestId(req.userId, req.requestId);
+            if (!hold)
+                throw new HoldNotFoundError();
+            if (hold.status === "captured") {
+                if (hold.capturedIdempotencyKey) {
+                    const settled = await tx.ledger.getByIdempotencyKey(req.userId, hold.capturedIdempotencyKey);
+                    if (settled) {
+                        const base = {
+                            charged: settled.amount < 0n ? -settled.amount : settled.amount,
+                            hold,
+                            account: await tx.accounts.getOrCreate(req.userId),
+                            ledgerEntry: settled,
+                        };
+                        if (tx.quota) {
+                            const quotaBucket = await this.tryGetBucket(tx, req.userId, now);
+                            if (quotaBucket)
+                                return { ...base, quotaBucket };
+                        }
+                        return base;
+                    }
+                }
+                throw new HoldStateError("Hold already captured");
+            }
+            if (hold.status === "released" || hold.status === "expired")
+                throw new HoldStateError(`Hold is ${hold.status}`);
+            if (hold.expiresAt.getTime() <= now.getTime())
+                throw new HoldExpiredError();
+            if (req.actualCost > hold.amount)
+                throw new InvalidCaptureAmountError("actualCost cannot exceed held amount");
+            // Lock capture to ensure at-most-once charge per requestId (even if callers use different idempotency keys).
+            const lockedHold = await tx.holds.lockCapture(req.userId, req.requestId, req.idempotencyKey, now);
+            if (lockedHold.capturedIdempotencyKey && lockedHold.capturedIdempotencyKey !== req.idempotencyKey) {
+                const settled = await tx.ledger.getByIdempotencyKey(req.userId, lockedHold.capturedIdempotencyKey);
+                if (settled) {
+                    const base = {
+                        charged: settled.amount < 0n ? -settled.amount : settled.amount,
+                        hold: lockedHold,
+                        account: await tx.accounts.getOrCreate(req.userId),
+                        ledgerEntry: settled,
+                    };
+                    if (tx.quota) {
+                        const quotaBucket = await this.tryGetBucket(tx, req.userId, now);
+                        if (quotaBucket)
+                            return { ...base, quotaBucket };
+                    }
+                    return base;
+                }
+                throw new HoldStateError("Hold capture is locked by another idempotency key");
+            }
+            const account = await tx.accounts.getOrCreate(req.userId);
+            // Convert frozen -> charged.
+            if (account.frozen < hold.amount)
+                throw new HoldStateError("Account frozen is less than hold amount");
+            const newFrozen = account.frozen - hold.amount;
+            const newBalance = account.balance - req.actualCost;
+            if (newBalance < 0n)
+                throw new InsufficientCreditsError("Account balance would go negative");
+            let quotaBucket = undefined;
+            if (tx.quota) {
+                quotaBucket = await this.settleQuota(tx, req.userId, now, hold.amount, req.actualCost, 1);
+            }
+            const updatedAccount = await tx.accounts.update(req.userId, { balance: newBalance, frozen: newFrozen });
+            const updatedHold = await tx.holds.finalizeCapture(req.userId, req.requestId, req.idempotencyKey);
+            const entry = {
+                userId: req.userId,
+                type: "charge",
+                amount: -req.actualCost,
+                referenceId: req.requestId,
+                idempotencyKey: req.idempotencyKey,
+                meta: {
+                    model: req.usage.model,
+                    tokens: req.usage.tokens,
+                    tools: req.usage.tools ?? [],
+                    ...(req.usage.meta ?? {}),
+                },
+                createdAt: now,
+            };
+            const ledgerEntry = await tx.ledger.append(entry);
+            if (tx.usage) {
+                await tx.usage.recordUsage({
+                    userId: req.userId,
+                    usage: req.usage,
+                    estimatedCost: hold.amount,
+                    actualCost: req.actualCost,
+                });
+            }
+            const base = {
+                charged: req.actualCost,
+                hold: updatedHold,
+                account: updatedAccount,
+                ledgerEntry,
+            };
+            if (quotaBucket)
+                return { ...base, quotaBucket };
+            return base;
+        });
+    }
+    async release(req) {
+        return this.persistence.withTransaction(async (tx) => {
+            const now = this.persistence.now();
+            const hold = await tx.holds.getByRequestId(req.userId, req.requestId);
+            if (!hold)
+                throw new HoldNotFoundError();
+            if (hold.status === "captured")
+                throw new HoldStateError("Cannot release a captured hold");
+            if (hold.status === "released" || hold.status === "expired") {
+                const base = {
+                    hold,
+                    account: await tx.accounts.getOrCreate(req.userId),
+                };
+                if (tx.quota) {
+                    const quotaBucket = await this.tryGetBucket(tx, req.userId, now);
+                    if (quotaBucket)
+                        return { ...base, quotaBucket };
+                }
+                return base;
+            }
+            const account = await tx.accounts.getOrCreate(req.userId);
+            const updatedAccount = await tx.accounts.update(req.userId, { frozen: account.frozen - hold.amount });
+            let quotaBucket = undefined;
+            if (tx.quota) {
+                quotaBucket = await this.unreserveQuota(tx, req.userId, now, hold.amount, 1);
+            }
+            const updatedHold = await tx.holds.update(req.userId, req.requestId, {
+                status: hold.expiresAt.getTime() <= now.getTime() ? "expired" : "released",
+            });
+            if (tx.usage) {
+                await tx.usage.recordUsage({
+                    userId: req.userId,
+                    usage: {
+                        requestId: req.requestId,
+                        model: "unknown",
+                        tokens: { inputTokens: 0, outputTokens: 0 },
+                        meta: { reason: req.reason },
+                    },
+                    estimatedCost: hold.amount,
+                    actualCost: 0n,
+                });
+            }
+            const base = { hold: updatedHold, account: updatedAccount };
+            if (quotaBucket)
+                return { ...base, quotaBucket };
+            return base;
+        });
+    }
+    // --- Quota helpers (optional store)
+    async tryGetBucket(tx, userId, now) {
+        const policy = await tx.quota.getActivePolicy(userId);
+        if (!policy)
+            return undefined;
+        return tx.quota.getOrCreateBucket(userId, policy, now);
+    }
+    async reserveQuota(tx, userId, now, creditsAmount, requests) {
+        const policy = await tx.quota.getActivePolicy(userId);
+        if (!policy)
+            return undefined;
+        const bucket = await tx.quota.getOrCreateBucket(userId, policy, now);
+        const remainingCredits = policy.limitCredits - bucket.usedCredits - bucket.reservedCredits;
+        const remainingReqs = policy.limitRequests == null ? Number.POSITIVE_INFINITY : policy.limitRequests - bucket.usedRequests - bucket.reservedRequests;
+        if (remainingCredits < creditsAmount || remainingReqs < requests) {
+            throw new QuotaExceededError("Quota remaining is insufficient for this hold");
+        }
+        return tx.quota.updateBucket(userId, policy.policyId, bucket.periodStart, {
+            reservedCredits: bucket.reservedCredits + creditsAmount,
+            reservedRequests: bucket.reservedRequests + requests,
+        });
+    }
+    async unreserveQuota(tx, userId, now, creditsAmount, requests) {
+        const policy = await tx.quota.getActivePolicy(userId);
+        if (!policy)
+            return undefined;
+        const bucket = await tx.quota.getOrCreateBucket(userId, policy, now);
+        return tx.quota.updateBucket(userId, policy.policyId, bucket.periodStart, {
+            reservedCredits: bucket.reservedCredits - creditsAmount,
+            reservedRequests: bucket.reservedRequests - requests,
+        });
+    }
+    async settleQuota(tx, userId, now, reservedCredits, usedCredits, requests) {
+        const policy = await tx.quota.getActivePolicy(userId);
+        if (!policy)
+            return undefined;
+        const bucket = await tx.quota.getOrCreateBucket(userId, policy, now);
+        return tx.quota.updateBucket(userId, policy.policyId, bucket.periodStart, {
+            reservedCredits: bucket.reservedCredits - reservedCredits,
+            reservedRequests: bucket.reservedRequests - requests,
+            usedCredits: bucket.usedCredits + usedCredits,
+            usedRequests: bucket.usedRequests + requests,
+        });
+    }
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "usage-meter-test",
+  "version": "0.1.0",
+  "description": "Usage metering core (credits + quota + holds + ledger) for AI and other compute costs.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3"
+  }
+}