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
feat(billing): log operation key and expected amount on firebill success (#5184)
Rakshith Ramprakashacd9d4155c21
diff --git a/apps/api/src/config.ts b/apps/api/src/config.tsindex 9747e0367..a9b8cecad 100644--- a/apps/api/src/config.ts+++ b/apps/api/src/config.ts@@ -664,6 +664,8 @@ const configSchema = z.object({FIREBILL_ROLLOUT_PERCENT: z.coerce.number().min(0).max(100).default(0),// Miscellaneous+ // The commit the image was built from, set by the Dockerfile's GIT_SHA.+ FIRECRAWL_BUILD_SHA: emptyStringAsUndefined(z.string().trim().min(1)),IDMUX_URL: z.string().optional(),GITHUB_RUN_NUMBER: z.string().optional(),GITHUB_REF_NAME: z.string().optional(),diff --git a/apps/api/src/services/autumn/__tests__/firebill.test.ts b/apps/api/src/services/autumn/__tests__/firebill.test.tsindex e97975e46..5c40cec3e 100644--- a/apps/api/src/services/autumn/__tests__/firebill.test.ts+++ b/apps/api/src/services/autumn/__tests__/firebill.test.ts@@ -20,6 +20,7 @@ const { configState } = vi.hoisted(() => ({FIREBILL_SECRET: "secret",FIREBILL_ORG_IDS: ["allow-listed-org"] as string[] | undefined,FIREBILL_ROLLOUT_PERCENT: 0,+ FIRECRAWL_BUILD_SHA: undefined as string | undefined,},}));@@ -66,6 +67,7 @@ beforeEach(() => {configState.FIREBILL_SECRET = "secret";configState.FIREBILL_ORG_IDS = ["allow-listed-org"];configState.FIREBILL_ROLLOUT_PERCENT = 0;+ configState.FIRECRAWL_BUILD_SHA = undefined;firebillTrackTotal.reset();firebillRetryTotal.reset();firebillCheckTotal.reset();@@ -486,6 +488,58 @@ describe("firebillTrack", () => {expect(fetchMock.mock.calls[0][0]).toBe("https://firebill.test/v1/refund");expect(JSON.parse(fetchMock.mock.calls[0][1].body).value).toBe(7);});++ it("logs one accepted line carrying the key, the amount and the build", async () => {+ configState.FIRECRAWL_BUILD_SHA = "abc123";+ vi.stubGlobal(+ "fetch",+ vi.fn().mockImplementation(async () => ok()),+ );++ await firebillTrack({ ...params, properties: { jobId: "job-1" } });++ expect(logger.info).toHaveBeenCalledTimes(1);+ expect(logger.info).toHaveBeenCalledWith(+ "firebill track succeeded",+ expect.objectContaining({+ operation: "track",+ outcome: "accepted",+ idempotencyKey: params.idempotencyKey,+ expectedValue: 3,+ jobId: "job-1",+ buildVersion: "abc123",+ }),+ );+ });++ it("logs a refund under its own operation with the amount made positive", async () => {+ vi.stubGlobal(+ "fetch",+ vi.fn().mockImplementation(async () => ok()),+ );++ await firebillTrack({ ...params, value: -7 });++ expect(logger.info).toHaveBeenCalledWith(+ "firebill track succeeded",+ expect.objectContaining({+ operation: "refund",+ expectedValue: 7,+ buildVersion: "unknown",+ }),+ );+ });++ it("logs no success line when firebill did not take the event", async () => {+ vi.stubGlobal(+ "fetch",+ vi.fn().mockImplementation(async () => refused()),+ );++ await firebillTrack(params);++ expect(logger.info).not.toHaveBeenCalled();+ });});describe("firebillCheck", () => {@@ -799,6 +853,53 @@ describe("firebillFinalize", () => {await expect(firebillFinalize(finalizeParams)).resolves.toBe(true);});+ it("logs the settle's key and the amount it bills", async () => {+ answer({ success: true });+ await firebillFinalize({+ ...finalizeParams,+ overrideValue: 2,+ heldValue: 5,+ });+ expect(logger.info).toHaveBeenCalledWith(+ "firebill finalize succeeded",+ expect.objectContaining({+ operation: "finalize",+ outcome: "accepted",+ idempotencyKey: "fc:finalize:confirm:monitor_check-1",+ expectedValue: 2,+ }),+ );++ vi.mocked(logger.info).mockClear();+ answer({ success: true });+ await firebillFinalize({ ...finalizeParams, heldValue: 5 });+ expect(logger.info).toHaveBeenCalledWith(+ "firebill finalize succeeded",+ expect.objectContaining({ expectedValue: 5 }),+ );++ vi.mocked(logger.info).mockClear();+ answer({ success: true });+ await firebillFinalize({+ ...finalizeParams,+ action: "release",+ heldValue: 5,+ });+ expect(logger.info).toHaveBeenCalledWith(+ "firebill finalize succeeded",+ expect.objectContaining({+ idempotencyKey: "fc:finalize:release:monitor_check-1",+ expectedValue: 0,+ }),+ );+ });++ it("logs nothing as succeeded when the settle was refused", async () => {+ answer({ success: false });+ await firebillFinalize(finalizeParams);+ expect(logger.info).not.toHaveBeenCalled();+ });+it("calls an explicit success:false refused", async () => {answer({ success: false });await expect(firebillFinalize(finalizeParams)).resolves.toBe(false);diff --git a/apps/api/src/services/autumn/firebill.ts b/apps/api/src/services/autumn/firebill.tsindex 2446aaa20..95451de55 100644--- a/apps/api/src/services/autumn/firebill.ts+++ b/apps/api/src/services/autumn/firebill.ts@@ -78,6 +78,30 @@ type FirebillCause =| "refused"| "ambiguous";+/**+ * The fields a billing success line carries so a monitor can join it, by+ * idempotency key, to firebill's own settlement line and to the reconciler's+ * amount verdicts. `expectedValue` is the amount the operation should bill: a+ * track's value, a refund's made positive, a confirm's override else its hold,+ * and 0 for a release, which bills nothing whatever it held.+ */+function billingSuccessFields(+ operation: "track" | "refund" | "finalize",+ idempotencyKey: string | undefined,+ expectedValue: number | undefined,+ properties: Record<string, unknown> | undefined,+) {+ const jobId = properties?.jobId;+ return {+ operation,+ outcome: "accepted",+ idempotencyKey,+ expectedValue,+ ...(typeof jobId === "string" ? { jobId } : {}),+ buildVersion: config.FIRECRAWL_BUILD_SHA ?? "unknown",+ };+}+/** What a thrown fetch tells us, once it is unwrapped. */type TransportFailure = {cause: "timeout" | "connection";@@ -490,7 +514,15 @@ async function firebillAttempt(return { ok: false, reason: "ambiguous", cause: "unusable" };}- logger.info("firebill track succeeded", context);+ logger.info("firebill track succeeded", {+ ...context,+ ...billingSuccessFields(+ path === "/v1/refund" ? "refund" : "track",+ idempotencyKey,+ Math.abs(value),+ properties,+ ),+ });return { ok: true };} catch (error) {// DO NOT fall back to Autumn directly: firebill may have accepted the event@@ -852,6 +884,11 @@ export async function firebillFinalize({heldValue?: number | null;}): Promise<boolean> {const url = firebillUrl("/v1/finalize");+ // Deterministic per (lock, action): the lock id is itself caller-chosen and+ // stable (`monitor_${check.id}`), so a re-finalize of the same settle β e.g.+ // the reconciler re-running a check it raced β dedupes upstream instead of+ // settling twice.+ const idempotencyKey = `fc:finalize:${action}:${lockId}`;try {const response = await fetch(url, {method: "POST",@@ -866,11 +903,7 @@ export async function firebillFinalize({? { override_value: overrideValue }: {}),properties,- // Deterministic per (lock, action): the lock id is itself caller-chosen- // and stable (`monitor_${check.id}`), so a re-finalize of the same- // settle β e.g. the reconciler re-running a check it raced β dedupes- // upstream instead of settling twice.- idempotency_key: `fc:finalize:${action}:${lockId}`,+ idempotency_key: idempotencyKey,// The run token, brought home as this settle's operation id....(externalRequestId? { external_request_id: externalRequestId }@@ -934,7 +967,16 @@ export async function firebillFinalize({return false;}- logger.info("firebill finalize succeeded", context);+ logger.info("firebill finalize succeeded", {+ ...context,+ ...billingSuccessFields(+ "finalize",+ idempotencyKey,+ // A release bills nothing; a confirm bills its override, else the hold.+ action === "release" ? 0 : (overrideValue ?? heldValue ?? undefined),+ properties,+ ),+ });return true;} catch (error) {const failure = classifyTransportError(error);