usage-sdk-test 0.1.0

package/README.md

@@ -0,0 +1,56 @@
+# @chronnote/usage
+
+一个 Bun/Node 服务端可用的、解耦的“积分(credits)/用量(usage)/限额(limits)”SDK（v0：预付余额、CNY、accountId 级 RPM、日/月额度按 credits）。
+
+## Quick Start
+
+```ts
+import { createUsageSdk } from "@chronnote/usage";
+
+const sdk = createUsageSdk({
+  plans: [
+    {
+      planId: "default",
+      rules: [
+        {
+          meter: "tokens.input",
+          when: { model: "*", provider: "*" },
+          unitPriceMinor: 1, // 1 分 / token（示例）
+          currency: "CNY",
+        },
+        {
+          meter: "tokens.output",
+          when: { model: "*", provider: "*" },
+          unitPriceMinor: 2,
+          currency: "CNY",
+        },
+      ],
+    },
+  ],
+  initialBalances: [
+    { accountId: "u1", money: { currency: "CNY", amountMinor: 10_000 } },
+  ],
+});
+
+const result = await sdk.enforce({
+  accountId: "u1",
+  planId: "default",
+  idempotencyKey: "req_001",
+  limits: { rpm: 60, dailyLimitMinor: 5000, monthlyLimitMinor: 50_000 },
+  events: [
+    { meter: "tokens.input", quantity: 1000, dimensions: { model: "gpt-4.1", provider: "openai" } },
+    { meter: "tokens.output", quantity: 300, dimensions: { model: "gpt-4.1", provider: "openai" } },
+  ],
+});
+
+if (!result.ok) {
+  throw new Error(`${result.code}: ${result.message ?? ""}`);
+}
+console.log("cost", result.cost, "balanceAfter", result.balanceAfter);
+```
+
+## Run Example (Bun)
+
+```bash
+bun packages/usage/examples/basic.ts
+```

package/examples/basic.ts

@@ -0,0 +1,35 @@
+import { createUsageSdk } from "../src/index.ts";
+
+const sdk = createUsageSdk({
+  plans: [
+    {
+      planId: "default",
+      rules: [
+        { meter: "tokens.input", when: { model: "*", provider: "*" }, unitPriceMinor: 1, currency: "CNY", ruleId: "in" },
+        { meter: "tokens.output", when: { model: "*", provider: "*" }, unitPriceMinor: 2, currency: "CNY", ruleId: "out" },
+      ],
+    },
+  ],
+  initialBalances: [{ accountId: "u1", money: { currency: "CNY", amountMinor: 10_000 } }],
+});
+
+const run = async () => {
+  const before = await sdk.getBalance({ accountId: "u1", currency: "CNY" });
+  console.log("before", before);
+
+  const result = await sdk.enforce({
+    accountId: "u1",
+    planId: "default",
+    idempotencyKey: "req_001",
+    limits: { rpm: 60, dailyLimitMinor: 5000, monthlyLimitMinor: 50_000 },
+    events: [
+      { meter: "tokens.input", quantity: 1000, dimensions: { model: "gpt-4.1", provider: "openai" } },
+      { meter: "tokens.output", quantity: 300, dimensions: { model: "gpt-4.1", provider: "openai" } },
+    ],
+  });
+
+  console.log("enforce", result);
+};
+
+await run();
+

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "usage-sdk-test",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.2"
+  }
+}

package/src/errors.ts

@@ -0,0 +1,19 @@
+import type { EnforceErrorCode } from "./types.ts";
+
+export class UsageError extends Error {
+  readonly code: EnforceErrorCode;
+  readonly retryAfterMs?: number;
+
+  constructor(code: EnforceErrorCode, message?: string, retryAfterMs?: number) {
+    super(message ?? code);
+    this.code = code;
+    this.retryAfterMs = retryAfterMs;
+  }
+}
+
+export const toEnforceResultError = (err: unknown) => {
+  if (err instanceof UsageError) {
+    return { ok: false as const, code: err.code, message: err.message, retryAfterMs: err.retryAfterMs };
+  }
+  return { ok: false as const, code: "INVALID_ARGUMENT" as const, message: err instanceof Error ? err.message : String(err) };
+};

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from "./types.ts";
+export * from "./errors.ts";
+export { createUsageSdk } from "./sdk/createUsageSdk.ts";

