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
import { fetch } from "undici";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { config } from "../config";
import { exchangeRequest } from "../services/alexandria/client";
import {
deserializeTransportableError,
serializeTransportableError,
} from "./error-serde";
import {
canUseExchangeForRequest,
clearExchangeProvidersForTest,
forwardExchangeToolFeedback,
reportExchangeBilling,
getExchangeAccessForRequest,
getExchangeRequestLogContext,
getExchangeResponseLogContext,
getExchangeSuccessCredits,
isSuccessfulExchangeStatusCode,
getUnsupportedExchangeFormat,
resolveExchangeProvider,
setExchangeProvidersForTest,
ThirdPartyDataTermsRequiredError,
ThirdPartyDataUnsupportedOptionError,
} from "./exchange";
import { logger } from "./logger";
vi.mock("undici", () => ({
fetch: vi.fn(),
}));
vi.mock("../services/alexandria/client", () => ({
exchangeRequest: vi.fn(),
}));
const originalConfig = {
FIRE_EXCHANGE_URL: config.FIRE_EXCHANGE_URL,
USE_DB_AUTHENTICATION: config.USE_DB_AUTHENTICATION,
};
const ACME_TERMS = { key: "acme", version: "2026-01-01" };
const TEST_PROVIDERS = [
{
id: "acme",
creditsCost: 12,
terms: ACME_TERMS,
routes: [
{
domains: ["profiles.example", "www.profiles.example"],
pathPrefixes: ["/person/", "/company/"],
},
],
},
{
id: "openfacts",
creditsCost: 0,
routes: [{ domains: ["facts.example"] }],
},
];
const ENABLED_EXCHANGE_FLAGS = {
professionalProfileCompanyDataBeta: true,
organizationDataSourceAccess: {
acme: {
status: "enabled",
termsKey: "acme",
termsVersion: "2026-01-01",
termsAcceptedAt: "2026-01-01T00:00:00.000Z",
enabledAt: "2026-01-01T00:00:00.000Z",
disabledAt: null,
disabledReason: null,
},
},
};
describe("Exchange routing", () => {
beforeEach(() => {
vi.mocked(fetch).mockReset();
config.FIRE_EXCHANGE_URL = "https://exchange.example";
config.USE_DB_AUTHENTICATION = true;
setExchangeProvidersForTest(TEST_PROVIDERS);
});
afterEach(() => {
config.FIRE_EXCHANGE_URL = originalConfig.FIRE_EXCHANGE_URL;
config.USE_DB_AUTHENTICATION = originalConfig.USE_DB_AUTHENTICATION;
clearExchangeProvidersForTest();
});
it("resolves URLs to providers using catalog routes", async () => {
await expect(
resolveExchangeProvider(
"https://profiles.example/person/example-person/details/?trk=foo",
),
).resolves.toMatchObject({ id: "acme", creditsCost: 12 });
await expect(
resolveExchangeProvider("https://www.profiles.example/company/example"),
).resolves.toMatchObject({ id: "acme" });
await expect(
resolveExchangeProvider("https://facts.example/any/path"),
).resolves.toMatchObject({ id: "openfacts" });
await expect(
resolveExchangeProvider("https://profiles.example/jobs/example"),
).resolves.toBeNull();
await expect(
resolveExchangeProvider("https://other.example/person/example"),
).resolves.toBeNull();
await expect(resolveExchangeProvider("not a url")).resolves.toBeNull();
await expect(
resolveExchangeProvider("https://profiles.example/person/example-person"),
).resolves.not.toBeNull();
});
it("respects path segment boundaries for prefixes without trailing slashes", async () => {
setExchangeProvidersForTest([
{
id: "acme",
creditsCost: 12,
routes: [{ domains: ["profiles.example"], pathPrefixes: ["/person"] }],
},
]);
await expect(
resolveExchangeProvider("https://profiles.example/person"),
).resolves.toMatchObject({ id: "acme" });
await expect(
resolveExchangeProvider("https://profiles.example/person/example"),
).resolves.toMatchObject({ id: "acme" });
await expect(
resolveExchangeProvider("https://profiles.example/personality/details"),
).resolves.toBeNull();
await expect(
resolveExchangeProvider("https://profiles.example/personnel"),
).resolves.toBeNull();
});
it("serves the stale catalog while refreshing in the background", async () => {
setExchangeProvidersForTest(TEST_PROVIDERS, -1);
let resolveFetch: (value: unknown) => void = () => {};
vi.mocked(fetch).mockReturnValue(
new Promise(resolve => {
resolveFetch = resolve;
}) as ReturnType<typeof fetch>,
);
// The catalog is expired and the refresh never resolves during the
// request - the stale value must be served without waiting.
await expect(
resolveExchangeProvider("https://profiles.example/person/example"),
).resolves.toMatchObject({ id: "acme" });
expect(fetch).toHaveBeenCalledTimes(1);
resolveFetch({ ok: false, status: 503 });
});
it("keeps serving the last good catalog when a refresh fails", async () => {
setExchangeProvidersForTest(TEST_PROVIDERS, -1);
vi.mocked(fetch).mockResolvedValue({
ok: false,
status: 503,
} as Awaited<ReturnType<typeof fetch>>);
await expect(
resolveExchangeProvider("https://profiles.example/person/example"),
).resolves.toMatchObject({ id: "acme" });
// Let the background refresh settle - the failure must not clobber
// the catalog, and the failure TTL must throttle the next attempt.
await new Promise(resolve => setTimeout(resolve, 0));
await expect(
resolveExchangeProvider("https://profiles.example/person/example"),
).resolves.toMatchObject({ id: "acme" });
expect(fetch).toHaveBeenCalledTimes(1);
});
it("degrades to ineligible when the access check itself throws", async () => {
const explodingFlags = new Proxy(
{},
{
get() {
throw new Error("flags backend exploded");
},
},
) as { professionalProfileCompanyDataBeta?: boolean };
await expect(
getExchangeAccessForRequest({
url: "https://profiles.example/person/example-person",
formats: [{ type: "markdown" }],
flags: explodingFlags,
}),
).resolves.toEqual({ allowed: false, termsRequired: false });
});
it("caches failed provider catalog lookups briefly", async () => {
clearExchangeProvidersForTest();
vi.mocked(fetch).mockResolvedValue({
ok: false,
status: 503,
} as Awaited<ReturnType<typeof fetch>>);
await expect(
resolveExchangeProvider("https://profiles.example/person/example-person"),
).resolves.toBeNull();
await expect(
resolveExchangeProvider("https://profiles.example/person/example-person"),
).resolves.toBeNull();
expect(fetch).toHaveBeenCalledTimes(1);
});
it("parses the provider catalog response", async () => {
clearExchangeProvidersForTest();
vi.mocked(fetch).mockResolvedValue({
ok: true,
status: 200,
json: async () => ({
success: true,
data: [
{
id: "acme",
name: "Acme",
description: "Structured records.",
creditsCost: 12,
terms: ACME_TERMS,
capabilities: {
scrape: {
resourceTypes: ["records"],
includes: [],
urlRoutes: [
{
domains: ["Profiles.Example"],
pathPrefixes: ["person/"],
},
],
},
},
},
{
id: "searchonly",
name: "Search Only",
description: "No scrape routes.",
creditsCost: 0,
capabilities: { search: { modes: ["semantic"] } },
},
],
}),
} as unknown as Awaited<ReturnType<typeof fetch>>);
await expect(
resolveExchangeProvider("https://profiles.example/person/example"),
).resolves.toMatchObject({ id: "acme", terms: ACME_TERMS });
await expect(
resolveExchangeProvider("https://searchonly.example/anything"),
).resolves.toBeNull();
expect(fetch).toHaveBeenCalledTimes(1);
});
it("builds a compact request log context", () => {
expect(
getExchangeRequestLogContext(
"https://profiles.example/person/example-person/details/?trk=foo",
),
).toEqual({
url: "https://profiles.example/person/example-person/details/?trk=foo",
host: "profiles.example",
pathPrefix: "person",
});
expect(getExchangeRequestLogContext("not a url")).toBeUndefined();
// Embedded credentials must never reach the logs.
expect(
getExchangeRequestLogContext(
"https://user:[email protected]/person/example",
),
).toEqual({
url: "https://profiles.example/person/example",
host: "profiles.example",
pathPrefix: "person",
});
});
it("extracts response cache metadata for logs", () => {
expect(
getExchangeResponseLogContext({
cacheState: "hit",
cachedAt: "2026-06-21T10:00:00.000Z",
cacheAgeMs: 1000,
request_id: "req_123",
extra: "ignored",
}),
).toEqual({
cacheState: "hit",
cachedAt: "2026-06-21T10:00:00.000Z",
cacheAgeMs: 1000,
providerRequestId: "req_123",
});
expect(getExchangeResponseLogContext(null)).toEqual({});
});
it("accepts only formats derivable from the Exchange's markdown", () => {
expect(getUnsupportedExchangeFormat(undefined)).toBeNull();
expect(getUnsupportedExchangeFormat([{ type: "markdown" }])).toBeNull();
expect(getUnsupportedExchangeFormat(["json"])).toBeNull();
expect(
getUnsupportedExchangeFormat([{ type: "markdown" }, { type: "json" }]),
).toBeNull();
expect(getUnsupportedExchangeFormat([{ type: "html" }])).toBeNull();
expect(getUnsupportedExchangeFormat([{ type: "screenshot" }])).toBe(
"the `screenshot` format",
);
// deterministicJson extractors run against page HTML, which Exchange
// responses do not carry.
expect(getUnsupportedExchangeFormat([{ type: "deterministicJson" }])).toBe(
"the `deterministicJson` format",
);
expect(getUnsupportedExchangeFormat([])).toBe("`formats`");
});
it("allows eligible requests when access and terms are current", async () => {
await expect(
getExchangeAccessForRequest({
url: "https://profiles.example/person/example-person",
formats: [{ type: "markdown" }],
flags: ENABLED_EXCHANGE_FLAGS,
}),
).resolves.toMatchObject({
allowed: true,
provider: { id: "acme", creditsCost: 12 },
});
await expect(
canUseExchangeForRequest({
url: "https://profiles.example/person/example-person",
formats: [{ type: "json" }],
actions: [{ type: "wait" }],
flags: ENABLED_EXCHANGE_FLAGS,
}),
).resolves.toBe(false);
await expect(
canUseExchangeForRequest({
url: "https://profiles.example/person/example-person",
formats: [{ type: "json" }],
zeroDataRetention: true,
flags: ENABLED_EXCHANGE_FLAGS,
}),
).resolves.toBe(false);
// Profile-backed scrapes expect session-specific content.
await expect(
canUseExchangeForRequest({
url: "https://profiles.example/person/example-person",
formats: [{ type: "markdown" }],
profile: { id: "profile-1" },
flags: ENABLED_EXCHANGE_FLAGS,
}),
).resolves.toBe(false);
// atsv requests stay on engines that support the flag.
await expect(
canUseExchangeForRequest({
url: "https://profiles.example/person/example-person",
formats: [{ type: "markdown" }],
atsv: true,
flags: ENABLED_EXCHANGE_FLAGS,
}),
).resolves.toBe(false);
// minAge asks for Firecrawl-cached data, which the Exchange never has.
await expect(
canUseExchangeForRequest({
url: "https://profiles.example/person/example-person",
formats: [{ type: "markdown" }],
minAge: 3_600_000,
flags: ENABLED_EXCHANGE_FLAGS,
}),
).resolves.toBe(false);
// Selector-based filtering does not apply to provider records.
await expect(
canUseExchangeForRequest({
url: "https://profiles.example/person/example-person",
formats: [{ type: "markdown" }],
includeTags: ["article"],
flags: ENABLED_EXCHANGE_FLAGS,
}),
).resolves.toBe(false);
await expect(
canUseExchangeForRequest({
url: "https://profiles.example/person/example-person",
formats: [{ type: "markdown" }],
excludeTags: ["nav"],
flags: ENABLED_EXCHANGE_FLAGS,
}),
).resolves.toBe(false);
});
it("requires the provider's terms before routing", async () => {
const access = await getExchangeAccessForRequest({
url: "https://profiles.example/person/example-person",
formats: [{ type: "markdown" }],
flags: { professionalProfileCompanyDataBeta: true },
});
expect(access).toEqual({
allowed: false,
termsRequired: true,
terms: ACME_TERMS,
});
const response = new ThirdPartyDataTermsRequiredError(
ACME_TERMS,
).response();
expect(response).toMatchObject({
success: false,
code: "THIRD_PARTY_DATA_TERMS_REQUIRED",
requiresAction: {
type: "accept_terms",
terms: "acme",
version: "2026-01-01",
url: expect.stringMatching(/\/app\/alexandria\/acme$/),
},
});
// The message carries the provider, version and link, since most clients relay only `error`.
expect(response.error).toContain("acme");
expect(response.error).toContain("2026-01-01");
expect(response.error).toContain(response.requiresAction.url);
});
it("requires current terms when the accepted version is stale", async () => {
await expect(
getExchangeAccessForRequest({
url: "https://profiles.example/person/example-person",
formats: [{ type: "markdown" }],
flags: {
professionalProfileCompanyDataBeta: true,
organizationDataSourceAccess: {
acme: {
status: "enabled",
termsKey: "acme",
termsVersion: "2025-12-01",
},
},
},
}),
).resolves.toEqual({
allowed: false,
termsRequired: true,
terms: ACME_TERMS,
});
});
it("does not route or prompt for terms when access is disabled", async () => {
await expect(
getExchangeAccessForRequest({
url: "https://profiles.example/person/example-person",
formats: [{ type: "markdown" }],
flags: {
professionalProfileCompanyDataBeta: true,
organizationDataSourceAccess: {
acme: {
status: "disabled",
termsKey: "acme",
termsVersion: "2026-01-01",
disabledAt: "2026-01-02T00:00:00.000Z",
disabledReason: "customer_disabled",
},
},
},
}),
).resolves.toEqual({ allowed: false, termsRequired: false });
});
it("allows providers with no declared terms without acceptance", async () => {
await expect(
getExchangeAccessForRequest({
url: "https://facts.example/records/1",
formats: [{ type: "markdown" }],
flags: { professionalProfileCompanyDataBeta: true },
}),
).resolves.toMatchObject({ allowed: true, provider: { id: "openfacts" } });
await expect(
getExchangeAccessForRequest({
url: "https://facts.example/records/1",
formats: [{ type: "markdown" }],
flags: {
professionalProfileCompanyDataBeta: true,
organizationDataSourceAccess: {
openfacts: { status: "disabled" },
},
},
}),
).resolves.toEqual({ allowed: false, termsRequired: false });
});
it("requires the beta flag except for blocked URLs", async () => {
await expect(
canUseExchangeForRequest({
url: "https://profiles.example/person/example-person",
formats: [{ type: "markdown" }],
}),
).resolves.toBe(false);
await expect(
canUseExchangeForRequest({
url: "https://profiles.example/person/example-person",
formats: [{ type: "markdown" }],
flags: { professionalProfileCompanyDataBeta: false },
}),
).resolves.toBe(false);
// A blocked URL has no other way to be served, and still needs its terms.
await expect(
canUseExchangeForRequest({
url: "https://facts.example/records/1",
formats: [{ type: "markdown" }],
waitFor: 1000,
blocked: true,
}),
).resolves.toBe(true);
await expect(
getExchangeAccessForRequest({
url: "https://profiles.example/person/example-person",
formats: [{ type: "markdown" }],
blocked: true,
}),
).resolves.toEqual({
allowed: false,
termsRequired: true,
terms: ACME_TERMS,
});
});
it("never routes Exchange-originated requests back to the Exchange", async () => {
const request = {
url: "https://facts.example/records/1",
formats: [{ type: "markdown" }],
flags: { professionalProfileCompanyDataBeta: true },
};
await expect(
canUseExchangeForRequest({ ...request, origin: "api" }),
).resolves.toBe(true);
await expect(
getExchangeAccessForRequest({ ...request, origin: "exchange" }),
).resolves.toEqual({ allowed: false, termsRequired: false });
// A blocked URL stays refused rather than offered to the Exchange.
await expect(
getExchangeAccessForRequest({
...request,
origin: "exchange",
blocked: true,
}),
).resolves.toEqual({ allowed: false, termsRequired: false });
});
it("does not route unless the Exchange is configured", async () => {
config.FIRE_EXCHANGE_URL = undefined;
await expect(
canUseExchangeForRequest({
url: "https://profiles.example/person/example-person",
formats: [{ type: "markdown" }],
flags: ENABLED_EXCHANGE_FLAGS,
}),
).resolves.toBe(false);
});
it("bills the reported credit cost only for successful handled responses", () => {
expect(isSuccessfulExchangeStatusCode(200)).toBe(true);
expect(isSuccessfulExchangeStatusCode(204)).toBe(true);
expect(isSuccessfulExchangeStatusCode(304)).toBe(true);
expect(isSuccessfulExchangeStatusCode(404)).toBe(false);
expect(
getExchangeSuccessCredits({
exchange: {
provider: { id: "acme", creditsCost: 12, steps: [] },
},
statusCode: 200,
}),
).toBe(12);
expect(
getExchangeSuccessCredits({
exchange: {
provider: { id: "acme", creditsCost: 0, steps: [] },
},
statusCode: 304,
}),
).toBe(0);
expect(
getExchangeSuccessCredits({
exchange: {
provider: { id: "acme", creditsCost: 12, steps: [] },
},
statusCode: 404,
}),
).toBeNull();
expect(
getExchangeSuccessCredits({
statusCode: 200,
}),
).toBeNull();
});
it("reports billing outcomes without throwing on service failures", async () => {
vi.mocked(fetch).mockResolvedValue({
ok: true,
status: 200,
} as Awaited<ReturnType<typeof fetch>>);
await expect(
reportExchangeBilling({
accessEventId: "6f1f5aab-3f78-4d0a-8a3d-2b1d3c4e5f60",
status: "confirmed",
billingReference: "bill-1",
}),
).resolves.toBe(true);
expect(fetch).toHaveBeenCalledWith(
"https://exchange.example/v1/access-events/6f1f5aab-3f78-4d0a-8a3d-2b1d3c4e5f60/billing",
expect.objectContaining({
method: "POST",
body: JSON.stringify({
status: "confirmed",
billingReference: "bill-1",
}),
}),
);
await expect(
reportExchangeBilling({
accessEventId: "6f1f5aab-3f78-4d0a-8a3d-2b1d3c4e5f60",
status: "void",
}),
).resolves.toBe(true);
expect(fetch).toHaveBeenLastCalledWith(
"https://exchange.example/v1/access-events/6f1f5aab-3f78-4d0a-8a3d-2b1d3c4e5f60/billing",
expect.objectContaining({
method: "POST",
body: JSON.stringify({ status: "void" }),
}),
);
vi.mocked(fetch).mockRejectedValue(new Error("connect timeout"));
vi.useFakeTimers();
try {
const report = reportExchangeBilling({
accessEventId: "6f1f5aab-3f78-4d0a-8a3d-2b1d3c4e5f60",
status: "confirmed",
billingReference: "bill-1",
});
await vi.runAllTimersAsync();
await expect(report).resolves.toBe(false);
} finally {
vi.useRealTimers();
}
});
it("retries transient billing report failures and stops on definitive rejections", async () => {
vi.mocked(fetch)
.mockResolvedValueOnce({
ok: false,
status: 503,
} as Awaited<ReturnType<typeof fetch>>)
.mockResolvedValueOnce({
ok: true,
status: 200,
} as Awaited<ReturnType<typeof fetch>>);
vi.useFakeTimers();
try {
const report = reportExchangeBilling({
accessEventId: "6f1f5aab-3f78-4d0a-8a3d-2b1d3c4e5f60",
status: "confirmed",
});
await vi.runAllTimersAsync();
await expect(report).resolves.toBe(true);
} finally {
vi.useRealTimers();
}
expect(fetch).toHaveBeenCalledTimes(2);
// 429 is transient rate limiting, not a final answer: it retries.
vi.mocked(fetch).mockClear();
vi.mocked(fetch)
.mockResolvedValueOnce({
ok: false,
status: 429,
headers: new Headers({ "retry-after": "1" }),
} as Awaited<ReturnType<typeof fetch>>)
.mockResolvedValueOnce({
ok: true,
status: 200,
} as Awaited<ReturnType<typeof fetch>>);
vi.useFakeTimers();
try {
const report = reportExchangeBilling({
accessEventId: "6f1f5aab-3f78-4d0a-8a3d-2b1d3c4e5f60",
status: "confirmed",
});
await vi.runAllTimersAsync();
await expect(report).resolves.toBe(true);
} finally {
vi.useRealTimers();
}
expect(fetch).toHaveBeenCalledTimes(2);
// Any other 4xx is the Exchange's final answer (conflict, unknown
// event): no retry, report failure to the caller.
vi.mocked(fetch).mockClear();
vi.mocked(fetch).mockResolvedValue({
ok: false,
status: 409,
} as Awaited<ReturnType<typeof fetch>>);
await expect(
reportExchangeBilling({
accessEventId: "6f1f5aab-3f78-4d0a-8a3d-2b1d3c4e5f60",
status: "void",
}),
).resolves.toBe(false);
expect(fetch).toHaveBeenCalledTimes(1);
});
});
describe("Exchange terms acceptance", () => {
const DIGEST = "a".repeat(64);
const PROFILE_REQUEST = {
url: "https://profiles.example/person/example-person",
formats: [{ type: "markdown" }],
teamId: "team-1",
orgId: "org-1",
};
// Answers the Exchange's requirements and ledger status routes the way
// the acceptance fallback reads them.
function ledgerAnswers(
ledger: {
version: string;
textHash: string;
acceptedAt?: string;
}[],
) {
vi.mocked(exchangeRequest).mockImplementation(async ({ path }) => {
if (path === "/v1/provider-terms/requirements") {
return {
status: 200,
body: {
providers: [
{
provider: "acme",
required: true,
exchangeRequired: false,
terms: { ...ACME_TERMS, digest: DIGEST },
},
],
},
};
}
if (path.startsWith("/v1/provider-terms/status")) {
return {
status: 200,
body: {
providers: ledger.map(entry => ({
provider: "acme",
revoked: false,
acceptedAt: "2026-01-05T00:00:00.000Z",
...entry,
})),
},
};
}
return { status: 404, body: {} };
});
}
beforeEach(() => {
vi.mocked(exchangeRequest).mockReset();
config.FIRE_EXCHANGE_URL = "https://exchange.example";
config.USE_DB_AUTHENTICATION = true;
setExchangeProvidersForTest(TEST_PROVIDERS);
});
afterEach(() => {
config.FIRE_EXCHANGE_URL = originalConfig.FIRE_EXCHANGE_URL;
config.USE_DB_AUTHENTICATION = originalConfig.USE_DB_AUTHENTICATION;
clearExchangeProvidersForTest();
});
it("still gates universal scrape when Exchange acceptance is optional", async () => {
ledgerAnswers([]);
expect(
await getExchangeAccessForRequest({
...PROFILE_REQUEST,
flags: { professionalProfileCompanyDataBeta: true },
}),
).toMatchObject({ allowed: false, termsRequired: true, terms: ACME_TERMS });
});
it("routes when the terms were accepted on the Exchange ledger", async () => {
ledgerAnswers([{ version: ACME_TERMS.version, textHash: DIGEST }]);
const access = await getExchangeAccessForRequest({
...PROFILE_REQUEST,
flags: { professionalProfileCompanyDataBeta: true },
});
expect(access.allowed).toBe(true);
});
it("accepts a ledger entry for the gating version after a non-material text change", async () => {
ledgerAnswers([{ version: ACME_TERMS.version, textHash: "b".repeat(64) }]);
await expect(
getExchangeAccessForRequest({
...PROFILE_REQUEST,
flags: { professionalProfileCompanyDataBeta: true },
}),
).resolves.toMatchObject({ allowed: true });
});
it("does not accept a ledger entry for another terms version", async () => {
ledgerAnswers([{ version: "old", textHash: DIGEST }]);
await expect(
getExchangeAccessForRequest({
...PROFILE_REQUEST,
flags: { professionalProfileCompanyDataBeta: true },
}),
).resolves.toEqual({
allowed: false,
termsRequired: true,
terms: ACME_TERMS,
});
});
it("skips the ledger for requests without an organization", async () => {
ledgerAnswers([{ version: ACME_TERMS.version, textHash: DIGEST }]);
const access = await getExchangeAccessForRequest({
...PROFILE_REQUEST,
orgId: null,
flags: { professionalProfileCompanyDataBeta: true },
});
expect(access).toMatchObject({ allowed: false, termsRequired: true });
expect(exchangeRequest).not.toHaveBeenCalled();
});
it("reads as not accepted when the ledger is unreachable", async () => {
vi.mocked(exchangeRequest).mockRejectedValue(new Error("unreachable"));
await expect(
getExchangeAccessForRequest({
...PROFILE_REQUEST,
flags: { professionalProfileCompanyDataBeta: true },
}),
).resolves.toMatchObject({ allowed: false, termsRequired: true });
});
it("caches ledger answers per organization and provider", async () => {
ledgerAnswers([{ version: ACME_TERMS.version, textHash: DIGEST }]);
const input = {
...PROFILE_REQUEST,
flags: { professionalProfileCompanyDataBeta: true },
};
await getExchangeAccessForRequest(input);
await getExchangeAccessForRequest(input);
// One requirements read and one ledger read, not two of each.
expect(exchangeRequest).toHaveBeenCalledTimes(2);
});
it("does not share cached ledger answers between teams", async () => {
ledgerAnswers([{ version: ACME_TERMS.version, textHash: DIGEST }]);
const flags = { professionalProfileCompanyDataBeta: true };
await getExchangeAccessForRequest({ ...PROFILE_REQUEST, flags });
await getExchangeAccessForRequest({
...PROFILE_REQUEST,
teamId: "team-2",
flags,
});
expect(exchangeRequest).toHaveBeenCalledTimes(4);
});
it("rechecks the ledger once the catalog carries new terms", async () => {
const input = {
...PROFILE_REQUEST,
flags: { professionalProfileCompanyDataBeta: true },
};
ledgerAnswers([{ version: ACME_TERMS.version, textHash: DIGEST }]);
await expect(getExchangeAccessForRequest(input)).resolves.toMatchObject({
allowed: true,
});
// The provider publishes new terms; the ledger still holds the old ones.
const NEW_TERMS = { key: "acme", version: "2026-02-01" };
setExchangeProvidersForTest(
TEST_PROVIDERS.map(provider =>
provider.id === "acme" ? { ...provider, terms: NEW_TERMS } : provider,
),
);
vi.mocked(exchangeRequest).mockImplementation(async ({ path }) =>
path === "/v1/provider-terms/requirements"
? {
status: 200,
body: {
providers: [
{
provider: "acme",
required: true,
terms: { ...NEW_TERMS, digest: "c".repeat(64) },
},
],
},
}
: {
status: 200,
body: {
providers: [
{
provider: "acme",
revoked: false,
version: ACME_TERMS.version,
textHash: DIGEST,
acceptedAt: "2026-01-05T00:00:00.000Z",
},
],
},
},
);
await expect(getExchangeAccessForRequest(input)).resolves.toEqual({
allowed: false,
termsRequired: true,
terms: NEW_TERMS,
});
});
it("asks for terms again after an admin revocation until re-accepted", async () => {
const revokedFlags = {
professionalProfileCompanyDataBeta: true,
organizationDataSourceAccess: {
acme: {
status: "disabled",
termsKey: "acme",
termsVersion: "2026-01-01",
disabledAt: "2026-01-10T00:00:00.000Z",
disabledReason: "revoked_by_organization_admin",
},
},
};
ledgerAnswers([
{
version: ACME_TERMS.version,
textHash: DIGEST,
acceptedAt: "2026-01-05T00:00:00.000Z",
},
]);
await expect(
getExchangeAccessForRequest({ ...PROFILE_REQUEST, flags: revokedFlags }),
).resolves.toEqual({
allowed: false,
termsRequired: true,
terms: ACME_TERMS,
});
clearExchangeProvidersForTest();
setExchangeProvidersForTest(TEST_PROVIDERS);
ledgerAnswers([
{
version: ACME_TERMS.version,
textHash: DIGEST,
acceptedAt: "2026-01-11T00:00:00.000Z",
},
]);
const access = await getExchangeAccessForRequest({
...PROFILE_REQUEST,
flags: revokedFlags,
});
expect(access.allowed).toBe(true);
});
it("carries the unsupported-option response through the worker queue", () => {
const original = new ThirdPartyDataUnsupportedOptionError("`actions`");
const error = deserializeTransportableError(
serializeTransportableError(original),
);
expect(error).toBeInstanceOf(ThirdPartyDataUnsupportedOptionError);
expect((error as ThirdPartyDataUnsupportedOptionError).response()).toEqual(
original.response(),
);
});
it("carries the terms-required response through the worker queue", () => {
const error = deserializeTransportableError(
serializeTransportableError(
new ThirdPartyDataTermsRequiredError(ACME_TERMS),
),
);
expect(error).toBeInstanceOf(ThirdPartyDataTermsRequiredError);
expect((error as ThirdPartyDataTermsRequiredError).response()).toEqual(
new ThirdPartyDataTermsRequiredError(ACME_TERMS).response(),
);
expect(error?.message).toBe(
new ThirdPartyDataTermsRequiredError(ACME_TERMS).response().error,
);
expect((error as ThirdPartyDataTermsRequiredError).requiresAction).toEqual(
new ThirdPartyDataTermsRequiredError(ACME_TERMS).response()
.requiresAction,
);
});
});
describe("Exchange tool feedback forward", () => {
const original = {
url: config.FIRE_EXCHANGE_URL,
secret: config.EXCHANGE_INTERNAL_SECRET,
};
const feedback = {
teamId: "01933161-0000-7000-8000-000000000001",
feedbackId: "01933161-0000-7000-8000-000000000009",
occurredAt: "2026-11-05T12:00:00.000Z",
rating: "bad" as const,
origin: "mcp",
attribution: "token" as const,
calls: [
{
requestId: "req-1",
provider: "fred",
capability: "series",
rating: "good" as const,
},
],
};
beforeEach(() => {
vi.mocked(fetch).mockReset();
config.FIRE_EXCHANGE_URL = "https://exchange.example/";
config.EXCHANGE_INTERNAL_SECRET = "internal-secret";
});
afterEach(() => {
config.FIRE_EXCHANGE_URL = original.url;
config.EXCHANGE_INTERNAL_SECRET = original.secret;
});
it("posts the rating and its calls with the internal secret and team header", async () => {
const info = vi.spyOn(logger, "info");
vi.mocked(fetch).mockResolvedValue({
ok: true,
status: 202,
text: async () => JSON.stringify({ success: true, outcome: "counted" }),
} as unknown as Awaited<ReturnType<typeof fetch>>);
await forwardExchangeToolFeedback(feedback);
expect(info).toHaveBeenCalledWith(
"Exchange tool feedback recorded",
expect.objectContaining({
feedbackId: feedback.feedbackId,
outcome: "counted",
attribution: "token",
calls: 1,
}),
);
info.mockRestore();
expect(fetch).toHaveBeenCalledExactlyOnceWith(
"https://exchange.example/v1/tool-feedback",
expect.objectContaining({
method: "POST",
headers: {
"Content-Type": "application/json",
"x-exchange-secret": "internal-secret",
"x-exchange-team-id": feedback.teamId,
},
signal: expect.any(AbortSignal),
}),
);
expect(
JSON.parse(vi.mocked(fetch).mock.calls[0][1]!.body as string),
).toEqual({
feedbackId: feedback.feedbackId,
occurredAt: feedback.occurredAt,
rating: "bad",
origin: "mcp",
attribution: "token",
calls: feedback.calls,
});
});
it.each(["FIRE_EXCHANGE_URL", "EXCHANGE_INTERNAL_SECRET"] as const)(
"skips the forward without %s",
async key => {
config[key] = undefined as never;
await forwardExchangeToolFeedback(feedback);
expect(fetch).not.toHaveBeenCalled();
},
);
it("resolves on rejected responses and network errors", async () => {
const cancel = vi.fn().mockResolvedValue(undefined);
vi.mocked(fetch).mockResolvedValueOnce({
ok: false,
status: 404,
body: { cancel },
} as unknown as Awaited<ReturnType<typeof fetch>>);
await expect(
forwardExchangeToolFeedback(feedback),
).resolves.toBeUndefined();
expect(cancel).toHaveBeenCalledOnce();
vi.mocked(fetch).mockRejectedValueOnce(new Error("timeout"));
await expect(
forwardExchangeToolFeedback(feedback),
).resolves.toBeUndefined();
});
});