@convex-dev/ai-budget 0.0.2-alpha.0

package/dist/component/schema.d.ts

@@ -0,0 +1,199 @@
+export declare const vMessage: import("convex/values").VObject<{
+    role: string;
+    content: string;
+}, {
+    role: import("convex/values").VString<string, "required">;
+    content: import("convex/values").VString<string, "required">;
+}, "required", "role" | "content">;
+declare const _default: import("convex/server").SchemaDefinition<{
+    users: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        requestsPerMinute?: number | undefined;
+        dailySpendLimitNanos?: number | undefined;
+        lifetimeSpendLimitNanos?: number | undefined;
+        dailyTokenLimit?: number | undefined;
+        lifetimeTokenLimit?: number | undefined;
+        blocked?: boolean | undefined;
+        enforcement?: "hard" | "soft" | undefined;
+        dailyBumpNanos?: number | undefined;
+        lifetimeBumpNanos?: number | undefined;
+        bumpDayStamp?: string | undefined;
+        tokensToday?: number | undefined;
+        reservedTodayNanos?: number | undefined;
+        reservedTotalNanos?: number | undefined;
+        reservedTodayTokens?: number | undefined;
+        reservedTotalTokens?: number | undefined;
+        pendingCount?: number | undefined;
+        userId: string;
+        totalSpendNanos: number;
+        totalRequests: number;
+        totalTokens: number;
+        dayStamp: string;
+        spendTodayNanos: number;
+    }, {
+        userId: import("convex/values").VString<string, "required">;
+        requestsPerMinute: import("convex/values").VFloat64<number | undefined, "optional">;
+        dailySpendLimitNanos: import("convex/values").VFloat64<number | undefined, "optional">;
+        lifetimeSpendLimitNanos: import("convex/values").VFloat64<number | undefined, "optional">;
+        dailyTokenLimit: import("convex/values").VFloat64<number | undefined, "optional">;
+        lifetimeTokenLimit: import("convex/values").VFloat64<number | undefined, "optional">;
+        blocked: import("convex/values").VBoolean<boolean | undefined, "optional">;
+        enforcement: import("convex/values").VUnion<"hard" | "soft" | undefined, [import("convex/values").VLiteral<"hard", "required">, import("convex/values").VLiteral<"soft", "required">], "optional", never>;
+        dailyBumpNanos: import("convex/values").VFloat64<number | undefined, "optional">;
+        lifetimeBumpNanos: import("convex/values").VFloat64<number | undefined, "optional">;
+        bumpDayStamp: import("convex/values").VString<string | undefined, "optional">;
+        totalSpendNanos: import("convex/values").VFloat64<number, "required">;
+        totalRequests: import("convex/values").VFloat64<number, "required">;
+        totalTokens: import("convex/values").VFloat64<number, "required">;
+        dayStamp: import("convex/values").VString<string, "required">;
+        spendTodayNanos: import("convex/values").VFloat64<number, "required">;
+        tokensToday: import("convex/values").VFloat64<number | undefined, "optional">;
+        reservedTodayNanos: import("convex/values").VFloat64<number | undefined, "optional">;
+        reservedTotalNanos: import("convex/values").VFloat64<number | undefined, "optional">;
+        reservedTodayTokens: import("convex/values").VFloat64<number | undefined, "optional">;
+        reservedTotalTokens: import("convex/values").VFloat64<number | undefined, "optional">;
+        pendingCount: import("convex/values").VFloat64<number | undefined, "optional">;
+    }, "required", "userId" | "requestsPerMinute" | "dailySpendLimitNanos" | "lifetimeSpendLimitNanos" | "dailyTokenLimit" | "lifetimeTokenLimit" | "blocked" | "enforcement" | "dailyBumpNanos" | "lifetimeBumpNanos" | "bumpDayStamp" | "totalSpendNanos" | "totalRequests" | "totalTokens" | "dayStamp" | "spendTodayNanos" | "tokensToday" | "reservedTodayNanos" | "reservedTotalNanos" | "reservedTodayTokens" | "reservedTotalTokens" | "pendingCount">, {
+        userId: ["userId", "_creationTime"];
+    }, {}, {}>;
+    actions: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        dailySpendLimitNanos?: number | undefined;
+        lifetimeSpendLimitNanos?: number | undefined;
+        dailyTokenLimit?: number | undefined;
+        lifetimeTokenLimit?: number | undefined;
+        enforcement?: "hard" | "soft" | undefined;
+        dailyBumpNanos?: number | undefined;
+        lifetimeBumpNanos?: number | undefined;
+        bumpDayStamp?: string | undefined;
+        tokensToday?: number | undefined;
+        reservedTodayNanos?: number | undefined;
+        reservedTotalNanos?: number | undefined;
+        reservedTodayTokens?: number | undefined;
+        reservedTotalTokens?: number | undefined;
+        pendingCount?: number | undefined;
+        disabled?: boolean | undefined;
+        totalSpendNanos: number;
+        totalRequests: number;
+        totalTokens: number;
+        dayStamp: string;
+        spendTodayNanos: number;
+        name: string;
+    }, {
+        name: import("convex/values").VString<string, "required">;
+        dailySpendLimitNanos: import("convex/values").VFloat64<number | undefined, "optional">;
+        lifetimeSpendLimitNanos: import("convex/values").VFloat64<number | undefined, "optional">;
+        dailyTokenLimit: import("convex/values").VFloat64<number | undefined, "optional">;
+        lifetimeTokenLimit: import("convex/values").VFloat64<number | undefined, "optional">;
+        disabled: import("convex/values").VBoolean<boolean | undefined, "optional">;
+        enforcement: import("convex/values").VUnion<"hard" | "soft" | undefined, [import("convex/values").VLiteral<"hard", "required">, import("convex/values").VLiteral<"soft", "required">], "optional", never>;
+        dailyBumpNanos: import("convex/values").VFloat64<number | undefined, "optional">;
+        lifetimeBumpNanos: import("convex/values").VFloat64<number | undefined, "optional">;
+        bumpDayStamp: import("convex/values").VString<string | undefined, "optional">;
+        totalSpendNanos: import("convex/values").VFloat64<number, "required">;
+        totalRequests: import("convex/values").VFloat64<number, "required">;
+        totalTokens: import("convex/values").VFloat64<number, "required">;
+        dayStamp: import("convex/values").VString<string, "required">;
+        spendTodayNanos: import("convex/values").VFloat64<number, "required">;
+        tokensToday: import("convex/values").VFloat64<number | undefined, "optional">;
+        reservedTodayNanos: import("convex/values").VFloat64<number | undefined, "optional">;
+        reservedTotalNanos: import("convex/values").VFloat64<number | undefined, "optional">;
+        reservedTodayTokens: import("convex/values").VFloat64<number | undefined, "optional">;
+        reservedTotalTokens: import("convex/values").VFloat64<number | undefined, "optional">;
+        pendingCount: import("convex/values").VFloat64<number | undefined, "optional">;
+    }, "required", "dailySpendLimitNanos" | "lifetimeSpendLimitNanos" | "dailyTokenLimit" | "lifetimeTokenLimit" | "enforcement" | "dailyBumpNanos" | "lifetimeBumpNanos" | "bumpDayStamp" | "totalSpendNanos" | "totalRequests" | "totalTokens" | "dayStamp" | "spendTodayNanos" | "tokensToday" | "reservedTodayNanos" | "reservedTotalNanos" | "reservedTodayTokens" | "reservedTotalTokens" | "pendingCount" | "name" | "disabled">, {
+        name: ["name", "_creationTime"];
+    }, {}, {}>;
+    requests: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        actionName?: string | undefined;
+        estimatedNanos?: number | undefined;
+        estimatedTokens?: number | undefined;
+        unpricedModel?: boolean | undefined;
+        overBudget?: boolean | undefined;
+        settled?: boolean | undefined;
+        error?: string | undefined;
+        responseText?: string | undefined;
+        promptTokens?: number | undefined;
+        completionTokens?: number | undefined;
+        cachedTokens?: number | undefined;
+        costNanos?: number | undefined;
+        latencyMs?: number | undefined;
+        rerunOf?: import("convex/values").GenericId<"requests"> | undefined;
+        userId: string;
+        model: string;
+        messages: {
+            role: string;
+            content: string;
+        }[];
+        status: "blocked" | "pending" | "success" | "error";
+    }, {
+        userId: import("convex/values").VString<string, "required">;
+        actionName: import("convex/values").VString<string | undefined, "optional">;
+        model: import("convex/values").VString<string, "required">;
+        estimatedNanos: import("convex/values").VFloat64<number | undefined, "optional">;
+        estimatedTokens: import("convex/values").VFloat64<number | undefined, "optional">;
+        unpricedModel: import("convex/values").VBoolean<boolean | undefined, "optional">;
+        overBudget: import("convex/values").VBoolean<boolean | undefined, "optional">;
+        settled: import("convex/values").VBoolean<boolean | undefined, "optional">;
+        messages: import("convex/values").VArray<{
+            role: string;
+            content: string;
+        }[], import("convex/values").VObject<{
+            role: string;
+            content: string;
+        }, {
+            role: import("convex/values").VString<string, "required">;
+            content: import("convex/values").VString<string, "required">;
+        }, "required", "role" | "content">, "required">;
+        status: import("convex/values").VUnion<"blocked" | "pending" | "success" | "error", [import("convex/values").VLiteral<"pending", "required">, import("convex/values").VLiteral<"success", "required">, import("convex/values").VLiteral<"error", "required">, import("convex/values").VLiteral<"blocked", "required">], "required", never>;
+        responseText: import("convex/values").VString<string | undefined, "optional">;
+        error: import("convex/values").VString<string | undefined, "optional">;
+        promptTokens: import("convex/values").VFloat64<number | undefined, "optional">;
+        completionTokens: import("convex/values").VFloat64<number | undefined, "optional">;
+        cachedTokens: import("convex/values").VFloat64<number | undefined, "optional">;
+        costNanos: import("convex/values").VFloat64<number | undefined, "optional">;
+        latencyMs: import("convex/values").VFloat64<number | undefined, "optional">;
+        rerunOf: import("convex/values").VId<import("convex/values").GenericId<"requests"> | undefined, "optional">;
+    }, "required", "userId" | "actionName" | "model" | "estimatedNanos" | "estimatedTokens" | "unpricedModel" | "overBudget" | "settled" | "messages" | "status" | "error" | "responseText" | "promptTokens" | "completionTokens" | "cachedTokens" | "costNanos" | "latencyMs" | "rerunOf">, {
+        userId: ["userId", "_creationTime"];
+        status: ["status", "_creationTime"];
+        rerunOf: ["rerunOf", "_creationTime"];
+        actionName: ["actionName", "_creationTime"];
+        settled: ["settled", "_creationTime"];
+    }, {}, {}>;
+    prices: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        model: string;
+        inputNanosPerMTok: number;
+        outputNanosPerMTok: number;
+    }, {
+        model: import("convex/values").VString<string, "required">;
+        inputNanosPerMTok: import("convex/values").VFloat64<number, "required">;
+        outputNanosPerMTok: import("convex/values").VFloat64<number, "required">;
+    }, "required", "model" | "inputNanosPerMTok" | "outputNanosPerMTok">, {
+        model: ["model", "_creationTime"];
+    }, {}, {}>;
+    settings: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        modelMode?: "open" | "allowlist" | "denylist" | undefined;
+        models?: string[] | undefined;
+        globalDailySpendLimitNanos?: number | undefined;
+        globalLifetimeSpendLimitNanos?: number | undefined;
+        globalEnforcement?: "hard" | "soft" | undefined;
+        globalDailyBumpNanos?: number | undefined;
+        globalLifetimeBumpNanos?: number | undefined;
+        globalBumpDayStamp?: string | undefined;
+        retentionMs?: number | undefined;
+        key: string;
+    }, {
+        key: import("convex/values").VString<string, "required">;
+        modelMode: import("convex/values").VUnion<"open" | "allowlist" | "denylist" | undefined, [import("convex/values").VLiteral<"open", "required">, import("convex/values").VLiteral<"allowlist", "required">, import("convex/values").VLiteral<"denylist", "required">], "optional", never>;
+        models: import("convex/values").VArray<string[] | undefined, import("convex/values").VString<string, "required">, "optional">;
+        globalDailySpendLimitNanos: import("convex/values").VFloat64<number | undefined, "optional">;
+        globalLifetimeSpendLimitNanos: import("convex/values").VFloat64<number | undefined, "optional">;
+        globalEnforcement: import("convex/values").VUnion<"hard" | "soft" | undefined, [import("convex/values").VLiteral<"hard", "required">, import("convex/values").VLiteral<"soft", "required">], "optional", never>;
+        globalDailyBumpNanos: import("convex/values").VFloat64<number | undefined, "optional">;
+        globalLifetimeBumpNanos: import("convex/values").VFloat64<number | undefined, "optional">;
+        globalBumpDayStamp: import("convex/values").VString<string | undefined, "optional">;
+        retentionMs: import("convex/values").VFloat64<number | undefined, "optional">;
+    }, "required", "key" | "modelMode" | "models" | "globalDailySpendLimitNanos" | "globalLifetimeSpendLimitNanos" | "globalEnforcement" | "globalDailyBumpNanos" | "globalLifetimeBumpNanos" | "globalBumpDayStamp" | "retentionMs">, {
+        key: ["key", "_creationTime"];
+    }, {}, {}>;
+}, true>;
+export default _default;