package/src/pricing/matchRule.ts

@@ -0,0 +1,36 @@
+import type { PriceRule, UsageEvent } from "../types.ts";
+
+const matchWhen = (when: PriceRule["when"] | undefined, dimensions: UsageEvent["dimensions"] | undefined) => {
+  if (!when) return { ok: true, score: 0 };
+  const dims = dimensions ?? {};
+  let score = 0;
+  for (const [key, expected] of Object.entries(when)) {
+    const actual = dims[key];
+    if (expected === "*") continue;
+    if (Array.isArray(expected)) {
+      if (!actual || !expected.includes(actual)) return { ok: false, score: 0 };
+      score += 1;
+      continue;
+    }
+    if (actual !== expected) return { ok: false, score: 0 };
+    score += 1;
+  }
+  return { ok: true, score };
+};
+
+export const pickBestRule = (rules: PriceRule[], event: UsageEvent): PriceRule | null => {
+  const candidates: Array<{ rule: PriceRule; score: number; priority: number }> = [];
+  for (const rule of rules) {
+    if (rule.meter !== event.meter) continue;
+    const matched = matchWhen(rule.when, event.dimensions);
+    if (!matched.ok) continue;
+    candidates.push({ rule, score: matched.score, priority: rule.priority ?? 0 });
+  }
+  if (candidates.length === 0) return null;
+  candidates.sort((a, b) => {
+    if (b.score !== a.score) return b.score - a.score;
+    if (b.priority !== a.priority) return b.priority - a.priority;
+    return 0;
+  });
+  return candidates[0]?.rule ?? null;
+};

package/src/pricing/quote.ts

@@ -0,0 +1,38 @@
+import { UsageError } from "../errors.ts";
+import type { Money, PricePlan, Quote, QuoteInput, QuoteItem } from "../types.ts";
+import { assertNonNegativeInteger, assertUsageEvent } from "../utils/guards.ts";
+import { pickBestRule } from "./matchRule.ts";
+
+export const quoteWithPlan = (input: QuoteInput, plan: PricePlan): Quote => {
+  if (!plan.rules.length) throw new UsageError("NO_PRICE_RULE", `plan ${plan.planId} has no rules`);
+
+  const items: QuoteItem[] = [];
+  let currency: Money["currency"] | null = null;
+  let totalMinor = 0;
+
+  for (let i = 0; i < input.events.length; i++) {
+    const event = input.events[i]!;
+    assertUsageEvent(event, `events[${i}]`);
+
+    const rule = pickBestRule(plan.rules, event);
+    if (!rule) {
+      throw new UsageError("NO_PRICE_RULE", `no price rule for meter=${event.meter}`);
+    }
+
+    if (!currency) currency = rule.currency;
+    if (currency !== rule.currency) {
+      throw new UsageError("CURRENCY_MISMATCH", `mixed currencies in a single quote are not supported (got ${currency} and ${rule.currency})`);
+    }
+
+    assertNonNegativeInteger(rule.unitPriceMinor, "rule.unitPriceMinor");
+
+    const costMinor = rule.unitPriceMinor * event.quantity;
+    assertNonNegativeInteger(costMinor, "computed costMinor");
+    totalMinor += costMinor;
+
+    items.push({ event, costMinor, ruleId: rule.ruleId });
+  }
+
+  const total: Money = { currency: currency ?? "CNY", amountMinor: totalMinor };
+  return { total, items };
+};

package/src/providers/memory/MemoryLedgerStore.ts

