Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. π₯
TypeScript aiai-agentsai-crawlerai-scrapingai-searchcrawlerdata-extractionhtml-to-markdownllmmarkdownscraperscrapingweb-crawlerweb-dataweb-data-extractionweb-scraperweb-scrapingweb-searchwebscraping
(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.tsindex 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.tsnew file mode 100644index 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.tsindex 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 & StoragePOSTGRES_HOST: z.string().default("localhost"),diff --git a/apps/api/src/controllers/v0/search.ts b/apps/api/src/controllers/v0/search.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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),