@convex-dev/ai-budget 0.0.2-alpha.13 → 0.0.2-alpha.15

package/README.md

@@ -282,6 +282,8 @@ ai.registerWebhook(http, {
 
 `begin` returns the admission result (it doesn't throw — check `allowed`).
 `settle` is idempotent (exactly-once server-side), so a retried webhook is safe.
+The webhook resolver receives the original, unread `Request`, allowing signature
+verification over the exact raw body; the parsed JSON comes from a clone.
 
 ### Replay
 
@@ -315,6 +317,25 @@ different dimensions. Each exposes:
 The identifier field is `userId` for `ai.users`, `name` for `ai.actions`, and
 `value` for `ai.tag(d)`. For example: `ai.tag("customer").setLimits(ctx, { value: "acme", … })`.
 
+### Request rate limits
+
+`requestsPerMinute` uses `@convex-dev/rate-limiter` 0.4.0 with a transactional
+**token bucket** for each user, action, or custom tag. A limit of 60 allows an
+initial burst of 60 requests and then refills at one request per second, up to
+60. Zero blocks all requests. Only admitted requests consume capacity: a budget,
+concurrency, or another bucket's rate rejection consumes none.
+
+This replaces the previous rolling 60-second request-log count. On upgrading,
+rate balances start full; historical requests are not imported. Budget balances,
+reservations, and spend history are preserved. Deploy the component update to
+mount its nested Rate Limiter component; applications do not register it separately.
+Changing a rate keeps its existing balance (clamped to the new capacity when
+checked); deleting and recreating a bucket starts a fresh balance.
+
+Rate limits remain transactional. Rate Limiter's asynchronous mode is not enabled
+here because simultaneous admissions must respect every configured bucket.
+Global spend accounting continues to use the existing sharded counter.
+
 ### Setting caps
 
 ```ts
@@ -549,21 +570,26 @@ this design). `ai-budget` instead **reserves then settles**:
    schedules a fold of the real cost into the totals, releasing the reservation —
    so a request is never orphaned mid-flight.
 3. **Reconcile.** A once-a-minute cron folds any stragglers and releases
-   reservations for requests that died before settling. Settlement is
-   **exactly-once** (a terminal request is never re-folded), so a slow request the
-   reconciler already swept can't double-count when it finally returns.
+   expired reservations using indexed deadlines. Expiry releases the hold but
+   leaves billing open: a late completion records its final charge once without
+   releasing the hold again. After content retention, unresolved requests retain
+   a small billing record with prompts and responses removed.
 
-Reservations are taken only on buckets that actually have a cap, so uncapped
-traffic never serializes — this is what makes arbitrary `tags` cheap: a request
-reserves on one row per *capped* dimension it carries, and nothing else.
+Requests record the exact bucket IDs and calendar windows they reserve.
+Settlement cannot release another request's hold, including across midnight or
+month boundaries. Admission reads separate policy documents; only capped buckets
+require reads of accounting state. Reporting updates still share bucket totals,
+but do not write the policy documents used by uncapped admission.
 
 **One admission rule, all scopes.** Every per-bucket cap — user, action, or any
 tag — runs through the *same* admission check: a request is admitted only when
 `committed + reserved + estimate ≤ cap` (bumps included) for **every** bucket it
 touches. Each per-bucket cap reserves on a single document, making concurrent
 admission atomic. The **global** killswitch is backed by a sharded counter for
-throughput, read as an eventually-consistent sum with no cross-request
-reservation, so concurrent global admissions can overshoot under a burst.
+throughput. Its sum is transactional but excludes unfinished and not-yet-folded
+requests and has no cross-request reservation, so global admissions can overshoot.
+Global usage is recorded even when limits are disabled. Historical usage omitted
+by older versions is not automatically reconstructed by this upgrade.
 
 Reservations are estimates, not provider-side maximum charges. If a response uses
 more tokens or costs more than estimated, settlement records the real amount and
@@ -604,14 +630,19 @@ endpoints verbatim. In production:
 
 `example/` is a full working demo: chat as different personas on the left; a live
 admin panel on the right — the request audit log (inspect → edit → re-run, with
-lineage), a users table (limits, soft toggle, block, bump), and per-action budgets.
+lineage), a users table (limits, soft toggle, block, bump), per-action budgets,
+and a **⚡ Burst** tab that fires N real concurrent AI requests against one
+tightly-capped budget: watch reservations appear live, some requests get
+admitted (with real settled costs), and the rest get atomically rejected by the
+cap — the reserve-then-settle admission design, visible.
 
 ![Users & Limits admin table](docs/users.png)
 ![Actions & Budgets admin table](docs/actions.png)
 
 ```sh
 cd example
-npm install
+npm install         # also links the repo-root node_modules the demo's
+                    # ../../src component imports resolve through (postinstall)
 npx convex dev      # terminal 1 — provisions a dev deployment
 npm run dev         # terminal 2 — Vite app
 ```
@@ -646,6 +677,16 @@ handles rather than taking a dependency on either sibling component.
 
 ---
 
+
+## Accounting upgrade notes
+
+New request fields are optional for existing deployments. Policy documents are
+created on first admission or limit update; pending requests without deadlines
+are migrated in batches by reconciliation. Existing reservations without ownership
+metadata use their creation period and current capped buckets as a compatibility
+fallback. Exact historical hold ownership cannot be reconstructed if those caps
+changed before the upgrade. New requests always store explicit ownership.
+
 ## Development
 
 ```sh

package/dist/client/index.d.ts

@@ -84,6 +84,7 @@ export type ChatResult = {
 };
 /** Limits/controls settable on any budget bucket (user, action, or tag). */
 export type BucketLimits = {
+    /** Token-bucket refill per minute and burst capacity; 0 blocks all requests. */
     requestsPerMinute?: number;
     maxConcurrent?: number;
     dailySpendLimitNanos?: number;
@@ -237,6 +238,14 @@ export declare class AIBudget {
                 dimension: string;
                 value: string;
             }[] | undefined;
+            heldBucketIds?: string[] | undefined;
+            reservationDay?: string | undefined;
+            reservationMonth?: string | undefined;
+            reservationReleased?: boolean | undefined;
+            reservationExpired?: boolean | undefined;
+            contentPurged?: boolean | undefined;
+            expiresAt?: number | undefined;
+            finishedAt?: number | undefined;
             estimatedNanos?: number | undefined;
             estimatedTokens?: number | undefined;
             unpricedModel?: boolean | undefined;
@@ -273,6 +282,14 @@ export declare class AIBudget {
                 dimension: string;
                 value: string;
             }[] | undefined;
+            heldBucketIds?: string[] | undefined;
+            reservationDay?: string | undefined;
+            reservationMonth?: string | undefined;
+            reservationReleased?: boolean | undefined;
+            reservationExpired?: boolean | undefined;
+            contentPurged?: boolean | undefined;
+            expiresAt?: number | undefined;
+            finishedAt?: number | undefined;
             estimatedNanos?: number | undefined;
             estimatedTokens?: number | undefined;
             unpricedModel?: boolean | undefined;
@@ -310,6 +327,14 @@ export declare class AIBudget {
                     dimension: string;
                     value: string;
                 }[] | undefined;
+                heldBucketIds?: string[] | undefined;
+                reservationDay?: string | undefined;
+                reservationMonth?: string | undefined;
+                reservationReleased?: boolean | undefined;
+                reservationExpired?: boolean | undefined;
+                contentPurged?: boolean | undefined;
+                expiresAt?: number | undefined;
+                finishedAt?: number | undefined;
                 estimatedNanos?: number | undefined;
                 estimatedTokens?: number | undefined;
                 unpricedModel?: boolean | undefined;
@@ -343,6 +368,14 @@ export declare class AIBudget {
                     dimension: string;
                     value: string;
                 }[] | undefined;
+                heldBucketIds?: string[] | undefined;
+                reservationDay?: string | undefined;
+                reservationMonth?: string | undefined;
+                reservationReleased?: boolean | undefined;
+                reservationExpired?: boolean | undefined;
+                contentPurged?: boolean | undefined;
+                expiresAt?: number | undefined;
+                finishedAt?: number | undefined;
                 estimatedNanos?: number | undefined;
                 estimatedTokens?: number | undefined;
                 unpricedModel?: boolean | undefined;

package/dist/client/index.js

@@ -692,7 +692,7 @@ export class AIBudget {
             path,
             method: "POST",
             handler: httpActionGeneric(async (ctx, request) => {
-                const body = await request.json().catch(() => ({}));
+                const body = await request.clone().json().catch(() => ({}));
                 const settle = await opts.resolve(ctx, request, body);
                 if (!settle)
                     return new Response("ignored", { status: 202 });

package/dist/component/_generated/api.d.ts

@@ -33,5 +33,6 @@ export declare const api: FilterApi<typeof fullApi, FunctionReference<any, "publ
 export declare const internal: FilterApi<typeof fullApi, FunctionReference<any, "internal">>;
 export declare const components: {
     shardedCounter: import("@convex-dev/sharded-counter/_generated/component.js").ComponentApi<"shardedCounter">;
+    rateLimiter: import("@convex-dev/rate-limiter/_generated/component.js").ComponentApi<"rateLimiter">;
 };
 export {};

package/dist/component/convex.config.js

@@ -1,6 +1,8 @@
 import { defineComponent } from "convex/server";
 import shardedCounter from "@convex-dev/sharded-counter/convex.config";
+import rateLimiter from "@convex-dev/rate-limiter/convex.config";
 const component = defineComponent("aiBudget");
 // Global spend totals use a sharded counter for high write throughput.
 component.use(shardedCounter);
+component.use(rateLimiter);
 export default component;

package/dist/component/lib.d.ts

@@ -58,6 +58,14 @@ export declare const lineage: import("convex/server").RegisteredQuery<"public",
             dimension: string;
             value: string;
         }[] | undefined;
+        heldBucketIds?: import("convex/values").GenericId<"buckets">[] | undefined;
+        reservationDay?: string | undefined;
+        reservationMonth?: string | undefined;
+        reservationReleased?: boolean | undefined;
+        reservationExpired?: boolean | undefined;
+        contentPurged?: boolean | undefined;
+        expiresAt?: number | undefined;
+        finishedAt?: number | undefined;
         estimatedNanos?: number | undefined;
         estimatedTokens?: number | undefined;
         unpricedModel?: boolean | undefined;
@@ -89,6 +97,14 @@ export declare const lineage: import("convex/server").RegisteredQuery<"public",
             dimension: string;
             value: string;
         }[] | undefined;
+        heldBucketIds?: import("convex/values").GenericId<"buckets">[] | undefined;
+        reservationDay?: string | undefined;
+        reservationMonth?: string | undefined;
+        reservationReleased?: boolean | undefined;
+        reservationExpired?: boolean | undefined;
+        contentPurged?: boolean | undefined;
+        expiresAt?: number | undefined;
+        finishedAt?: number | undefined;
         estimatedNanos?: number | undefined;
         estimatedTokens?: number | undefined;
         unpricedModel?: boolean | undefined;
@@ -123,6 +139,14 @@ export declare const getRequest: import("convex/server").RegisteredQuery<"public
         dimension: string;
         value: string;
     }[] | undefined;
+    heldBucketIds?: import("convex/values").GenericId<"buckets">[] | undefined;
+    reservationDay?: string | undefined;
+    reservationMonth?: string | undefined;
+    reservationReleased?: boolean | undefined;
+    reservationExpired?: boolean | undefined;
+    contentPurged?: boolean | undefined;
+    expiresAt?: number | undefined;
+    finishedAt?: number | undefined;
     estimatedNanos?: number | undefined;
     estimatedTokens?: number | undefined;
     unpricedModel?: boolean | undefined;
@@ -159,6 +183,14 @@ export declare const listRequests: import("convex/server").RegisteredQuery<"publ
         dimension: string;
         value: string;
     }[] | undefined;
+    heldBucketIds?: import("convex/values").GenericId<"buckets">[] | undefined;
+    reservationDay?: string | undefined;
+    reservationMonth?: string | undefined;
+    reservationReleased?: boolean | undefined;
+    reservationExpired?: boolean | undefined;
+    contentPurged?: boolean | undefined;
+    expiresAt?: number | undefined;
+    finishedAt?: number | undefined;
     estimatedNanos?: number | undefined;
     estimatedTokens?: number | undefined;
     unpricedModel?: boolean | undefined;