@@ -0,0 +1,90 @@
+import { UsageError } from "../../errors.ts";
+import type { LedgerApplyResult, LedgerCreditInput, LedgerDebitInput, LedgerStore } from "../../stores/LedgerStore.ts";
+import type { Money } from "../../types.ts";
+import { assertMoney, assertNonNegativeInteger } from "../../utils/guards.ts";
+
+const makeBalanceKey = (accountId: string, currency: Money["currency"]) => `${accountId}::${currency}`;
+
+const randomId = () => {
+  const c = globalThis.crypto as Crypto | undefined;
+  if (c?.randomUUID) return c.randomUUID();
+  return `tx_${Date.now()}_${Math.random().toString(16).slice(2)}`;
+};
+
+type IdempotencyRecord = {
+  fingerprint: string;
+  result: LedgerApplyResult;
+};
+
+export class MemoryLedgerStore implements LedgerStore {
+  private readonly balances = new Map<string, number>();
+  private readonly idempotency = new Map<string, IdempotencyRecord>();
+
+  constructor(initialBalances?: Array<{ accountId: string; money: Money }>) {
+    for (const b of initialBalances ?? []) {
+      assertMoney(b.money, "initialBalances[].money");
+      const key = makeBalanceKey(b.accountId, b.money.currency);
+      this.balances.set(key, b.money.amountMinor);
+    }
+  }
+
+  async getBalance(input: { accountId: string; currency: Money["currency"] }): Promise<Money> {
+    const key = makeBalanceKey(input.accountId, input.currency);
+    const amountMinor = this.balances.get(key) ?? 0;
+    return { currency: input.currency, amountMinor };
+  }
+
+  async debit(input: LedgerDebitInput): Promise<LedgerApplyResult> {
+    assertMoney(input.money, "money");
+    if (!input.idempotencyKey) throw new UsageError("INVALID_ARGUMENT", "idempotencyKey is required");
+    if (!input.fingerprint) throw new UsageError("INVALID_ARGUMENT", "fingerprint is required");
+    assertNonNegativeInteger(input.nowMs, "nowMs");
+
+    const existing = this.idempotency.get(input.idempotencyKey);
+    if (existing) {
+      if (existing.fingerprint !== input.fingerprint) throw new UsageError("IDEMPOTENCY_CONFLICT", "idempotencyKey already used with different input");
+      return existing.result;
+    }
+
+    const key = makeBalanceKey(input.accountId, input.money.currency);
+    const current = this.balances.get(key) ?? 0;
+    if (current < input.money.amountMinor) throw new UsageError("INSUFFICIENT_BALANCE", "insufficient balance");
+
+    const next = current - input.money.amountMinor;
+    this.balances.set(key, next);
+
+    const result: LedgerApplyResult = {
+      txId: randomId(),
+      balanceAfter: { currency: input.money.currency, amountMinor: next },
+    };
+
+    this.idempotency.set(input.idempotencyKey, { fingerprint: input.fingerprint, result });
+    return result;
+  }
+
+  async credit(input: LedgerCreditInput): Promise<LedgerApplyResult> {
+    assertMoney(input.money, "money");
+    if (!input.idempotencyKey) throw new UsageError("INVALID_ARGUMENT", "idempotencyKey is required");
+    if (!input.fingerprint) throw new UsageError("INVALID_ARGUMENT", "fingerprint is required");
+    assertNonNegativeInteger(input.nowMs, "nowMs");
+
+    const existing = this.idempotency.get(input.idempotencyKey);
+    if (existing) {
+      if (existing.fingerprint !== input.fingerprint) throw new UsageError("IDEMPOTENCY_CONFLICT", "idempotencyKey already used with different input");
+      return existing.result;
+    }
+
+    const key = makeBalanceKey(input.accountId, input.money.currency);
+    const current = this.balances.get(key) ?? 0;
+    const next = current + input.money.amountMinor;
+    this.balances.set(key, next);
+
+    const result: LedgerApplyResult = {
+      txId: randomId(),
+      balanceAfter: { currency: input.money.currency, amountMinor: next },
+    };
+
+    this.idempotency.set(input.idempotencyKey, { fingerprint: input.fingerprint, result });
+    return result;
+  }
+}

