usage-sdk-test 0.1.0 → 0.1.1

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "usage-sdk-test",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "private": false,
-  "type": "module",
-  "exports": {
-    ".": {
-      "types": "./src/index.ts",
-      "default": "./src/index.ts"
-    }
-  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
-    "typecheck": "tsc -p tsconfig.json"
+    "typecheck": "tsc -p tsconfig.json",
+    "prepublishOnly": "bun run build"
   },
   "devDependencies": {
     "typescript": "^5.9.2"

package/examples/basic.ts

@@ -1,35 +0,0 @@
-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/src/errors.ts

@@ -1,19 +0,0 @@
-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

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

package/src/pricing/matchRule.ts

@@ -1,36 +0,0 @@
-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

@@ -1,38 +0,0 @@
-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

@@ -1,90 +0,0 @@
-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

@@ -1,102 +0,0 @@
-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

@@ -1,14 +0,0 @@
-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

@@ -1,10 +0,0 @@
-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

@@ -1,117 +0,0 @@
-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

@@ -1,38 +0,0 @@
-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

@@ -1,30 +0,0 @@
-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

@@ -1,5 +0,0 @@
-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

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

package/src/stores/UsageStore.ts

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