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
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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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(