package/src/providers/memory/MemoryLimitStore.ts

@@ -0,0 +1,102 @@
+import { UsageError } from "../../errors.ts";
+import type { LimitStore } from "../../stores/LimitStore.ts";
+import { assertNonNegativeInteger } from "../../utils/guards.ts";
+
+type Counter = { value: number; expiresAtMs: number };
+
+const pad2 = (n: number) => String(n).padStart(2, "0");
+
+const getMinuteKey = (nowMs: number) => {
+  const d = new Date(nowMs);
+  return `${d.getUTCFullYear()}${pad2(d.getUTCMonth() + 1)}${pad2(d.getUTCDate())}${pad2(d.getUTCHours())}${pad2(d.getUTCMinutes())}`;
+};
+
+const getDayKey = (nowMs: number) => {
+  const d = new Date(nowMs);
+  return `${d.getUTCFullYear()}${pad2(d.getUTCMonth() + 1)}${pad2(d.getUTCDate())}`;
+};
+
+const getMonthKey = (nowMs: number) => {
+  const d = new Date(nowMs);
+  return `${d.getUTCFullYear()}${pad2(d.getUTCMonth() + 1)}`;
+};
+
+const endOfUtcMinute = (nowMs: number) => Math.floor(nowMs / 60000) * 60000 + 60000;
+
+const endOfUtcDay = (nowMs: number) => {
+  const d = new Date(nowMs);
+  const next = Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate() + 1, 0, 0, 0, 0);
+  return next;
+};
+
+const endOfUtcMonth = (nowMs: number) => {
+  const d = new Date(nowMs);
+  const next = Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + 1, 1, 0, 0, 0, 0);
+  return next;
+};
+
+export class MemoryLimitStore implements LimitStore {
+  private readonly counters = new Map<string, Counter>();
+
+  private getCounter(key: string, nowMs: number): Counter | null {
+    const c = this.counters.get(key);
+    if (!c) return null;
+    if (c.expiresAtMs <= nowMs) {
+      this.counters.delete(key);
+      return null;
+    }
+    return c;
+  }
+
+  private setCounter(key: string, value: number, expiresAtMs: number) {
+    this.counters.set(key, { value, expiresAtMs });
+  }
+
+  async consumeRpm(input: { accountId: string; rpm: number; requestCount: number; nowMs: number }): Promise<void> {
+    assertNonNegativeInteger(input.nowMs, "nowMs");
+    assertNonNegativeInteger(input.requestCount, "requestCount");
+    if (input.rpm <= 0) throw new UsageError("RPM_LIMIT_EXCEEDED", "rpm limit exceeded", 60_000);
+
+    const window = getMinuteKey(input.nowMs);
+    const key = `rpm::${input.accountId}::${window}`;
+    const current = this.getCounter(key, input.nowMs)?.value ?? 0;
+
+    const next = current + input.requestCount;
+    if (next > input.rpm) {
+      const retryAfterMs = Math.max(0, endOfUtcMinute(input.nowMs) - input.nowMs);
+      throw new UsageError("RPM_LIMIT_EXCEEDED", "rpm limit exceeded", retryAfterMs);
+    }
+
+    this.setCounter(key, next, endOfUtcMinute(input.nowMs));
+  }
+
+  async consumeDailyMinor(input: { accountId: string; amountMinor: number; limitMinor: number; nowMs: number }): Promise<void> {
+    assertNonNegativeInteger(input.nowMs, "nowMs");
+    assertNonNegativeInteger(input.amountMinor, "amountMinor");
+    if (input.limitMinor <= 0) throw new UsageError("DAILY_LIMIT_EXCEEDED", "daily limit exceeded");
+
+    const window = getDayKey(input.nowMs);
+    const key = `dailyMinor::${input.accountId}::${window}`;
+    const current = this.getCounter(key, input.nowMs)?.value ?? 0;
+
+    const next = current + input.amountMinor;
+    if (next > input.limitMinor) throw new UsageError("DAILY_LIMIT_EXCEEDED", "daily limit exceeded");
+
+    this.setCounter(key, next, endOfUtcDay(input.nowMs));
+  }
+
+  async consumeMonthlyMinor(input: { accountId: string; amountMinor: number; limitMinor: number; nowMs: number }): Promise<void> {
+    assertNonNegativeInteger(input.nowMs, "nowMs");
+    assertNonNegativeInteger(input.amountMinor, "amountMinor");
+    if (input.limitMinor <= 0) throw new UsageError("MONTHLY_LIMIT_EXCEEDED", "monthly limit exceeded");
+
+    const window = getMonthKey(input.nowMs);
+    const key = `monthlyMinor::${input.accountId}::${window}`;
+    const current = this.getCounter(key, input.nowMs)?.value ?? 0;
+
+    const next = current + input.amountMinor;
+    if (next > input.limitMinor) throw new UsageError("MONTHLY_LIMIT_EXCEEDED", "monthly limit exceeded");
+
+    this.setCounter(key, next, endOfUtcMonth(input.nowMs));
+  }
+}

