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
refactor(billing): parse firebill responses with Zod schemas (#4551)
Rakshith Ramprakash1cfe7d9dfc50
diff --git a/apps/api/src/services/autumn/__tests__/firebill.test.ts b/apps/api/src/services/autumn/__tests__/firebill.test.tsindex c52442c44..1a3085a30 100644--- a/apps/api/src/services/autumn/__tests__/firebill.test.ts+++ b/apps/api/src/services/autumn/__tests__/firebill.test.ts@@ -1,6 +1,8 @@import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";import {firebillCheck,+ firebillFinalize,+ firebillLock,firebillTrack,shouldRouteToFirebill,} from "../firebill";@@ -663,3 +665,151 @@ describe("firebillCheck", () => {expect(fetchMock).toHaveBeenCalledTimes(1);});});++describe("firebillLock", () => {+ const lockParams = {+ customerId: "org-1",+ entityId: "team-1",+ featureId: "CREDITS",+ value: 10,+ lockId: "monitor_check-1",+ expiresAt: Date.now() + 60_000,+ };++ const answer = (body: unknown, status = 200) =>+ vi.stubGlobal(+ "fetch",+ vi.fn().mockResolvedValue(new Response(JSON.stringify(body), { status })),+ );++ it("locks and carries the operation token back on a gated hold", async () => {+ answer({+ success: true,+ allowed: true,+ lock_id: "monitor_check-1",+ operation_token: "op-tok",+ });+ await expect(firebillLock(lockParams)).resolves.toEqual({+ status: "locked",+ lockId: "monitor_check-1",+ operationToken: "op-tok",+ });+ });++ it("falls back to the caller's lock id when firebill echoes none", async () => {+ answer({ success: true, allowed: true });+ await expect(firebillLock(lockParams)).resolves.toEqual({+ status: "locked",+ lockId: "monitor_check-1",+ });+ });++ it("reads a denial and its reason", async () => {+ answer({ success: true, allowed: false, reason: "out_of_credits" });+ await expect(firebillLock(lockParams)).resolves.toEqual({+ status: "denied",+ reason: "out_of_credits",+ });+ });++ it("drops an unrecognised denial reason rather than passing it through", async () => {+ answer({ success: true, allowed: false, reason: "some_new_reason" });+ await expect(firebillLock(lockParams)).resolves.toEqual({+ status: "denied",+ });+ });++ // A shape firebill sent on purpose (`success: false`) is `refused`; one we+ // could not read is `unusable`. Both proceed unlocked, but slicing the cause+ // counter must tell them apart.+ it("calls an explicit success:false refused", async () => {+ answer({ success: false });+ await expect(firebillLock(lockParams)).resolves.toEqual({+ status: "unavailable",+ });+ expect(await failureCauses()).toEqual({ "lock/refused": 1 });+ });++ it.each([+ ["a missing allowed", { success: true }],+ ["a non-boolean allowed", { success: true, allowed: "yes" }],+ ["a missing success", { locked: true }],+ ])("calls %s unusable, not refused", async (_label, body) => {+ answer(body);+ await expect(firebillLock(lockParams)).resolves.toEqual({+ status: "unavailable",+ });+ expect(await failureCauses()).toEqual({ "lock/unusable": 1 });+ });++ it("calls an unreadable body unusable", async () => {+ vi.stubGlobal(+ "fetch",+ vi+ .fn()+ .mockResolvedValue(new Response("<html>502</html>", { status: 200 })),+ );+ await expect(firebillLock(lockParams)).resolves.toEqual({+ status: "unavailable",+ });+ expect(await failureCauses()).toEqual({ "lock/unusable": 1 });+ });++ it("names a non-OK status as its own cause", async () => {+ answer({ success: true, allowed: true }, 503);+ await expect(firebillLock(lockParams)).resolves.toEqual({+ status: "unavailable",+ });+ expect(await failureCauses()).toEqual({ "lock/non_ok": 1 });+ });+});++describe("firebillFinalize", () => {+ const finalizeParams = {+ lockId: "monitor_check-1",+ action: "confirm" as const,+ };++ const answer = (body: unknown, status = 200) =>+ vi.stubGlobal(+ "fetch",+ vi.fn().mockResolvedValue(new Response(JSON.stringify(body), { status })),+ );++ it("returns true when firebill accepted the settle", async () => {+ answer({ success: true });+ await expect(firebillFinalize(finalizeParams)).resolves.toBe(true);+ });++ it("calls an explicit success:false refused", async () => {+ answer({ success: false });+ await expect(firebillFinalize(finalizeParams)).resolves.toBe(false);+ expect(await failureCauses()).toEqual({ "finalize/refused": 1 });+ });++ it.each([+ ["a missing success", { queued: true }],+ ["a non-boolean success", { success: "yes" }],+ ])("calls %s unusable, not refused", async (_label, body) => {+ answer(body);+ await expect(firebillFinalize(finalizeParams)).resolves.toBe(false);+ expect(await failureCauses()).toEqual({ "finalize/unusable": 1 });+ });++ it("calls an unreadable body unusable", async () => {+ vi.stubGlobal(+ "fetch",+ vi+ .fn()+ .mockResolvedValue(new Response("<html>502</html>", { status: 200 })),+ );+ await expect(firebillFinalize(finalizeParams)).resolves.toBe(false);+ expect(await failureCauses()).toEqual({ "finalize/unusable": 1 });+ });++ it("reads a 504 as ambiguous rather than refused", async () => {+ answer({ success: false, ambiguous: true }, 504);+ await expect(firebillFinalize(finalizeParams)).resolves.toBe(false);+ expect(await failureCauses()).toEqual({ "finalize/ambiguous": 1 });+ });+});diff --git a/apps/api/src/services/autumn/firebill.ts b/apps/api/src/services/autumn/firebill.tsindex 26506d754..5c1580a68 100644--- a/apps/api/src/services/autumn/firebill.ts+++ b/apps/api/src/services/autumn/firebill.ts@@ -1,4 +1,5 @@import { randomUUID } from "crypto";+import { z } from "zod";import { config } from "../../config";import { logger } from "../../lib/logger";import { sampled } from "../../lib/rollout";@@ -189,6 +190,38 @@ function saysAmbiguous(return (body !== UNUSABLE_BODY && body.ambiguous === true) || status === 504;}+// firebill's answer bodies (firebill `src/api.rs`). `success` discriminates: it+// sends `allowed`/`remaining` (check) and `allowed`/`lock_id`/β¦ (lock) only when+// `success: true`. Splitting the arms keeps an explicit `success: false`+// (`refused`) distinct from a shape that matches neither (`unusable`).++// `ambiguous` is read off the raw body by saysAmbiguous before this.+const usageAnswerSchema = z.object({ success: z.boolean() });++// `remaining` is lenient β a missing or non-finite figure falls back to the+// clamp below rather than discarding the answer.+const checkAnswerSchema = z.discriminatedUnion("success", [+ z.object({+ success: z.literal(true),+ allowed: z.boolean(),+ remaining: z.number().finite().optional().catch(undefined),+ }),+ z.object({ success: z.literal(false) }),+]);++// `lock_id` is caught to undefined so a mis-shaped echo falls back to the+// caller's own id; reason/operation_token are validated where they are read.+const lockAnswerSchema = z.discriminatedUnion("success", [+ z.object({+ success: z.literal(true),+ allowed: z.boolean(),+ lock_id: z.string().optional().catch(undefined),+ reason: z.unknown().optional(),+ operation_token: z.unknown().optional(),+ }),+ z.object({ success: z.literal(false) }),+]);+// 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 =@@ -436,11 +469,13 @@ async function firebillAttempt(// telling us it took the event in a shape we did not understand β so it is// ambiguous, and the caller retries under the same key rather than logging// usage as lost.- if (body !== UNUSABLE_BODY && body.success === false) {+ const parsed =+ body === UNUSABLE_BODY ? undefined : usageAnswerSchema.safeParse(body);+ if (parsed?.success && parsed.data.success === false) {logger.warn("firebill refused the event β it did not take it", context);return { ok: false, reason: "not_success", cause: "refused" };}- if (body === UNUSABLE_BODY || body.success !== true) {+ if (!parsed?.success) {logger.warn("firebill answered with a body we could not read", {...context,status: response.status,@@ -582,29 +617,20 @@ export async function firebillCheck({status: response.status,});}- const body = answered as {- success?: boolean;- allowed?: boolean;- remaining?: number;- };+ const parsed = checkAnswerSchema.safeParse(answered);+ // Unreadable, not refused: a missing `success` or a mis-shaped `allowed` read+ // as a denial would 402 a paying customer, and counting it `refused` would+ // have anyone slicing by cause counting it a decline. So it fails open.+ if (!parsed.success) {+ return unavailable("answered without a usable shape", "unusable");+ }// `success: false` is firebill saying it does not know β an unanswered// balance, or a gateway lookup that failed. Never a denial.- if (body.success === false) {+ if (parsed.data.success === false) {return unavailable("firebill could not answer", "refused");}- // Anything else that is not `success: true` is an answer we cannot read- // rather than one firebill gave: `refused` is documented as an explicit- // `success: false`, and labelling a shape we did not understand with it- // would have anyone slicing by cause counting these as declines.- if (body.success !== true) {- return unavailable("answered without a usable `success`", "unusable");- }- // A missing or mis-shaped `allowed` is not something firebill sends today.- // Reading it as a denial would 402 a paying customer, so it fails open.- if (typeof body.allowed !== "boolean") {- return unavailable("answered without a usable `allowed`", "unusable");- }+ const body = parsed.data;// `remaining` clamps downstream limits, and the safe default inverts with// `allowed`, so there is no single one.@@ -719,21 +745,17 @@ export async function firebillLock({firebillFailureCauseTotal.labels("lock", "unusable").inc();return { status: "unavailable" };}- const body = answered as {- success?: boolean;- allowed?: boolean;- lock_id?: string;- reason?: unknown;- operation_token?: unknown;- };-- if (body.success !== true) {+ const parsed = lockAnswerSchema.safeParse(answered);+ // Both proceed unlocked, but the cause has to tell them apart: an explicit+ // `success: false` is `refused`, a shape matching neither arm is `unusable`.+ if (!parsed.success || parsed.data.success === false) {logger.error("firebill lock did not succeed", context);firebillFailureCauseTotal- .labels("lock", body.success === false ? "refused" : "unusable")+ .labels("lock", parsed.success ? "refused" : "unusable").inc();return { status: "unavailable" };}+ const body = parsed.data;if (body.allowed === false) {const reason = lockDeniedReason(body.reason);@@ -748,19 +770,8 @@ export async function firebillLock({return { status: "denied", ...(reason ? { reason } : {}) };}- // Only an explicit `allowed: false` is a denial. `success: true` with a- // missing or mis-shaped `allowed` is not an answer firebill sends today;- // treating it as a denial would hard-stop the check (skipped_no_credits),- // so it maps to unavailable β proceed unlocked β instead.- if (body.allowed !== true) {- logger.error(- "firebill lock answered without a usable `allowed`",- context,- );- firebillFailureCauseTotal.labels("lock", "unusable").inc();- return { status: "unavailable" };- }-+ // allowed is a schema-guaranteed boolean and the denial above took the+ // false, so this is allowed: true.const operationToken =typeof body.operation_token === "string" &&body.operation_token.length > 0@@ -906,11 +917,12 @@ export async function firebillFinalize({firebillFailureCauseTotal.labels("finalize", "unusable").inc();return false;}- const body = answered as { success?: boolean };- if (body.success !== true) {+ const parsed = usageAnswerSchema.safeParse(answered);+ if (!parsed.success || parsed.data.success !== true) {logger.error("firebill finalize did not succeed", context);firebillFailureCauseTotal- .labels("finalize", body.success === false ? "refused" : "unusable")+ // Explicit `success: false` is `refused`; an unreadable shape `unusable`.+ .labels("finalize", parsed.success ? "refused" : "unusable").inc();return false;}