package/dist/component/schema.js

@@ -0,0 +1,123 @@
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+export const vMessage = v.object({
+    role: v.string(), // "system" | "user" | "assistant" | "tool"
+    content: v.string(),
+});
+export default defineSchema({
+    users: defineTable({
+        userId: v.string(), // app-provided stable key (your user id)
+        // limits (all optional — unlimited by default)
+        requestsPerMinute: v.optional(v.number()),
+        dailySpendLimitNanos: v.optional(v.number()),
+        lifetimeSpendLimitNanos: v.optional(v.number()),
+        dailyTokenLimit: v.optional(v.number()),
+        lifetimeTokenLimit: v.optional(v.number()),
+        blocked: v.optional(v.boolean()),
+        // "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") added on top of the cap. Daily bump
+        // is scoped to bumpDayStamp (resets with the day); lifetime bump is permanent.
+        dailyBumpNanos: v.optional(v.number()),
+        lifetimeBumpNanos: v.optional(v.number()),
+        bumpDayStamp: v.optional(v.string()),
+        // settled totals (from finished requests)
+        totalSpendNanos: v.number(),
+        totalRequests: v.number(),
+        totalTokens: v.number(),
+        // daily window
+        dayStamp: v.string(), // e.g. "2026-08-27" (UTC)
+        spendTodayNanos: v.number(),
+        tokensToday: v.optional(v.number()),
+        // in-flight reservations (pessimistic holds; released on settle/expiry)
+        reservedTodayNanos: v.optional(v.number()),
+        reservedTotalNanos: v.optional(v.number()),
+        reservedTodayTokens: v.optional(v.number()),
+        reservedTotalTokens: v.optional(v.number()),
+        pendingCount: v.optional(v.number()),
+    }).index("userId", ["userId"]),
+    // per-action-name budgets and running totals (e.g. "chat", "summarize")
+    actions: defineTable({
+        name: v.string(),
+        dailySpendLimitNanos: v.optional(v.number()),
+        lifetimeSpendLimitNanos: v.optional(v.number()),
+        dailyTokenLimit: v.optional(v.number()),
+        lifetimeTokenLimit: v.optional(v.number()),
+        disabled: v.optional(v.boolean()),
+        enforcement: v.optional(v.union(v.literal("hard"), v.literal("soft"))),
+        dailyBumpNanos: v.optional(v.number()),
+        lifetimeBumpNanos: v.optional(v.number()),
+        bumpDayStamp: v.optional(v.string()),
+        totalSpendNanos: v.number(),
+        totalRequests: v.number(),
+        totalTokens: v.number(),
+        dayStamp: v.string(),
+        spendTodayNanos: v.number(),
+        tokensToday: v.optional(v.number()),
+        reservedTodayNanos: v.optional(v.number()),
+        reservedTotalNanos: v.optional(v.number()),
+        reservedTodayTokens: v.optional(v.number()),
+        reservedTotalTokens: v.optional(v.number()),
+        pendingCount: v.optional(v.number()),
+    }).index("name", ["name"]),
+    requests: defineTable({
+        userId: v.string(),
+        actionName: v.optional(v.string()),
+        model: v.string(),
+        // pessimistic holds placed at start; reconciled to actual on settle
+        estimatedNanos: v.optional(v.number()),
+        estimatedTokens: v.optional(v.number()),
+        // true when the model had no known/override price and was charged the
+        // conservative fallback — a signal to add a real price via setPrice.
+        unpricedModel: v.optional(v.boolean()),
+        // true when a soft budget was exceeded (allowed with a warning).
+        overBudget: v.optional(v.boolean()),
+        // false once finished and awaiting fold into totals; true once folded.
+        // absent while pending or blocked (so the reconciler ignores those).
+        settled: v.optional(v.boolean()),
+        messages: v.array(vMessage),
+        status: v.union(v.literal("pending"), v.literal("success"), v.literal("error"), v.literal("blocked")),
+        responseText: v.optional(v.string()),
+        error: v.optional(v.string()),
+        promptTokens: v.optional(v.number()),
+        completionTokens: v.optional(v.number()),
+        // subset of promptTokens served from the provider's prompt cache (cheaper).
+        cachedTokens: v.optional(v.number()),
+        costNanos: v.optional(v.number()),
+        latencyMs: v.optional(v.number()),
+        rerunOf: v.optional(v.id("requests")),
+    })
+        .index("userId", ["userId"])
+        .index("status", ["status"])
+        .index("rerunOf", ["rerunOf"])
+        .index("actionName", ["actionName"])
+        .index("settled", ["settled"]),
+    // per-model price overrides (nanodollars per million tokens)
+    prices: defineTable({
+        model: v.string(),
+        inputNanosPerMTok: v.number(),
+        outputNanosPerMTok: v.number(),
+    }).index("model", ["model"]),
+    // singleton component config (key === "singleton")
+    settings: defineTable({
+        key: v.string(),
+        // "open": any model allowed. "allowlist": only listed models.
+        // "denylist": any model except the listed ones.
+        modelMode: v.optional(v.union(v.literal("open"), v.literal("allowlist"), v.literal("denylist"))),
+        models: v.optional(v.array(v.string())),
+        // Deployment-wide ("global") spend cap across ALL users and actions. The
+        // running totals live in a sharded counter (high write throughput); only
+        // the limit config lives here. The cap is enforced approximately — the
+        // sharded total is read without a reservation, so under heavy concurrency
+        // it can overshoot by a bounded amount. Right for a global killswitch;
+        // per-user/per-action caps stay exact via reserve/settle.
+        globalDailySpendLimitNanos: v.optional(v.number()),
+        globalLifetimeSpendLimitNanos: v.optional(v.number()),
+        globalEnforcement: v.optional(v.union(v.literal("hard"), v.literal("soft"))),
+        globalDailyBumpNanos: v.optional(v.number()),
+        globalLifetimeBumpNanos: v.optional(v.number()),
+        globalBumpDayStamp: v.optional(v.string()),
+        // request-row retention window in ms (default 1h); 0 disables sweeping.
+        retentionMs: v.optional(v.number()),
+    }).index("key", ["key"]),
+});

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@convex-dev/ai-budget",
+  "description": "Metered, budget-governed AI Gateway usage for Convex: cost & usage tracking, per-user/per-action/global spend/token/rate limits, request logging, re-run, and an Agent-component adapter.",
+  "repository": "github:get-convex/ai-budget",
+  "homepage": "https://github.com/get-convex/ai-budget#readme",
+  "bugs": {
+    "email": "support@convex.dev",
+    "url": "https://github.com/get-convex/ai-budget/issues"
+  },
+  "version": "0.0.2-alpha.0",
+  "license": "Apache-2.0",
+  "type": "module",
+  "keywords": [
+    "convex",
+    "convex-component",
+    "ai-gateway",
+    "llm",
+    "usage",
+    "cost",
+    "budget",
+    "rate-limit"
+  ],
+  "scripts": {
+    "build": "tsc --project ./tsconfig.build.json",
+    "build:codegen": "convex codegen --component-dir ./src/component && npm run build",
+    "build:clean": "rm -rf dist *.tsbuildinfo && npm run build:codegen",
+    "typecheck": "tsc --noEmit --project ./tsconfig.build.json && tsc --noEmit -p example",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepack": "npm run build",
+    "alpha": "npm version prerelease --preid alpha && git push --follow-tags",
+    "release": "npm version patch && git push --follow-tags"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/client/index.d.ts",
+      "default": "./dist/client/index.js"
+    },
+    "./convex.config": {
+      "types": "./dist/component/convex.config.d.ts",
+      "default": "./dist/component/convex.config.js"
+    },
+    "./convex.config.js": {
+      "types": "./dist/component/convex.config.d.ts",
+      "default": "./dist/component/convex.config.js"
+    },
+    "./_generated/component.js": {
+      "types": "./dist/component/_generated/component.d.ts"
+    }
+  },
+  "types": "./dist/client/index.d.ts",
+  "module": "./dist/client/index.js",
+  "dependencies": {
+    "@convex-dev/sharded-counter": "^0.2.1"
+  },
+  "peerDependencies": {
+    "@convex-dev/ai-sdk-provider": "*",
+    "ai": "^5.0.0 || ^6.0.0 || ^7.0.0",
+    "convex": "^1.45.0"
+  },
+  "devDependencies": {
+    "@edge-runtime/vm": "^5.0.0",
+    "convex": "^1.45.0",
+    "convex-test": "^0.0.38",
+    "typescript": "^5.7.0",
+    "vitest": "^4.0.0"
+  }
+}