package/src/providers/memory/MemoryPlanStore.ts

@@ -0,0 +1,14 @@
+import type { PlanStore } from "../../stores/PlanStore.ts";
+import type { PricePlan } from "../../types.ts";
+
+export class MemoryPlanStore implements PlanStore {
+  private readonly plans = new Map<string, PricePlan>();
+
+  constructor(plans: PricePlan[]) {
+    for (const plan of plans) this.plans.set(plan.planId, plan);
+  }
+
+  async getPlan(planId: string): Promise<PricePlan | null> {
+    return this.plans.get(planId) ?? null;
+  }
+}

package/src/providers/memory/MemoryUsageStore.ts

@@ -0,0 +1,10 @@
+import type { UsageStore } from "../../stores/UsageStore.ts";
+import type { UsageRecord } from "../../types.ts";
+
+export class MemoryUsageStore implements UsageStore {
+  readonly records: UsageRecord[] = [];
+
+  async append(record: UsageRecord): Promise<void> {
+    this.records.push(record);
+  }
+}

package/src/sdk/UsageSdk.ts

@@ -0,0 +1,117 @@
+import type { LedgerStore } from "../stores/LedgerStore.ts";
+import type { LimitStore } from "../stores/LimitStore.ts";
+import type { PlanStore } from "../stores/PlanStore.ts";
+import type { UsageStore } from "../stores/UsageStore.ts";
+import type { EnforceInput, EnforceResult, Money, Quote, QuoteInput } from "../types.ts";
+import { toEnforceResultError, UsageError } from "../errors.ts";
+import { quoteWithPlan } from "../pricing/quote.ts";
+import { assertNonNegativeInteger } from "../utils/guards.ts";
+import { makeFingerprint } from "../utils/fingerprint.ts";
+
+export type UsageSdkDeps = {
+  planStore: PlanStore;
+  ledgerStore: LedgerStore;
+  limitStore: LimitStore;
+  usageStore: UsageStore;
+};
+
+export class UsageSdk {
+  constructor(private readonly deps: UsageSdkDeps) {}
+
+  async quote(input: QuoteInput): Promise<Quote> {
+    const plan = await this.deps.planStore.getPlan(input.planId);
+    if (!plan) throw new UsageError("INVALID_ARGUMENT", `unknown planId: ${input.planId}`);
+    return quoteWithPlan(input, plan);
+  }
+
+  async getBalance(input: { accountId: string; currency: Money["currency"] }): Promise<Money> {
+    return this.deps.ledgerStore.getBalance(input);
+  }
+
+  async enforce(input: EnforceInput): Promise<EnforceResult> {
+    try {
+      if (!input.idempotencyKey) throw new UsageError("INVALID_ARGUMENT", "idempotencyKey is required");
+      const nowMs = input.nowMs ?? Date.now();
+      assertNonNegativeInteger(nowMs, "nowMs");
+
+      const quote = await this.quote(input);
+
+      const debitFingerprint = makeFingerprint({
+        op: "debit",
+        accountId: input.accountId,
+        planId: input.planId,
+        idempotencyKey: input.idempotencyKey,
+        total: quote.total,
+        events: quote.items.map((i) => ({ meter: i.event.meter, quantity: i.event.quantity, dimensions: i.event.dimensions ?? {} })),
+        limits: input.limits ?? null,
+      });
+
+      const debitResult = await this.deps.ledgerStore.debit({
+        accountId: input.accountId,
+        money: quote.total,
+        idempotencyKey: input.idempotencyKey,
+        fingerprint: debitFingerprint,
+        metadata: input.metadata,
+        nowMs,
+      });
+
+      try {
+        const requestCount = input.requestCount ?? 1;
+        assertNonNegativeInteger(requestCount, "requestCount");
+        const limits = input.limits;
+        if (limits?.rpm !== undefined) {
+          await this.deps.limitStore.consumeRpm({ accountId: input.accountId, rpm: limits.rpm, requestCount, nowMs });
+        }
+        if (limits?.dailyLimitMinor !== undefined) {
+          await this.deps.limitStore.consumeDailyMinor({
+            accountId: input.accountId,
+            amountMinor: quote.total.amountMinor,
+            limitMinor: limits.dailyLimitMinor,
+            nowMs,
+          });
+        }
+        if (limits?.monthlyLimitMinor !== undefined) {
+          await this.deps.limitStore.consumeMonthlyMinor({
+            accountId: input.accountId,
+            amountMinor: quote.total.amountMinor,
+            limitMinor: limits.monthlyLimitMinor,
+            nowMs,
+          });
+        }
+      } catch (limitErr) {
+        const refundKey = `${input.idempotencyKey}::refund`;
+        const refundFingerprint = makeFingerprint({
+          op: "refund",
+          accountId: input.accountId,
+          currency: quote.total.currency,
+          amountMinor: quote.total.amountMinor,
+          for: input.idempotencyKey,
+        });
+        await this.deps.ledgerStore.credit({
+          accountId: input.accountId,
+          money: quote.total,
+          idempotencyKey: refundKey,
+          fingerprint: refundFingerprint,
+          metadata: { reason: "limits_failed", for: input.idempotencyKey },
+          nowMs,
+        });
+        throw limitErr;
+      }
+
+      await this.deps.usageStore.append({
+        accountId: input.accountId,
+        planId: input.planId,
+        idempotencyKey: input.idempotencyKey,
+        txId: debitResult.txId,
+        cost: quote.total,
+        events: input.events,
+        tsMs: nowMs,
+        metadata: input.metadata,
+      });
+
+      return { ok: true, txId: debitResult.txId, cost: quote.total, balanceAfter: debitResult.balanceAfter };
+    } catch (err) {
+      return toEnforceResultError(err);
+    }
+  }
+}

