@agent-native/core 0.152.1 → 0.153.1

package/dist/usage/actions/manage-usage-alert.js

@@ -0,0 +1,48 @@
+import { z } from "zod";
+import { defineAction } from "../../action.js";
+import { dismissUsageAlert, saveUsageAlert, setUsageAlertEnabled, } from "../alerts-store.js";
+const channel = z.enum(["in-app", "email"]);
+export default defineAction({
+    description: "Create or edit an LLM usage alert, enable or disable it, or dismiss the current alert event. Alerts can be scoped to the current user or active organization and filtered to an app.",
+    schema: z.object({
+        operation: z.enum(["save", "set-enabled", "dismiss"]),
+        scope: z.enum(["user", "workspace"]).default("user"),
+        ruleId: z.string().trim().max(200).optional(),
+        appId: z.string().trim().max(200).nullable().optional(),
+        unit: z.enum(["usd", "builder-credits", "tokens"]).optional(),
+        period: z.enum(["day", "month"]).optional(),
+        /** Display units: dollars, Builder credits, or raw tokens. */
+        limit: z.number().finite().positive().max(9_000_000_000_000).optional(),
+        channels: z.array(channel).min(1).optional(),
+        enabled: z.boolean().optional(),
+    }),
+    run: async ({ operation, scope, ruleId, appId, unit, period, limit, channels, enabled }, ctx) => {
+        if (!ctx?.userEmail)
+            throw new Error("Not authenticated.");
+        const access = { ownerEmail: ctx.userEmail, orgId: ctx.orgId };
+        const alertScope = scope;
+        if (operation === "dismiss") {
+            if (!ruleId)
+                throw new Error("ruleId is required to dismiss an alert.");
+            return {
+                dismissed: await dismissUsageAlert(ruleId, alertScope, access),
+            };
+        }
+        if (operation === "set-enabled") {
+            if (!ruleId || enabled === undefined) {
+                throw new Error("ruleId and enabled are required to change an alert.");
+            }
+            return setUsageAlertEnabled(ruleId, alertScope, enabled, access);
+        }
+        return saveUsageAlert({
+            scope: alertScope,
+            ruleId,
+            appId,
+            unit: unit,
+            period: period,
+            limit,
+            channels: channels,
+            enabled,
+        }, access);
+    },
+});

package/dist/usage/alerts-store.d.ts

@@ -0,0 +1,78 @@
+export declare const USAGE_ALERT_DEFAULT_DAILY_USD = 100;
+export declare const USAGE_ALERT_UNIT_SCALE: {
+    readonly usd: 100;
+    readonly "builder-credits": 1;
+    readonly tokens: 1;
+};
+export type UsageAlertScope = "user" | "workspace";
+export type UsageAlertUnit = "usd" | "builder-credits" | "tokens";
+export type UsageAlertPeriod = "day" | "month";
+export type UsageAlertChannel = "in-app" | "email";
+export type UsageAlertStatus = "ok" | "triggered" | "dismissed";
+export interface UsageAlertAccess {
+    ownerEmail: string;
+    orgId?: string | null;
+}
+export interface UsageAlertRule {
+    id: string;
+    appId: string | null;
+    scope: UsageAlertScope;
+    unit: UsageAlertUnit;
+    period: UsageAlertPeriod;
+    limit: number;
+    channels: UsageAlertChannel[];
+    enabled: boolean;
+    isDefault: boolean;
+    status: UsageAlertStatus;
+    current: number;
+    percent: number;
+    windowStart: number;
+    windowEnd: number;
+    dismissedAt: number | null;
+    updatedAt: number;
+}
+export interface UsageAlertEventSummary {
+    status: UsageAlertStatus;
+    current: number;
+    limit: number;
+    percent: number;
+    windowStart: number;
+    windowEnd: number;
+}
+export interface UsageAlertListOptions {
+    scope?: UsageAlertScope;
+    appId?: string | null;
+}
+export interface SaveUsageAlertInput {
+    scope: UsageAlertScope;
+    ruleId?: string;
+    appId?: string | null;
+    unit?: UsageAlertUnit;
+    period?: UsageAlertPeriod;
+    limit?: number;
+    channels?: UsageAlertChannel[];
+    enabled?: boolean;
+}
+export interface UsageAlertMutationResult {
+    rule: UsageAlertRule;
+    rules: UsageAlertRule[];
+    current: UsageAlertEventSummary | null;
+}
+export declare function listUsageAlerts(input: UsageAlertListOptions, access: UsageAlertAccess): Promise<UsageAlertRule[]>;
+export declare function saveUsageAlert(input: SaveUsageAlertInput, access: UsageAlertAccess): Promise<UsageAlertMutationResult>;
+export declare function setUsageAlertEnabled(ruleId: string, scope: UsageAlertScope, enabled: boolean, access: UsageAlertAccess): Promise<UsageAlertMutationResult>;
+export declare function dismissUsageAlert(ruleId: string, scope: UsageAlertScope, access: UsageAlertAccess): Promise<UsageAlertMutationResult>;
+interface UsageAlertEvaluationRecord {
+    ownerEmail: string;
+    app?: string;
+    orgId?: string | null;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    costCentsX100?: number;
+}
+export declare function enqueueUsageAlertEvaluation(record: UsageAlertEvaluationRecord): void;
+export declare function _resetUsageAlertStoreForTests(): void;
+export declare function _waitForUsageAlertEvaluationsForTests(): Promise<void>;
+export {};