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
Close the rerun-divergence holes cubic found in the key design
Rakshith Ramprakashefd26caf79cb
diff --git a/apps/api/src/services/autumn/__tests__/autumn.service.test.ts b/apps/api/src/services/autumn/__tests__/autumn.service.test.tsindex 7c5bc469b..42249c36c 100644--- a/apps/api/src/services/autumn/__tests__/autumn.service.test.ts+++ b/apps/api/src/services/autumn/__tests__/autumn.service.test.ts@@ -739,10 +739,19 @@ describe("firebill routing", () => {).toBe(false);});- it("gives a refund its own key, distinct from the track's", async () => {+ it("a track/refund pair for one charge carries two distinct keys", async () => {state.configRef = firebillConfig();const svc = makeService();+ // The convention the billers rely on: same charge identity, different+ // prefix per direction β a shared key would 409 as a duplicate of the+ // track and silently drop the refund.+ await svc.trackCredits({+ teamId: "team-1",+ value: 5,+ properties: { source: "billScrapeJob", endpoint: "scrape" },+ idempotencyKey: "fc:track:scrape:job-123",+ });await svc.refundCredits({teamId: "team-1",value: 5,@@ -750,11 +759,15 @@ describe("firebill routing", () => {idempotencyKey: "fc:refund:scrape:job-123",});- const [url, init] = mockFetch.mock.calls[0]!;- expect(String(url)).toContain("/v1/refund");- expect(JSON.parse(init.body).idempotency_key).toBe(- "fc:refund:scrape:job-123",- );+ const [trackUrl, trackInit] = mockFetch.mock.calls[0]!;+ const [refundUrl, refundInit] = mockFetch.mock.calls[1]!;+ expect(String(trackUrl)).toContain("/v1/track");+ expect(String(refundUrl)).toContain("/v1/refund");+ const trackKey = JSON.parse(trackInit.body).idempotency_key;+ const refundKey = JSON.parse(refundInit.body).idempotency_key;+ expect(trackKey).toBe("fc:track:scrape:job-123");+ expect(refundKey).toBe("fc:refund:scrape:job-123");+ expect(trackKey).not.toBe(refundKey);});it("routes trackCredits for an allowlisted org to firebill, not Autumn", async () => {diff --git a/apps/api/src/services/autumn/autumn.service.ts b/apps/api/src/services/autumn/autumn.service.tsindex 462f68e70..020d44427 100644--- a/apps/api/src/services/autumn/autumn.service.ts+++ b/apps/api/src/services/autumn/autumn.service.ts@@ -209,6 +209,22 @@ export class AutumnService {}}+ /**+ * Whether this team's usage is currently routed through firebill. Used by+ * billers to pick route-specific failure handling (on the firebill route a+ * recorded charge stands and dedupes, so compensating refunds and duplicate+ * enqueues behave differently). Never throws: an error means "not routed",+ * falling back to the pre-firebill behavior.+ */+ async isRoutedThroughFirebill(teamId: string): Promise<boolean> {+ if (this.isPreviewTeam(teamId)) return false;+ try {+ return shouldRouteToFirebill(await this.resolveOrgId(teamId));+ } catch {+ return false;+ }+ }+private async track({customerId,entityId,diff --git a/apps/api/src/services/billing/__tests__/credit_billing.test.ts b/apps/api/src/services/billing/__tests__/credit_billing.test.tsindex fdbca451f..452fa7320 100644--- a/apps/api/src/services/billing/__tests__/credit_billing.test.ts+++ b/apps/api/src/services/billing/__tests__/credit_billing.test.ts@@ -2,13 +2,19 @@ import { vi } from "vitest";// vi.mock is hoisted; factory-referenced values must be created in vi.hoisted().// (Jest didn't hoist jest.mock here because `jest` was imported from @jest/globals.)-const { withAuth, queueBillingOperation, trackCredits, refundCredits } =- vi.hoisted(() => ({- withAuth: vi.fn((fn: any) => fn),- queueBillingOperation: vi.fn<(args: any[]) => Promise<any>>(),- trackCredits: vi.fn<(args: any) => Promise<boolean>>(),- refundCredits: vi.fn<(args: any) => Promise<void>>(),- }));+const {+ withAuth,+ queueBillingOperation,+ trackCredits,+ refundCredits,+ isRoutedThroughFirebill,+} = vi.hoisted(() => ({+ withAuth: vi.fn((fn: any) => fn),+ queueBillingOperation: vi.fn<(args: any[]) => Promise<any>>(),+ trackCredits: vi.fn<(args: any) => Promise<boolean>>(),+ refundCredits: vi.fn<(args: any) => Promise<void>>(),+ isRoutedThroughFirebill: vi.fn<(teamId: string) => Promise<boolean>>(),+}));vi.mock("../../../lib/withAuth", () => ({withAuth,@@ -22,6 +28,7 @@ vi.mock("../../autumn/autumn.service", () => ({autumnService: {trackCredits,refundCredits,+ isRoutedThroughFirebill,},featureIdForBillingEndpoint: (endpoint?: string) =>endpoint === "search" ? "SEARCH_CREDITS" : "CREDITS",@@ -49,6 +56,7 @@ beforeEach(() => {queueBillingOperation.mockResolvedValue({ success: true });trackCredits.mockResolvedValue(true);refundCredits.mockResolvedValue(undefined);+ isRoutedThroughFirebill.mockResolvedValue(false);});describe("billTeam", () => {@@ -68,6 +76,23 @@ describe("billTeam", () => {);});+ it("skips the compensating refund on the firebill route β the charge stands", async () => {+ isRoutedThroughFirebill.mockResolvedValue(true);+ 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).not.toHaveBeenCalled();+ });+it("gives the compensating refund its own fc:refund key", async () => {queueBillingOperation.mockResolvedValueOnce({success: false,diff --git a/apps/api/src/services/billing/credit_billing.ts b/apps/api/src/services/billing/credit_billing.tsindex 9da9d6268..8083aa90d 100644--- a/apps/api/src/services/billing/credit_billing.ts+++ b/apps/api/src/services/billing/credit_billing.ts@@ -50,16 +50,28 @@ export async function billTeam();if (!result.success && trackedInRequest) {- await autumnService.refundCredits({- teamId: team_id,- 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,- });+ if (await autumnService.isRoutedThroughFirebill(team_id)) {+ // No compensating refund on the firebill route: the tracked charge+ // is durable and correct, and a refund here poisons a retried+ // request β its track would dedupe against the intent row (no new+ // charge) while the ledger enqueue succeeds, leaving Autumn+ // net-zero for billed work.+ logger?.warn(+ "billing enqueue failed on the firebill route; charge stands",+ { team_id, credits, billing },+ );+ } else {+ await autumnService.refundCredits({+ teamId: team_id,+ 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,+ });+ }}return result;diff --git a/apps/api/src/services/worker/scrape-worker.ts b/apps/api/src/services/worker/scrape-worker.tsindex a0c94697e..0ac252a65 100644--- a/apps/api/src/services/worker/scrape-worker.ts+++ b/apps/api/src/services/worker/scrape-worker.ts@@ -171,6 +171,9 @@ async function billScrapeJob(config.USE_DB_AUTHENTICATION) {try {+ const routedToFirebill = await autumnService.isRoutedThroughFirebill(+ job.data.team_id,+ );trackedInRequest = await autumnService.trackCredits({teamId: job.data.team_id,value: creditsToBeBilled,@@ -183,7 +186,13 @@ async function billScrapeJob(// the re-run dedupes instead of double-billing (firebill route).idempotencyKey: `fc:track:${billing.endpoint}:${job.id}`,});- const billingJobId = uuidv7();+ // On the firebill route the ledger enqueue must be idempotent by the+ // originating job: a stalled job reruns under the same job.id, the+ // track dedupes in firebill, and a fresh random billing job id would+ // debit the ledger twice (the same pattern monitors already use with+ // their deterministic monitor-bill-{id}). Off the route, behavior is+ // unchanged.+ const billingJobId = routedToFirebill ? `bill-${job.id}` : uuidv7();logger.debug(`Adding billing job to queue for team ${job.data.team_id}`,{@@ -226,15 +235,28 @@ async function billScrapeJob({ error },);if (trackedInRequest && creditsToBeBilled !== null) {- await autumnService.refundCredits({- teamId: job.data.team_id,- value: creditsToBeBilled,- properties: autumnProperties,- featureId,- // Distinct from the track key: a refund is its own charge event- // (same key would 409 as a duplicate of the track and be dropped).- idempotencyKey: `fc:refund:${billing.endpoint}:${job.id}`,- });+ if (routedToFirebill) {+ // No compensating refund on the firebill route: the tracked charge+ // is durable and correct (the scrape ran), and refunding it here+ // poisons a rerun β the rerun's track dedupes against the intent+ // row (no new charge) while the ledger enqueue succeeds, leaving+ // Autumn net-zero for work the ledger billed. The rerun retries+ // the enqueue under the deterministic bill-{job.id} instead.+ logger.warn(+ "billing enqueue failed on the firebill route; charge stands, enqueue retries on rerun",+ { jobId: job.id, credits: creditsToBeBilled },+ );+ } else {+ await autumnService.refundCredits({+ teamId: job.data.team_id,+ value: creditsToBeBilled,+ properties: autumnProperties,+ featureId,+ // Distinct from the track key: a refund is its own charge event+ // (same key would 409 as a duplicate of the track and be dropped).+ idempotencyKey: `fc:refund:${billing.endpoint}:${job.id}`,+ });+ }}// The billing operation never reached the queue, so no debit will// commit and no confirmation will ever arrive: void the Exchange