captify 0.1.18 → 1.1.0

package/dist/model-budget/model-budget.schemas.js

@@ -0,0 +1,196 @@
+/**
+ * Model Budget module Zod schemas
+ *
+ * Validation schemas for API requests and responses.
+ */
+import { z } from "zod";
+// ============================================================================
+// API Request Schemas
+// ============================================================================
+/**
+ * Budget period type enum for API requests.
+ */
+export const budgetPeriodTypeSchema = z
+    .enum(["monthly", "weekly", "daily", "custom"])
+    .describe("Budget period type");
+/**
+ * Schema for setting/updating budget configuration via API.
+ * Used by PUT /api/llm-providers/:providerId/models/:modelId/budget
+ */
+export const setBudgetConfigBodySchema = z
+    .object({
+    budgetAmount: z
+        .number({ error: "Budget amount is required" })
+        .nonnegative("Budget amount must be non-negative")
+        .describe("Budget limit in USD for the period"),
+    budgetPeriodType: budgetPeriodTypeSchema
+        .default("monthly")
+        .describe("Period type (monthly, weekly, daily, custom)"),
+    budgetPeriodDays: z
+        .number()
+        .int("Budget period must be a whole number")
+        .positive("Budget period must be at least 1 day")
+        .optional()
+        .describe("Custom period length in days (only for custom period type)"),
+    requestsPerMinute: z
+        .number({ error: "Requests per minute is required" })
+        .int("Requests per minute must be a whole number")
+        .nonnegative("Requests per minute must be non-negative")
+        .describe("Maximum requests per minute (0 = unlimited)"),
+    tokenLimit: z
+        .number()
+        .int("Token limit must be a whole number")
+        .nonnegative("Token limit must be non-negative")
+        .nullish()
+        .describe("Optional token limit for the period"),
+    isEnabled: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe("Whether budget limits are actively enforced"),
+})
+    .refine((data) => data.budgetPeriodType !== "custom" || data.budgetPeriodDays != null, {
+    message: "budgetPeriodDays is required for custom budgetPeriodType",
+    path: ["budgetPeriodDays"],
+});
+/**
+ * Schema for a single model identifier in batch requests.
+ */
+export const modelIdentifierSchema = z.object({
+    providerId: z.string({ error: "providerId is required" }).min(1, "providerId cannot be empty"),
+    modelId: z.string({ error: "modelId is required" }).min(1, "modelId cannot be empty"),
+});
+/**
+ * Schema for batch usage request body.
+ * Used by POST /api/llm-providers/usage/batch
+ */
+export const batchUsageBodySchema = z.object({
+    models: z
+        .array(modelIdentifierSchema, {
+        error: "models array is required",
+    })
+        .min(1, "models array cannot be empty"),
+});
+// ============================================================================
+// API Response Schemas
+// ============================================================================
+/**
+ * Schema for budget usage in API responses.
+ */
+export const budgetUsageSchema = z.object({
+    limit: z.number().describe("Budget limit in USD"),
+    spent: z.number().describe("Amount spent in current period"),
+    remaining: z.number().describe("Remaining budget"),
+    periodStart: z.string().describe("Period start date (ISO string)"),
+    periodEnd: z.string().describe("Period end date (ISO string)"),
+    requestCount: z.number().optional().describe("Total requests in the period"),
+});
+/**
+ * Schema for token usage in API responses.
+ */
+export const tokenUsageSchema = z.object({
+    limit: z.number().describe("Token limit for the period"),
+    used: z.number().describe("Tokens used in current period"),
+    remaining: z.number().describe("Remaining tokens"),
+});
+/**
+ * Schema for rate limit info in API responses.
+ */
+export const rateLimitInfoSchema = z.object({
+    limit: z.number().describe("Requests per minute limit"),
+    currentMinuteCount: z.number().describe("Requests in current minute"),
+    resetsIn: z.number().describe("Seconds until rate limit resets"),
+});
+/**
+ * Schema for complete model usage response.
+ * Used by GET /api/llm-providers/:providerId/models/:modelId/usage
+ */
+export const modelUsageResponseSchema = z.object({
+    modelId: z.string().describe("Model identifier"),
+    providerId: z.string().describe("Provider UUID"),
+    tenantId: z.string().describe("Tenant ID"),
+    budget: budgetUsageSchema.optional().describe("Budget usage info"),
+    tokenUsage: tokenUsageSchema.optional().describe("Token usage info"),
+    rateLimit: rateLimitInfoSchema.optional().describe("Rate limit info"),
+    hasLimitsConfigured: z.boolean().describe("Whether any limits are configured"),
+});
+// ============================================================================
+// Error Response Schemas
+// ============================================================================
+/**
+ * Schema for budget exceeded error response.
+ */
+export const budgetExceededResponseSchema = z.object({
+    error: z.literal("budget_exceeded"),
+    message: z.string(),
+    details: z.object({
+        modelId: z.string(),
+        providerId: z.string(),
+        spent: z.number(),
+        limit: z.number(),
+        periodEnds: z.string(),
+    }),
+});
+/**
+ * Schema for rate limit exceeded error response.
+ */
+export const rateLimitExceededResponseSchema = z.object({
+    error: z.literal("rate_limit_exceeded"),
+    message: z.string(),
+    details: z.object({
+        modelId: z.string(),
+        providerId: z.string(),
+        current: z.number(),
+        limit: z.number(),
+        retryAfter: z.number(),
+    }),
+    retryAfter: z.number(),
+});
+/**
+ * Schema for token limit exceeded error response.
+ */
+export const tokenLimitExceededResponseSchema = z.object({
+    error: z.literal("token_limit_exceeded"),
+    message: z.string(),
+    details: z.object({
+        modelId: z.string(),
+        providerId: z.string(),
+        used: z.number(),
+        limit: z.number(),
+        periodEnds: z.string(),
+    }),
+});
+// ============================================================================
+// Form Schemas
+// ============================================================================
+/**
+ * Schema for the budget configuration form input.
+ * Used by the BudgetConfigForm component for client-side validation.
+ */
+export const budgetConfigFormSchema = z
+    .object({
+    budgetAmount: z
+        .number({ error: "Budget amount is required" })
+        .nonnegative("Budget amount must be non-negative"),
+    budgetPeriodType: budgetPeriodTypeSchema,
+    budgetPeriodDays: z
+        .number()
+        .int("Period must be a whole number")
+        .positive("Period must be at least 1 day")
+        .optional(),
+    requestsPerMinute: z
+        .number({ error: "Requests per minute is required" })
+        .int("Must be a whole number")
+        .nonnegative("Must be non-negative"),
+    tokenLimit: z
+        .number({ error: "Token limit must be a number" })
+        .int("Must be a whole number")
+        .nonnegative("Must be non-negative")
+        .nullish(),
+    isEnabled: z.boolean(),
+})
+    .refine((data) => data.budgetPeriodType !== "custom" || data.budgetPeriodDays != null, {
+    message: "budgetPeriodDays is required for custom budgetPeriodType",
+    path: ["budgetPeriodDays"],
+});
+//# sourceMappingURL=model-budget.schemas.js.map

