@convex-dev/ai-budget 0.0.2-alpha.14 → 0.0.2-alpha.16

package/src/client/index.ts

@@ -71,6 +71,8 @@ export type BudgetEventInfo = {
 export type SoftLimitInfo = BudgetEventInfo & { warnings: string[] };
 export type AIBudgetOptions = {
   defaultModel?: string;
+  /** Default model for `decisions()` (the Decisions/"Jev" endpoint). */
+  defaultEvalModel?: string;
   /**
    * A *soft* limit was exceeded (request still allowed). Lets you surface budget
    * warnings even on the languageModel/Agent path where they can't be returned.
@@ -143,6 +145,17 @@ export type ChatResult = {
   notices: string[];
 };
 
+/** The tracked result of a `decisions()` call: budgeting metadata plus the
+ * structured answers from the Decisions ("Jev") endpoint. */
+export type DecisionResult = Omit<ChatResult, "text"> & {
+  /** Structured answers keyed by your question names (shape depends on each
+   * question type: `choice`, `score`, or `boolean`). */
+  answers: Record<string, any>;
+  /** The raw gateway response, including provider-specific fields (e.g.
+   * `confidence`) under `response.body`. */
+  response?: any;
+};
+
 // ---------- helpers ----------
 
 // Token counts across AI SDK versions come as plain numbers or, in v7, as a
@@ -239,6 +252,7 @@ function timingSafeEqual(a: string, b: string): boolean {
 
 /** 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;
@@ -261,6 +275,7 @@ export type BumpArgs = {
 
 export class AIBudget {
   public defaultModel: string;
+  public defaultEvalModel: string;
   private onSoftLimit?: AIBudgetOptions["onSoftLimit"];
   private onThreshold?: AIBudgetOptions["onThreshold"];
   private onLimitReached?: AIBudgetOptions["onLimitReached"];
@@ -269,6 +284,7 @@ export class AIBudget {
     options?: AIBudgetOptions
   ) {
     this.defaultModel = options?.defaultModel ?? "openai/gpt-4o-mini";
+    this.defaultEvalModel = options?.defaultEvalModel ?? "typesafe/jev-1.13";
     this.onSoftLimit = options?.onSoftLimit;
     this.onThreshold = options?.onThreshold;
     this.onLimitReached = options?.onLimitReached;
@@ -533,6 +549,103 @@ export class AIBudget {
     );
   }
 
+  /**
+   * Budget a structured decision through the AI Gateway's Decisions ("Jev")
+   * endpoint — sugar over `meter`. Evaluates typed `questions` (choice / score /
+   * boolean) about the `state` you provide, with the same reserve→settle
+   * limits, audit log, cost tracking, and per-tag attribution as `chat`. Call
+   * from an action. `userId` defaults to the authenticated caller.
+   *
+   * Requires `@convex-dev/ai-sdk-provider` >= 0.2.1 and an `ai` version that
+   * exposes `experimental_evaluate` (AI SDK 7's evaluation interface); both are
+   * imported lazily, so consumers who never call `decisions()` are unaffected.
+   *
+   *   const { answers } = await ai.decisions(ctx, {
+   *     state: { ticket: "Customer cannot sign in" },
+   *     questions: {
+   *       priority: { type: "choice", instructions: "...", criteria: { urgent: "...", normal: "..." } },
+   *       needsReview: { type: "boolean", instructions: "..." },
+   *     },
+   *   });
+   *   answers.priority.choice; // "urgent" | "normal"
+   */
+  async decisions(
+    ctx: RunMutationCtx,
+    args: {
+      /** The evaluation model. Defaults to `defaultEvalModel` ("typesafe/jev-1.13"). */
+      model?: string;
+      /** Context the questions are evaluated against (a string or an object). */
+      state: unknown;
+      /** Typed questions (choice / score / boolean) keyed by name. */
+      questions: Record<string, unknown>;
+      /** Whom to bill. Defaults to the authenticated user (ctx.auth). */
+      userId?: string;
+      /** Attribute spend to this action name. Defaults to the calling action. */
+      action?: string;
+      /** Extra attribution dimensions to bill/limit (team, customer, env, …). */
+      tags?: Tag[];
+      /** Reserve this exact amount (nanodollars) up front — the decision cost
+       * isn't known before the call, so a hard cap is only exact with this. */
+      estimatedCostNanos?: number;
+      rerunOf?: string;
+      /** Cancel the underlying request. */
+      abortSignal?: AbortSignal;
+    }
+  ): Promise<DecisionResult> {
+    const model = args.model ?? this.defaultEvalModel;
+    // `evaluate` is an experimental, version-gated export; import it lazily and
+    // untyped so consumers on an older `ai` (who never call this) aren't broken.
+    const evaluate = ((await import("ai")) as any).experimental_evaluate;
+    if (typeof evaluate !== "function") {
+      throw new Error(
+        "ai-budget: decisions() needs `experimental_evaluate` from the `ai` " +
+          "package (AI SDK 7's evaluation interface). Upgrade `ai` to a " +
+          "version that exports it."
+      );
+    }
+    // Likewise, `evaluationModel` exists on @convex-dev/ai-sdk-provider >= 0.2.1.
+    const evaluationModel = (convexGateway as any).evaluationModel;
+    if (typeof evaluationModel !== "function") {
+      throw new Error(
+        "ai-budget: decisions() needs `convexGateway.evaluationModel` from " +
+          "@convex-dev/ai-sdk-provider >= 0.2.1. Upgrade the provider."
+      );
+    }
+    let decision: any;
+    const result = await this.meter(
+      ctx,
+      {
+        model,
+        // Store the structured request for audit/replay.
+        messages: [
+          {
+            role: "user",
+            content: JSON.stringify({ state: args.state, questions: args.questions }),
+          },
+        ],
+        userId: args.userId,
+        action: args.action,
+        tags: args.tags,
+        estimatedCostNanos: args.estimatedCostNanos,
+        rerunOf: args.rerunOf,
+      },
+      async () => {
+        decision = await evaluate({
+          model: evaluationModel(model),
+          state: args.state,
+          questions: args.questions,
+          ...(args.abortSignal ? { abortSignal: args.abortSignal } : {}),
+        });
+        return {
+          usage: decision?.usage,
+          costNanos: extractGatewayCostNanos(decision),
+        };
+      }
+    );
+    const { text: _text, ...tracking } = result;
+    return { ...tracking, answers: decision?.answers ?? {}, response: decision?.response };
+  }
+
   /**
    * An AI SDK LanguageModel that enforces limits and records usage/cost for
    * `userId` on every call. Drop it into `generateText`, `streamText`, or the
@@ -1061,7 +1174,7 @@ export class AIBudget {
       path,
       method: "POST",
       handler: httpActionGeneric(async (ctx: any, request: 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 });
         await self.settle(ctx, settle);

package/src/client/webhook.test.ts

@@ -0,0 +1,32 @@
+import { test, expect, vi } from "vitest";
+import { httpRouter } from "convex/server";
+import { AIBudget } from "./index";
+
+test("webhook resolver can verify the exact raw body before settlement", async () => {
+  const budget = new AIBudget({} as any);
+  const settle = vi.spyOn(budget, "settle").mockResolvedValue({ costNanos: 123 });
+  const http = httpRouter();
+  const raw = '{ "id": "job", "cost": 123 }\n';
+  const key = await crypto.subtle.importKey("raw", new TextEncoder().encode("test-secret"),
+    { name: "HMAC", hash: "SHA-256" }, false, ["sign", "verify"]);
+  const signature = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(raw));
+  budget.registerWebhook(http, {
+    resolve: async (_ctx, request, body) => {
+      const bytes = await request.arrayBuffer();
+      if (!await crypto.subtle.verify("HMAC", key, signature, bytes)) return null;
+      expect(body.id).toBe("job");
+      return { requestId: "request", costNanos: body.cost };
+    },
+  });
+  const [handler] = http.lookup("/aibudget/webhook", "POST")!;
+  const response = await (handler as any)._handler({}, new Request("https://example.test/aibudget/webhook", {
+    method: "POST", body: raw,
+  }));
+  expect(response.status).toBe(200);
+  expect(settle).toHaveBeenCalledOnce();
+  const rejected = await (handler as any)._handler({}, new Request("https://example.test/aibudget/webhook", {
+    method: "POST", body: raw.replace("123", "999"),
+  }));
+  expect(rejected.status).toBe(202);
+  expect(settle).toHaveBeenCalledOnce();
+});

package/src/component/_generated/api.ts

@@ -51,4 +51,5 @@ export const internal: FilterApi<
 
 export const components = componentsGeneric() as unknown as {
   shardedCounter: import("@convex-dev/sharded-counter/_generated/component.js").ComponentApi<"shardedCounter">;
+  rateLimiter: import("@convex-dev/rate-limiter/_generated/component.js").ComponentApi<"rateLimiter">;
 };

package/src/component/convex.config.ts

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