Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. π₯
TypeScript aiai-agentsai-crawlerai-scrapingai-searchcrawlerdata-extractionhtml-to-markdownllmmarkdownscraperscrapingweb-crawlerweb-dataweb-data-extractionweb-scraperweb-scrapingweb-searchwebscraping
Route Autumn usage through firebill for allowlisted orgs
Rakshith Ramprakashaff12e20b1e0
diff --git a/apps/api/src/config.ts b/apps/api/src/config.tsindex 8998cfd6d..e03c4d4f5 100644--- a/apps/api/src/config.ts+++ b/apps/api/src/config.ts@@ -378,6 +378,13 @@ const configSchema = z.object({// BillingAUTO_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(),// MiscellaneousIDMUX_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.tsindex 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.tsindex 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.tsnew file mode 100644index 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;+ }+}