Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. πŸ”₯

(feat/interact) Interact Billing (#3222)

Nicolasb5e2c8bc4cc4
diff --git a/apps/api/src/controllers/v2/__tests__/browser-billing.test.ts b/apps/api/src/controllers/v2/__tests__/browser-billing.test.ts
new file mode 100644
index 000000000..db2b07dfb
--- /dev/null
+++ b/apps/api/src/controllers/v2/__tests__/browser-billing.test.ts
@@ -0,0 +1,310 @@
+import { jest } from "@jest/globals";
+
+// ---------------------------------------------------------------------------
+// Mocks β€” must come before imports
+// ---------------------------------------------------------------------------
+
+const mockGetValue = jest.fn<(key: string) => Promise<string | null>>();
+const mockSetValue =
+ jest.fn<(key: string, value: string, ttl: number) => Promise<void>>();
+const mockDeleteKey = jest.fn<(key: string) => Promise<void>>();
+
+jest.mock("../../../services/redis", () => ({
+ getValue: (key: string) => mockGetValue(key),
+ setValue: (key: string, value: string, ttl: number) =>
+ mockSetValue(key, value, ttl),
+ deleteKey: (key: string) => mockDeleteKey(key),
+}));
+
+jest.mock("../../../services/supabase", () => ({
+ supabase_service: {},
+ isPostgrestNoRowsError: jest.fn(() => true),
+}));
+
+jest.mock("../../../lib/logger", () => ({
+ logger: {
+ info: jest.fn(),
+ warn: jest.fn(),
+ error: jest.fn(),
+ child: jest.fn().mockReturnThis(),
+ },
+}));
+
+import {
+ calculateBrowserSessionCredits,
+ BROWSER_CREDITS_PER_HOUR,
+ INTERACT_CREDITS_PER_HOUR,
+} from "../../../lib/browser-billing";
+
+import {
+ markBrowserSessionUsedPrompt,
+ didBrowserSessionUsePrompt,
+ clearBrowserSessionPromptFlag,
+} from "../../../lib/browser-sessions";
+
+// ---------------------------------------------------------------------------
+// Setup
+// ---------------------------------------------------------------------------
+
+beforeEach(() => {
+ jest.clearAllMocks();
+ mockGetValue.mockResolvedValue(null);
+ mockSetValue.mockResolvedValue(undefined);
+ mockDeleteKey.mockResolvedValue(undefined);
+});
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+describe("billing constants", () => {
+ it("browser rate is 120 credits/hour", () => {
+ expect(BROWSER_CREDITS_PER_HOUR).toBe(120);
+ });
+
+ it("interact rate is 420 credits/hour (7 credits/min)", () => {
+ expect(INTERACT_CREDITS_PER_HOUR).toBe(420);
+ });
+});
+
+// ---------------------------------------------------------------------------
+// calculateBrowserSessionCredits
+// ---------------------------------------------------------------------------
+
+describe("calculateBrowserSessionCredits", () => {
+ describe("with default browser rate (120/hr)", () => {
+ it("returns minimum 2 credits for very short sessions", () => {
+ expect(calculateBrowserSessionCredits(0)).toBe(2);
+ expect(calculateBrowserSessionCredits(1000)).toBe(2);
+ expect(calculateBrowserSessionCredits(10_000)).toBe(2);
+ });
+
+ it("calculates correctly for 1 minute", () => {
+ expect(calculateBrowserSessionCredits(60_000)).toBe(2);
+ });
+
+ it("calculates correctly for 5 minutes", () => {
+ expect(calculateBrowserSessionCredits(5 * 60_000)).toBe(10);
+ });
+
+ it("calculates correctly for 10 minutes", () => {
+ expect(calculateBrowserSessionCredits(10 * 60_000)).toBe(20);
+ });
+
+ it("calculates correctly for 1 hour", () => {
+ expect(calculateBrowserSessionCredits(3_600_000)).toBe(120);
+ });
+
+ it("rounds up to next integer", () => {
+ // 61s / 3600s * 120 = 2.033... β†’ ceil = 3
+ expect(calculateBrowserSessionCredits(61_000)).toBe(3);
+ });
+ });
+
+ describe("with interact rate (420/hr)", () => {
+ it("returns minimum 2 credits for very short sessions", () => {
+ expect(calculateBrowserSessionCredits(0, INTERACT_CREDITS_PER_HOUR)).toBe(
+ 2,
+ );
+ expect(
+ calculateBrowserSessionCredits(1000, INTERACT_CREDITS_PER_HOUR),
+ ).toBe(2);
+ });
+
+ it("calculates 7 credits per minute", () => {
+ expect(
+ calculateBrowserSessionCredits(60_000, INTERACT_CREDITS_PER_HOUR),
+ ).toBe(7);
+ });
+
+ it("calculates 35 credits for 5 minutes", () => {
+ expect(
+ calculateBrowserSessionCredits(5 * 60_000, INTERACT_CREDITS_PER_HOUR),
+ ).toBe(35);
+ });
+
+ it("calculates 70 credits for 10 minutes", () => {
+ expect(
+ calculateBrowserSessionCredits(10 * 60_000, INTERACT_CREDITS_PER_HOUR),
+ ).toBe(70);
+ });
+
+ it("calculates 420 credits for 1 hour", () => {
+ expect(
+ calculateBrowserSessionCredits(3_600_000, INTERACT_CREDITS_PER_HOUR),
+ ).toBe(420);
+ });
+
+ it("rounds up to next integer", () => {
+ // 31s / 3600s * 420 = 3.616... β†’ ceil = 4
+ expect(
+ calculateBrowserSessionCredits(31_000, INTERACT_CREDITS_PER_HOUR),
+ ).toBe(4);
+ });
+ });
+
+ describe("rate comparison", () => {
+ it("interact rate is always >= browser rate for same duration", () => {
+ const durations = [0, 1000, 30_000, 60_000, 300_000, 600_000, 3_600_000];
+ for (const ms of durations) {
+ const browserCredits = calculateBrowserSessionCredits(
+ ms,
+ BROWSER_CREDITS_PER_HOUR,
+ );
+ const interactCredits = calculateBrowserSessionCredits(
+ ms,
+ INTERACT_CREDITS_PER_HOUR,
+ );
+ expect(interactCredits).toBeGreaterThanOrEqual(browserCredits);
+ }
+ });
+
+ it("interact rate is 3.5x browser rate for non-trivial durations", () => {
+ const browser = calculateBrowserSessionCredits(
+ 5 * 60_000,
+ BROWSER_CREDITS_PER_HOUR,
+ );
+ const interact = calculateBrowserSessionCredits(
+ 5 * 60_000,
+ INTERACT_CREDITS_PER_HOUR,
+ );
+ expect(interact / browser).toBe(3.5);
+ });
+ });
+});
+
+// ---------------------------------------------------------------------------
+// Prompt flag Redis helpers
+// ---------------------------------------------------------------------------
+
+describe("prompt usage tracking", () => {
+ describe("markBrowserSessionUsedPrompt", () => {
+ it("sets Redis flag with 2-hour TTL", async () => {
+ await markBrowserSessionUsedPrompt("session-123");
+
+ expect(mockSetValue).toHaveBeenCalledWith(
+ "browser_session:used_prompt:session-123",
+ "1",
+ 7200,
+ );
+ });
+
+ it("does not throw on Redis failure", async () => {
+ mockSetValue.mockRejectedValueOnce(new Error("Redis down"));
+
+ await expect(
+ markBrowserSessionUsedPrompt("session-123"),
+ ).resolves.not.toThrow();
+ });
+ });
+
+ describe("didBrowserSessionUsePrompt", () => {
+ it("returns true when flag is set", async () => {
+ mockGetValue.mockResolvedValueOnce("1");
+
+ const result = await didBrowserSessionUsePrompt("session-123");
+ expect(result).toBe(true);
+ expect(mockGetValue).toHaveBeenCalledWith(
+ "browser_session:used_prompt:session-123",
+ );
+ });
+
+ it("returns false when flag is not set", async () => {
+ mockGetValue.mockResolvedValueOnce(null);
+
+ const result = await didBrowserSessionUsePrompt("session-123");
+ expect(result).toBe(false);
+ });
+
+ it("returns false on Redis failure (graceful fallback to browser rate)", async () => {
+ mockGetValue.mockRejectedValueOnce(new Error("Redis down"));
+
+ const result = await didBrowserSessionUsePrompt("session-123");
+ expect(result).toBe(false);
+ });
+ });
+
+ describe("clearBrowserSessionPromptFlag", () => {
+ it("deletes the Redis key", async () => {
+ await clearBrowserSessionPromptFlag("session-123");
+
+ expect(mockDeleteKey).toHaveBeenCalledWith(
+ "browser_session:used_prompt:session-123",
+ );
+ });
+
+ it("does not throw on Redis failure", async () => {
+ mockDeleteKey.mockRejectedValueOnce(new Error("Redis down"));
+
+ await expect(
+ clearBrowserSessionPromptFlag("session-123"),
+ ).resolves.not.toThrow();
+ });
+ });
+});
+
+// ---------------------------------------------------------------------------
+// Billing rate selection (integration of flag + rate)
+// ---------------------------------------------------------------------------
+
+describe("billing rate selection", () => {
+ it("uses 420/hr when prompt flag is set", async () => {
+ mockGetValue.mockResolvedValueOnce("1");
+
+ const usedPrompt = await didBrowserSessionUsePrompt("session-123");
+ const rate = usedPrompt
+ ? INTERACT_CREDITS_PER_HOUR
+ : BROWSER_CREDITS_PER_HOUR;
+ const credits = calculateBrowserSessionCredits(5 * 60_000, rate);
+
+ expect(usedPrompt).toBe(true);
+ expect(rate).toBe(420);
+ expect(credits).toBe(35);
+ });
+
+ it("uses 120/hr when no prompt was used", async () => {
+ mockGetValue.mockResolvedValueOnce(null);
+
+ const usedPrompt = await didBrowserSessionUsePrompt("session-123");
+ const rate = usedPrompt
+ ? INTERACT_CREDITS_PER_HOUR
+ : BROWSER_CREDITS_PER_HOUR;
+ const credits = calculateBrowserSessionCredits(5 * 60_000, rate);
+
+ expect(usedPrompt).toBe(false);
+ expect(rate).toBe(120);
+ expect(credits).toBe(10);
+ });
+
+ it("falls back to 120/hr when Redis is down", async () => {
+ mockGetValue.mockRejectedValueOnce(new Error("Redis down"));
+
+ const usedPrompt = await didBrowserSessionUsePrompt("session-123");
+ const rate = usedPrompt
+ ? INTERACT_CREDITS_PER_HOUR
+ : BROWSER_CREDITS_PER_HOUR;
+ const credits = calculateBrowserSessionCredits(5 * 60_000, rate);
+
+ expect(usedPrompt).toBe(false);
+ expect(rate).toBe(120);
+ expect(credits).toBe(10);
+ });
+
+ it("full flow: mark β†’ check β†’ bill β†’ clear", async () => {
+ await markBrowserSessionUsedPrompt("session-456");
+ expect(mockSetValue).toHaveBeenCalledTimes(1);
+
+ mockGetValue.mockResolvedValueOnce("1");
+ const usedPrompt = await didBrowserSessionUsePrompt("session-456");
+ expect(usedPrompt).toBe(true);
+
+ const credits = calculateBrowserSessionCredits(
+ 3 * 60_000,
+ INTERACT_CREDITS_PER_HOUR,
+ );
+ expect(credits).toBe(21); // 3 min * 7 credits/min
+
+ await clearBrowserSessionPromptFlag("session-456");
+ expect(mockDeleteKey).toHaveBeenCalledTimes(1);
+ });
+});
diff --git a/apps/api/src/controllers/v2/browser.ts b/apps/api/src/controllers/v2/browser.ts
index 1f861fc06..875fafa6a 100644
--- a/apps/api/src/controllers/v2/browser.ts
+++ b/apps/api/src/controllers/v2/browser.ts
@@ -16,23 +16,19 @@ import {
getActiveBrowserSessionCount,
invalidateActiveBrowserSessionCount,
MAX_ACTIVE_BROWSER_SESSIONS_PER_TEAM,
+ didBrowserSessionUsePrompt,
+ clearBrowserSessionPromptFlag,
} from "../../lib/browser-sessions";
import { RequestWithAuth } from "./types";
import { billTeam } from "../../services/billing/credit_billing";
import { enqueueBrowserSessionActivity } from "../../lib/browser-session-activity";
import { logRequest } from "../../services/logging/log_job";
import { integrationSchema } from "../../utils/integration";
-
-const BROWSER_CREDITS_PER_HOUR = 120;
-
-/**
- * Calculate credits to bill for a browser session based on its duration.
- * Prorates to the millisecond. Minimum charge is 2 credits.
- */
-function calculateBrowserSessionCredits(durationMs: number): number {
- const hours = durationMs / 3_600_000;
- return Math.max(2, Math.ceil(hours * BROWSER_CREDITS_PER_HOUR));
-}
+import {
+ BROWSER_CREDITS_PER_HOUR,
+ INTERACT_CREDITS_PER_HOUR,
+ calculateBrowserSessionCredits,
+} from "../../lib/browser-billing";
// ---------------------------------------------------------------------------
// Zod schemas
@@ -558,7 +554,14 @@ export async function browserDeleteController(
sessionDurationMs && sessionDurationMs > 0
? sessionDurationMs
: wallClockMs;
- const creditsBilled = calculateBrowserSessionCredits(durationMs);
+
+ const usedPrompt = await didBrowserSessionUsePrompt(session.id);
+ const rate = usedPrompt
+ ? INTERACT_CREDITS_PER_HOUR
+ : BROWSER_CREDITS_PER_HOUR;
+ const creditsBilled = calculateBrowserSessionCredits(durationMs, rate);
+
+ clearBrowserSessionPromptFlag(session.id).catch(() => {});
updateBrowserSessionCreditsUsed(session.id, creditsBilled).catch(error => {
logger.error("Failed to update credits_used on browser session", {
@@ -573,7 +576,7 @@ export async function browserDeleteController(
req.acuc?.sub_id ?? undefined,
creditsBilled,
req.acuc?.api_key_id ?? null,
- { endpoint: "browser", jobId: session.id },
+ { endpoint: usedPrompt ? "interact" : "browser", jobId: session.id },
).catch(error => {
logger.error("Failed to bill team for browser session", {
error,
@@ -682,7 +685,14 @@ export async function browserWebhookDestroyedController(
}
const durationMs = Date.now() - new Date(session.created_at).getTime();
- const creditsBilled = calculateBrowserSessionCredits(durationMs);
+
+ const usedPrompt = await didBrowserSessionUsePrompt(session.id);
+ const rate = usedPrompt
+ ? INTERACT_CREDITS_PER_HOUR
+ : BROWSER_CREDITS_PER_HOUR;
+ const creditsBilled = calculateBrowserSessionCredits(durationMs, rate);
+
+ clearBrowserSessionPromptFlag(session.id).catch(() => {});
updateBrowserSessionCreditsUsed(session.id, creditsBilled).catch(error => {
logger.error(
@@ -700,7 +710,7 @@ export async function browserWebhookDestroyedController(
undefined, // subscription_id β€” billTeam will look it up
creditsBilled,
null, // api_key_id not available in webhook context
- { endpoint: "browser", jobId: session.id },
+ { endpoint: usedPrompt ? "interact" : "browser", jobId: session.id },
).catch(error => {
logger.error("Failed to bill team for browser session via webhook", {
error,
@@ -716,6 +726,8 @@ export async function browserWebhookDestroyedController(
browserId,
durationMs,
creditsBilled,
+ usedPrompt,
+ rate,
});
return res.status(200).json({ ok: true });
diff --git a/apps/api/src/controllers/v2/scrape-browser.ts b/apps/api/src/controllers/v2/scrape-browser.ts
index 9f6215bee..1af1f9d01 100644
--- a/apps/api/src/controllers/v2/scrape-browser.ts
+++ b/apps/api/src/controllers/v2/scrape-browser.ts
@@ -15,6 +15,9 @@ import {
invalidateActiveBrowserSessionCount,
MAX_ACTIVE_BROWSER_SESSIONS_PER_TEAM,
getBrowserSessionFromScrape,
+ markBrowserSessionUsedPrompt,
+ didBrowserSessionUsePrompt,
+ clearBrowserSessionPromptFlag,
} from "../../lib/browser-sessions";
import {
browserServiceRequest,
@@ -39,18 +42,16 @@ import { enqueueBrowserSessionActivity } from "../../lib/browser-session-activit
import { logRequest } from "../../services/logging/log_job";
import { integrationSchema } from "../../utils/integration";
import { supabaseGetScrapeById } from "../../lib/supabase-jobs";
+import {
+ BROWSER_CREDITS_PER_HOUR,
+ INTERACT_CREDITS_PER_HOUR,
+ calculateBrowserSessionCredits,
+} from "../../lib/browser-billing";
// ---------------------------------------------------------------------------
-// Constants & schemas
+// Schemas
// ---------------------------------------------------------------------------
-const BROWSER_CREDITS_PER_HOUR = 120;
-
-function calculateBrowserSessionCredits(durationMs: number): number {
- const hours = durationMs / 3_600_000;
- return Math.max(2, Math.ceil(hours * BROWSER_CREDITS_PER_HOUR));
-}
-
const browserCreateRequestSchema = z.object({
ttl: z.number().min(30).max(3600).default(600),
activityTtl: z.number().min(10).max(3600).default(300),
@@ -218,6 +219,8 @@ export async function scrapeInteractController(
if (prompt && !rawCode) {
logger.info("Starting agent loop from prompt", { prompt, timeout });
+ markBrowserSessionUsedPrompt(session.id).catch(() => {});
+
try {
execResult = await executePromptViaBrowserAgent(
prompt,
@@ -360,7 +363,14 @@ export async function scrapeStopInteractiveBrowserController(
sessionDurationMs && sessionDurationMs > 0
? sessionDurationMs
: wallClockMs;
- const creditsBilled = calculateBrowserSessionCredits(durationMs);
+
+ const usedPrompt = await didBrowserSessionUsePrompt(session.id);
+ const rate = usedPrompt
+ ? INTERACT_CREDITS_PER_HOUR
+ : BROWSER_CREDITS_PER_HOUR;
+ const creditsBilled = calculateBrowserSessionCredits(durationMs, rate);
+
+ clearBrowserSessionPromptFlag(session.id).catch(() => {});
updateBrowserSessionCreditsUsed(session.id, creditsBilled).catch(error => {
logger.error("Failed to update credits_used on browser session", {
@@ -387,9 +397,15 @@ export async function scrapeStopInteractiveBrowserController(
logger.info("Browser session destroyed", {
sessionDurationMs: durationMs,
creditsBilled,
+ usedPrompt,
+ rate,
});
- return res.status(200).json({ success: true });
+ return res.status(200).json({
+ success: true,
+ sessionDurationMs: durationMs,
+ creditsBilled,
+ });
}
// ---------------------------------------------------------------------------
@@ -434,7 +450,7 @@ async function createSessionForScrape(
activityTtl,
});
- // Credit check
+ // Credit check (uses base rate β€” actual billing may be higher if prompts are used)
const estimatedCredits = calculateBrowserSessionCredits(ttl * 1000);
if (req.acuc && req.acuc.remaining_credits < estimatedCredits) {
return {
diff --git a/apps/api/src/lib/browser-billing.ts b/apps/api/src/lib/browser-billing.ts
new file mode 100644
index 000000000..e0344add0
--- /dev/null
+++ b/apps/api/src/lib/browser-billing.ts
@@ -0,0 +1,10 @@
+export const BROWSER_CREDITS_PER_HOUR = 120;
+export const INTERACT_CREDITS_PER_HOUR = 420;
+
+export function calculateBrowserSessionCredits(
+ durationMs: number,
+ creditsPerHour = BROWSER_CREDITS_PER_HOUR,
+): number {
+ const hours = durationMs / 3_600_000;
+ return Math.max(2, Math.ceil(hours * creditsPerHour));
+}
diff --git a/apps/api/src/lib/browser-sessions.ts b/apps/api/src/lib/browser-sessions.ts
index 911ee78d9..5e5d078d7 100644
--- a/apps/api/src/lib/browser-sessions.ts
+++ b/apps/api/src/lib/browser-sessions.ts
@@ -235,6 +235,47 @@ export async function updateBrowserSessionCreditsUsed(
}
}
+// ---------------------------------------------------------------------------
+// Prompt usage tracking (Redis)
+// ---------------------------------------------------------------------------
+
+const PROMPT_FLAG_TTL_SECONDS = 7200; // 2 hours, well beyond max session TTL
+
+function promptFlagKey(sessionId: string): string {
+ return `browser_session:used_prompt:${sessionId}`;
+}
+
+export async function markBrowserSessionUsedPrompt(
+ sessionId: string,
+): Promise<void> {
+ try {
+ await setValue(promptFlagKey(sessionId), "1", PROMPT_FLAG_TTL_SECONDS);
+ } catch {
+ // Redis down β€” non-fatal, will fall back to standard rate at billing time
+ }
+}
+
+export async function didBrowserSessionUsePrompt(
+ sessionId: string,
+): Promise<boolean> {
+ try {
+ const val = await getValue(promptFlagKey(sessionId));
+ return val === "1";
+ } catch {
+ return false;
+ }
+}
+
+export async function clearBrowserSessionPromptFlag(
+ sessionId: string,
+): Promise<void> {
+ try {
+ await deleteKey(promptFlagKey(sessionId));
+ } catch {
+ // non-fatal
+ }
+}
+
// ---------------------------------------------------------------------------
// Active session count (cached)
// ---------------------------------------------------------------------------