Skip to content

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

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.ts
index 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.ts
index 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.ts
index 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);