Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. πŸ”₯

(feat/search) Search feedback (#3537)

Nicolas6ad113446383
diff --git a/apps/api/src/__tests__/snips/v2/lib.ts b/apps/api/src/__tests__/snips/v2/lib.ts
index 1e5583f71..f647bfc6e 100644
--- a/apps/api/src/__tests__/snips/v2/lib.ts
+++ b/apps/api/src/__tests__/snips/v2/lib.ts
@@ -13,6 +13,7 @@ import {
MapRequestInput,
BatchScrapeRequestInput,
SearchRequestInput,
+ SearchFeedbackRequestInput,
ParseRequestInput,
} from "../../../controllers/v2/types";
import request from "supertest";
@@ -612,6 +613,73 @@ export async function searchWithFailure(
return raw.body;
}
+export async function searchRawFull(
+ body: SearchRequestInput,
+ identity: Identity,
+) {
+ return await request(TEST_API_URL)
+ .post("/v2/search")
+ .set("Authorization", `Bearer ${identity.apiKey}`)
+ .set("Content-Type", "application/json")
+ .send(body);
+}
+
+export async function searchFeedbackRaw(
+ searchId: string,
+ body: SearchFeedbackRequestInput,
+ identity: Identity,
+) {
+ return await request(TEST_API_URL)
+ .post("/v2/search/" + encodeURIComponent(searchId) + "/feedback")
+ .set("Authorization", `Bearer ${identity.apiKey}`)
+ .set("Content-Type", "application/json")
+ .send(body);
+}
+
+export async function searchFeedback(
+ searchId: string,
+ body: SearchFeedbackRequestInput,
+ identity: Identity,
+): Promise<{
+ success: true;
+ feedbackId: string;
+ creditsRefunded: number;
+ creditsRefundedToday?: number;
+ dailyRefundCap?: number;
+ dailyCapReached?: boolean;
+ alreadySubmitted?: boolean;
+ warning?: string;
+}> {
+ const raw = await searchFeedbackRaw(searchId, body, identity);
+ if (raw.statusCode !== 200) {
+ console.warn(
+ "Search feedback did not succeed",
+ JSON.stringify(raw.body, null, 2),
+ );
+ }
+ expect(raw.statusCode).toBe(200);
+ expect(raw.body.success).toBe(true);
+ expect(typeof raw.body.feedbackId).toBe("string");
+ expect(typeof raw.body.creditsRefunded).toBe("number");
+ return raw.body;
+}
+
+export async function searchFeedbackWithFailure(
+ searchId: string,
+ body: SearchFeedbackRequestInput,
+ identity: Identity,
+): Promise<{
+ success: false;
+ error: string;
+ details?: unknown;
+}> {
+ const raw = await searchFeedbackRaw(searchId, body, identity);
+ expect(raw.statusCode).not.toBe(200);
+ expect(raw.body.success).toBe(false);
+ expect(typeof raw.body.error).toBe("string");
+ return raw.body;
+}
+
// =========================================
// Billing API
// =========================================
diff --git a/apps/api/src/__tests__/snips/v2/search-feedback.test.ts b/apps/api/src/__tests__/snips/v2/search-feedback.test.ts
new file mode 100644
index 000000000..a36288a94
--- /dev/null
+++ b/apps/api/src/__tests__/snips/v2/search-feedback.test.ts
@@ -0,0 +1,452 @@
+import { describeIf, TEST_PRODUCTION } from "../lib";
+import {
+ searchRawFull,
+ searchFeedback,
+ searchFeedbackRaw,
+ searchFeedbackWithFailure,
+ idmux,
+ Identity,
+} from "./lib";
+import { supabase_service } from "../../../services/supabase";
+
+let identity: Identity;
+let secondaryIdentity: Identity;
+
+beforeAll(async () => {
+ identity = await idmux({
+ name: "search-feedback",
+ concurrency: 100,
+ credits: 1000000,
+ });
+ secondaryIdentity = await idmux({
+ name: "search-feedback-other",
+ concurrency: 100,
+ credits: 1000000,
+ });
+}, 20000);
+
+// Skipped in self-hosted mode: depends on Supabase for the `searches` row
+// lookup, Autumn for credit refunds, and the per-team daily refund cap β€”
+// none of which exist in self-hosted setups.
+describeIf(TEST_PRODUCTION)(
+ "Search feedback tests",
+ () => {
+ it.concurrent(
+ "records feedback and refunds 1 credit on first submission",
+ async () => {
+ const raw = await searchRawFull(
+ { query: "firecrawl", limit: 3 },
+ identity,
+ );
+ expect(raw.statusCode).toBe(200);
+ expect(typeof raw.body.id).toBe("string");
+ expect((raw.body.data?.web ?? []).length).toBeGreaterThan(0);
+
+ const result = await searchFeedback(
+ raw.body.id,
+ {
+ rating: "good",
+ valuableSources: [
+ {
+ url: raw.body.data.web[0].url,
+ reason: "Most directly answered the question.",
+ },
+ ],
+ missingContent: [
+ {
+ topic: "Enterprise pricing",
+ description:
+ "Pricing tier table for the Enterprise plan was not in any result.",
+ },
+ {
+ topic: "SLA terms",
+ description: "Uptime SLA and support SLAs not surfaced.",
+ },
+ ],
+ querySuggestions:
+ "Include site:firecrawl.dev when the user mentions firecrawl by name.",
+ },
+ identity,
+ );
+
+ expect(result.success).toBe(true);
+ expect(result.creditsRefunded).toBe(1);
+ expect(result.alreadySubmitted).toBeFalsy();
+ expect(typeof result.feedbackId).toBe("string");
+ },
+ 90000,
+ );
+
+ it.concurrent(
+ "is idempotent β€” second submission returns 0 refund",
+ async () => {
+ const raw = await searchRawFull(
+ { query: "firecrawl docs", limit: 3 },
+ identity,
+ );
+ expect(raw.statusCode).toBe(200);
+ expect(typeof raw.body.id).toBe("string");
+
+ const first = await searchFeedback(
+ raw.body.id,
+ {
+ rating: "partial",
+ missingContent: [
+ { topic: "Recent results", description: "Nothing past 2024." },
+ ],
+ },
+ identity,
+ );
+ expect(first.creditsRefunded).toBe(1);
+
+ const second = await searchFeedback(
+ raw.body.id,
+ {
+ rating: "bad",
+ missingContent: [
+ { topic: "Recent results", description: "Still nothing past 2024." },
+ ],
+ },
+ identity,
+ );
+ expect(second.creditsRefunded).toBe(0);
+ expect(second.alreadySubmitted).toBe(true);
+ },
+ 90000,
+ );
+
+ it.concurrent(
+ "rejects feedback for a search owned by another team",
+ async () => {
+ const raw = await searchRawFull(
+ { query: "firecrawl api", limit: 3 },
+ identity,
+ );
+ expect(raw.statusCode).toBe(200);
+ const searchId = raw.body.id;
+
+ const failed = await searchFeedbackWithFailure(
+ searchId,
+ {
+ rating: "good",
+ valuableSources: [{ url: "https://firecrawl.dev/" }],
+ },
+ secondaryIdentity,
+ );
+ expect(failed.error.toLowerCase()).toContain("not found");
+ expect((failed as any).feedbackErrorCode).toBe("SEARCH_NOT_FOUND");
+ },
+ 90000,
+ );
+
+ it.concurrent(
+ "rejects feedback for a non-existent search id",
+ async () => {
+ const failed = await searchFeedbackWithFailure(
+ "00000000-0000-7000-8000-000000000000",
+ {
+ rating: "bad",
+ missingContent: [{ topic: "Anything at all" }],
+ },
+ identity,
+ );
+ expect(failed.error.toLowerCase()).toContain("not found");
+ expect((failed as any).feedbackErrorCode).toBe("SEARCH_NOT_FOUND");
+ },
+ 30000,
+ );
+
+ it.concurrent(
+ "rejects an invalid jobId format with 400",
+ async () => {
+ const raw = await searchFeedbackRaw(
+ "not-a-uuid",
+ {
+ rating: "good",
+ valuableSources: [{ url: "https://firecrawl.dev/" }],
+ },
+ identity,
+ );
+ expect(raw.statusCode).toBe(400);
+ expect(raw.body.success).toBe(false);
+ },
+ 30000,
+ );
+
+ it.concurrent(
+ "rejects an invalid rating value",
+ async () => {
+ const raw = await searchRawFull(
+ { query: "firecrawl", limit: 3 },
+ identity,
+ );
+ expect(raw.statusCode).toBe(200);
+
+ const failed = await searchFeedbackRaw(
+ raw.body.id,
+ { rating: "amazing" as any },
+ identity,
+ );
+ expect(failed.statusCode).toBe(400);
+ expect(failed.body.success).toBe(false);
+ },
+ 90000,
+ );
+
+ it.concurrent(
+ "rejects feedback with a non-http URL in valuableSources",
+ async () => {
+ const raw = await searchRawFull(
+ { query: "firecrawl", limit: 3 },
+ identity,
+ );
+ expect(raw.statusCode).toBe(200);
+
+ const failed = await searchFeedbackRaw(
+ raw.body.id,
+ {
+ rating: "good",
+ valuableSources: [
+ { url: "ftp://example.com/file", reason: "valuable" },
+ ],
+ },
+ identity,
+ );
+ expect(failed.statusCode).toBe(400);
+ expect(failed.body.success).toBe(false);
+ },
+ 90000,
+ );
+
+ it.concurrent(
+ "rejects 'good' rating without any valuableSources",
+ async () => {
+ const raw = await searchRawFull(
+ { query: "firecrawl", limit: 3 },
+ identity,
+ );
+ expect(raw.statusCode).toBe(200);
+
+ const failed = await searchFeedbackRaw(
+ raw.body.id,
+ {
+ rating: "good",
+ missingContent: [
+ { topic: "Irrelevant for good rating" },
+ ],
+ },
+ identity,
+ );
+ expect(failed.statusCode).toBe(400);
+ expect(failed.body.success).toBe(false);
+ expect(String(failed.body.error).toLowerCase()).toContain(
+ "substantive",
+ );
+ },
+ 90000,
+ );
+
+ it.concurrent(
+ "rejects 'partial' rating with no sources and no missing content",
+ async () => {
+ const raw = await searchRawFull(
+ { query: "firecrawl", limit: 3 },
+ identity,
+ );
+ expect(raw.statusCode).toBe(200);
+
+ const failed = await searchFeedbackRaw(
+ raw.body.id,
+ { rating: "partial" },
+ identity,
+ );
+ expect(failed.statusCode).toBe(400);
+ expect(failed.body.success).toBe(false);
+ },
+ 90000,
+ );
+
+ it.concurrent(
+ "rejects 'bad' rating with no missing content or query suggestions",
+ async () => {
+ const raw = await searchRawFull(
+ { query: "firecrawl", limit: 3 },
+ identity,
+ );
+ expect(raw.statusCode).toBe(200);
+
+ const failed = await searchFeedbackRaw(
+ raw.body.id,
+ {
+ rating: "bad",
+ valuableSources: [{ url: "https://firecrawl.dev/" }],
+ },
+ identity,
+ );
+ expect(failed.statusCode).toBe(400);
+ expect(failed.body.success).toBe(false);
+ },
+ 90000,
+ );
+
+ it.concurrent(
+ "rejects missingContent entries without a topic",
+ async () => {
+ const raw = await searchRawFull(
+ { query: "firecrawl", limit: 3 },
+ identity,
+ );
+ expect(raw.statusCode).toBe(200);
+
+ const failed = await searchFeedbackRaw(
+ raw.body.id,
+ {
+ rating: "bad",
+ // @ts-expect-error testing invalid shape
+ missingContent: [{ description: "no topic supplied" }],
+ },
+ identity,
+ );
+ expect(failed.statusCode).toBe(400);
+ expect(failed.body.success).toBe(false);
+ },
+ 90000,
+ );
+
+ it.concurrent(
+ "accepts a structured 'partial' rating with multiple missing topics",
+ async () => {
+ const raw = await searchRawFull(
+ { query: "firecrawl pricing", limit: 3 },
+ identity,
+ );
+ expect(raw.statusCode).toBe(200);
+
+ const result = await searchFeedback(
+ raw.body.id,
+ {
+ rating: "partial",
+ missingContent: [
+ {
+ topic: "Enterprise pricing",
+ description:
+ "Pricing tier table for Enterprise was not surfaced.",
+ },
+ { topic: "Self-hosted pricing" },
+ {
+ topic: "Annual discount",
+ description: "Annual vs monthly discount comparison.",
+ },
+ ],
+ },
+ identity,
+ );
+
+ expect(result.success).toBe(true);
+ expect(result.creditsRefunded).toBe(1);
+ },
+ 90000,
+ );
+
+ // TEAM_OPTED_OUT (server-side opt-out via searchFeedbackOptOut flag)
+ // is not covered by E2E because idmux identities can't set ACUC flags.
+
+ it.concurrent(
+ "stops refunding once the team's daily refund cap is reached",
+ async () => {
+ const cappedIdentity = await idmux({
+ name: "search-feedback-cap",
+ concurrency: 100,
+ credits: 1000000,
+ });
+
+ const dailyCap = 100;
+
+ const seedSearchId =
+ "00000000-0000-7000-8000-" +
+ Math.floor(Math.random() * 1e12)
+ .toString(16)
+ .padStart(12, "0");
+ const { error: seedErr } = await supabase_service
+ .from("search_feedback")
+ .insert({
+ search_id: seedSearchId,
+ team_id: cappedIdentity.teamId,
+ overall_rating: "good",
+ valuable_sources: [{ url: "https://firecrawl.dev/" }],
+ missing_content: [],
+ integration: null,
+ origin: "test-seed",
+ credits_refunded: dailyCap,
+ });
+ expect(seedErr).toBeFalsy();
+
+ // Now do a real search and submit feedback.
+ const raw = await searchRawFull(
+ { query: "firecrawl daily cap", limit: 3 },
+ cappedIdentity,
+ );
+ expect(raw.statusCode).toBe(200);
+
+ const result = await searchFeedback(
+ raw.body.id,
+ {
+ rating: "good",
+ valuableSources: [{ url: raw.body.data.web[0].url }],
+ },
+ cappedIdentity,
+ );
+
+ expect(result.success).toBe(true);
+ expect(result.creditsRefunded).toBe(0);
+ expect(result.dailyCapReached).toBe(true);
+ expect(result.creditsRefundedToday).toBeGreaterThanOrEqual(dailyCap);
+ expect(result.dailyRefundCap).toBe(dailyCap);
+ expect(String(result.warning ?? "").toLowerCase()).toContain(
+ "daily refund cap",
+ );
+
+ await supabase_service
+ .from("search_feedback")
+ .delete()
+ .eq("search_id", seedSearchId);
+ },
+ 120000,
+ );
+
+ // Back-date the searches row so we don't have to wait the full window.
+ it.concurrent(
+ "rejects feedback submitted outside the configured time window",
+ async () => {
+ const raw = await searchRawFull(
+ { query: "firecrawl windowed", limit: 3 },
+ identity,
+ );
+ expect(raw.statusCode).toBe(200);
+ const searchId = raw.body.id;
+
+ await new Promise(r => setTimeout(r, 750));
+ const aged = new Date(Date.now() - 60 * 60 * 1000).toISOString();
+ const { error: updateErr } = await supabase_service
+ .from("searches")
+ .update({ created_at: aged })
+ .eq("id", searchId)
+ .eq("team_id", identity.teamId);
+ expect(updateErr).toBeFalsy();
+
+ const failed = await searchFeedbackWithFailure(
+ searchId,
+ {
+ rating: "good",
+ valuableSources: [{ url: "https://firecrawl.dev/" }],
+ },
+ identity,
+ );
+ expect((failed as any).feedbackErrorCode).toBe(
+ "FEEDBACK_WINDOW_EXPIRED",
+ );
+ },
+ 90000,
+ );
+ },
+);
diff --git a/apps/api/src/config.ts b/apps/api/src/config.ts
index d58732f99..907b57c9b 100644
--- a/apps/api/src/config.ts
+++ b/apps/api/src/config.ts
@@ -63,6 +63,8 @@ const configSchema = z.object({
PREVIEW_TOKEN: z.string().optional(),
SEARCH_PREVIEW_TOKEN: z.string().optional(),
SEARCH_SERVICE_API_SECRET: z.string().optional(),
+ SEARCH_FEEDBACK_MAX_AGE_SEC: z.coerce.number().int().positive().default(120),
+ SEARCH_FEEDBACK_DAILY_CAP_CREDITS: z.coerce.number().int().nonnegative().default(100),
// Database & Storage
POSTGRES_HOST: z.string().default("localhost"),
diff --git a/apps/api/src/controllers/v0/search.ts b/apps/api/src/controllers/v0/search.ts
index d9955b398..c43bd4162 100644
--- a/apps/api/src/controllers/v0/search.ts
+++ b/apps/api/src/controllers/v0/search.ts
@@ -81,16 +81,17 @@ async function searchHelper(
);
if (justSearch) {
+ const searchCredits = Math.ceil(res.length / 10) * 2;
billTeam(
team_id,
subscription_id,
- res.length,
+ searchCredits,
api_key_id,
{ endpoint: "search", jobId },
logger,
).catch(error => {
logger.error(
- `Failed to bill team ${team_id} for ${res.length} credits: ${error}`,
+ `Failed to bill team ${team_id} for ${searchCredits} credits: ${error}`,
);
// Optionally, you could notify an admin or add to a retry queue here
});
@@ -264,7 +265,7 @@ export async function searchController(req: Request, res: Response) {
options: searchOptions,
credits_cost: pageOptions.fetchPageContent
? 0
- : (result.data?.length ?? 0),
+ : Math.ceil((result.data?.length ?? 0) / 10) * 2,
zeroDataRetention: false, // not supported
});
return res.status(result.returnCode).json(result);
diff --git a/apps/api/src/controllers/v1/types.ts b/apps/api/src/controllers/v1/types.ts
index 478a1b541..14cae4fd4 100644
--- a/apps/api/src/controllers/v1/types.ts
+++ b/apps/api/src/controllers/v1/types.ts
@@ -1299,6 +1299,8 @@ export type TeamFlags = {
bypassCreditChecks?: boolean;
debugBranding?: boolean;
maxBrowserSessions?: number;
+ // POST /v2/search/:jobId/feedback returns 403 TEAM_OPTED_OUT when true.
+ searchFeedbackOptOut?: boolean;
} | null;
export type AuthCreditUsageChunkFromTeam = Omit<
diff --git a/apps/api/src/controllers/v2/search-feedback.ts b/apps/api/src/controllers/v2/search-feedback.ts
new file mode 100644
index 000000000..17969f117
--- /dev/null
+++ b/apps/api/src/controllers/v2/search-feedback.ts
@@ -0,0 +1,391 @@
+import { Response } from "express";
+import { v7 as uuidv7 } from "uuid";
+import { z } from "zod";
+import { config } from "../../config";
+import { logger as _logger } from "../../lib/logger";
+import { autumnService } from "../../services/autumn/autumn.service";
+import {
+ isPostgrestNoRowsError,
+ supabase_service,
+ supabase_rr_service,
+} from "../../services/supabase";
+import { captureExceptionWithZdrCheck } from "../../services/sentry";
+import {
+ RequestWithAuth,
+ SearchFeedbackErrorCode,
+ SearchFeedbackRequest,
+ SearchFeedbackResponse,
+ searchFeedbackSchema,
+} from "./types";
+
+export const SEARCH_FEEDBACK_REFUND_CREDITS = 1;
+
+// Must match the previewTeamId in services/logging/log_job.ts.
+const PREVIEW_TEAM_ID = "3adefd26-77ec-5968-8dcf-c94b5630d1de";
+
+const POSTGRES_UNIQUE_VIOLATION = "23505";
+
+// logSearch in the search controller is fire-and-forget; this retry covers
+// the gap when feedback arrives before the searches row has been inserted.
+const SEARCH_LOOKUP_RACE_RETRY_MS = 250;
+
+type FailReason = {
+ status: number;
+ code: SearchFeedbackErrorCode;
+ error: string;
+};
+
+function fail(
+ res: Response<SearchFeedbackResponse>,
+ reason: FailReason,
+): Response<SearchFeedbackResponse> {
+ return res.status(reason.status).json({
+ success: false,
+ error: reason.error,
+ feedbackErrorCode: reason.code,
+ });
+}
+
+function isPreviewTeam(teamId: string): boolean {
+ return teamId === "preview" || teamId.startsWith("preview_");
+}
+
+function normalizeTeamId(teamId: string): string {
+ return isPreviewTeam(teamId) ? PREVIEW_TEAM_ID : teamId;
+}
+
+type SearchRowForFeedback = {
+ id: string;
+ team_id: string;
+ credits_cost: number | null;
+ created_at: string;
+ is_successful: boolean | null;
+};
+
+async function lookupSearchRow(
+ searchId: string,
+ dbTeamId: string,
+): Promise<SearchRowForFeedback | null> {
+ const { data, error } = await supabase_rr_service
+ .from("searches")
+ .select("id, team_id, credits_cost, created_at, is_successful")
+ .eq("id", searchId)
+ .eq("team_id", dbTeamId)
+ .single();
+
+ if (error) {
+ if (isPostgrestNoRowsError(error)) return null;
+ throw error;
+ }
+ return data as SearchRowForFeedback | null;
+}
+
+function startOfUtcDay(now: Date = new Date()): Date {
+ const start = new Date(now.getTime());
+ start.setUTCHours(0, 0, 0, 0);
+ return start;
+}
+
+// Best-effort: on DB error we return 0 rather than block legitimate
+// refunds; overshoot is bounded by the rate limiter.
+async function sumTeamCreditsRefundedToday(
+ dbTeamId: string,
+ logger: ReturnType<typeof _logger.child>,
+): Promise<number> {
+ const since = startOfUtcDay().toISOString();
+
+ const { data, error } = await supabase_rr_service
+ .from("search_feedback")
+ .select("credits_refunded")
+ .eq("team_id", dbTeamId)
+ .gte("created_at", since);
+
+ if (error) {
+ logger.warn(
+ "Failed to compute today's refund total; allowing refund this call",
+ { error },
+ );
+ return 0;
+ }
+
+ return (data ?? []).reduce(
+ (sum, row: { credits_refunded: number | null }) =>
+ sum + (row.credits_refunded ?? 0),
+ 0,
+ );
+}
+
+export async function searchFeedbackController(
+ req: RequestWithAuth<
+ { jobId: string },
+ SearchFeedbackResponse,
+ SearchFeedbackRequest
+ >,
+ res: Response<SearchFeedbackResponse>,
+) {
+ const searchId = req.params.jobId;
+ const logger = _logger.child({
+ module: "api/v2",
+ method: "searchFeedbackController",
+ searchId,
+ teamId: req.auth.team_id,
+ });
+
+ let parsedBody: SearchFeedbackRequest;
+ try {
+ parsedBody = searchFeedbackSchema.parse(req.body);
+ } catch (error) {
+ if (error instanceof z.ZodError) {
+ logger.warn("Invalid feedback body", { error: error.issues });
+ return res.status(400).json({
+ success: false,
+ error: "Invalid request body",
+ details: error.issues,
+ feedbackErrorCode: "INVALID_BODY",
+ });
+ }
+ throw error;
+ }
+
+ if (config.USE_DB_AUTHENTICATION !== true) {
+ return fail(res, {
+ status: 503,
+ code: "DB_DISABLED",
+ error:
+ "Search feedback requires database authentication and is unavailable on this deployment.",
+ });
+ }
+
+ // Preview tenants share one team_id in the searches table, so one
+ // preview agent could otherwise submit feedback on another's searches.
+ if (isPreviewTeam(req.auth.team_id)) {
+ return fail(res, {
+ status: 403,
+ code: "PREVIEW_TEAM_NOT_ALLOWED",
+ error: "Search feedback is not available for preview teams.",
+ });
+ }
+
+ if (req.acuc?.flags?.searchFeedbackOptOut === true) {
+ logger.info("Rejected feedback: team opted out");
+ return fail(res, {
+ status: 403,
+ code: "TEAM_OPTED_OUT",
+ error:
+ "Search feedback is disabled for this team. Contact [email protected] to re-enable.",
+ });
+ }
+
+ const dbTeamId = normalizeTeamId(req.auth.team_id);
+
+ try {
+ let searchRow: SearchRowForFeedback | null;
+ try {
+ searchRow = await lookupSearchRow(searchId, dbTeamId);
+ if (!searchRow) {
+ await new Promise(resolve =>
+ setTimeout(resolve, SEARCH_LOOKUP_RACE_RETRY_MS),
+ );
+ searchRow = await lookupSearchRow(searchId, dbTeamId);
+ }
+ } catch (lookupErr) {
+ logger.error("Failed to look up search for feedback", {
+ error: lookupErr,
+ });
+ return fail(res, {
+ status: 500,
+ code: "INTERNAL",
+ error: "Failed to look up search.",
+ });
+ }
+
+ if (!searchRow) {
+ return fail(res, {
+ status: 404,
+ code: "SEARCH_NOT_FOUND",
+ error: "Search not found for this team.",
+ });
+ }
+
+ if (searchRow.is_successful === false) {
+ return fail(res, {
+ status: 409,
+ code: "SEARCH_FAILED",
+ error:
+ "Cannot submit feedback for a search that did not succeed.",
+ });
+ }
+
+ const maxAgeMs = config.SEARCH_FEEDBACK_MAX_AGE_SEC * 1000;
+ const createdAtMs = new Date(searchRow.created_at).getTime();
+ if (Number.isNaN(createdAtMs)) {
+ logger.warn("Search row had unparseable created_at", {
+ created_at: searchRow.created_at,
+ });
+ } else {
+ const ageMs = Date.now() - createdAtMs;
+ if (ageMs > maxAgeMs) {
+ logger.info("Rejected feedback outside time window", {
+ ageMs,
+ maxAgeMs,
+ });
+ return fail(res, {
+ status: 409,
+ code: "FEEDBACK_WINDOW_EXPIRED",
+ error: `Search feedback must be submitted within ${config.SEARCH_FEEDBACK_MAX_AGE_SEC} seconds of the search.`,
+ });
+ }
+ }
+
+ const feedbackId = uuidv7();
+ const { error: insertErr } = await supabase_service
+ .from("search_feedback")
+ .insert({
+ id: feedbackId,
+ search_id: searchId,
+ team_id: dbTeamId,
+ overall_rating: parsedBody.rating,
+ valuable_sources: parsedBody.valuableSources ?? [],
+ missing_content: parsedBody.missingContent ?? [],
+ query_suggestions: parsedBody.querySuggestions ?? null,
+ integration: parsedBody.integration ?? null,
+ origin: parsedBody.origin ?? null,
+ credits_refunded: 0,
+ });
+
+ if (insertErr) {
+ if ((insertErr as { code?: string }).code === POSTGRES_UNIQUE_VIOLATION) {
+ const { data: existing } = await supabase_rr_service
+ .from("search_feedback")
+ .select("id, credits_refunded")
+ .eq("search_id", searchId)
+ .single();
+
+ const dailyCapForResponse = config.SEARCH_FEEDBACK_DAILY_CAP_CREDITS;
+ const refundedTodayForResponse = await sumTeamCreditsRefundedToday(
+ dbTeamId,
+ logger,
+ );
+
+ return res.status(200).json({
+ success: true,
+ feedbackId: existing?.id ?? "",
+ creditsRefunded: 0,
+ alreadySubmitted: true,
+ creditsRefundedToday: refundedTodayForResponse,
+ dailyRefundCap: dailyCapForResponse,
+ warning:
+ "Feedback was already submitted for this search; no additional refund issued.",
+ });
+ }
+
+ logger.error("Failed to insert search feedback", { error: insertErr });
+ return fail(res, {
+ status: 500,
+ code: "INTERNAL",
+ error: "Failed to record feedback.",
+ });
+ }
+
+ // The just-inserted row has credits_refunded=0, so reading the SUM
+ // here is safe whether or not it shows up in the read replica yet.
+ const dailyCap = config.SEARCH_FEEDBACK_DAILY_CAP_CREDITS;
+ const refundedTodayBefore = await sumTeamCreditsRefundedToday(
+ dbTeamId,
+ logger,
+ );
+ const remainingDailyCap = Math.max(0, dailyCap - refundedTodayBefore);
+
+ let creditsRefunded = 0;
+ let dailyCapReached = false;
+ const billedCredits = searchRow.credits_cost ?? 0;
+
+ const desiredRefund = Math.min(
+ SEARCH_FEEDBACK_REFUND_CREDITS,
+ billedCredits,
+ );
+ const cappedRefund = Math.min(desiredRefund, remainingDailyCap);
+
+ if (billedCredits > 0 && desiredRefund > 0 && cappedRefund === 0) {
+ dailyCapReached = true;
+ logger.info(
+ "Daily refund cap reached for team; feedback recorded with zero refund",
+ {
+ dailyCap,
+ refundedTodayBefore,
+ },
+ );
+ } else if (cappedRefund > 0) {
+ try {
+ await autumnService.refundCredits({
+ teamId: req.auth.team_id,
+ value: cappedRefund,
+ properties: {
+ source: "search_feedback",
+ endpoint: "search",
+ jobId: searchId,
+ feedbackId,
+ rating: parsedBody.rating,
+ },
+ });
+ creditsRefunded = cappedRefund;
+ } catch (error) {
+ logger.error("Search feedback refund failed; feedback retained", {
+ error,
+ });
+ }
+
+ if (creditsRefunded > 0) {
+ const { error: updateErr } = await supabase_service
+ .from("search_feedback")
+ .update({ credits_refunded: creditsRefunded })
+ .eq("id", feedbackId);
+ if (updateErr) {
+ logger.warn(
+ "Failed to persist credits_refunded on search_feedback row",
+ { error: updateErr, feedbackId, creditsRefunded },
+ );
+ }
+ }
+ }
+
+ const creditsRefundedToday = refundedTodayBefore + creditsRefunded;
+ if (!dailyCapReached && creditsRefundedToday >= dailyCap && dailyCap > 0) {
+ dailyCapReached = true;
+ }
+
+ logger.info("Search feedback recorded", {
+ feedbackId,
+ creditsRefunded,
+ rating: parsedBody.rating,
+ valuableSourcesCount: parsedBody.valuableSources?.length ?? 0,
+ missingContentCount: parsedBody.missingContent?.length ?? 0,
+ hasQuerySuggestions: !!parsedBody.querySuggestions,
+ creditsRefundedToday,
+ dailyRefundCap: dailyCap,
+ dailyCapReached,
+ });
+
+ return res.status(200).json({
+ success: true,
+ feedbackId,
+ creditsRefunded,
+ creditsRefundedToday,
+ dailyRefundCap: dailyCap,
+ ...(dailyCapReached
+ ? {
+ dailyCapReached: true,
+ warning: `Daily refund cap of ${dailyCap} credits reached for this team (UTC day). Feedback was recorded; further /feedback calls today will not refund credits.`,
+ }
+ : {}),
+ });
+ } catch (error) {
+ captureExceptionWithZdrCheck(error);
+ logger.error("Unhandled error in search feedback controller", { error });
+ return fail(res, {
+ status: 500,
+ code: "INTERNAL",
+ error: error instanceof Error ? error.message : "Unknown error",
+ });
+ }
+}
diff --git a/apps/api/src/controllers/v2/types.ts b/apps/api/src/controllers/v2/types.ts
index d2b8238e5..c86ad9832 100644
--- a/apps/api/src/controllers/v2/types.ts
+++ b/apps/api/src/controllers/v2/types.ts
@@ -1945,6 +1945,98 @@ export type SearchResponse =
id: string;
};
+// =============================================
+// Search Feedback
+// =============================================
+
+const searchFeedbackUrlSchema = z
+ .string()
+ .trim()
+ .min(1)
+ .max(2048)
+ .refine(value => {
+ try {
+ const u = new globalThis.URL(value);
+ return u.protocol === "http:" || u.protocol === "https:";
+ } catch {
+ return false;
+ }
+ }, "Must be a valid http(s) URL");
+
+const missingContentEntrySchema = z.strictObject({
+ topic: z
+ .string()
+ .trim()
+ .min(1, "topic must not be empty")
+ .max(200, "topic must be 200 characters or fewer"),
+ description: z.string().trim().max(2000).optional(),
+});
+
+export const searchFeedbackSchema = z
+ .strictObject({
+ rating: z.enum(["good", "bad", "partial"]),
+ valuableSources: z
+ .array(
+ z.strictObject({
+ url: searchFeedbackUrlSchema,
+ reason: z.string().trim().max(1000).optional(),
+ }),
+ )
+ .max(50)
+ .optional(),
+ missingContent: z.array(missingContentEntrySchema).max(20).optional(),
+ querySuggestions: z.string().trim().max(2000).optional(),
+ origin: z.string().optional().prefault("api"),
+ integration: integrationSchema.optional().transform(val => val || null),
+ })
+ .refine(
+ data => {
+ const hasSources = (data.valuableSources?.length ?? 0) > 0;
+ const hasMissing = (data.missingContent?.length ?? 0) > 0;
+ const hasSuggestions =
+ !!data.querySuggestions && data.querySuggestions.length > 0;
+
+ switch (data.rating) {
+ case "good":
+ return hasSources;
+ case "partial":
+ return hasSources || hasMissing;
+ case "bad":
+ return hasMissing || hasSuggestions;
+ }
+ },
+ {
+ message:
+ "Feedback must be substantive. 'good' requires at least one valuableSources entry; 'partial' requires valuableSources or at least one missingContent entry; 'bad' requires at least one missingContent entry or querySuggestions.",
+ },
+ );
+
+export type SearchFeedbackRequest = z.infer<typeof searchFeedbackSchema>;
+export type SearchFeedbackRequestInput = z.input<typeof searchFeedbackSchema>;
+
+export type SearchFeedbackErrorCode =
+ | "SEARCH_NOT_FOUND"
+ | "FEEDBACK_WINDOW_EXPIRED"
+ | "SEARCH_FAILED"
+ | "PREVIEW_TEAM_NOT_ALLOWED"
+ | "TEAM_OPTED_OUT"
+ | "INVALID_BODY"
+ | "DB_DISABLED"
+ | "INTERNAL";
+
+export type SearchFeedbackResponse =
+ | (ErrorResponse & { feedbackErrorCode?: SearchFeedbackErrorCode })
+ | {
+ success: true;
+ feedbackId: string;
+ creditsRefunded: number;
+ alreadySubmitted?: boolean;
+ dailyCapReached?: boolean;
+ creditsRefundedToday?: number;
+ dailyRefundCap?: number;
+ warning?: string;
+ };
+
export type TokenUsage = {
promptTokens: number;
completionTokens: number;
diff --git a/apps/api/src/routes/v2.ts b/apps/api/src/routes/v2.ts
index 0c738f92c..006d15b50 100644
--- a/apps/api/src/routes/v2.ts
+++ b/apps/api/src/routes/v2.ts
@@ -4,6 +4,7 @@ import { config } from "../config";
import { RateLimiterMode } from "../types";
import expressWs from "express-ws";
import { searchController } from "../controllers/v2/search";
+import { searchFeedbackController } from "../controllers/v2/search-feedback";
import { x402SearchController } from "../controllers/v2/x402-search";
import { scrapeController } from "../controllers/v2/scrape";
import {
@@ -240,6 +241,13 @@ v2Router.post(
wrap(searchController),
);
+v2Router.post(
+ "/search/:jobId/feedback",
+ authMiddleware(RateLimiterMode.Account),
+ validateJobIdParam,
+ wrap(searchFeedbackController),
+);
+
v2Router.post(
"/parse",
authMiddleware(RateLimiterMode.Scrape),