Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥

feat(api): forward the team's billing country on Alexandria requests (#5297)

Developers Digest5488d2fdc9db
diff --git a/apps/api/src/__tests__/routes/exchange-agent-managed-key.routes.test.ts b/apps/api/src/__tests__/routes/exchange-agent-managed-key.routes.test.ts
index 8f34a4274..4ceddcd46 100644
--- a/apps/api/src/__tests__/routes/exchange-agent-managed-key.routes.test.ts
+++ b/apps/api/src/__tests__/routes/exchange-agent-managed-key.routes.test.ts
@@ -1,6 +1,10 @@
import express from "express";
import request from "supertest";
+vi.mock("../../lib/billing-country", () => ({
+ billingCountryForTeam: vi.fn(async () => undefined),
+}));
+
// The real exchangeRouter, authMiddleware and auth.ts; only I/O is mocked.
const mocks = vi.hoisted(() => ({
authChunk: vi.fn(),
diff --git a/apps/api/src/__tests__/routes/exchange-connectors.routes.test.ts b/apps/api/src/__tests__/routes/exchange-connectors.routes.test.ts
index 381dd53d0..37dc5a19b 100644
--- a/apps/api/src/__tests__/routes/exchange-connectors.routes.test.ts
+++ b/apps/api/src/__tests__/routes/exchange-connectors.routes.test.ts
@@ -5,6 +5,11 @@ import request from "supertest";
const mocks = vi.hoisted(() => ({
authChunk: vi.fn(),
upstreamFetch: vi.fn(),
+ billingCountry: vi.fn(async (): Promise<string | undefined> => undefined),
+}));
+
+vi.mock("../../lib/billing-country", () => ({
+ billingCountryForTeam: mocks.billingCountry,
}));
vi.mock("../../db/connection", () => ({ db: {}, dbRr: {}, dbIndex: {} }));
@@ -215,6 +220,27 @@ describe("Alexandria connector routes on the Exchange proxy", () => {
},
);
+ it("forwards the team's billing country only when known, never the caller's own", async () => {
+ keyResolvesAs({});
+ mocks.billingCountry.mockResolvedValueOnce("DE");
+ await request(app)
+ .get("/exchange/team-skills")
+ .set("authorization", `Bearer ${KEY}`)
+ .set("x-exchange-billing-country", "US");
+ expect(upstream().init.headers).toMatchObject({
+ "x-exchange-billing-country": "DE",
+ });
+
+ mocks.upstreamFetch.mockClear();
+ await request(app)
+ .get("/exchange/team-skills")
+ .set("authorization", `Bearer ${KEY}`)
+ .set("x-exchange-billing-country", "US");
+ expect(upstream().init.headers).not.toHaveProperty(
+ "x-exchange-billing-country",
+ );
+ });
+
it("never forwards a caller's own x-exchange-connectors header", async () => {
keyResolvesAs({});
// A route open without the flag: the header must still not reach Exchange.
diff --git a/apps/api/src/controllers/v2/scrape-alexandria.test.ts b/apps/api/src/controllers/v2/scrape-alexandria.test.ts
index 34af95d21..f6e6709dc 100644
--- a/apps/api/src/controllers/v2/scrape-alexandria.test.ts
+++ b/apps/api/src/controllers/v2/scrape-alexandria.test.ts
@@ -1,5 +1,9 @@
import express from "express";
import request from "supertest";
+
+vi.mock("../../lib/billing-country", () => ({
+ billingCountryForTeam: vi.fn(async () => undefined),
+}));
const mocks = vi.hoisted(() => ({
retrieve: vi.fn(),
log: vi.fn(),
diff --git a/apps/api/src/controllers/v2/scrape-alexandria.ts b/apps/api/src/controllers/v2/scrape-alexandria.ts
index 524942bdf..31c85949e 100644
--- a/apps/api/src/controllers/v2/scrape-alexandria.ts
+++ b/apps/api/src/controllers/v2/scrape-alexandria.ts
@@ -7,6 +7,7 @@ import { logger } from "../../lib/logger";
import { isAgentInteropSecretValid } from "../../lib/agent-interop";
import { externalRequestId } from "../../lib/external-request-id";
import { getScrapeZDR } from "../../lib/zdr-helpers";
+import { billingCountryForTeam } from "../../lib/billing-country";
import { checkKeyFormatRestriction } from "../../lib/key-restriction";
import { orgIdFromAcuc } from "../../lib/team-org";
import { logProviderScrape, logRequest } from "../../services/logging/log_job";
@@ -137,6 +138,7 @@ export async function providerScrapeController(
timeoutMs: body.timeout,
bypassBilling: body.__agentInterop?.shouldBill === false,
clientIp: req.ip,
+ billingCountry: await billingCountryForTeam(req.auth.team_id),
});
} catch (error) {
logger.error("Provider scrape unavailable", {
diff --git a/apps/api/src/lib/billing-country.test.ts b/apps/api/src/lib/billing-country.test.ts
new file mode 100644
index 000000000..bf4a2fa57
--- /dev/null
+++ b/apps/api/src/lib/billing-country.test.ts
@@ -0,0 +1,116 @@
+const mocks = vi.hoisted(() => ({
+ rows: [] as { billing_address: unknown }[],
+ query: vi.fn(),
+ orderBy: vi.fn(),
+ getValue: vi.fn(),
+ setValue: vi.fn(),
+}));
+
+vi.mock("../db/connection", () => {
+ const chain: Record<string, unknown> = {};
+ for (const name of ["select", "from", "innerJoin", "where"])
+ chain[name] = () => chain;
+ chain.orderBy = async (...args: unknown[]) => {
+ mocks.orderBy(...args);
+ mocks.query();
+ return mocks.rows;
+ };
+ return { dbRr: chain };
+});
+vi.mock("../services/redis", () => ({
+ getValue: mocks.getValue,
+ setValue: mocks.setValue,
+}));
+
+import { asc } from "drizzle-orm";
+import * as schema from "../db/schema";
+import { billingCountryForTeam } from "./billing-country";
+
+describe("billingCountryForTeam", () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ mocks.orderBy.mockReset();
+ mocks.getValue.mockResolvedValue(null);
+ mocks.setValue.mockResolvedValue(undefined);
+ mocks.query.mockReturnValue(undefined);
+ mocks.rows = [];
+ });
+
+ it("takes the first member with a valid country and caches it", async () => {
+ mocks.rows = [
+ { billing_address: null },
+ { billing_address: { country: "xx1" } },
+ { billing_address: { country: "ZZ" } },
+ { billing_address: { country: " de " } },
+ { billing_address: { country: "FR" } },
+ ];
+ await expect(billingCountryForTeam("team")).resolves.toBe("DE");
+ expect(mocks.setValue).toHaveBeenCalledWith(
+ "billing-country:team",
+ "DE",
+ 3600,
+ );
+ });
+
+ it("asks for the members oldest first", async () => {
+ await billingCountryForTeam("team");
+ expect(mocks.orderBy).toHaveBeenCalledTimes(1);
+ expect(mocks.orderBy.mock.calls[0]).toEqual([
+ asc(schema.user_teams.created_at),
+ ]);
+ });
+
+ it("caches a team with no billing country so it is not queried again", async () => {
+ await expect(billingCountryForTeam("team")).resolves.toBeUndefined();
+ expect(mocks.setValue).toHaveBeenCalledWith(
+ "billing-country:team",
+ "",
+ 3600,
+ );
+ mocks.getValue.mockResolvedValue("");
+ await expect(billingCountryForTeam("team")).resolves.toBeUndefined();
+ expect(mocks.query).toHaveBeenCalledTimes(1);
+ });
+
+ it("serves a cached country without querying", async () => {
+ mocks.getValue.mockResolvedValue("US");
+ await expect(billingCountryForTeam("team")).resolves.toBe("US");
+ expect(mocks.query).not.toHaveBeenCalled();
+ });
+
+ it.each([
+ [
+ "a cache read",
+ () => mocks.getValue.mockRejectedValue(new Error("redis down")),
+ ],
+ [
+ "the query",
+ () =>
+ mocks.orderBy.mockImplementation(() => {
+ throw new Error("db down");
+ }),
+ ],
+ [
+ "a cache write",
+ () => {
+ mocks.rows = [{ billing_address: { country: "DE" } }];
+ mocks.setValue.mockRejectedValue(new Error("redis down"));
+ },
+ ],
+ ])("reads a failed %s as unknown", async (_, fail) => {
+ fail();
+ await expect(billingCountryForTeam("team")).resolves.toBeUndefined();
+ });
+
+ it("reads a lookup that never answers as unknown", async () => {
+ vi.useFakeTimers();
+ try {
+ mocks.getValue.mockReturnValue(new Promise(() => {}));
+ const pending = billingCountryForTeam("team");
+ await vi.advanceTimersByTimeAsync(1000);
+ await expect(pending).resolves.toBeUndefined();
+ } finally {
+ vi.useRealTimers();
+ }
+ });
+});
diff --git a/apps/api/src/lib/billing-country.ts b/apps/api/src/lib/billing-country.ts
new file mode 100644
index 000000000..6b58e8d57
--- /dev/null
+++ b/apps/api/src/lib/billing-country.ts
@@ -0,0 +1,63 @@
+import { asc, eq } from "drizzle-orm";
+import { dbRr } from "../db/connection";
+import * as schema from "../db/schema";
+import { getValue, setValue } from "../services/redis";
+import { logger } from "./logger";
+import { countries } from "./validate-country";
+
+const CACHE_TTL_SECONDS = 60 * 60;
+const LOOKUP_TIMEOUT_MS = 1000;
+const cacheKey = (teamId: string) => `billing-country:${teamId}`;
+
+async function resolve(teamId: string): Promise<string | undefined> {
+ const cached = await getValue(cacheKey(teamId));
+ if (cached !== null) return cached || undefined;
+
+ const rows = await dbRr
+ .select({ billing_address: schema.users.billing_address })
+ .from(schema.user_teams)
+ .innerJoin(schema.users, eq(schema.user_teams.user_id, schema.users.id))
+ .where(eq(schema.user_teams.team_id, teamId))
+ .orderBy(asc(schema.user_teams.created_at));
+
+ let country = "";
+ for (const row of rows) {
+ const candidate = (row.billing_address as { country?: unknown } | null)
+ ?.country;
+ if (typeof candidate !== "string") continue;
+ const upper = candidate.trim().toUpperCase();
+ if (!Object.hasOwn(countries, upper)) continue;
+ country = upper;
+ break;
+ }
+
+ await setValue(cacheKey(teamId), country, CACHE_TTL_SECONDS);
+ return country || undefined;
+}
+
+/**
+ * ISO 3166-1 alpha-2 country on the billing address of the team's longest-standing member that has
+ * one (users.billing_address, copied from the card when a subscription is created), or undefined.
+ * Cached per team. Any failure, or a lookup slower than LOOKUP_TIMEOUT_MS, reads as unknown.
+ */
+export async function billingCountryForTeam(
+ teamId: string,
+): Promise<string | undefined> {
+ let timer: NodeJS.Timeout | undefined;
+ try {
+ return await Promise.race([
+ resolve(teamId),
+ new Promise<undefined>(resolveTimeout => {
+ timer = setTimeout(() => resolveTimeout(undefined), LOOKUP_TIMEOUT_MS);
+ }),
+ ]);
+ } catch (error) {
+ logger.warn("Failed to resolve the team's billing country", {
+ teamId,
+ error,
+ });
+ return undefined;
+ } finally {
+ clearTimeout(timer);
+ }
+}
diff --git a/apps/api/src/routes/exchange.ts b/apps/api/src/routes/exchange.ts
index 9f661cb12..8615a3268 100644
--- a/apps/api/src/routes/exchange.ts
+++ b/apps/api/src/routes/exchange.ts
@@ -1,5 +1,6 @@
import { bountyBlocklistMiddleware } from "./exchange-blocklist";
import { providerScrapeController } from "../controllers/v2/scrape-alexandria";
+import { billingCountryForTeam } from "../lib/billing-country";
import { orgIdFromAcuc } from "../lib/team-org";
import {
acceptProviderTerms,
@@ -75,6 +76,7 @@ function exchangeProxy(
}
const hasBody = req.method !== "GET";
+ const billingCountry = await billingCountryForTeam(authedReq.auth.team_id);
const path = req.originalUrl.replace(/^\/exchange/, "/v1");
try {
@@ -90,6 +92,9 @@ function exchangeProxy(
...(hasBody ? { "content-type": "application/json" } : {}),
"x-exchange-team-id": authedReq.auth.team_id,
...(req.ip ? { "x-exchange-client-ip": req.ip } : {}),
+ ...(billingCountry
+ ? { "x-exchange-billing-country": billingCountry }
+ : {}),
// Built here, never forwarded from the caller: the connectors whitelist is this flag.
...(authedReq.acuc?.flags?.exchangeRetrieve
? { "x-exchange-connectors": "true" }
diff --git a/apps/api/src/services/alexandria/access.ts b/apps/api/src/services/alexandria/access.ts
index 1b9cc86fa..960831a3e 100644
--- a/apps/api/src/services/alexandria/access.ts
+++ b/apps/api/src/services/alexandria/access.ts
@@ -40,6 +40,7 @@ export async function authorizeProviders(
flags: TeamFlags | null | undefined,
orgId: string | null = null,
clientIp?: string,
+ billingCountry?: string,
): Promise<ExchangeResponse | undefined> {
const providers = [...new Set(calls.map(call => call.provider))];
const response = await exchangeRequest({
@@ -48,6 +49,7 @@ export async function authorizeProviders(
body: { providers },
timeoutMs: 10000,
clientIp,
+ billingCountry,
}).catch(() => undefined);
if (response?.status === 404)
return refusal(404, "Unknown provider. No provider was executed.", {
diff --git a/apps/api/src/services/alexandria/client.test.ts b/apps/api/src/services/alexandria/client.test.ts
index 82ee9eea7..5983e01ce 100644
--- a/apps/api/src/services/alexandria/client.test.ts
+++ b/apps/api/src/services/alexandria/client.test.ts
@@ -61,6 +61,26 @@ describe("exchangeRequest", () => {
expect(headersOf()).not.toHaveProperty("x-exchange-client-ip");
});
+ it("sends the billing country only when known", async () => {
+ await exchangeRequest({
+ teamId: "team",
+ path: "/v1/retrieve",
+ body: {},
+ timeoutMs: 1000,
+ billingCountry: "DE",
+ });
+ expect(headersOf()["x-exchange-billing-country"]).toBe("DE");
+
+ mocks.fetch.mockClear();
+ await exchangeRequest({
+ teamId: "team",
+ path: "/v1/retrieve",
+ body: {},
+ timeoutMs: 1000,
+ });
+ expect(headersOf()).not.toHaveProperty("x-exchange-billing-country");
+ });
+
it("sends no connectors grant by default", async () => {
await exchangeRequest({
teamId: "team",
diff --git a/apps/api/src/services/alexandria/client.ts b/apps/api/src/services/alexandria/client.ts
index a2db7fc7d..855f49b9f 100644
--- a/apps/api/src/services/alexandria/client.ts
+++ b/apps/api/src/services/alexandria/client.ts
@@ -19,6 +19,8 @@ export async function exchangeRequest(input: {
termsIdentity?: { organizationId: string; apiKeyId: string };
/** Caller's IP as the API sees it; Exchange resolves what it needs from it. */
clientIp?: string;
+ /** Country on the team's billing address, when it has one. */
+ billingCountry?: string;
/**
* The team may use its own MCP connectors (Alexandria connectors). Sent for teams with the
* `exchangeRetrieve` flag, which is the connectors whitelist; Exchange reads it as the grant.
@@ -47,6 +49,9 @@ export async function exchangeRequest(input: {
: {}),
"x-exchange-extended-catalog-access": "true",
...(input.clientIp ? { "x-exchange-client-ip": input.clientIp } : {}),
+ ...(input.billingCountry
+ ? { "x-exchange-billing-country": input.billingCountry }
+ : {}),
...(input.connectors ? { "x-exchange-connectors": "true" } : {}),
...(input.requestId ? { "x-request-id": input.requestId } : {}),
...(input.maximumCredits === undefined
diff --git a/apps/api/src/services/alexandria/retrieve.ts b/apps/api/src/services/alexandria/retrieve.ts
index b2274c010..2261b6750 100644
--- a/apps/api/src/services/alexandria/retrieve.ts
+++ b/apps/api/src/services/alexandria/retrieve.ts
@@ -95,6 +95,7 @@ export async function retrieveProviders(input: {
bypassBilling?: boolean;
resultAuthorization?: string;
clientIp?: string;
+ billingCountry?: string;
}): Promise<ProviderRetrieval> {
const notExecuted = (response: ExchangeResponse): ProviderRetrieval => ({
...response,
@@ -245,6 +246,7 @@ export async function retrieveProviders(input: {
input.flags,
input.orgId,
input.clientIp,
+ input.billingCountry,
);
if (denied) return refuse(denied);
@@ -269,6 +271,7 @@ export async function retrieveProviders(input: {
body: { requests: input.calls },
timeoutMs: Math.min(10000, remaining()),
clientIp: input.clientIp,
+ billingCountry: input.billingCountry,
connectors: input.flags?.exchangeRetrieve === true,
}).catch(error => {
logger.warn("Provider quote unavailable", { error, chargeId: id });
@@ -396,6 +399,7 @@ export async function retrieveProviders(input: {
timeoutMs: remaining(),
requestId: id,
clientIp: input.clientIp,
+ billingCountry: input.billingCountry,
// The team's own MCP connectors (mcp-...) resolve only when Exchange is told it may use them.
connectors: input.flags?.exchangeRetrieve === true,
// Sent with every execution so Exchange tools that call Firecrawl as the caller