Class SpendControl

src/spend-control.ts:158–348

}

export class SpendControl {
  private limits: SpendLimits = {};
  private history: SpendRecord[] = [];
  private sessionSpent: number = 0;
  private sessionCalls: number = 0;
  private readonly storage: SpendControlStorage;
  private readonly now: () => number;

  constructor(options?: SpendControlOptions) {
    this.storage = options?.storage ?? new FileSpendControlStorage();
    this.now = options?.now ?? (() => Date.now());
    this.load();
  }

  setLimit(window: SpendWindow, amount: number): void {
    if (!Number.isFinite(amount) || amount <= 0) {
      throw new Error("Limit must be a finite positive number");
    }
    this.limits[window] = amount;
    this.save();
  }

  clearLimit(window: SpendWindow): void {
    delete this.limits[window];
    this.save();
  }

  getLimits(): SpendLimits {
    return { ...this.limits };
  }

  check(estimatedCost: number): CheckResult {
    const now = this.now();

    if (this.limits.perRequest !== undefined) {
      if (estimatedCost > this.limits.perRequest) {
        return {
          allowed: false,
          blockedBy: "perRequest",
          remaining: this.limits.perRequest,
          reason: `Per-request limit exceeded: $${estimatedCost.toFixed(4)} > $${this.limits.perRequest.toFixed(2)} max`,
        };
      }
    }

    if (this.limits.hourly !== undefined) {
      const hourlySpent = this.getSpendingInWindow(now - HOUR_MS, now);
      const remaining = this.limits.hourly - hourlySpent;
      if (estimatedCost > remaining) {
        const oldestInWindow = this.history.find((r) => r.timestamp >= now - HOUR_MS);
        const resetIn = oldestInWindow
          ? Math.ceil((oldestInWindow.timestamp + HOUR_MS - now) / 1000)
          : 0;
        return {
          allowed: false,
          blockedBy: "hourly",
          remaining,
          reason: `Hourly limit exceeded: $${(hourlySpent + estimatedCost).toFixed(2)} > $${this.limits.hourly.toFixed(2)} max`,