Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥
TypeScript aiai-agentsai-crawlerai-scrapingai-searchcrawlerdata-extractionhtml-to-markdownllmmarkdownscraperscrapingweb-crawlerweb-dataweb-data-extractionweb-scraperweb-scrapingweb-searchwebscraping
import { 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 {
getRecentAlexandriaCalls,
hasRecentAlexandriaActivity,
} from "../../../lib/alexandria-activity";
import {
checkFeedbackToken,
type FeedbackTokenRejection,
} from "../../../lib/alexandria-feedback-token";
import { forwardExchangeToolFeedback } from "../../../lib/exchange";
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";
import { refundAlexandriaFeedback } from "./alexandria-refund";
const failure = (
status: number,
feedbackErrorCode: EndpointFeedbackErrorCode,
error: string,
): FeedbackRecordResult => ({
status,
body: { success: false, feedbackErrorCode, error },
});
type FeedbackCall = {
requestId: string;
provider: string;
capability: string;
rating: AlexandriaFeedbackRequest["rating"] | null;
};
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,
creditsRefundedToday: 0,
dailyRefundCap: config.ALEXANDRIA_FEEDBACK_DAILY_CAP_CREDITS,
},
};
}
const now = Date.now();
const callRatings = new Map(
(body.callRatings ?? []).map(entry => [entry.token, entry.rating]),
);
const submittedTokens = [
...new Set([...(body.tokens ?? []), ...callRatings.keys()]),
];
const calls = new Map<string, FeedbackCall>();
let rejectedTokens = 0;
const rejectionReasons: Partial<Record<FeedbackTokenRejection, number>> = {};
for (const token of submittedTokens) {
const checked = checkFeedbackToken(token, teamId, now);
if (!checked.claims) {
rejectedTokens++;
rejectionReasons[checked.reason] =
(rejectionReasons[checked.reason] ?? 0) + 1;
continue;
}
const { claims } = checked;
const key = JSON.stringify([
claims.requestId,
claims.provider,
claims.capability,
]);
const rating = callRatings.get(token) ?? calls.get(key)?.rating ?? null;
calls.set(key, {
requestId: claims.requestId,
provider: claims.provider,
capability: claims.capability,
rating,
});
}
const attribution = calls.size > 0 ? "token" : "window";
if (rejectedTokens > 0) {
logger.warn("Alexandria feedback tokens rejected", {
teamId,
submittedTokens: submittedTokens.length,
rejectedTokens,
reasons: rejectionReasons,
attribution,
});
}
if (attribution === "window") {
let withinWindow: boolean;
try {
withinWindow = await hasRecentAlexandriaActivity(teamId);
} catch (error) {
logger.error("Failed to check the Alexandria feedback window", {
error,
teamId,
});
return failure(500, "INTERNAL", "Failed to check the feedback window.");
}
if (!withinWindow) {
return failure(
409,
"FEEDBACK_WINDOW_EXPIRED",
`Alexandria feedback must be submitted within ${config.ALEXANDRIA_FEEDBACK_WINDOW_SEC} seconds of an Alexandria search, discovery, or execution, or name its calls with valid feedback tokens.`,
);
}
const windowStart = now - config.ALEXANDRIA_FEEDBACK_WINDOW_SEC * 1000;
for (const call of await getRecentAlexandriaCalls(teamId)) {
if (call.at < windowStart) continue;
const { requestId, provider, capability } = call;
calls.set(JSON.stringify([requestId, provider, capability]), {
requestId,
provider,
capability,
rating: null,
});
}
}
const feedbackId = uuidv7();
const occurredAt = new Date(now).toISOString();
const providerRows = (body.providerFeedback ?? []).map((entry, position) => ({
feedback_id: feedbackId,
team_id: teamId,
position,
name: entry.name,
issue: entry.issue,
why: entry.why,
}));
const capabilityRows = (body.capabilityFeedback ?? []).map(
(entry, position) => ({
feedback_id: feedbackId,
team_id: teamId,
position,
name: entry.name,
provider: entry.provider,
issue: entry.issue,
why: entry.why,
requested_functionality: entry.requestedFunctionality ?? null,
}),
);
try {
await db.transaction(async tx => {
await tx.insert(schema.alexandria_feedback).values({
id: feedbackId,
team_id: teamId,
api_key_id: req.acuc?.api_key_id ?? null,
api_version: "v2",
rating: body.rating,
requested_url: body.requestedWebsite.url,
requested_functionality: body.requestedWebsite.requestedFunctionality,
rationale: body.rationale,
objective: body.objective ?? null,
origin: body.origin,
integration: body.integration ?? null,
schema_version: 2,
});
if (providerRows.length > 0) {
await tx
.insert(schema.alexandria_feedback_providers)
.values(providerRows);
}
if (capabilityRows.length > 0) {
await tx
.insert(schema.alexandria_feedback_capabilities)
.values(capabilityRows);
}
if (calls.size > 0) {
await tx.insert(schema.alexandria_feedback_calls).values(
[...calls.values()].map((call, position) => ({
feedback_id: feedbackId,
team_id: teamId,
position,
request_id: call.requestId,
provider: call.provider,
capability: call.capability,
rating: call.rating,
attribution,
})),
);
}
});
} 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.");
}
const refund = await refundAlexandriaFeedback({
feedbackId,
teamId,
orgId: req.acuc?.org_id ?? null,
rating: body.rating,
requestedUrl: body.requestedWebsite.url,
});
void forwardExchangeToolFeedback({
teamId,
feedbackId,
occurredAt,
rating: body.rating,
origin: body.origin,
attribution,
calls: [...calls.values()],
});
return {
status: 200,
body: {
success: true,
feedbackId,
...refund,
...(rejectedTokens > 0 ? { rejectedTokens } : {}),
},
};
}