package/src/sdk/createUsageSdk.ts

@@ -0,0 +1,38 @@
+import type { Limits, Money, PricePlan } from "../types.ts";
+import { MemoryLedgerStore } from "../providers/memory/MemoryLedgerStore.ts";
+import { MemoryLimitStore } from "../providers/memory/MemoryLimitStore.ts";
+import { MemoryPlanStore } from "../providers/memory/MemoryPlanStore.ts";
+import { MemoryUsageStore } from "../providers/memory/MemoryUsageStore.ts";
+import { UsageSdk } from "./UsageSdk.ts";
+
+export type CreateUsageSdkInput = {
+  plans: PricePlan[];
+  initialBalances?: Array<{ accountId: string; money: Money }>;
+  /**
+   * Optional: default limits applied by callers (you can also pass per-call limits in enforce()).
+   */
+  defaultLimits?: Limits;
+};
+
+export const createUsageSdk = (input: CreateUsageSdkInput) => {
+  const planStore = new MemoryPlanStore(input.plans);
+  const ledgerStore = new MemoryLedgerStore(input.initialBalances);
+  const limitStore = new MemoryLimitStore();
+  const usageStore = new MemoryUsageStore();
+
+  const sdk = new UsageSdk({ planStore, ledgerStore, limitStore, usageStore });
+
+  return {
+    quote: sdk.quote.bind(sdk),
+    enforce: async (enforceInput: Parameters<typeof sdk.enforce>[0]) =>
+      sdk.enforce({
+        ...enforceInput,
+        limits: enforceInput.limits ?? input.defaultLimits,
+      }),
+    getBalance: sdk.getBalance.bind(sdk),
+    /**
+     * Memory-only escape hatch for debugging/analytics.
+     */
+    __unsafe: { usageStore, ledgerStore, limitStore, planStore },
+  };
+};

