@convex-dev/ai-budget 0.0.2-alpha.4 → 0.0.2-alpha.6

package/src/component/schema.ts

@@ -20,18 +20,26 @@ export default defineSchema({
     value: v.string(),
     // limits (all optional — unlimited by default)
     requestsPerMinute: v.optional(v.number()), // enforced on the "user" dimension
+    maxConcurrent: v.optional(v.number()), // max in-flight (pending) requests
     dailySpendLimitNanos: v.optional(v.number()),
+    monthlySpendLimitNanos: v.optional(v.number()),
     lifetimeSpendLimitNanos: v.optional(v.number()),
     dailyTokenLimit: v.optional(v.number()),
+    monthlyTokenLimit: v.optional(v.number()),
     lifetimeTokenLimit: v.optional(v.number()),
     blocked: v.optional(v.boolean()), // hard block (was `blocked`/`disabled`)
+    // Fire an approaching-limit alert once usage crosses this fraction of a cap
+    // (e.g. 0.8 = warn at 80%). Falls back to the deployment default.
+    warnAtPct: v.optional(v.number()),
     // "hard" (default): exceeding a budget blocks. "soft": warn but allow.
     enforcement: v.optional(v.union(v.literal("hard"), v.literal("soft"))),
-    // one-time bumps ("approve another $X"). Daily bump is scoped to bumpDayStamp
-    // (resets with the day); lifetime bump is permanent.
+    // one-time bumps ("approve another $X"). Daily/monthly bumps are scoped to
+    // their stamp (reset with the window); lifetime bump is permanent.
     dailyBumpNanos: v.optional(v.number()),
+    monthlyBumpNanos: v.optional(v.number()),
     lifetimeBumpNanos: v.optional(v.number()),
     bumpDayStamp: v.optional(v.string()),
+    bumpMonthStamp: v.optional(v.string()),
     // settled totals (from finished requests)
     totalSpendNanos: v.number(),
     totalRequests: v.number(),
@@ -40,16 +48,59 @@ export default defineSchema({
     dayStamp: v.string(),
     spendTodayNanos: v.number(),
     tokensToday: v.optional(v.number()),
+    // monthly window (UTC calendar month, e.g. "2026-09")
+    monthStamp: v.optional(v.string()),
+    spendThisMonthNanos: v.optional(v.number()),
+    tokensThisMonth: v.optional(v.number()),
     // in-flight reservations (pessimistic holds; released on settle/expiry)
     reservedTodayNanos: v.optional(v.number()),
+    reservedMonthNanos: v.optional(v.number()),
     reservedTotalNanos: v.optional(v.number()),
     reservedTodayTokens: v.optional(v.number()),
+    reservedMonthTokens: v.optional(v.number()),
     reservedTotalTokens: v.optional(v.number()),
     pendingCount: v.optional(v.number()),
   })
     .index("dim_value", ["dimension", "value"])
     .index("dimension", ["dimension"]),
 
+  // Durable per-(bucket, period) spend history. Written from settled requests
+  // and manual adjustments; NEVER swept by request retention, so spend charts
+  // and "what did we spend last month" survive long after the raw request rows
+  // are purged. period is "day" ("2026-09-04") or "month" ("2026-09").
+  usage: defineTable({
+    dimension: v.string(),
+    value: v.string(),
+    period: v.union(v.literal("day"), v.literal("month")),
+    stamp: v.string(),
+    spendNanos: v.number(),
+    tokens: v.number(),
+    requests: v.number(),
+  })
+    .index("bucket_period_stamp", ["dimension", "value", "period", "stamp"])
+    .index("period_stamp", ["period", "stamp"]),
+
+  // Reverse index for filtering the request log by an arbitrary tag dimension
+  // (user/action are already indexed on `requests`). One row per extra tag per
+  // request; cleaned up with the request on retention/deletion.
+  requestTags: defineTable({
+    dimension: v.string(),
+    value: v.string(),
+    requestId: v.id("requests"),
+  })
+    .index("dim_value", ["dimension", "value"])
+    .index("requestId", ["requestId"]),
+
+  // Manual credits/debits applied to a bucket (comp a user, correct an
+  // overcharge). Negative delta = credit/refund, positive = extra charge.
+  adjustments: defineTable({
+    dimension: v.string(),
+    value: v.string(),
+    deltaNanos: v.number(),
+    tokens: v.optional(v.number()),
+    reason: v.optional(v.string()),
+  }).index("dim_value", ["dimension", "value"]),
+
   requests: defineTable({
     // `user` and `action` stay first-class + indexed (the hot-path filters and
     // rate limiting); the full attribution incl. extra tags lives in `tags`.
@@ -96,6 +147,9 @@ export default defineSchema({
     model: v.string(),
     inputNanosPerMTok: v.number(),
     outputNanosPerMTok: v.number(),
+    // price for cached (prompt-cache-read) input tokens. Providers bill these
+    // at a fraction of the input rate; if unset, a default discount is applied.
+    cachedNanosPerMTok: v.optional(v.number()),
   }).index("model", ["model"]),
 
   // singleton component config (key === "singleton")
@@ -127,5 +181,8 @@ export default defineSchema({
     globalBumpDayStamp: v.optional(v.string()),
     // request-row retention window in ms (default 1h); 0 disables sweeping.
     retentionMs: v.optional(v.number()),
+    // default approaching-limit alert threshold (fraction of a cap) for buckets
+    // that don't set their own warnAtPct. 0/unset disables threshold alerts.
+    defaultWarnAtPct: v.optional(v.number()),
   }).index("key", ["key"]),
 });