package/dist/model-budget/model-budget.schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-budget.schemas.js","sourceRoot":"","sources":["../../lib/model-budget/model-budget.schemas.ts"],"names":[],"mappings":"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"}

package/dist/model-budget/services/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Model Budget services module
+ *
+ * Services for budget enforcement and usage tracking.
+ */
+export { ModelBudgetService, getModelBudgetService } from "./model-budget.service";
+export { UsageTrackingService, getUsageTrackingService } from "./usage-tracking.service";
+//# sourceMappingURL=index.d.ts.map

package/dist/model-budget/services/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../lib/model-budget/services/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AACnF,OAAO,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/model-budget/services/index.js

@@ -0,0 +1,8 @@
+/**
+ * Model Budget services module
+ *
+ * Services for budget enforcement and usage tracking.
+ */
+export { ModelBudgetService, getModelBudgetService } from "./model-budget.service";
+export { UsageTrackingService, getUsageTrackingService } from "./usage-tracking.service";
+//# sourceMappingURL=index.js.map

package/dist/model-budget/services/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../lib/model-budget/services/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AACnF,OAAO,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/model-budget/services/model-budget.service.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Model Budget Service
+ *
+ * Provides budget and rate limit enforcement for LLM model usage.
+ * Supports per-model spend limits, request rate limits, and optional token quotas.
+ *
+ * Features:
+ * - Budget tracking with auto-reset periods
+ * - Post-increment rate limiting (counts only successful completions)
+ * - Token limit tracking (optional)
+ * - In-memory config caching with 60-second TTL
+ * - Multi-tenant support
+ */
+import { BaseAwsService } from "../../shared/services/base-aws-service";
+import { DynamoDbService } from "../../shared/services/dynamodb";
+import { type Logger } from "../../shared/services/logger";
+import type { ModelUsageTableSchema } from "../../db/schemas";
+import type { LimitCheckResult, ModelBudgetParams, RecordSpendParams, ModelUsageResponse } from "../model-budget.interfaces";
+interface ModelBudgetServiceDeps {
+    logger?: Logger;
+    db?: DynamoDbService<ModelUsageTableSchema>;
+}
+export declare class ModelBudgetService extends BaseAwsService {
+    private readonly db;
+    /**
+     * In-memory cache for model budget configurations.
+     * Keyed by `${tenantId}:${providerId}:${modelId}`.
+     */
+    private readonly configCache;
+    constructor(deps?: ModelBudgetServiceDeps);
+    /**
+     * Check if a request is allowed based on budget and rate limits.
+     * This should be called BEFORE making the LLM request.
+     *
+     * @param params - Model identification params
+     * @returns LimitCheckResult indicating if request is allowed
+     *
+     * @example
+     * ```typescript
+     * const result = await budgetService.checkLimits({
+     *   tenantId: "tenant-123",
+     *   providerId: "provider-uuid",
+     *   modelId: "model-uuid",
+     * });
+     *
+     * if (!result.allowed) {
+     *   throw new BudgetExceededError(result.budget);
+     * }
+     * ```
+     */
+    checkLimits(params: ModelBudgetParams): Promise<LimitCheckResult>;
+    /**
+     * Atomically check rate limit and record request.
+     * Uses conditional update to prevent race conditions.
+     *
+     * @param params - Model identification params
+     * @throws RateLimitExceededError if rate limit is exceeded
+     *
+     * @example
+     * ```typescript
+     * // Before making LLM call
+     * await budgetService.recordRequest({
+     *   tenantId: "tenant-123",
+     *   providerId: "provider-uuid",
+     *   modelId: "model-uuid",
+     * });
+     * ```
+     */
+    recordRequest(params: ModelBudgetParams): Promise<void>;
+    /**
+     * Record spend after a request completes.
+     * This should be called AFTER the request completes successfully.
+     *
+     * @param params - Model identification and spend amount
+     *
+     * @example
+     * ```typescript
+     * // In onFinish callback
+     * await budgetService.recordSpend({
+     *   tenantId: "tenant-123",
+     *   providerId: "provider-uuid",
+     *   modelId: "model-uuid",
+     *   amount: 0.0025, // USD
+     *   tokens: 500,    // Optional
+     * });
+     * ```
+     */
+    recordSpend(params: RecordSpendParams): Promise<void>;
+    /**
+     * Get current usage statistics for a model.
+     *
+     * @param params - Model identification params
+     * @returns ModelUsageResponse with budget and rate limit info
+     *
+     * @example
+     * ```typescript
+     * const usage = await budgetService.getUsage({
+     *   tenantId: "tenant-123",
+     *   providerId: "provider-uuid",
+     *   modelId: "model-uuid",
+     * });
+     * console.log(`Spent: $${usage.budget?.spent}`);
+     * ```
+     */
+    getUsage(params: ModelBudgetParams): Promise<ModelUsageResponse>;
+    /**
+     * Get usage for multiple models in a single call.
+     * More efficient than calling getUsage multiple times.
+     *
+     * @param params - Array of model identifiers
+     * @returns Array of usage responses (in same order as input)
+     *
+     * @example
+     * ```typescript
+     * const usages = await budgetService.getBatchUsage([
+     *   { tenantId: "t1", providerId: "p1", modelId: "uuid1" },
+     *   { tenantId: "t1", providerId: "p1", modelId: "uuid2" },
+     * ]);
+     * ```
+     */
+    getBatchUsage(params: ModelBudgetParams[]): Promise<ModelUsageResponse[]>;
+    /**
+     * Clear the config cache for a specific model.
+     * Call this when budget config is updated to ensure immediate effect.
+     */
+    clearConfigCache(params: ModelBudgetParams): void;
+    /**
+     * Clear all cached configs.
+     * Useful for testing or after bulk updates.
+     */
+    clearAllConfigCache(): void;
+    /**
+     * Check budget limit for a model.
+     */
+    private checkBudget;
+    /**
+     * Get budget config from cache or fetch from LLM service.
+     */
+    private getCachedBudgetConfig;
+    /**
+     * Build cache key for model config.
+     */
+    private buildCacheKey;
+}
+/**
+ * Get the singleton ModelBudgetService instance.
+ *
+ * @returns ModelBudgetService instance
+ *
+ * @example
+ * ```typescript
+ * const budgetService = getModelBudgetService();
+ * const result = await budgetService.checkLimits({ tenantId, providerId, modelId });
+ * ```
+ */
+export declare function getModelBudgetService(): ModelBudgetService;
+export {};
+//# sourceMappingURL=model-budget.service.d.ts.map