package/src/stores/LedgerStore.ts

@@ -0,0 +1,30 @@
+import type { Money } from "../types.ts";
+
+export type LedgerDebitInput = {
+  accountId: string;
+  money: Money;
+  idempotencyKey: string;
+  fingerprint: string;
+  metadata?: Record<string, unknown>;
+  nowMs: number;
+};
+
+export type LedgerCreditInput = {
+  accountId: string;
+  money: Money;
+  idempotencyKey: string;
+  fingerprint: string;
+  metadata?: Record<string, unknown>;
+  nowMs: number;
+};
+
+export type LedgerApplyResult = {
+  txId: string;
+  balanceAfter: Money;
+};
+
+export interface LedgerStore {
+  getBalance(input: { accountId: string; currency: Money["currency"] }): Promise<Money>;
+  debit(input: LedgerDebitInput): Promise<LedgerApplyResult>;
+  credit(input: LedgerCreditInput): Promise<LedgerApplyResult>;
+}

package/src/stores/LimitStore.ts

@@ -0,0 +1,5 @@
+export interface LimitStore {
+  consumeRpm(input: { accountId: string; rpm: number; requestCount: number; nowMs: number }): Promise<void>;
+  consumeDailyMinor(input: { accountId: string; amountMinor: number; limitMinor: number; nowMs: number }): Promise<void>;
+  consumeMonthlyMinor(input: { accountId: string; amountMinor: number; limitMinor: number; nowMs: number }): Promise<void>;
+}

package/src/stores/PlanStore.ts

@@ -0,0 +1,5 @@
+import type { PricePlan } from "../types.ts";
+
+export interface PlanStore {
+  getPlan(planId: string): Promise<PricePlan | null>;
+}

package/src/stores/UsageStore.ts

@@ -0,0 +1,5 @@
+import type { UsageRecord } from "../types.ts";
+
+export interface UsageStore {
+  append(record: UsageRecord): Promise<void>;
+}

package/src/types.ts

