Skip to content

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

fix(fireclaw): gate credits via Autumn instead of ACUC remaining_credits (#3903)

firecrawl-spring[bot]d9b5cd9f7b6f
diff --git a/apps/api/src/__tests__/controllers/fireclaw.test.ts b/apps/api/src/__tests__/controllers/fireclaw.test.ts
new file mode 100644
index 000000000..4d5642511
--- /dev/null
+++ b/apps/api/src/__tests__/controllers/fireclaw.test.ts
@@ -0,0 +1,140 @@
+import type { MockedFunction } from "vitest";
+
+vi.mock("../../services/autumn/autumn.service", () => ({
+ autumnService: {
+ checkCredits: vi.fn(),
+ },
+ CREDITS_FEATURE_ID: "CREDITS",
+}));
+
+vi.mock("../../services/autumn/usage", () => ({
+ getTeamBalance: vi.fn(),
+}));
+
+vi.mock("../../services/billing/credit_billing", () => ({
+ billTeam: vi.fn(),
+}));
+
+vi.mock("../../controllers/auth", () => ({
+ getACUCTeam: vi.fn(),
+}));
+
+vi.mock("../../lib/logger", () => ({
+ logger: { error: vi.fn(), warn: vi.fn(), info: vi.fn(), debug: vi.fn() },
+}));
+
+import { fireclawController } from "../../controllers/v1/fireclaw";
+import { autumnService } from "../../services/autumn/autumn.service";
+import { getTeamBalance } from "../../services/autumn/usage";
+import { billTeam } from "../../services/billing/credit_billing";
+
+const checkCreditsMock = autumnService.checkCredits as MockedFunction<
+ typeof autumnService.checkCredits
+>;
+const getTeamBalanceMock = getTeamBalance as MockedFunction<
+ typeof getTeamBalance
+>;
+const billTeamMock = billTeam as MockedFunction<typeof billTeam>;
+
+function buildReq(overrides: any = {}): any {
+ return {
+ body: { plays: 1 },
+ auth: { team_id: "team_test", org_id: "org_test" },
+ acuc: { sub_id: "sub_1", api_key_id: 1 },
+ ...overrides,
+ };
+}
+
+function buildRes(): any {
+ const res: any = {
+ statusCode: 200,
+ body: undefined,
+ status: vi.fn((code: number) => {
+ res.statusCode = code;
+ return res;
+ }),
+ json: vi.fn((payload: any) => {
+ res.body = payload;
+ return res;
+ }),
+ };
+ return res;
+}
+
+describe("fireclawController credit gating (Autumn)", () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ getTeamBalanceMock.mockResolvedValue({
+ remaining: 4000,
+ granted: 5000,
+ planCredits: 5000,
+ usage: 1000,
+ unlimited: false,
+ periodStart: null,
+ periodEnd: null,
+ } as any);
+ });
+
+ it("402s when Autumn denies the full multi-play cost", async () => {
+ const req = buildReq({ body: { plays: 10 } }); // 10 * 100 = 1000
+ const res = buildRes();
+ checkCreditsMock.mockResolvedValue({ allowed: false, remaining: 50 });
+
+ await fireclawController(req, res);
+
+ // Checked against the real cost, not a single play
+ expect(checkCreditsMock).toHaveBeenCalledWith(
+ expect.objectContaining({ teamId: "team_test", value: 1000 }),
+ );
+ expect(res.statusCode).toBe(402);
+ expect(res.body.success).toBe(false);
+ expect(res.body.error).toContain("50"); // surfaces Autumn's remaining
+ expect(billTeamMock).not.toHaveBeenCalled();
+ });
+
+ it("bills and returns the Autumn balance when allowed", async () => {
+ const req = buildReq({ body: { plays: 2 } }); // 2 * 100 = 200
+ const res = buildRes();
+ checkCreditsMock.mockResolvedValue({ allowed: true, remaining: 5000 });
+
+ await fireclawController(req, res);
+
+ expect(checkCreditsMock).toHaveBeenCalledWith(
+ expect.objectContaining({ value: 200 }),
+ );
+ expect(billTeamMock).toHaveBeenCalledWith(
+ "team_test",
+ "sub_1",
+ 200,
+ 1,
+ expect.objectContaining({ endpoint: "fireclaw" }),
+ );
+ expect(res.statusCode).toBe(200);
+ expect(res.body).toEqual(
+ expect.objectContaining({
+ success: true,
+ credits_billed: 200,
+ plays: 2,
+ remaining_credits: 4000, // from getTeamBalance
+ }),
+ );
+ });
+
+ it("fails open and bills when Autumn is unavailable (checkCredits null)", async () => {
+ const req = buildReq({ body: { plays: 3 } });
+ const res = buildRes();
+ checkCreditsMock.mockResolvedValue(null);
+
+ await fireclawController(req, res);
+
+ expect(billTeamMock).toHaveBeenCalledWith(
+ "team_test",
+ "sub_1",
+ 300,
+ 1,
+ expect.objectContaining({ endpoint: "fireclaw" }),
+ );
+ expect(res.statusCode).toBe(200);
+ expect(res.body.success).toBe(true);
+ });
+});
diff --git a/apps/api/src/controllers/v1/fireclaw.ts b/apps/api/src/controllers/v1/fireclaw.ts
index 25fd50de1..46b9f4a7c 100644
--- a/apps/api/src/controllers/v1/fireclaw.ts
+++ b/apps/api/src/controllers/v1/fireclaw.ts
@@ -4,6 +4,8 @@ import { billTeam } from "../../services/billing/credit_billing";
import { getACUCTeam } from "../auth";
import { RateLimiterMode } from "../../types";
import { logger } from "../../lib/logger";
+import { autumnService } from "../../services/autumn/autumn.service";
+import { getTeamBalance } from "../../services/autumn/usage";
const FIRECLAW_COST_PER_PLAY = 100;
const MAX_PLAYS = 10;
@@ -24,7 +26,10 @@ export async function fireclawController(
req: RequestWithAuth<{}, undefined, { plays?: number }>,
res: Response<FireclawResponse | FireclawErrorResponse>,
): Promise<void> {
- const plays = Math.max(1, Math.min(MAX_PLAYS, Math.floor(Number(req.body?.plays) || 1)));
+ const plays = Math.max(
+ 1,
+ Math.min(MAX_PLAYS, Math.floor(Number(req.body?.plays) || 1)),
+ );
const totalCredits = plays * FIRECLAW_COST_PER_PLAY;
const chunk =
@@ -32,14 +37,28 @@ export async function fireclawController(
(await getACUCTeam(req.auth.team_id, false, false, RateLimiterMode.Scrape));
if (!chunk) {
- res.status(404).json({ success: false, error: "Could not find team billing information." });
+ res.status(404).json({
+ success: false,
+ error: "Could not find team billing information.",
+ });
return;
}
- if (chunk.remaining_credits < totalCredits) {
+ // Autumn is the source of truth for credits. The route-level
+ // checkCreditsMiddleware only verifies a single play's worth (100), so the
+ // full multi-play cost is checked here. Fail open on an Autumn outage
+ // (checkCredits returns null), matching checkCreditsMiddleware — don't turn an
+ // Autumn outage into a customer outage.
+ const creditCheck = await autumnService.checkCredits({
+ teamId: req.auth.team_id,
+ value: totalCredits,
+ properties: { source: "fireclaw" },
+ });
+
+ if (creditCheck !== null && !creditCheck.allowed) {
res.status(402).json({
success: false,
- error: `Not enough credits. You need ${totalCredits} credits (${plays} play${plays > 1 ? "s" : ""} x ${FIRECLAW_COST_PER_PLAY}) but only have ${chunk.remaining_credits}.`,
+ error: `Not enough credits. You need ${totalCredits} credits (${plays} play${plays > 1 ? "s" : ""} x ${FIRECLAW_COST_PER_PLAY}) but only have ${creditCheck.remaining}.`,
});
return;
}
@@ -53,17 +72,37 @@ export async function fireclawController(
{ endpoint: "fireclaw" },
);
} catch (error) {
- logger.error(`Fireclaw billing failed for team ${req.auth.team_id}`, { error });
- res.status(500).json({ success: false, error: "Failed to process billing. Please try again." });
+ logger.error(`Fireclaw billing failed for team ${req.auth.team_id}`, {
+ error,
+ });
+ res.status(500).json({
+ success: false,
+ error: "Failed to process billing. Please try again.",
+ });
return;
}
- const updatedChunk = await getACUCTeam(req.auth.team_id, false, false, RateLimiterMode.Scrape);
+ // Report the post-bill balance from Autumn (the source of truth). Best-effort:
+ // on failure, estimate from the pre-bill credit check minus this charge.
+ let remainingCredits: number;
+ try {
+ const balance = await getTeamBalance(req.auth.team_id);
+ remainingCredits = balance?.remaining ?? 0;
+ } catch (error) {
+ logger.warn("Failed to fetch Autumn balance for fireclaw response", {
+ error,
+ teamId: req.auth.team_id,
+ });
+ remainingCredits = Math.max(
+ 0,
+ (creditCheck?.remaining ?? totalCredits) - totalCredits,
+ );
+ }
res.json({
success: true,
credits_billed: totalCredits,
plays,
- remaining_credits: updatedChunk?.remaining_credits ?? chunk.remaining_credits - totalCredits,
+ remaining_credits: remainingCredits,
});
}