package/dist/model-budget/services/model-budget.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-budget.service.d.ts","sourceRoot":"","sources":["../../../lib/model-budget/services/model-budget.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC;AACxE,OAAO,EACL,eAAe,EAGhB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAiB,KAAK,MAAM,EAAE,MAAM,8BAA8B,CAAC;AAK1E,OAAO,KAAK,EACV,qBAAqB,EAGtB,MAAM,kBAAkB,CAAC;AAW1B,OAAO,KAAK,EACV,gBAAgB,EAEhB,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAEnB,MAAM,4CAA4C,CAAC;AAMpD,UAAU,sBAAsB;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,EAAE,CAAC,EAAE,eAAe,CAAC,qBAAqB,CAAC,CAAC;CAC7C;AAMD,qBAAa,kBAAmB,SAAQ,cAAc;IACpD,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAyC;IAE5D;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6C;gBAE7D,IAAI,GAAE,sBAA2B;IAS7C;;;;;;;;;;;;;;;;;;;OAmBG;IACG,WAAW,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA2CvE;;;;;;;;;;;;;;;;OAgBG;IACG,aAAa,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IA8F7D;;;;;;;;;;;;;;;;;OAiBG;IACG,WAAW,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAkF3D;;;;;;;;;;;;;;;OAeG;IACG,QAAQ,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA2FtE;;;;;;;;;;;;;;OAcG;IACG,aAAa,CAAC,MAAM,EAAE,iBAAiB,EAAE,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAM/E;;;OAGG;IACH,gBAAgB,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI;IAUjD;;;OAGG;IACH,mBAAmB,IAAI,IAAI;IAK3B;;OAEG;YACW,WAAW;IAuEzB;;OAEG;YACW,qBAAqB;IA+EnC;;OAEG;IACH,OAAO,CAAC,aAAa;CAGtB;AAWD;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,IAAI,kBAAkB,CAU1D"}