Skip to content

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

34.2 KB
Raw Blame
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();
  });
});