Skip to content

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

Route Autumn usage through firebill for allowlisted orgs

Rakshith Ramprakashaff12e20b1e0
diff --git a/apps/api/src/config.ts b/apps/api/src/config.ts
index 8998cfd6d..e03c4d4f5 100644
--- a/apps/api/src/config.ts
+++ b/apps/api/src/config.ts
@@ -378,6 +378,13 @@ const configSchema = z.object({
// Billing
AUTO_RECHARGE_ENABLED: z.stringbool().default(false),
+ // firebill β€” durable usage-event store that sits in front of Autumn. When
+ // both URL and SECRET are set, usage tracking for orgs listed in
+ // FIREBILL_ORG_IDS (comma-separated org UUIDs) is routed through firebill
+ // instead of directly to Autumn (gradual rollout).
+ FIREBILL_URL: emptyStringAsUndefined(z.string().url()),
+ FIREBILL_SECRET: emptyStringAsUndefined(z.string()),
+ FIREBILL_ORG_IDS: delimitedList(",").optional(),
// Miscellaneous
IDMUX_URL: z.string().optional(),
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 9cc8fa67f..0702be9ab 100644
--- a/apps/api/src/services/autumn/__tests__/autumn.service.test.ts
+++ b/apps/api/src/services/autumn/__tests__/autumn.service.test.ts
@@ -75,6 +75,7 @@ const {
data: unknown;
error: unknown;
},
+ configRef: {} as Record<string, unknown>,
},
};
});
@@ -93,7 +94,10 @@ vi.mock("../../../db/connection", () => ({
vi.mock("../../../config", () => ({
// Stubbed so importing the real config (which parses env) is avoided.
- config: {},
+ // A getter so individual tests can swap the config (e.g. firebill routing).
+ get config() {
+ return state.configRef;
+ },
}));
// Import AFTER mocks are wired up.
@@ -124,6 +128,7 @@ beforeEach(() => {
vi.clearAllMocks();
state.autumnClientRef = mockAutumnClient;
state.supabaseStubData = { data: { org_id: "org-1" }, error: null };
+ state.configRef = {};
mockCheck.mockResolvedValue({
allowed: true,
customerId: "org-1",
@@ -666,3 +671,151 @@ describe("entity limits fallback", () => {
expect(await svc.getRateLimitMultiplier("team-1", "org-1")).toBe(10);
});
});
+
+// ---------------------------------------------------------------------------
+// firebill routing (gradual rollout by org allowlist)
+// ---------------------------------------------------------------------------
+
+describe("firebill routing", () => {
+ const mockFetch = vi.fn<(url: any, init?: any) => Promise<Response>>();
+
+ const firebillConfig = () => ({
+ FIREBILL_URL: "http://firebill.test",
+ FIREBILL_SECRET: "fb-secret",
+ FIREBILL_ORG_IDS: ["org-1", "org-2"],
+ });
+
+ const firebillResponse = (success: boolean) =>
+ new Response(JSON.stringify({ success }), { status: 200 });
+
+ beforeEach(() => {
+ mockFetch.mockReset();
+ mockFetch.mockResolvedValue(firebillResponse(true));
+ vi.stubGlobal("fetch", mockFetch);
+ });
+
+ afterEach(() => {
+ vi.unstubAllGlobals();
+ });
+
+ it("routes trackCredits for an allowlisted org to firebill, not Autumn", async () => {
+ state.configRef = firebillConfig();
+ const svc = makeService();
+
+ const result = await svc.trackCredits({
+ teamId: "team-1",
+ value: 42,
+ properties: { source: "test", endpoint: "extract" },
+ });
+
+ expect(result).toBe(true);
+ expect(mockTrack).not.toHaveBeenCalled();
+ expect(mockFetch).toHaveBeenCalledTimes(1);
+
+ const [url, init] = mockFetch.mock.calls[0];
+ expect(String(url)).toBe("http://firebill.test/v1/track");
+ expect(init.headers.authorization).toBe("Bearer fb-secret");
+ expect(init.headers["content-type"]).toBe("application/json");
+ expect(JSON.parse(init.body)).toEqual({
+ customer_id: "org-1",
+ entity_id: "team-1",
+ feature_id: "CREDITS",
+ value: 42,
+ properties: { source: "test", endpoint: "extract" },
+ });
+ });
+
+ it("routes refundCredits to /v1/refund with the POSITIVE value", async () => {
+ state.configRef = firebillConfig();
+ const svc = makeService();
+
+ await svc.refundCredits({
+ teamId: "team-1",
+ value: 30,
+ properties: { endpoint: "extract" },
+ });
+
+ expect(mockTrack).not.toHaveBeenCalled();
+ expect(mockFetch).toHaveBeenCalledTimes(1);
+
+ const [url, init] = mockFetch.mock.calls[0];
+ expect(String(url)).toBe("http://firebill.test/v1/refund");
+ const body = JSON.parse(init.body);
+ // firebill negates refunds itself β€” the value must NOT be pre-negated.
+ expect(body.value).toBe(30);
+ expect(body.properties.source).toBe("autumn_refund");
+ expect(body.properties.endpoint).toBe("extract");
+ });
+
+ it("uses the direct Autumn path for orgs NOT on the allowlist", async () => {
+ state.configRef = {
+ ...firebillConfig(),
+ FIREBILL_ORG_IDS: ["some-other-org"],
+ };
+ const svc = makeService();
+
+ const result = await svc.trackCredits({ teamId: "team-1", value: 42 });
+
+ expect(result).toBe(true);
+ expect(mockFetch).not.toHaveBeenCalled();
+ expect(mockTrack).toHaveBeenCalledTimes(1);
+ });
+
+ it("uses the direct Autumn path when FIREBILL_SECRET is missing", async () => {
+ state.configRef = { ...firebillConfig(), FIREBILL_SECRET: undefined };
+ const svc = makeService();
+
+ await svc.trackCredits({ teamId: "team-1", value: 42 });
+
+ expect(mockFetch).not.toHaveBeenCalled();
+ expect(mockTrack).toHaveBeenCalledTimes(1);
+ });
+
+ it("trims whitespace and ignores empty entries in FIREBILL_ORG_IDS", async () => {
+ state.configRef = {
+ ...firebillConfig(),
+ FIREBILL_ORG_IDS: [" org-1 ", "", " "],
+ };
+ const svc = makeService();
+
+ await svc.trackCredits({ teamId: "team-1", value: 1 });
+
+ expect(mockFetch).toHaveBeenCalledTimes(1);
+ expect(mockTrack).not.toHaveBeenCalled();
+ });
+
+ it("returns false when firebill responds success:false β€” no Autumn fallback", async () => {
+ state.configRef = firebillConfig();
+ mockFetch.mockResolvedValue(firebillResponse(false));
+ const svc = makeService();
+
+ const result = await svc.trackCredits({ teamId: "team-1", value: 42 });
+
+ expect(result).toBe(false);
+ // CRITICAL: firebill may have durably recorded the event; falling back to
+ // Autumn here would double-bill the customer.
+ expect(mockTrack).not.toHaveBeenCalled();
+ });
+
+ it("returns false when firebill errors (timeout / refused) β€” no Autumn fallback", async () => {
+ state.configRef = firebillConfig();
+ mockFetch.mockRejectedValue(new Error("ECONNREFUSED"));
+ const svc = makeService();
+
+ const result = await svc.trackCredits({ teamId: "team-1", value: 42 });
+
+ expect(result).toBe(false);
+ expect(mockTrack).not.toHaveBeenCalled();
+ });
+
+ it("returns false on a non-200 firebill response β€” no Autumn fallback", async () => {
+ state.configRef = firebillConfig();
+ mockFetch.mockResolvedValue(new Response("unauthorized", { status: 401 }));
+ const svc = makeService();
+
+ const result = await svc.trackCredits({ teamId: "team-1", value: 42 });
+
+ expect(result).toBe(false);
+ expect(mockTrack).not.toHaveBeenCalled();
+ });
+});
diff --git a/apps/api/src/services/autumn/autumn.service.ts b/apps/api/src/services/autumn/autumn.service.ts
index 12df559f3..605f80b07 100644
--- a/apps/api/src/services/autumn/autumn.service.ts
+++ b/apps/api/src/services/autumn/autumn.service.ts
@@ -4,6 +4,7 @@ import { eq } from "drizzle-orm";
import { dbRr } from "../../db/connection";
import * as schema from "../../db/schema";
import { autumnClient } from "./client";
+import { firebillTrack, shouldRouteToFirebill } from "./firebill";
import type {
CreateEntityParams,
CreateEntityResult,
@@ -215,6 +216,22 @@ export class AutumnService {
value,
properties,
}: TrackParams): Promise<boolean> {
+ // Gradual firebill rollout: allowlisted orgs record usage via firebill (a
+ // durable store that forwards to Autumn) instead of calling Autumn
+ // directly. If the firebill call fails we must NOT fall back to Autumn β€”
+ // firebill may have durably recorded the event and will deliver it later,
+ // so a direct-Autumn fallback could double-bill the customer. firebillTrack
+ // returns false on failure, exactly like an Autumn track failure.
+ if (shouldRouteToFirebill(customerId)) {
+ return await firebillTrack({
+ customerId,
+ entityId,
+ featureId,
+ value,
+ properties,
+ });
+ }
+
if (!autumnClient) return false;
try {
diff --git a/apps/api/src/services/autumn/firebill.ts b/apps/api/src/services/autumn/firebill.ts
new file mode 100644
index 000000000..0ab167d54
--- /dev/null
+++ b/apps/api/src/services/autumn/firebill.ts
@@ -0,0 +1,123 @@
+import { config } from "../../config";
+import { logger } from "../../lib/logger";
+import type { TrackParams } from "./types";
+
+// firebill's own internal budget (durable write + forward attempt) is up to
+// ~3.5s worst case, so this is deliberately looser than the 2s timeout on the
+// direct Autumn client.
+const FIREBILL_TIMEOUT_MS = 5000;
+
+// FIREBILL_ORG_IDS is decoded once at startup by the config schema; the Set is
+// built lazily on first use and cached, keyed on the decoded array reference.
+let allowlistCache: { source: string[] | undefined; ids: Set<string> } | null =
+ null;
+
+function firebillOrgIds(): Set<string> {
+ const source = config.FIREBILL_ORG_IDS;
+ if (!allowlistCache || allowlistCache.source !== source) {
+ allowlistCache = {
+ source,
+ ids: new Set(
+ (source ?? []).map(id => id.trim()).filter(id => id.length > 0),
+ ),
+ };
+ }
+ return allowlistCache.ids;
+}
+
+/**
+ * Whether usage tracking for this org should be routed through firebill
+ * instead of directly to Autumn. Requires firebill to be fully configured AND
+ * the org to be on the rollout allowlist.
+ */
+export function shouldRouteToFirebill(orgId: string): boolean {
+ if (!config.FIREBILL_URL || !config.FIREBILL_SECRET) return false;
+ return firebillOrgIds().has(orgId);
+}
+
+/**
+ * Sends a usage event to firebill, which records it durably in Postgres and
+ * forwards it to Autumn (replaying failed deliveries instead of losing them).
+ *
+ * A negative value is a refund (refundCredits negates before calling track);
+ * firebill's /v1/refund endpoint expects the POSITIVE amount and negates it
+ * itself, so the absolute value is sent either way.
+ *
+ * Returns true when firebill accepted the event, mirroring the boolean
+ * contract of the direct Autumn track path. A `false` here means "not billed
+ * yet" β€” firebill keeps retrying delivery on its side.
+ */
+export async function firebillTrack({
+ customerId,
+ entityId,
+ featureId,
+ value,
+ properties,
+}: TrackParams): Promise<boolean> {
+ const path = value < 0 ? "/v1/refund" : "/v1/track";
+ try {
+ const response = await fetch(new URL(path, config.FIREBILL_URL), {
+ method: "POST",
+ headers: {
+ authorization: `Bearer ${config.FIREBILL_SECRET}`,
+ "content-type": "application/json",
+ },
+ body: JSON.stringify({
+ customer_id: customerId,
+ entity_id: entityId,
+ feature_id: featureId,
+ value: Math.abs(value),
+ properties,
+ }),
+ signal: AbortSignal.timeout(FIREBILL_TIMEOUT_MS),
+ });
+
+ if (!response.ok) {
+ logger.error("firebill track failed β€” non-OK response", {
+ customerId,
+ entityId,
+ featureId,
+ value,
+ path,
+ status: response.status,
+ });
+ return false;
+ }
+
+ const body = (await response.json()) as { success?: boolean };
+ if (body.success !== true) {
+ logger.error("firebill track did not succeed", {
+ customerId,
+ entityId,
+ featureId,
+ value,
+ path,
+ });
+ return false;
+ }
+
+ logger.info("firebill track succeeded", {
+ customerId,
+ entityId,
+ featureId,
+ value,
+ path,
+ });
+ return true;
+ } catch (error) {
+ // DO NOT fall back to calling Autumn directly here: firebill may have
+ // durably recorded the event before this call failed and will deliver it
+ // to Autumn later, so a direct-Autumn fallback could double-bill the
+ // customer. A firebill failure (timeout, 5xx, connection refused) is
+ // treated exactly like an Autumn track failure: log and return false.
+ logger.error("firebill track failed β€” firebill may be unavailable", {
+ customerId,
+ entityId,
+ featureId,
+ value,
+ path,
+ error,
+ });
+ return false;
+ }
+}