Skip to content

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

feat(api): accept session feedback (#4717)

Maxda74735f532c
diff --git a/apps/api/src/__tests__/snips/v2/alexandria-feedback.test.ts b/apps/api/src/__tests__/snips/v2/alexandria-feedback.test.ts
new file mode 100644
index 000000000..756f49d88
--- /dev/null
+++ b/apps/api/src/__tests__/snips/v2/alexandria-feedback.test.ts
@@ -0,0 +1,161 @@
+import request from "supertest";
+import { eq } from "drizzle-orm";
+import { describeIf, TEST_API_URL, TEST_PRODUCTION } from "../lib";
+import { idmux, Identity } from "./lib";
+import { db } from "../../../db/connection";
+import * as schema from "../../../db/schema";
+
+describeIf(TEST_PRODUCTION)("Alexandria session feedback", () => {
+ let identity: Identity;
+ const body = {
+ endpoint: "alexandria",
+ rating: "partial",
+ requestedWebsite: {
+ url: "https://sam.gov",
+ requestedFunctionality:
+ "Find active contracts by agency and export their attachments as CSV.",
+ },
+ rationale: "Found contract summaries but could not retrieve attachments.",
+ };
+ const submit = (payload: object, apiKey = identity.apiKey) =>
+ request(TEST_API_URL)
+ .post("/v2/feedback")
+ .set("Authorization", `Bearer ${apiKey}`)
+ .send(payload);
+
+ beforeAll(async () => {
+ identity = await idmux({ name: "alexandria-feedback", credits: 1000 });
+ });
+
+ it("records the minimum session feedback without any search or scrape job", async () => {
+ const response = await submit(body);
+ expect(response.statusCode).toBe(200);
+ expect(response.body).toMatchObject({ success: true, creditsRefunded: 0 });
+ expect(response.body.feedbackId).toEqual(expect.any(String));
+ try {
+ const [row] = await db
+ .select()
+ .from(schema.search_feedback)
+ .where(eq(schema.search_feedback.id, response.body.feedbackId));
+ expect(row).toMatchObject({
+ endpoint: "alexandria",
+ team_id: identity.teamId,
+ job_id: null,
+ search_id: null,
+ request_id: null,
+ job_status: null,
+ overall_rating: "partial",
+ comment: body.rationale,
+ credits_refunded: 0,
+ metadata: {
+ endpoint: "alexandria",
+ requestedWebsite: body.requestedWebsite,
+ rationale: body.rationale,
+ },
+ });
+ } finally {
+ await db
+ .delete(schema.search_feedback)
+ .where(eq(schema.search_feedback.id, response.body.feedbackId));
+ }
+ });
+
+ it("persists provider issues and both new and existing capability feedback", async () => {
+ const providerFeedback = [
+ {
+ name: "sam.gov",
+ issue: "insufficient_coverage",
+ why: "The provider returned summaries without attachments.",
+ },
+ ];
+ const capabilityFeedback = [
+ {
+ name: "download-attachments",
+ provider: "sam.gov",
+ issue: "new_capability_request",
+ why: "Need source documents to compare contract requirements.",
+ requestedFunctionality: "Return all attachment URLs for a contract ID.",
+ },
+ {
+ name: "contracts",
+ provider: "sam.gov",
+ issue: "execution_error",
+ why: "The second page request timed out.",
+ },
+ ];
+ const response = await submit({
+ ...body,
+ providerFeedback,
+ capabilityFeedback,
+ integration: "cli",
+ });
+ expect(response.statusCode).toBe(200);
+ try {
+ const [row] = await db
+ .select()
+ .from(schema.search_feedback)
+ .where(eq(schema.search_feedback.id, response.body.feedbackId));
+ expect(row.metadata).toEqual({
+ schemaVersion: 1,
+ endpoint: "alexandria",
+ requestedWebsite: body.requestedWebsite,
+ rationale: body.rationale,
+ providerFeedback,
+ capabilityFeedback,
+ });
+ expect(row.comment).toBe(body.rationale);
+ expect(row.integration).toBe("cli");
+ } finally {
+ await db
+ .delete(schema.search_feedback)
+ .where(eq(schema.search_feedback.id, response.body.feedbackId));
+ }
+ });
+
+ it.each(["endpoint", "rating", "requestedWebsite", "rationale"])(
+ "requires %s",
+ async field => {
+ const response = await submit({ ...body, [field]: undefined });
+ expect(response.statusCode).toBe(400);
+ expect(response.body.feedbackErrorCode).toBe("INVALID_BODY");
+ },
+ );
+
+ it("requires the website functionality brief", async () => {
+ const response = await submit({
+ ...body,
+ requestedWebsite: { url: body.requestedWebsite.url },
+ });
+ expect(response.statusCode).toBe(400);
+ expect(response.body.feedbackErrorCode).toBe("INVALID_BODY");
+ });
+
+ it("requires requested functionality for a new capability request", async () => {
+ const response = await submit({
+ ...body,
+ capabilityFeedback: [
+ {
+ name: "download-attachments",
+ provider: "sam.gov",
+ issue: "new_capability_request",
+ why: "Need the source documents for each contract.",
+ },
+ ],
+ });
+ expect(response.statusCode).toBe(400);
+ expect(response.body.feedbackErrorCode).toBe("INVALID_BODY");
+ });
+
+ it("requires authentication", async () => {
+ const response = await request(TEST_API_URL)
+ .post("/v2/feedback")
+ .send(body);
+ expect(response.statusCode).toBe(401);
+ });
+
+ it("rejects unsupported integration identifiers", async () => {
+ const response = await submit({ ...body, integration: "unsupported" });
+ expect(response.statusCode).toBe(400);
+ expect(response.body.feedbackErrorCode).toBe("INVALID_BODY");
+ });
+});
diff --git a/apps/api/src/controllers/v2/feedback/alexandria-schema.ts b/apps/api/src/controllers/v2/feedback/alexandria-schema.ts
new file mode 100644
index 000000000..fe0226969
--- /dev/null
+++ b/apps/api/src/controllers/v2/feedback/alexandria-schema.ts
@@ -0,0 +1,72 @@
+import { z } from "zod";
+import { integrationSchema } from "../../../utils/integration";
+
+const detail = z.string().trim().min(1).max(2000);
+const name = z.string().trim().min(1).max(200);
+const providerFeedback = z.strictObject({
+ name,
+ issue: z.enum([
+ "missing_provider",
+ "insufficient_coverage",
+ "provider_unavailable",
+ "other",
+ ]),
+ why: detail,
+});
+const capabilityFeedback = z
+ .strictObject({
+ name,
+ provider: name,
+ issue: z.enum([
+ "new_capability_request",
+ "insufficient_functionality",
+ "incorrect_result",
+ "execution_error",
+ "other",
+ ]),
+ why: detail,
+ requestedFunctionality: detail.optional(),
+ })
+ .refine(
+ value =>
+ value.issue !== "new_capability_request" ||
+ value.requestedFunctionality !== undefined,
+ {
+ path: ["requestedFunctionality"],
+ message: "requestedFunctionality is required for new_capability_request",
+ },
+ );
+
+export const alexandriaFeedbackSchema = z
+ .strictObject({
+ endpoint: z.literal("alexandria"),
+ rating: z.enum(["good", "partial", "bad"]),
+ requestedWebsite: z.strictObject({
+ url: z.url({ protocol: /^https?$/ }).max(2048),
+ requestedFunctionality: detail,
+ }),
+ rationale: detail,
+ providerFeedback: z.array(providerFeedback).max(20).optional(),
+ capabilityFeedback: z.array(capabilityFeedback).max(20).optional(),
+ origin: z.string().trim().min(1).max(100).default("api"),
+ integration: z
+ .string()
+ .trim()
+ .min(1)
+ .max(100)
+ .pipe(integrationSchema)
+ .nullable()
+ .optional(),
+ })
+ .refine(
+ // Bound normalized feedback after trimming and applying defaults.
+ value => new TextEncoder().encode(JSON.stringify(value)).length <= 8 * 1024,
+ "Normalized feedback payload must be 8 KiB or smaller",
+ );
+
+export type AlexandriaFeedbackRequest = z.infer<
+ typeof alexandriaFeedbackSchema
+>;
+export type AlexandriaFeedbackRequestInput = z.input<
+ typeof alexandriaFeedbackSchema
+>;
diff --git a/apps/api/src/controllers/v2/feedback/alexandria.integration.test.ts b/apps/api/src/controllers/v2/feedback/alexandria.integration.test.ts
new file mode 100644
index 000000000..a2658deb7
--- /dev/null
+++ b/apps/api/src/controllers/v2/feedback/alexandria.integration.test.ts
@@ -0,0 +1,185 @@
+import express from "express";
+import request from "supertest";
+import { randomUUID } from "node:crypto";
+import { Pool } from "pg";
+import { drizzle } from "drizzle-orm/node-postgres";
+
+const fixture = vi.hoisted(() => ({
+ db: undefined as ReturnType<typeof drizzle> | undefined,
+}));
+vi.mock("../../../db/connection", () => ({ db: fixture.db }));
+vi.mock("./record", () => ({
+ recordEndpointFeedback: () => {
+ throw new Error("Alexandria must not enter the job/refund path");
+ },
+}));
+
+// Opt in with a local database containing the feedback migrations, including
+// the Alexandria endpoint constraint. Each run owns an isolated schema.
+const databaseUrl = process.env.ALEXANDRIA_FEEDBACK_TEST_DATABASE_URL;
+const suite = databaseUrl ? describe : describe.skip;
+suite("Alexandria feedback HTTP and PostgreSQL persistence", () => {
+ const schemaName = `alexandria_feedback_${randomUUID().replaceAll("-", "")}`;
+ const teamId = randomUUID();
+ let pool: Pool;
+ let admin: Pool;
+ let app: express.Express;
+ let config: typeof import("../../../config").config;
+ let originalAuthentication: boolean | undefined;
+ const minimal = {
+ endpoint: "alexandria",
+ rating: "bad",
+ requestedWebsite: {
+ url: "https://sam.gov",
+ requestedFunctionality:
+ "Find active contracts by agency and export their attachments as CSV.",
+ },
+ rationale: "Found contract summaries but could not retrieve attachments.",
+ };
+ const submit = (body: object) => request(app).post("/v2/feedback").send(body);
+
+ beforeAll(async () => {
+ if (
+ !["localhost", "127.0.0.1", "[::1]"].includes(
+ new URL(databaseUrl!).hostname,
+ )
+ ) {
+ throw new Error("Alexandria integration tests require a local database");
+ }
+ admin = new Pool({ connectionString: databaseUrl });
+ await admin.query(`CREATE SCHEMA ${schemaName}`);
+ pool = new Pool({
+ connectionString: databaseUrl,
+ options: `-c search_path=${schemaName},public`,
+ });
+ await pool.query(
+ "CREATE TABLE search_feedback (LIKE public.search_feedback INCLUDING ALL)",
+ );
+ fixture.db = drizzle({ client: pool });
+ config = (await import("../../../config.js")).config;
+ originalAuthentication = config.USE_DB_AUTHENTICATION;
+ config.USE_DB_AUTHENTICATION = true;
+ const { feedbackController } = await import("./controller.js");
+ app = express();
+ app.use(express.json());
+ app.use((req, _res, next) => {
+ Object.assign(req, {
+ auth: { team_id: teamId },
+ acuc: { flags: {}, api_key_id: 42 },
+ });
+ next();
+ });
+ app.post("/v2/feedback", feedbackController as any);
+ });
+
+ afterAll(async () => {
+ if (config) config.USE_DB_AUTHENTICATION = originalAuthentication;
+ await pool?.end();
+ if (admin) {
+ await admin.query(`DROP SCHEMA IF EXISTS ${schemaName} CASCADE`);
+ await admin.end();
+ }
+ });
+
+ it("persists the minimum payload and independent sessions without inventing job IDs", async () => {
+ const first = await submit(minimal);
+ const second = await submit(minimal);
+ expect(first.status).toBe(200);
+ expect(second.status).toBe(200);
+ expect(second.body.feedbackId).not.toBe(first.body.feedbackId);
+ const { rows } = await pool.query(
+ "SELECT * FROM search_feedback WHERE team_id = $1",
+ [teamId],
+ );
+ expect(rows).toHaveLength(2);
+ for (const row of rows) {
+ expect(row).toMatchObject({
+ endpoint: "alexandria",
+ team_id: teamId,
+ overall_rating: "bad",
+ comment: minimal.rationale,
+ job_id: null,
+ search_id: null,
+ request_id: null,
+ job_status: null,
+ credits_refunded: 0,
+ credits_billed: 0,
+ refund_policy: null,
+ metadata: {
+ schemaVersion: 1,
+ endpoint: "alexandria",
+ requestedWebsite: minimal.requestedWebsite,
+ rationale: minimal.rationale,
+ },
+ });
+ }
+ });
+
+ it("round-trips website requirements and provider/capability feedback in existing columns", async () => {
+ const providerFeedback = [
+ {
+ name: "sam.gov",
+ issue: "insufficient_coverage",
+ why: "The provider only returned contract summaries.",
+ },
+ ];
+ const capabilityFeedback = [
+ {
+ name: "download-attachments",
+ provider: "sam.gov",
+ issue: "new_capability_request",
+ why: "Need the source documents to compare contract requirements.",
+ requestedFunctionality:
+ "Given a contract ID, return all attachment URLs and document text.",
+ },
+ {
+ name: "contracts",
+ provider: "sam.gov",
+ issue: "execution_error",
+ why: "The second page request timed out.",
+ },
+ ];
+ const response = await submit({
+ ...minimal,
+ providerFeedback,
+ capabilityFeedback,
+ });
+ expect(response.status).toBe(200);
+ const { rows } = await pool.query(
+ "SELECT metadata, comment, overall_rating, job_id, credits_refunded FROM search_feedback WHERE id = $1",
+ [response.body.feedbackId],
+ );
+ expect(rows[0]).toEqual({
+ overall_rating: minimal.rating,
+ comment: minimal.rationale,
+ job_id: null,
+ credits_refunded: 0,
+ metadata: {
+ schemaVersion: 1,
+ endpoint: "alexandria",
+ requestedWebsite: minimal.requestedWebsite,
+ rationale: minimal.rationale,
+ providerFeedback,
+ capabilityFeedback,
+ },
+ });
+ });
+
+ it("rejects invalid feedback before persistence", async () => {
+ const before = await pool.query("SELECT count(*) FROM search_feedback");
+ const response = await submit({
+ ...minimal,
+ capabilityFeedback: [
+ {
+ name: "download-attachments",
+ provider: "sam.gov",
+ issue: "new_capability_request",
+ why: "Need access to contract attachments.",
+ },
+ ],
+ });
+ expect(response.status).toBe(400);
+ const after = await pool.query("SELECT count(*) FROM search_feedback");
+ expect(after.rows).toEqual(before.rows);
+ });
+});
diff --git a/apps/api/src/controllers/v2/feedback/alexandria.test.ts b/apps/api/src/controllers/v2/feedback/alexandria.test.ts
new file mode 100644
index 000000000..204c91b60
--- /dev/null
+++ b/apps/api/src/controllers/v2/feedback/alexandria.test.ts
@@ -0,0 +1,589 @@
+import express from "express";
+import request from "supertest";
+import { DrizzleQueryError } from "drizzle-orm/errors";
+import { alexandriaFeedbackSchema } from "./alexandria-schema";
+
+const mocks = vi.hoisted(() => ({
+ values: vi.fn(),
+ recordEndpointFeedback: vi.fn(),
+ logError: vi.fn(),
+}));
+vi.mock("../../../db/connection", () => ({
+ db: { insert: () => ({ values: mocks.values }) },
+}));
+vi.mock("../../../lib/logger", () => ({ logger: { error: mocks.logError } }));
+vi.mock("./record", () => ({
+ recordEndpointFeedback: mocks.recordEndpointFeedback,
+}));
+vi.mock("./record-options", () => ({
+ endpointFeedbackRecordOptions: (options: unknown) => options,
+}));
+
+import { config } from "../../../config";
+import { feedbackController } from "./controller";
+
+const minimal = {
+ endpoint: "alexandria",
+ rating: "partial",
+ requestedWebsite: {
+ url: "https://sam.gov",
+ requestedFunctionality:
+ "Find active contracts by agency and export their attachments as CSV.",
+ },
+ rationale: "Found contract summaries but could not retrieve attachments.",
+};
+const teamId = "01933161-0000-7000-8000-000000000001";
+const jobId = "01933161-0000-7000-8000-000000000002";
+const originalDbAuthentication = config.USE_DB_AUTHENTICATION;
+let flags: Record<string, unknown>;
+let authTeam: string;
+const app = express();
+app.use(express.json());
+app.use((req, _res, next) => {
+ Object.assign(req, {
+ auth: { team_id: authTeam },
+ acuc: { api_key_id: 42, flags },
+ });
+ next();
+});
+app.post("/v2/feedback", feedbackController as any);
+const submit = (body: object) => request(app).post("/v2/feedback").send(body);
+
+beforeEach(() => {
+ vi.clearAllMocks();
+ config.USE_DB_AUTHENTICATION = true;
+ authTeam = teamId;
+ flags = {};
+ mocks.values.mockResolvedValue(undefined);
+});
+afterAll(() => {
+ config.USE_DB_AUTHENTICATION = originalDbAuthentication;
+});
+
+it.each(["good", "partial", "bad"])(
+ "records a %s session without job lookup or refund",
+ async rating => {
+ const response = await submit({ ...minimal, rating });
+ expect(response.status).toBe(200);
+ expect(response.body).toEqual({
+ success: true,
+ feedbackId: expect.any(String),
+ creditsRefunded: 0,
+ });
+ expect(mocks.recordEndpointFeedback).not.toHaveBeenCalled();
+ expect(mocks.values).toHaveBeenCalledWith(
+ expect.objectContaining({
+ id: response.body.feedbackId,
+ endpoint: "alexandria",
+ team_id: teamId,
+ api_key_id: 42,
+ overall_rating: rating,
+ comment: minimal.rationale,
+ job_id: null,
+ search_id: null,
+ request_id: null,
+ job_status: null,
+ credits_billed: 0,
+ credits_refunded: 0,
+ refund_policy: null,
+ metadata: {
+ schemaVersion: 1,
+ endpoint: "alexandria",
+ requestedWebsite: minimal.requestedWebsite,
+ rationale: minimal.rationale,
+ },
+ }),
+ );
+ },
+);
+
+it.each(["endpoint", "rating", "requestedWebsite", "rationale"])(
+ "requires %s",
+ async field => {
+ const response = await submit({ ...minimal, [field]: undefined });
+ expect(response.status).toBe(400);
+ expect(response.body.feedbackErrorCode).toBe("INVALID_BODY");
+ expect(mocks.values).not.toHaveBeenCalled();
+ },
+);
+
+it.each(["url", "requestedFunctionality"])(
+ "requires requestedWebsite.%s",
+ async field => {
+ const response = await submit({
+ ...minimal,
+ requestedWebsite: { ...minimal.requestedWebsite, [field]: undefined },
+ });
+ expect(response.status).toBe(400);
+ expect(mocks.values).not.toHaveBeenCalled();
+ },
+);
+
+it("rejects the unpublished categories discriminator", async () => {
+ const response = await submit({
+ ...minimal,
+ endpoint: undefined,
+ categories: ["alexandria"],
+ });
+ expect(response.status).toBe(400);
+ expect(response.body.feedbackErrorCode).toBe("INVALID_BODY");
+ expect(mocks.values).not.toHaveBeenCalled();
+ expect(mocks.recordEndpointFeedback).not.toHaveBeenCalled();
+});
+
+it.each(["search", "scrape", "parse", "map"])(
+ "still requires a job ID for %s feedback",
+ async endpoint => {
+ const response = await submit({
+ endpoint,
+ rating: "bad",
+ missingContent: [{ topic: "Required data" }],
+ });
+ expect(response.status).toBe(400);
+ expect(response.body.feedbackErrorCode).toBe("INVALID_BODY");
+ expect(mocks.values).not.toHaveBeenCalled();
+ expect(mocks.recordEndpointFeedback).not.toHaveBeenCalled();
+ },
+);
+
+it.each([
+ { endpoint: ["alexandria"] },
+ { endpoint: "unknown" },
+ { endpoint: null },
+ { categories: ["alexandria"] },
+ { requestedWebsite: "https://sam.gov" },
+ { requestedWebsite: { ...minimal.requestedWebsite, url: "ftp://sam.gov" } },
+ { requestedWebsite: { ...minimal.requestedWebsite, url: "not a website" } },
+ {
+ requestedWebsite: {
+ ...minimal.requestedWebsite,
+ requestedFunctionality: " ",
+ },
+ },
+ { requestedWebsite: { ...minimal.requestedWebsite, extra: "not allowed" } },
+ { requestedVertical: "government" },
+ { rationale: " " },
+ { rationale: "x".repeat(2001) },
+ { rating: true },
+ { jobId },
+ { endpoint: "search", jobId },
+ { extra: "not allowed" },
+ { search: [] },
+ { scrape: [] },
+ { task: "Find current contracts" },
+ { assessment: "The response was incomplete." },
+ {
+ providerFeedback: { name: "sam.gov", issue: "other", why: "Slow response" },
+ },
+ {
+ providerFeedback: [
+ { issue: "missing_provider", why: "Need contract attachments" },
+ ],
+ },
+ { providerFeedback: [{ name: "sam.gov", why: "Need contract attachments" }] },
+ { providerFeedback: [{ name: "sam.gov", issue: "missing_provider" }] },
+ {
+ providerFeedback: [
+ {
+ name: " ",
+ issue: "missing_provider",
+ why: "Need contract attachments",
+ },
+ ],
+ },
+ {
+ providerFeedback: [
+ { name: "sam.gov", issue: "execution_error", why: "Request failed" },
+ ],
+ },
+ { providerFeedback: [{ name: "sam.gov", issue: "other", why: " " }] },
+ {
+ providerFeedback: [
+ { name: "sam.gov", issue: "other", why: "Request failed", extra: true },
+ ],
+ },
+ {
+ capabilityFeedback: [
+ {
+ provider: "sam.gov",
+ issue: "execution_error",
+ why: "Request timed out",
+ },
+ ],
+ },
+ {
+ capabilityFeedback: [
+ { name: "contracts", issue: "execution_error", why: "Request timed out" },
+ ],
+ },
+ {
+ capabilityFeedback: [
+ { name: "contracts", provider: "sam.gov", why: "Request timed out" },
+ ],
+ },
+ {
+ capabilityFeedback: [
+ { name: "contracts", provider: "sam.gov", issue: "execution_error" },
+ ],
+ },
+ {
+ capabilityFeedback: [
+ {
+ name: "contracts",
+ provider: "sam.gov",
+ issue: "missing_provider",
+ why: "No matching tool",
+ },
+ ],
+ },
+ {
+ capabilityFeedback: [
+ {
+ name: "contracts",
+ provider: "sam.gov",
+ issue: "other",
+ why: "Request failed",
+ extra: true,
+ },
+ ],
+ },
+])("rejects malformed feedback %j", async fields => {
+ const response = await submit({ ...minimal, ...fields });
+ expect(response.status).toBe(400);
+ expect(response.body.feedbackErrorCode).toBe("INVALID_BODY");
+ expect(mocks.values).not.toHaveBeenCalled();
+ expect(mocks.recordEndpointFeedback).not.toHaveBeenCalled();
+});
+
+it("preserves website requirements and provider/capability feedback for the session", async () => {
+ const evidence = {
+ providerFeedback: [
+ {
+ name: "sam.gov",
+ issue: "insufficient_coverage",
+ why: "The provider returns summaries without attachments.",
+ },
+ ],
+ capabilityFeedback: [
+ {
+ name: "download-attachments",
+ provider: "sam.gov",
+ issue: "new_capability_request",
+ why: "Need the source documents to compare contract requirements.",
+ requestedFunctionality:
+ "Given a contract ID, return all attachment URLs and document text.",
+ },
+ {
+ name: "contracts",
+ provider: "sam.gov",
+ issue: "execution_error",
+ why: "The second page request returned a timeout.",
+ },
+ ],
+ };
+ const response = await submit({ ...minimal, ...evidence });
+ expect(response.status).toBe(200);
+ expect(mocks.values).toHaveBeenCalledWith(
+ expect.objectContaining({
+ metadata: expect.objectContaining(evidence),
+ }),
+ );
+});
+
+it.each([
+ "missing_provider",
+ "insufficient_coverage",
+ "provider_unavailable",
+ "other",
+])(
+ "accepts provider issue %s independently of capability feedback",
+ async issue => {
+ const providerFeedback = [
+ { name: "sam.gov", issue, why: "Need complete contract data." },
+ ];
+ expect((await submit({ ...minimal, providerFeedback })).status).toBe(200);
+ expect(mocks.values).toHaveBeenCalledWith(
+ expect.objectContaining({
+ metadata: expect.objectContaining({ providerFeedback }),
+ }),
+ );
+ },
+);
+
+it.each([
+ "insufficient_functionality",
+ "incorrect_result",
+ "execution_error",
+ "other",
+])(
+ "accepts capability issue %s with or without requested functionality",
+ async issue => {
+ for (const requestedFunctionality of [
+ undefined,
+ "Return the complete contract data as CSV.",
+ ]) {
+ const capabilityFeedback = [
+ {
+ name: "contracts",
+ provider: "sam.gov",
+ issue,
+ why: "The returned data did not satisfy the request.",
+ ...(requestedFunctionality ? { requestedFunctionality } : {}),
+ },
+ ];
+ expect((await submit({ ...minimal, capabilityFeedback })).status).toBe(
+ 200,
+ );
+ expect(mocks.values).toHaveBeenLastCalledWith(
+ expect.objectContaining({
+ metadata: expect.objectContaining({ capabilityFeedback }),
+ }),
+ );
+ }
+ },
+);
+
+it.each([undefined, "", " "])(
+ "requires nonempty functionality for a new capability request: %j",
+ async requestedFunctionality => {
+ const payload = {
+ ...minimal,
+ capabilityFeedback: [
+ {
+ name: "download-attachments",
+ provider: "sam.gov",
+ issue: "new_capability_request",
+ why: "Need the source contract documents.",
+ requestedFunctionality,
+ },
+ ],
+ };
+ expect((await submit(payload)).status).toBe(400);
+ expect(mocks.values).not.toHaveBeenCalled();
+ const parsed = alexandriaFeedbackSchema.safeParse(payload);
+ expect(parsed.success).toBe(false);
+ if (!parsed.success) {
+ expect(parsed.error.issues).toContainEqual(
+ expect.objectContaining({
+ path: ["capabilityFeedback", 0, "requestedFunctionality"],
+ }),
+ );
+ }
+ },
+);
+
+it("allows omitted or empty optional feedback arrays", async () => {
+ for (const fields of [
+ {},
+ { providerFeedback: [] },
+ { capabilityFeedback: [] },
+ ]) {
+ expect((await submit({ ...minimal, ...fields })).status).toBe(200);
+ }
+});
+
+it.each([
+ [undefined, null],
+ [null, null],
+ ["cli", "cli"],
+ [" cli ", "cli"],
+ ["_custom", "_custom"],
+ ["_" + "x".repeat(99), "_" + "x".repeat(99)],
+])("accepts and normalizes integration %j", async (integration, expected) => {
+ expect((await submit({ ...minimal, integration })).status).toBe(200);
+ expect(mocks.values).toHaveBeenCalledWith(
+ expect.objectContaining({ integration: expected }),
+ );
+});
+
+it.each(["unsupported", " ", "_" + "x".repeat(100)])(
+ "rejects invalid integration %j before persistence",
+ async integration => {
+ const response = await submit({ ...minimal, integration });
+ expect(response.status).toBe(400);
+ expect(response.body.feedbackErrorCode).toBe("INVALID_BODY");
+ expect(mocks.values).not.toHaveBeenCalled();
+ },
+);
+
+it.each(["providerFeedback", "capabilityFeedback"])(
+ "accepts 20 entries and rejects 21 in %s",
+ async field => {
+ const entry = {
+ name: "contracts",
+ issue: "other",
+ why: "Incomplete",
+ ...(field === "capabilityFeedback" ? { provider: "sam.gov" } : {}),
+ };
+ for (const length of [20, 21]) {
+ mocks.values.mockClear();
+ const response = await submit({
+ ...minimal,
+ [field]: Array.from({ length }, () => ({ ...entry })),
+ });
+ expect(response.status).toBe(length === 20 ? 200 : 400);
+ expect(mocks.values).toHaveBeenCalledTimes(length === 20 ? 1 : 0);
+ }
+ },
+);
+
+it.each([
+ ["providerFeedback", "name", 200],
+ ["providerFeedback", "why", 2000],
+ ["capabilityFeedback", "name", 200],
+ ["capabilityFeedback", "provider", 200],
+ ["capabilityFeedback", "why", 2000],
+ ["capabilityFeedback", "requestedFunctionality", 2000],
+] as const)("bounds %s.%s to %i characters", async (array, field, limit) => {
+ const entry = {
+ name: "contracts",
+ issue: "other",
+ why: "Incomplete",
+ ...(array === "capabilityFeedback" ? { provider: "sam.gov" } : {}),
+ };
+ for (const length of [limit, limit + 1]) {
+ mocks.values.mockClear();
+ const response = await submit({
+ ...minimal,
+ [array]: [{ ...entry, [field]: "x".repeat(length) }],
+ });
+ expect(response.status).toBe(length === limit ? 200 : 400);
+ expect(mocks.values).toHaveBeenCalledTimes(length === limit ? 1 : 0);
+ }
+});
+
+it("limits website URLs to 2048 characters and accepts HTTP and HTTPS", async () => {
+ for (const protocol of ["http", "https"]) {
+ const prefix = `${protocol}://example.com/`;
+ for (const length of [2048, 2049]) {
+ const response = await submit({
+ ...minimal,
+ requestedWebsite: {
+ ...minimal.requestedWebsite,
+ url: prefix + "x".repeat(length - prefix.length),
+ },
+ });
+ expect(response.status).toBe(length === 2048 ? 200 : 400);
+ }
+ }
+});
+
+it("bounds the complete UTF-8 evidence payload", async () => {
+ const response = await submit({
+ ...minimal,
+ providerFeedback: Array.from({ length: 4 }, () => ({
+ name: "sam.gov",
+ issue: "insufficient_coverage",
+ why: "界".repeat(1000),
+ })),
+ });
+ expect(response.status).toBe(400);
+ expect(mocks.values).not.toHaveBeenCalled();
+});
+
+it("applies the payload limit after normalizing feedback", async () => {
+ const response = await submit({
+ ...minimal,
+ rationale: " ".repeat(9 * 1024) + minimal.rationale,
+ });
+ expect(response.status).toBe(200);
+ expect(mocks.values).toHaveBeenCalledWith(
+ expect.objectContaining({ comment: minimal.rationale }),
+ );
+});
+
+it.each([
+ { forceZDR: true },
+ { scrapeZDR: "forced" },
+ { searchZDR: "forced" },
+ { searchZDR: "forced-zdr" },
+ { searchZDR: "forced-anon" },
+])("skips persistence for forced retention flags %j", async teamFlags => {
+ flags = teamFlags;
+ const response = await submit(minimal);
+ expect(response.status).toBe(200);
+ expect(response.body.feedbackId).toBe("00000000-0000-0000-0000-000000000000");
+ expect(mocks.values).not.toHaveBeenCalled();
+});
+
+it("honors team opt-out", async () => {
+ flags = { searchFeedbackOptOut: true };
+ const response = await submit(minimal);
+ expect(response.status).toBe(403);
+ expect(response.body.feedbackErrorCode).toBe("TEAM_OPTED_OUT");
+ expect(mocks.values).not.toHaveBeenCalled();
+});
+
+it.each(["preview", "preview_example", "preview_keyless_example"])(
+ "rejects preview team %s",
+ async team => {
+ authTeam = team;
+ const response = await submit(minimal);
+ expect(response.status).toBe(403);
+ expect(response.body.feedbackErrorCode).toBe("PREVIEW_TEAM_NOT_ALLOWED");
+ expect(mocks.values).not.toHaveBeenCalled();
+ },
+);
+
+it("rejects deployments without database authentication", async () => {
+ config.USE_DB_AUTHENTICATION = false;
+ const response = await submit(minimal);
+ expect(response.status).toBe(503);
+ expect(response.body.feedbackErrorCode).toBe("DB_DISABLED");
+ expect(mocks.values).not.toHaveBeenCalled();
+});
+
+it.each([
+ [new Error("sensitive database query payload"), null],
+ [Object.assign(new Error("sensitive detail"), { code: "23514" }), "23514"],
+ [
+ new DrizzleQueryError(
+ "INSERT INTO search_feedback VALUES ($1)",
+ ["sensitive feedback payload"],
+ Object.assign(new Error("sensitive database detail"), { code: "23514" }),
+ ),
+ "23514",
+ ],
+ [{ code: "sensitive database detail" }, null],
+ [{ code: { detail: "sensitive feedback payload" } }, null],
+ [null, null],
+])("logs only SQLSTATE on persistence failure %#", async (error, errorCode) => {
+ mocks.values.mockRejectedValueOnce(error);
+ const response = await submit(minimal);
+ expect(response.status).toBe(500);
+ expect(response.body).toEqual({
+ success: false,
+ feedbackErrorCode: "INTERNAL",
+ error: "Failed to record feedback.",
+ });
+ expect(mocks.logError).toHaveBeenCalledExactlyOnceWith(
+ "Failed to record Alexandria feedback",
+ { feedbackId: expect.any(String), errorCode },
+ );
+ expect(JSON.stringify(mocks.logError.mock.calls)).not.toContain("sensitive");
+ expect(mocks.recordEndpointFeedback).not.toHaveBeenCalled();
+});
+
+it.each(["search", "scrape", "parse", "map"])(
+ "preserves the existing %s job feedback path",
+ async endpoint => {
+ mocks.recordEndpointFeedback.mockResolvedValueOnce({
+ status: 200,
+ body: { success: true, feedbackId: jobId, creditsRefunded: 1 },
+ });
+ const response = await submit({
+ endpoint,
+ jobId,
+ rating: "bad",
+ note: "The expected page content was missing.",
+ missingContent: [{ topic: "Required data" }],
+ });
+ expect(response.status).toBe(200);
+ expect(response.body.creditsRefunded).toBe(1);
+ expect(mocks.recordEndpointFeedback).toHaveBeenCalledWith(
+ expect.anything(),
+ expect.objectContaining({ endpoint, jobId }),
+ );
+ expect(mocks.values).not.toHaveBeenCalled();
+ },
+);
diff --git a/apps/api/src/controllers/v2/feedback/alexandria.ts b/apps/api/src/controllers/v2/feedback/alexandria.ts
new file mode 100644
index 000000000..317a3b097
--- /dev/null
+++ b/apps/api/src/controllers/v2/feedback/alexandria.ts
@@ -0,0 +1,107 @@
+import { v7 as uuidv7 } from "uuid";
+import { DrizzleQueryError } from "drizzle-orm/errors";
+import { config } from "../../../config";
+import { db } from "../../../db/connection";
+import * as schema from "../../../db/schema";
+import { logger } from "../../../lib/logger";
+import { getScrapeZDR, getSearchZDR } from "../../../lib/zdr-helpers";
+import type { RequestWithAuth, EndpointFeedbackErrorCode } from "../types";
+import type { FeedbackRecordResult } from "./internal-types";
+import type { AlexandriaFeedbackRequest } from "./alexandria-schema";
+
+const failure = (
+ status: number,
+ feedbackErrorCode: EndpointFeedbackErrorCode,
+ error: string,
+): FeedbackRecordResult => ({
+ status,
+ body: { success: false, feedbackErrorCode, error },
+});
+
+export async function recordAlexandriaFeedback(
+ req: RequestWithAuth<any, any, any>,
+ body: AlexandriaFeedbackRequest,
+): Promise<FeedbackRecordResult> {
+ if (!config.USE_DB_AUTHENTICATION) {
+ return failure(
+ 503,
+ "DB_DISABLED",
+ "Feedback requires database authentication.",
+ );
+ }
+ const teamId = req.auth.team_id;
+ if (teamId === "preview" || teamId.startsWith("preview_")) {
+ return failure(
+ 403,
+ "PREVIEW_TEAM_NOT_ALLOWED",
+ "Feedback is not available for preview teams.",
+ );
+ }
+ if (req.acuc?.flags?.searchFeedbackOptOut === true) {
+ return failure(
+ 403,
+ "TEAM_OPTED_OUT",
+ "Feedback is disabled for this team. Contact [email protected] to re-enable.",
+ );
+ }
+
+ // A session can contain both search and scrape data. Honor either forced
+ // retention policy without looking up or recording individual jobs.
+ const searchZdr = getSearchZDR(req.acuc?.flags);
+ if (
+ getScrapeZDR(req.acuc?.flags) === "forced" ||
+ searchZdr === "forced-zdr" ||
+ searchZdr === "forced-anon"
+ ) {
+ return {
+ status: 200,
+ body: {
+ success: true,
+ feedbackId: "00000000-0000-0000-0000-000000000000",
+ creditsRefunded: 0,
+ },
+ };
+ }
+
+ const feedbackId = uuidv7();
+ const { rating, origin, integration, ...metadata } = body;
+ try {
+ await db.insert(schema.search_feedback).values({
+ id: feedbackId,
+ endpoint: "alexandria",
+ team_id: teamId,
+ api_key_id: req.acuc?.api_key_id ?? null,
+ search_id: null,
+ job_id: null,
+ request_id: null,
+ job_status: null,
+ api_version: "v2",
+ overall_rating: rating,
+ comment: body.rationale,
+ metadata: { schemaVersion: 1, ...metadata },
+ origin,
+ integration: integration ?? null,
+ credits_billed: 0,
+ credits_refunded: 0,
+ refund_policy: null,
+ });
+ } catch (error) {
+ // Database errors may embed the submitted payload. Keep feedback content
+ // out of logs; only retain the underlying PostgreSQL SQLSTATE.
+ const cause = error instanceof DrizzleQueryError ? error.cause : error;
+ const code =
+ cause !== null && typeof cause === "object" && "code" in cause
+ ? cause.code
+ : undefined;
+ logger.error("Failed to record Alexandria feedback", {
+ feedbackId,
+ errorCode:
+ typeof code === "string" && /^[0-9A-Z]{5}$/.test(code) ? code : null,
+ });
+ return failure(500, "INTERNAL", "Failed to record feedback.");
+ }
+ return {
+ status: 200,
+ body: { success: true, feedbackId, creditsRefunded: 0 },
+ };
+}
diff --git a/apps/api/src/controllers/v2/feedback/controller.ts b/apps/api/src/controllers/v2/feedback/controller.ts
index 1114aed0e..2859ed80f 100644
--- a/apps/api/src/controllers/v2/feedback/controller.ts
+++ b/apps/api/src/controllers/v2/feedback/controller.ts
@@ -9,14 +9,28 @@ import {
import { recordEndpointFeedback } from "./record";
import { endpointFeedbackRecordOptions } from "./record-options";
import { toFeedbackInput } from "./request-input";
+import {
+ alexandriaFeedbackSchema,
+ AlexandriaFeedbackRequest,
+} from "./alexandria-schema";
+import { recordAlexandriaFeedback } from "./alexandria";
+
+const feedbackSchema = z.union([
+ alexandriaFeedbackSchema,
+ endpointFeedbackSchema,
+]);
export async function feedbackController(
- req: RequestWithAuth<{}, EndpointFeedbackResponse, EndpointFeedbackRequest>,
+ req: RequestWithAuth<
+ {},
+ EndpointFeedbackResponse,
+ EndpointFeedbackRequest | AlexandriaFeedbackRequest
+ >,
res: Response<EndpointFeedbackResponse>,
) {
- let parsedBody: EndpointFeedbackRequest;
+ let parsedBody: EndpointFeedbackRequest | AlexandriaFeedbackRequest;
try {
- parsedBody = endpointFeedbackSchema.parse(req.body);
+ parsedBody = feedbackSchema.parse(req.body);
} catch (error) {
if (error instanceof z.ZodError) {
return res.status(400).json({
@@ -29,6 +43,11 @@ export async function feedbackController(
throw error;
}
+ if (parsedBody.endpoint === "alexandria") {
+ const result = await recordAlexandriaFeedback(req, parsedBody);
+ return res.status(result.status).json(result.body);
+ }
+
const result = await recordEndpointFeedback(
req,
endpointFeedbackRecordOptions({
diff --git a/apps/api/src/controllers/v2/feedback/feedback-window.test.ts b/apps/api/src/controllers/v2/feedback/feedback-window.test.ts
new file mode 100644
index 000000000..8b2c96d67
--- /dev/null
+++ b/apps/api/src/controllers/v2/feedback/feedback-window.test.ts
@@ -0,0 +1,207 @@
+import express from "express";
+import request from "supertest";
+import type { FeedbackJobRow } from "./internal-types";
+
+const fixture = vi.hoisted(() => ({
+ job: undefined as FeedbackJobRow | undefined,
+ lookup: vi.fn(),
+ insert: vi.fn(),
+ alexandriaInsert: vi.fn(),
+ refund: vi.fn(),
+ refundedToday: vi.fn(),
+}));
+vi.mock("./feedback-store", () => ({
+ lookupFeedbackJob: fixture.lookup,
+ insertFeedback: fixture.insert,
+ findExistingFeedback: async () => ({
+ id: "already-recorded",
+ credits_refunded: 1,
+ }),
+ updateFeedbackRefundDetails: async () => null,
+}));
+vi.mock("../../../db/connection", () => ({
+ db: { insert: () => ({ values: fixture.alexandriaInsert }) },
+}));
+vi.mock("./refund-totals", () => ({
+ sumCreditsRefundedToday: fixture.refundedToday,
+}));
+vi.mock("../../../services/autumn/autumn.service", () => ({
+ SEARCH_CREDITS_FEATURE_ID: "SEARCH_CREDITS",
+ featureIdForBillingEndpoint: (endpoint: string) =>
+ endpoint === "search" ? "SEARCH_CREDITS" : "CREDITS",
+ autumnService: { refundCredits: fixture.refund },
+}));
+
+import { config } from "../../../config";
+import { feedbackController } from "./controller";
+import { searchFeedbackController } from "../search-feedback";
+
+const original = { ...config };
+const jobId = "01933161-0000-7000-8000-000000000001";
+const teamId = "01933161-0000-7000-8000-000000000002";
+const now = Date.now();
+const app = express();
+app.use(express.json());
+app.use((req, _res, next) => {
+ Object.assign(req, {
+ auth: { team_id: teamId },
+ acuc: { flags: {}, org_id: "test-org" },
+ });
+ next();
+});
+app.post("/v2/feedback", feedbackController as any);
+app.post("/v2/search/:jobId/feedback", searchFeedbackController as any);
+
+type Route = "legacy-search" | "search" | "scrape" | "parse" | "map";
+const routes: Route[] = ["legacy-search", "search", "scrape", "parse", "map"];
+const stores = ["postgres", "bigtable"] as const;
+const submit = (route: Route) =>
+ request(app)
+ .post(
+ route === "legacy-search"
+ ? `/v2/search/${jobId}/feedback`
+ : "/v2/feedback",
+ )
+ .send({
+ ...(route === "legacy-search" ? {} : { endpoint: route, jobId }),
+ rating: "bad",
+ ...(route === "search" || route === "legacy-search"
+ ? { missingContent: [{ topic: "Contract attachments" }] }
+ : { note: "The returned content was incomplete." }),
+ });
+
+function job(route: Route, store: (typeof stores)[number], ageSec: number) {
+ const endpoint = route === "legacy-search" ? "search" : route;
+ const window =
+ endpoint === "search"
+ ? config.SEARCH_FEEDBACK_MAX_AGE_SEC
+ : config.FEEDBACK_MAX_AGE_SEC;
+ fixture.job = {
+ id: jobId,
+ request_id: jobId,
+ endpoint,
+ team_id: teamId,
+ credits_cost: 2,
+ is_successful: true,
+ options: {},
+ created_at: new Date(now - ageSec * 1000).toISOString(),
+ ...(store === "bigtable"
+ ? {
+ feedback_deadline_ms: now + (window - ageSec) * 1000,
+ zero_data_retention: false,
+ }
+ : {}),
+ };
+}
+
+beforeEach(() => {
+ vi.clearAllMocks();
+ vi.spyOn(Date, "now").mockReturnValue(now);
+ Object.assign(config, original, {
+ USE_DB_AUTHENTICATION: true,
+ FEEDBACK_REFUND_ENABLED: true,
+ SEARCH_FEEDBACK_MAX_AGE_SEC: 120,
+ FEEDBACK_MAX_AGE_SEC: 120,
+ });
+ fixture.job = undefined;
+ fixture.lookup.mockImplementation(
+ async (endpoint: string, id: string, team: string) =>
+ fixture.job?.endpoint === endpoint &&
+ fixture.job.id === id &&
+ fixture.job.team_id === team
+ ? fixture.job
+ : null,
+ );
+ fixture.insert.mockResolvedValue(null);
+ fixture.alexandriaInsert.mockResolvedValue(undefined);
+ fixture.refundedToday.mockResolvedValue(0);
+});
+afterEach(() => {
+ vi.restoreAllMocks();
+ Object.assign(config, original);
+});
+
+describe.each(routes)("%s job feedback keeps its submission window", route => {
+ it.each(stores)(
+ "accepts %s feedback before the 120-second deadline",
+ async store => {
+ job(route, store, 119);
+ expect((await submit(route)).status).toBe(200);
+ expect(fixture.lookup).toHaveBeenCalledWith(
+ route === "legacy-search" ? "search" : route,
+ jobId,
+ teamId,
+ );
+ expect(fixture.insert).toHaveBeenCalledTimes(1);
+ expect(fixture.alexandriaInsert).not.toHaveBeenCalled();
+ },
+ );
+
+ it.each(stores)(
+ "rejects %s feedback after the 120-second deadline",
+ async store => {
+ job(route, store, 121);
+ const response = await submit(route);
+ expect(response.status).toBe(409);
+ expect(response.body.feedbackErrorCode).toBe("FEEDBACK_WINDOW_EXPIRED");
+ expect(fixture.insert).not.toHaveBeenCalled();
+ expect(fixture.refund).not.toHaveBeenCalled();
+ expect(fixture.alexandriaInsert).not.toHaveBeenCalled();
+ },
+ );
+
+ it("honors the stored Bigtable deadline even for a recently created job", async () => {
+ job(route, "bigtable", 1);
+ fixture.job!.feedback_deadline_ms = now - 1;
+ expect((await submit(route)).body.feedbackErrorCode).toBe(
+ "FEEDBACK_WINDOW_EXPIRED",
+ );
+ expect(fixture.insert).not.toHaveBeenCalled();
+ expect(fixture.refund).not.toHaveBeenCalled();
+ });
+});
+
+it.each(stores)(
+ "accepts Alexandria feedback when the session's original %s search has expired",
+ async store => {
+ job("search", store, 30 * 60);
+ const expiredSearch = await submit("search");
+ expect(expiredSearch.status).toBe(409);
+ expect(expiredSearch.body.feedbackErrorCode).toBe(
+ "FEEDBACK_WINDOW_EXPIRED",
+ );
+ expect(fixture.lookup).toHaveBeenCalledTimes(1);
+ fixture.lookup.mockClear();
+
+ const response = await request(app)
+ .post("/v2/feedback")
+ .send({
+ endpoint: "alexandria",
+ rating: "partial",
+ requestedWebsite: {
+ url: "https://example.com",
+ requestedFunctionality: "Retrieve records and their attachments.",
+ },
+ rationale: "Found record summaries but could not retrieve attachments.",
+ });
+
+ expect(response.status).toBe(200);
+ expect(response.body).toEqual({
+ success: true,
+ feedbackId: expect.any(String),
+ creditsRefunded: 0,
+ });
+ expect(fixture.lookup).not.toHaveBeenCalled();
+ expect(fixture.insert).not.toHaveBeenCalled();
+ expect(fixture.refund).not.toHaveBeenCalled();
+ expect(fixture.alexandriaInsert).toHaveBeenCalledWith(
+ expect.objectContaining({
+ endpoint: "alexandria",
+ search_id: null,
+ job_id: null,
+ request_id: null,
+ credits_refunded: 0,
+ }),
+ );
+ },
+);