Skip to content

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

Extend stable idempotency keys to every billTeam call site with a unique charge

Rakshith Ramprakashe62e8afeb2dd
diff --git a/apps/api/src/controllers/v0/search.ts b/apps/api/src/controllers/v0/search.ts
index 55bd5ee8b..4a6363a57 100644
--- a/apps/api/src/controllers/v0/search.ts
+++ b/apps/api/src/controllers/v0/search.ts
@@ -90,7 +90,7 @@ async function searchHelper(
team_id,
searchCredits,
api_key_id,
- { endpoint: "search", jobId },
+ { endpoint: "search", jobId, chargeId: jobId },
logger,
).catch(error => {
logger.error(
diff --git a/apps/api/src/controllers/v1/batch-scrape.ts b/apps/api/src/controllers/v1/batch-scrape.ts
index 1e69f7bce..4ea25a619 100644
--- a/apps/api/src/controllers/v1/batch-scrape.ts
+++ b/apps/api/src/controllers/v1/batch-scrape.ts
@@ -214,7 +214,7 @@ export async function batchScrapeController(
req.auth.team_id,
threatScanCredits,
req.acuc?.api_key_id ?? null,
- { endpoint: "batch_scrape", jobId: id },
+ { endpoint: "batch_scrape", jobId: id, chargeId: `${id}:threat` },
).catch(error => {
logger.error(
`Failed to bill team ${req.auth.team_id} for ${threatScanCredits} threat scan credit(s): ${error}`,
diff --git a/apps/api/src/controllers/v1/crawl.ts b/apps/api/src/controllers/v1/crawl.ts
index 4557802d5..d7b9ff20e 100644
--- a/apps/api/src/controllers/v1/crawl.ts
+++ b/apps/api/src/controllers/v1/crawl.ts
@@ -87,6 +87,8 @@ export async function crawlController(
req.auth.team_id,
threatScanCredits,
req.acuc?.api_key_id ?? null,
+ // No chargeId: the crawl id is not minted on this rejection path,
+ // and there is no other per-charge identity here.
{ endpoint: "crawl" },
).catch(error => {
_logger.error(
diff --git a/apps/api/src/controllers/v1/extract.ts b/apps/api/src/controllers/v1/extract.ts
index 9b4fbf893..20eede498 100644
--- a/apps/api/src/controllers/v1/extract.ts
+++ b/apps/api/src/controllers/v1/extract.ts
@@ -192,6 +192,7 @@ export async function extractController(
req.auth.team_id,
threatScanCredits,
req.acuc?.api_key_id ?? null,
+ // No chargeId: v1 has no extract id in scope on this path.
{ endpoint: "extract" },
).catch(error => {
_logger.error(
diff --git a/apps/api/src/controllers/v1/fireclaw.ts b/apps/api/src/controllers/v1/fireclaw.ts
index 0f2bdbf3b..8eaba43aa 100644
--- a/apps/api/src/controllers/v1/fireclaw.ts
+++ b/apps/api/src/controllers/v1/fireclaw.ts
@@ -68,6 +68,9 @@ export async function fireclawController(
req.auth.team_id,
totalCredits,
req.acuc?.api_key_id ?? null,
+ // No chargeId: fireclaw has no per-charge identity to key on β€” a
+ // server-minted UUID here would be equivalent to firebill's own
+ // per-request key, so this stays keyless until fireclaw carries one.
{ endpoint: "fireclaw" },
);
} catch (error) {
diff --git a/apps/api/src/controllers/v1/map.ts b/apps/api/src/controllers/v1/map.ts
index 2b46f79ac..a774cfb4c 100644
--- a/apps/api/src/controllers/v1/map.ts
+++ b/apps/api/src/controllers/v1/map.ts
@@ -517,6 +517,7 @@ export async function mapController(
billTeam(req.auth.team_id, creditsToBill, req.acuc?.api_key_id ?? null, {
endpoint: "map",
jobId: mapId,
+ chargeId: mapId,
}).catch(error => {
logger.error(
`Failed to bill team ${req.auth.team_id} for ${creditsToBill} credit(s): ${error}`,
diff --git a/apps/api/src/controllers/v1/search.ts b/apps/api/src/controllers/v1/search.ts
index fea667c0e..6e401c74c 100644
--- a/apps/api/src/controllers/v1/search.ts
+++ b/apps/api/src/controllers/v1/search.ts
@@ -212,9 +212,9 @@ export async function searchController(
);
if (!reservation.ok) {
applyAgentAuthDiscoveryHeader(res);
- return res.status(429).json(
- await keylessLimitBody(req.auth.team_id, "v1_search"),
- );
+ return res
+ .status(429)
+ .json(await keylessLimitBody(req.auth.team_id, "v1_search"));
}
reservedKeylessCredits = projectedKeylessCredits;
}
@@ -284,7 +284,7 @@ export async function searchController(
req.auth.team_id,
result.searchCredits,
req.acuc?.api_key_id ?? null,
- { endpoint: "search", jobId },
+ { endpoint: "search", jobId, chargeId: jobId },
).catch(error => {
logger.error(
`Failed to bill team ${req.auth.team_id} for ${result.searchCredits} credits: ${error}`,
diff --git a/apps/api/src/controllers/v2/agent.ts b/apps/api/src/controllers/v2/agent.ts
index 86ee7f346..e0e1ae32b 100644
--- a/apps/api/src/controllers/v2/agent.ts
+++ b/apps/api/src/controllers/v2/agent.ts
@@ -89,7 +89,7 @@ export async function agentController(
req.auth.team_id,
threatScanCredits,
req.acuc?.api_key_id ?? null,
- { endpoint: "agent", jobId: agentId },
+ { endpoint: "agent", jobId: agentId, chargeId: `${agentId}:threat` },
).catch(error => {
logger.error(
`Failed to bill team ${req.auth.team_id} for ${threatScanCredits} threat scan credit(s): ${error}`,
diff --git a/apps/api/src/controllers/v2/batch-scrape.ts b/apps/api/src/controllers/v2/batch-scrape.ts
index e4ac42355..b01e0745b 100644
--- a/apps/api/src/controllers/v2/batch-scrape.ts
+++ b/apps/api/src/controllers/v2/batch-scrape.ts
@@ -242,7 +242,7 @@ export async function batchScrapeController(
req.auth.team_id,
threatScanCredits,
req.acuc?.api_key_id ?? null,
- billing,
+ { ...billing, chargeId: `${id}:threat` },
).catch(error => {
logger.error(
`Failed to bill team ${req.auth.team_id} for ${threatScanCredits} threat scan credit(s): ${error}`,
diff --git a/apps/api/src/controllers/v2/browser.ts b/apps/api/src/controllers/v2/browser.ts
index 8b351f31c..2e0f9c3f2 100644
--- a/apps/api/src/controllers/v2/browser.ts
+++ b/apps/api/src/controllers/v2/browser.ts
@@ -615,6 +615,9 @@ export async function browserDeleteController(
billTeam(req.auth.team_id, creditsBilled, req.acuc?.api_key_id ?? null, {
endpoint: usedPrompt ? "interact" : "browser",
jobId: session.id,
+ // Per-path suffix: the webhook teardown below bills the same session id
+ // through a different path; a shared key would silently drop one charge.
+ chargeId: `${session.id}:destroy`,
}).catch(error => {
logger.error("Failed to bill team for browser session", {
error,
@@ -757,7 +760,11 @@ export async function browserWebhookDestroyedController(
session.team_id,
creditsBilled,
null, // api_key_id not available in webhook context
- { endpoint: usedPrompt ? "interact" : "browser", jobId: session.id },
+ {
+ endpoint: usedPrompt ? "interact" : "browser",
+ jobId: session.id,
+ chargeId: `${session.id}:webhook`,
+ },
).catch(error => {
logger.error("Failed to bill team for browser session via webhook", {
error,
diff --git a/apps/api/src/controllers/v2/crawl.ts b/apps/api/src/controllers/v2/crawl.ts
index 090aa94b2..b5ef6f383 100644
--- a/apps/api/src/controllers/v2/crawl.ts
+++ b/apps/api/src/controllers/v2/crawl.ts
@@ -91,6 +91,8 @@ export async function crawlController(
req.auth.team_id,
threatScanCredits,
req.acuc?.api_key_id ?? null,
+ // No chargeId: the crawl id is not minted on this rejection path,
+ // and there is no other per-charge identity here.
{ endpoint: "crawl" },
).catch(error => {
_logger.error(
diff --git a/apps/api/src/controllers/v2/extract.ts b/apps/api/src/controllers/v2/extract.ts
index 5691cf498..d90f1754e 100644
--- a/apps/api/src/controllers/v2/extract.ts
+++ b/apps/api/src/controllers/v2/extract.ts
@@ -132,7 +132,13 @@ export async function extractController(
req.auth.team_id,
threatScanCredits,
req.acuc?.api_key_id ?? null,
- { endpoint: "extract", jobId: extractId },
+ {
+ endpoint: "extract",
+ jobId: extractId,
+ // Suffixed: the extract's MAIN charge (fire-0) uses the bare
+ // extractId β€” a shared key would collapse the two into one charge.
+ chargeId: `${extractId}:threat`,
+ },
).catch(error => {
_logger.error(
`Failed to bill team ${req.auth.team_id} for ${threatScanCredits} threat scan credit(s): ${error}`,
diff --git a/apps/api/src/controllers/v2/feedback/record.ts b/apps/api/src/controllers/v2/feedback/record.ts
index 63c262a6c..0eb116d83 100644
--- a/apps/api/src/controllers/v2/feedback/record.ts
+++ b/apps/api/src/controllers/v2/feedback/record.ts
@@ -216,6 +216,9 @@ async function refundCredits(params: {
await autumnService.refundCredits({
teamId: req.auth.team_id,
value: cappedRefund,
+ // One refund per feedback record; a retried refund dedupes (firebill
+ // route) instead of crediting twice.
+ idempotencyKey: `fc:refund:feedback:${feedbackId}`,
featureId:
options.refundFeatureId ??
featureIdForBillingEndpoint(options.endpoint),
diff --git a/apps/api/src/controllers/v2/map.ts b/apps/api/src/controllers/v2/map.ts
index e6a2165b5..217d01b4a 100644
--- a/apps/api/src/controllers/v2/map.ts
+++ b/apps/api/src/controllers/v2/map.ts
@@ -103,6 +103,9 @@ export async function mapController(
billTeam(req.auth.team_id, creditsCost, req.acuc?.api_key_id ?? null, {
endpoint: "map",
jobId: mapId,
+ // Suffixed so this early-return path can never collide with the main
+ // map charge below, even if both ever billed the same mapId.
+ chargeId: `${mapId}:avgrab`,
}).catch(error => {
logger.error(
`Failed to bill team ${req.auth.team_id} for ${creditsCost} credits: ${error}`,
@@ -238,6 +241,7 @@ export async function mapController(
billTeam(req.auth.team_id, creditsToBill, req.acuc?.api_key_id ?? null, {
endpoint: "map",
jobId: mapId,
+ chargeId: mapId,
}).catch(error => {
logger.error("Failed to bill team for map credits", {
teamId: req.auth.team_id,
diff --git a/apps/api/src/controllers/v2/research-proxy.ts b/apps/api/src/controllers/v2/research-proxy.ts
index fde48922f..dc41fddf2 100644
--- a/apps/api/src/controllers/v2/research-proxy.ts
+++ b/apps/api/src/controllers/v2/research-proxy.ts
@@ -335,6 +335,7 @@ function createResearchController(
{
endpoint: endpoint.billAs === "scrape" ? "scrape" : "search",
jobId,
+ chargeId: jobId,
},
).catch(billingError => {
logger.error("Failed to bill research request", {
diff --git a/apps/api/src/controllers/v2/scrape-browser.ts b/apps/api/src/controllers/v2/scrape-browser.ts
index 5751c7127..8377784af 100644
--- a/apps/api/src/controllers/v2/scrape-browser.ts
+++ b/apps/api/src/controllers/v2/scrape-browser.ts
@@ -477,6 +477,7 @@ export async function scrapeStopInteractiveBrowserController(
billTeam(req.auth.team_id, creditsBilled, req.acuc?.api_key_id ?? null, {
endpoint: "interact",
jobId: session.id,
+ chargeId: `${session.id}:scrape-browser`,
}).catch(error => {
logger.error("Failed to bill team for interact session", {
error,
diff --git a/apps/api/src/controllers/v2/search.ts b/apps/api/src/controllers/v2/search.ts
index 47dfb6fe8..bb56ce89c 100644
--- a/apps/api/src/controllers/v2/search.ts
+++ b/apps/api/src/controllers/v2/search.ts
@@ -265,7 +265,7 @@ export async function searchController(
req.auth.team_id,
result.searchCredits,
req.acuc?.api_key_id ?? null,
- billing,
+ { ...billing, chargeId: jobId },
).catch(error =>
logger.error("Failed to bill team for search credits", {
teamId: req.auth.team_id,
diff --git a/apps/api/src/lib/deep-research/deep-research-service.ts b/apps/api/src/lib/deep-research/deep-research-service.ts
index ef0853e44..dbda145ef 100644
--- a/apps/api/src/lib/deep-research/deep-research-service.ts
+++ b/apps/api/src/lib/deep-research/deep-research-service.ts
@@ -429,7 +429,7 @@ export async function performDeepResearch(options: DeepResearchServiceOptions) {
teamId,
credits_billed,
apiKeyId,
- { endpoint: "deep_research", jobId: researchId },
+ { endpoint: "deep_research", jobId: researchId, chargeId: researchId },
logger,
).catch(error => {
logger.error(
diff --git a/apps/api/src/lib/extract/fire-0/extraction-service-f0.ts b/apps/api/src/lib/extract/fire-0/extraction-service-f0.ts
index 553be8a86..b7319dbaa 100644
--- a/apps/api/src/lib/extract/fire-0/extraction-service-f0.ts
+++ b/apps/api/src/lib/extract/fire-0/extraction-service-f0.ts
@@ -873,7 +873,7 @@ export async function performExtraction_F0(
teamId,
creditsToBill,
apiKeyId,
- { endpoint: "extract", jobId: extractId },
+ { endpoint: "extract", jobId: extractId, chargeId: extractId },
logger,
).catch(error => {
logger.error(
diff --git a/apps/api/src/lib/generate-llmstxt/generate-llmstxt-service.ts b/apps/api/src/lib/generate-llmstxt/generate-llmstxt-service.ts
index f841c2c82..8e5d0e7e0 100644
--- a/apps/api/src/lib/generate-llmstxt/generate-llmstxt-service.ts
+++ b/apps/api/src/lib/generate-llmstxt/generate-llmstxt-service.ts
@@ -282,7 +282,7 @@ export async function performGenerateLlmsTxt(
teamId,
urls.length,
apiKeyId,
- { endpoint: "llms_txt", jobId: generationId },
+ { endpoint: "llms_txt", jobId: generationId, chargeId: generationId },
logger,
).catch(error => {
logger.error(`Failed to bill team ${teamId} for ${urls.length} urls`, {
diff --git a/apps/api/src/services/billing/__tests__/credit_billing.test.ts b/apps/api/src/services/billing/__tests__/credit_billing.test.ts
index e23f28468..fdbca451f 100644
--- a/apps/api/src/services/billing/__tests__/credit_billing.test.ts
+++ b/apps/api/src/services/billing/__tests__/credit_billing.test.ts
@@ -52,6 +52,40 @@ beforeEach(() => {
});
describe("billTeam", () => {
+ it("derives firebill idempotency keys from chargeId, and omits them without one", async () => {
+ await billTeam("team-1", 3, 123, {
+ endpoint: "search",
+ jobId: "job-9",
+ chargeId: "job-9",
+ });
+ expect(trackCredits).toHaveBeenLastCalledWith(
+ expect.objectContaining({ idempotencyKey: "fc:track:search:job-9" }),
+ );
+
+ await billTeam("team-1", 3, 123, { endpoint: "search", jobId: "job-9" });
+ expect(trackCredits).toHaveBeenLastCalledWith(
+ expect.objectContaining({ idempotencyKey: undefined }),
+ );
+ });
+
+ it("gives the compensating refund its own fc:refund key", async () => {
+ queueBillingOperation.mockResolvedValueOnce({
+ success: false,
+ message: "enqueue failed",
+ });
+ trackCredits.mockResolvedValueOnce(true);
+
+ await billTeam("team-1", 3, 123, {
+ endpoint: "map",
+ jobId: "map-1",
+ chargeId: "map-1",
+ });
+
+ expect(refundCredits).toHaveBeenCalledWith(
+ expect.objectContaining({ idempotencyKey: "fc:refund:map:map-1" }),
+ );
+ });
+
it("marks billing as already tracked when request tracking succeeds", async () => {
await billTeam("team-1", 3, 123, {
endpoint: "search",
diff --git a/apps/api/src/services/billing/credit_billing.ts b/apps/api/src/services/billing/credit_billing.ts
index a08d527d4..9da9d6268 100644
--- a/apps/api/src/services/billing/credit_billing.ts
+++ b/apps/api/src/services/billing/credit_billing.ts
@@ -28,11 +28,16 @@ export async function billTeam(
apiKeyId: api_key_id,
};
const featureId = featureIdForBillingEndpoint(billing.endpoint);
+ // Stable per-charge key (firebill route only): a caller retry or re-run
+ // job with the same chargeId dedupes instead of double-billing.
const trackedInRequest = await autumnService.trackCredits({
teamId: team_id,
value: credits,
properties: autumnProperties,
featureId,
+ idempotencyKey: billing.chargeId
+ ? `fc:track:${billing.endpoint}:${billing.chargeId}`
+ : undefined,
});
const result = await queueBillingOperation(
@@ -50,6 +55,10 @@ export async function billTeam(
value: credits,
properties: autumnProperties,
featureId,
+ // Distinct from the track key: the refund is its own charge event.
+ idempotencyKey: billing.chargeId
+ ? `fc:refund:${billing.endpoint}:${billing.chargeId}`
+ : undefined,
});
}
diff --git a/apps/api/src/services/billing/types.ts b/apps/api/src/services/billing/types.ts
index 87ae1ec54..bf18e5358 100644
--- a/apps/api/src/services/billing/types.ts
+++ b/apps/api/src/services/billing/types.ts
@@ -17,6 +17,20 @@ export type BillingEndpoint =
export type BillingMetadata = {
endpoint: BillingEndpoint;
jobId?: string;
+ /**
+ * Unique-per-CHARGE identity, set by the call site that knows what "one
+ * charge" is. billTeam derives the firebill idempotency key from it
+ * (`fc:track:{endpoint}:{chargeId}`), so a retried call β€” or a re-run job β€”
+ * dedupes instead of double-billing on the firebill route.
+ *
+ * Rules: it must never be shared by two charges that should BOTH bill
+ * (collision = silent underbilling). A jobId shared with another charge on
+ * the same endpoint needs a suffix (e.g. `${extractId}:threat` for the
+ * threat-scan fee vs the extract's main charge). Sites with no unique
+ * identity (fireclaw, grouped charges) leave it unset and keep firebill's
+ * per-request UUID, which dedupes only firebill's own retries.
+ */
+ chargeId?: string;
};
export function resolveBillingMetadata({
diff --git a/apps/api/src/services/worker/scrape-worker.ts b/apps/api/src/services/worker/scrape-worker.ts
index 3bc55ecf6..a0c94697e 100644
--- a/apps/api/src/services/worker/scrape-worker.ts
+++ b/apps/api/src/services/worker/scrape-worker.ts
@@ -284,6 +284,10 @@ function billThreatBlockedDiscoveries(
blocked.map(x => x.decision),
);
if (threatScanCredits <= 0) return;
+ // Deliberately no chargeId: MULTIPLE legitimate charges share this exact
+ // billing metadata (each page job that discovers new blocked URLs bills its
+ // own batch under the same crawl id) β€” a shared key would collapse them
+ // into one charge, i.e. underbill. Keyless until per-batch identity exists.
billTeam(args.teamId, threatScanCredits, args.apiKeyId, args.billing).catch(
error => {
logger.error(