@@ -0,0 +1,116 @@
+export type Currency = "CNY" | (string & {});
+
+export type Money = {
+  currency: Currency;
+  /**
+   * Minor units (e.g. CNY=分). Integer only.
+   */
+  amountMinor: number;
+};
+
+export type UsageEvent = {
+  meter: string;
+  quantity: number;
+  dimensions?: Record<string, string>;
+  ts?: number;
+};
+
+export type PriceRule = {
+  /**
+   * A logical meter name, e.g. "tokens.input", "tokens.output", "requests".
+   */
+  meter: string;
+  /**
+   * Dimension matchers. v0 supports:
+   * - "*" wildcard
+   * - string equality
+   * - string[] membership
+   */
+  when?: Record<string, "*" | string | string[]>;
+  /**
+   * Price per unit in minor units (e.g. 分). Integer only.
+   */
+  unitPriceMinor: number;
+  currency: Currency;
+  priority?: number;
+  ruleId?: string;
+};
+
+export type PricePlan = {
+  planId: string;
+  rules: PriceRule[];
+};
+
+export type Limits = {
+  /**
+   * Requests per minute. v0: each `enforce()` call consumes 1 request by default.
+   */
+  rpm?: number;
+  /**
+   * Daily spending limit in minor units.
+   */
+  dailyLimitMinor?: number;
+  /**
+   * Monthly spending limit in minor units.
+   */
+  monthlyLimitMinor?: number;
+};
+
+export type QuoteInput = {
+  accountId: string;
+  planId: string;
+  events: UsageEvent[];
+};
+
+export type QuoteItem = {
+  event: UsageEvent;
+  costMinor: number;
+  ruleId?: string;
+};
+
+export type Quote = {
+  total: Money;
+  items: QuoteItem[];
+};
+
+export type EnforceInput = QuoteInput & {
+  idempotencyKey: string;
+  limits?: Limits;
+  /**
+   * Overrides RPM consumption for this call. Defaults to 1.
+   */
+  requestCount?: number;
+  nowMs?: number;
+  metadata?: Record<string, unknown>;
+};
+
+export type EnforceErrorCode =
+  | "INSUFFICIENT_BALANCE"
+  | "RPM_LIMIT_EXCEEDED"
+  | "DAILY_LIMIT_EXCEEDED"
+  | "MONTHLY_LIMIT_EXCEEDED"
+  | "NO_PRICE_RULE"
+  | "CURRENCY_MISMATCH"
+  | "IDEMPOTENCY_CONFLICT"
+  | "INVALID_ARGUMENT";
+
+export type EnforceResult =
+  | { ok: true; txId: string; cost: Money; balanceAfter: Money }
+  | {
+      ok: false;
+      code: EnforceErrorCode;
+      message?: string;
+      retryAfterMs?: number;
+    };
+
+export type UsageRecord = {
+  accountId: string;
+  planId: string;
+  idempotencyKey: string;
+  txId: string;
+  cost: Money;
+  events: UsageEvent[];
+  tsMs: number;
+  metadata?: Record<string, unknown>;
+};
+

package/src/utils/fingerprint.ts

@@ -0,0 +1,14 @@
+const stableStringifyValue = (value: unknown): unknown => {
+  if (Array.isArray(value)) return value.map(stableStringifyValue);
+  if (!value || typeof value !== "object") return value;
+  const record = value as Record<string, unknown>;
+  const keys = Object.keys(record).sort();
+  const out: Record<string, unknown> = {};
+  for (const key of keys) out[key] = stableStringifyValue(record[key]);
+  return out;
+};
+
+export const stableStringify = (value: unknown) => JSON.stringify(stableStringifyValue(value));
+
+export const makeFingerprint = (value: unknown) => stableStringify(value);
+

package/src/utils/guards.ts

@@ -0,0 +1,23 @@
+import { UsageError } from "../errors.ts";
+import type { Money, UsageEvent } from "../types.ts";
+
+export const assertInteger = (value: number, field: string) => {
+  if (!Number.isInteger(value)) throw new UsageError("INVALID_ARGUMENT", `${field} must be an integer`);
+};
+
+export const assertNonNegativeInteger = (value: number, field: string) => {
+  assertInteger(value, field);
+  if (value < 0) throw new UsageError("INVALID_ARGUMENT", `${field} must be >= 0`);
+};
+
+export const assertMoney = (money: Money, field: string) => {
+  if (!money || typeof money !== "object") throw new UsageError("INVALID_ARGUMENT", `${field} is required`);
+  if (!money.currency) throw new UsageError("INVALID_ARGUMENT", `${field}.currency is required`);
+  assertNonNegativeInteger(money.amountMinor, `${field}.amountMinor`);
+};
+
+export const assertUsageEvent = (event: UsageEvent, field: string) => {
+  if (!event || typeof event !== "object") throw new UsageError("INVALID_ARGUMENT", `${field} is required`);
+  if (!event.meter) throw new UsageError("INVALID_ARGUMENT", `${field}.meter is required`);
+  assertNonNegativeInteger(event.quantity, `${field}.quantity`);
+};

package/tsconfig.build.json

@@ -0,0 +1,14 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "rewriteRelativeImportExtensions": true
+  },
+  "include": ["src/**/*"]
+}
+

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"]
+}