Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥

fix(api): free monitor usage (#3742)

tomsideguide47cb0092a7ec
diff --git a/apps/api/src/services/autumn/__tests__/autumn.service.test.ts b/apps/api/src/services/autumn/__tests__/autumn.service.test.ts
index 70f66aeec..3fde9bd82 100644
--- a/apps/api/src/services/autumn/__tests__/autumn.service.test.ts
+++ b/apps/api/src/services/autumn/__tests__/autumn.service.test.ts
@@ -280,21 +280,21 @@ describe("ensureTrackingContext warm-cache short-circuit", () => {
// ---------------------------------------------------------------------------
describe("lockCredits", () => {
- it("returns null when autumnClient is null", async () => {
+ it("returns skipped when autumnClient is null", async () => {
autumnClientRef = null;
const svc = makeService();
const result = await svc.lockCredits({ teamId: "team-1", value: 10 });
- expect(result).toBeNull();
+ expect(result).toEqual({ status: "skipped" });
expect(mockCheck).not.toHaveBeenCalled();
});
- it("returns null for preview teams", async () => {
+ it("returns skipped for preview teams", async () => {
const svc = makeService();
const result = await svc.lockCredits({
teamId: "preview_abc",
value: 10,
});
- expect(result).toBeNull();
+ expect(result).toEqual({ status: "skipped" });
expect(mockCheck).not.toHaveBeenCalled();
});
@@ -308,7 +308,7 @@ describe("lockCredits", () => {
properties: { source: "billTeam", endpoint: "extract" },
});
- expect(result).toBe("lock-123");
+ expect(result).toEqual({ status: "locked", lockId: "lock-123" });
expect(mockCheck).toHaveBeenCalledWith(
expect.objectContaining({
customerId: "org-1",
@@ -324,7 +324,7 @@ describe("lockCredits", () => {
);
});
- it("returns null when Autumn denies the lock", async () => {
+ it("returns denied when Autumn denies the lock", async () => {
mockCheck.mockResolvedValue({
allowed: false,
customerId: "org-1",
@@ -336,7 +336,18 @@ describe("lockCredits", () => {
value: 10,
lockId: "lock-123",
});
- expect(result).toBeNull();
+ expect(result).toEqual({ status: "denied" });
+ });
+
+ it("returns skipped when the billing API throws (fallback)", async () => {
+ mockCheck.mockRejectedValue(new Error("autumn down"));
+ const svc = makeService();
+ const result = await svc.lockCredits({
+ teamId: "team-1",
+ value: 10,
+ lockId: "lock-123",
+ });
+ expect(result).toEqual({ status: "skipped" });
});
});
diff --git a/apps/api/src/services/autumn/autumn.service.ts b/apps/api/src/services/autumn/autumn.service.ts
index 15d49728a..54d1e51a0 100644
--- a/apps/api/src/services/autumn/autumn.service.ts
+++ b/apps/api/src/services/autumn/autumn.service.ts
@@ -14,6 +14,7 @@ import type {
GetEntityParams,
GetOrCreateCustomerParams,
LockCreditsParams,
+ LockCreditsResult,
TrackCreditsParams,
TrackParams,
} from "./types";
@@ -397,8 +398,7 @@ export class AutumnService {
}
/**
- * Reserves a team's credits in Autumn without letting Autumn gate usage.
- * Returns the lock ID on success, or null if no lock was acquired.
+ * Attempts to reserve a team's credits in Autumn. See {@link LockCreditsResult}.
*/
async lockCredits({
teamId,
@@ -407,9 +407,9 @@ export class AutumnService {
expiresAt,
properties,
featureId = CREDITS_FEATURE_ID,
- }: LockCreditsParams): Promise<string | null> {
+ }: LockCreditsParams): Promise<LockCreditsResult> {
if (!autumnClient || this.isPreviewTeam(teamId)) {
- return null;
+ return { status: "skipped" };
}
const resolvedLockId = lockId ?? `billing_${randomUUID()}`;
@@ -434,7 +434,7 @@ export class AutumnService {
value,
lockId: resolvedLockId,
});
- return null;
+ return { status: "denied" };
}
logger.info("Autumn lockCredits succeeded", {
@@ -445,7 +445,7 @@ export class AutumnService {
lockId: resolvedLockId,
properties,
});
- return resolvedLockId;
+ return { status: "locked", lockId: resolvedLockId };
} catch (error) {
logger.error(
"Autumn lockCredits failed — billing API may be unavailable, falling back",
@@ -456,7 +456,7 @@ export class AutumnService {
error,
},
);
- return null;
+ return { status: "skipped" };
}
}
diff --git a/apps/api/src/services/autumn/types.ts b/apps/api/src/services/autumn/types.ts
index 1d75874e7..bd7c8e78a 100644
--- a/apps/api/src/services/autumn/types.ts
+++ b/apps/api/src/services/autumn/types.ts
@@ -46,6 +46,19 @@ export type LockCreditsParams = {
featureId?: string;
};
+/**
+ * Outcome of an Autumn credit lock attempt.
+ *
+ * - `denied`: Autumn refused (`allowed: false`); the caller must NOT proceed.
+ * - `skipped`: billing not in effect (no client, preview team, or API fallback);
+ * the caller should proceed without a lock.
+ * - `locked`: reserved; `lockId` must be finalized later.
+ */
+export type LockCreditsResult =
+ | { status: "locked"; lockId: string }
+ | { status: "denied" }
+ | { status: "skipped" };
+
export type FinalizeCreditsLockParams = {
lockId: string;
action: "confirm" | "release";
diff --git a/apps/api/src/services/monitoring/runner.ts b/apps/api/src/services/monitoring/runner.ts
index 58354e9fa..b3148f4dc 100644
--- a/apps/api/src/services/monitoring/runner.ts
+++ b/apps/api/src/services/monitoring/runner.ts
@@ -65,11 +65,14 @@ export { isMonitorCheckStale, MONITOR_CHECK_STALE_TIMEOUT_MS };
const MONITOR_NOTIFY_CLAIM_TTL_SECONDS = 7 * 24 * 60 * 60;
const MONITOR_CHECK_PAGE_SCAN_LIMIT = 100_000;
+const MONITOR_CHECK_NO_CREDITS_ERROR =
+ "Monitor check skipped: insufficient credits.";
const TERMINAL_CHECK_STATUSES = new Set([
"completed",
"partial",
"failed",
"skipped_overlap",
+ "skipped_no_credits",
]);
async function claimMonitorNotification(checkId: string): Promise<boolean> {
@@ -943,7 +946,7 @@ export async function processMonitorCheckJob(
let lockId: string | null = null;
try {
- lockId = await autumnService.lockCredits({
+ const lock = await autumnService.lockCredits({
teamId: monitor.team_id,
value: check.estimated_credits ?? 1,
lockId: `monitor_${check.id}`,
@@ -955,6 +958,27 @@ export async function processMonitorCheckJob(
},
});
+ if (lock.status === "denied") {
+ check = await updateMonitorCheck(check.id, {
+ status: "skipped_no_credits",
+ finished_at: new Date().toISOString(),
+ actual_credits: 0,
+ billing_status: "not_applicable",
+ error: MONITOR_CHECK_NO_CREDITS_ERROR,
+ });
+
+ await updateMonitorScheduleAfterRun({ monitor, check });
+
+ logger.info("Skipped monitor check: insufficient credits", {
+ monitorId: monitor.id,
+ checkId: check.id,
+ teamId: monitor.team_id,
+ });
+ return;
+ }
+
+ lockId = lock.status === "locked" ? lock.lockId : null;
+
check = await updateMonitorCheck(check.id, {
autumn_lock_id: lockId,
reserved_credits: lockId ? (check.estimated_credits ?? 1) : null,
diff --git a/apps/api/src/services/monitoring/types.ts b/apps/api/src/services/monitoring/types.ts
index 4f3d33c35..75f0e8957 100644
--- a/apps/api/src/services/monitoring/types.ts
+++ b/apps/api/src/services/monitoring/types.ts
@@ -147,6 +147,7 @@ export const listMonitorChecksQuerySchema = z.object({
"failed",
"partial",
"skipped_overlap",
+ "skipped_no_credits",
])
.optional(),
});
@@ -200,7 +201,8 @@ export type MonitorCheckRow = {
| "completed"
| "failed"
| "partial"
- | "skipped_overlap";
+ | "skipped_overlap"
+ | "skipped_no_credits";
scheduled_for: string | null;
started_at: string | null;
finished_at: string | null;