Open source alternative to Semrush and Ahrefs
TypeScript backlink-analysisgoogle-search-console-mcpkeyword-researchmcpseoseo-agentseo-auditseo-automationseo-skillsseo-toolssite-audit
Load AI visibility results once instead of re-fetching on every visit (#922)
Carter Smith38ad80865acb
diff --git a/src/client/features/ai-visibility/AiResearchSetupGate.tsx b/src/client/features/ai-visibility/AiResearchSetupGate.tsxindex af479738..51105611 100644--- a/src/client/features/ai-visibility/AiResearchSetupGate.tsx+++ b/src/client/features/ai-visibility/AiResearchSetupGate.tsx@@ -60,7 +60,7 @@ export function AiResearchSetupGate({const tracker = aiTrackerQueryOptions(projectId);const keywords = aiResearchKeywordsQueryOptions(projectId);await Promise.all([- queryClient.fetchQuery(tracker).then(+ queryClient.fetchQuery({ ...tracker, staleTime: 0 }).then(({ recentRuns }) => {const runId = recentRuns[0]?.id;if (runId)diff --git a/src/client/features/ai-visibility/aiTrackerQuery.test.ts b/src/client/features/ai-visibility/aiTrackerQuery.test.tsnew file mode 100644index 00000000..44f6978a--- /dev/null+++ b/src/client/features/ai-visibility/aiTrackerQuery.test.ts@@ -0,0 +1,37 @@+import { QueryClient } from "@tanstack/react-query";+import { beforeEach, describe, expect, it, vi } from "vitest";+import { getAiVisibilityTracker } from "@/serverFunctions/ai-visibility";+import type { AiRun, AiTrackerState } from "@/shared/ai-visibility";+import { aiTrackerQueryOptions, aiVisibilityKey } from "./shared";++vi.mock("@/serverFunctions/ai-visibility", () => ({+ getAiVisibilityTracker: vi.fn(),+}));++const trend = [...aiVisibilityKey("p1"), "results", "trend", 7];++const tracker = (status: AiRun["status"]) =>+ // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- the query only reads recentRuns+ ({ recentRuns: [{ id: "run1", status }] }) as AiTrackerState;++let client: QueryClient;++beforeEach(() => {+ client = new QueryClient();+ client.setQueryData(aiTrackerQueryOptions("p1").queryKey, tracker("running"));+ client.setQueryData(trend, { runs: [] });+});++describe("AI visibility tracker query", () => {+ it("marks answers read during a run stale once a read sees it finish", async () => {+ vi.mocked(getAiVisibilityTracker).mockResolvedValue(tracker("completed"));+ await client.fetchQuery({ ...aiTrackerQueryOptions("p1"), staleTime: 0 });+ expect(client.getQueryState(trend)?.isInvalidated).toBe(true);+ });++ it("leaves them alone while the run is still collecting", async () => {+ vi.mocked(getAiVisibilityTracker).mockResolvedValue(tracker("running"));+ await client.fetchQuery({ ...aiTrackerQueryOptions("p1"), staleTime: 0 });+ expect(client.getQueryState(trend)?.isInvalidated).toBe(false);+ });+});diff --git a/src/client/features/ai-visibility/shared.tsx b/src/client/features/ai-visibility/shared.tsxindex feb6612d..a677cc29 100644--- a/src/client/features/ai-visibility/shared.tsx+++ b/src/client/features/ai-visibility/shared.tsx@@ -1,4 +1,4 @@-import { useEffect } from "react";+import { useEffect, useRef } from "react";import { Link } from "@tanstack/react-router";import { queryOptions, useQuery, useQueryClient } from "@tanstack/react-query";import { Loader2 } from "lucide-react";@@ -15,39 +15,45 @@ import {getAiVisibilityResults,listAiResearchKeywords,} from "@/serverFunctions/ai-visibility";-import type { AiRun } from "@/shared/ai-visibility";+import type { AiRun, AiTrackerState } from "@/shared/ai-visibility";export const aiVisibilityKey = (projectId: string) => ["aiVisibility",projectId,];-/** Read the full bounded result set for prompt inventory and history. */-async function fetchAllAiVisibilityResults(- input: Omit<- Parameters<typeof getAiVisibilityResults>[0]["data"],- "cursor" | "limit" | "branded"- >,-) {- const first = await getAiVisibilityResults({- data: { ...input, branded: "all", limit: 50 },- });- const rows = [...first.rows];- for (let cursor = first.nextCursor; cursor; ) {- const page = await getAiVisibilityResults({- data: { ...input, branded: "all", limit: 50, cursor },- });- rows.push(...page.rows);- cursor = page.nextCursor;- }- return { ...first, rows };-}+const isRunPending = (run: AiRun | null | undefined) =>+ run?.status === "running" || run?.status === "queued";export const aiTrackerQueryOptions = (projectId: string) =>queryOptions({queryKey: [...aiVisibilityKey(projectId), "tracker"],- queryFn: () => getAiVisibilityTracker({ data: { projectId } }),- staleTime: 0,+ queryFn: async ({ client, queryKey }) => {+ const before = client.getQueryData<AiTrackerState>(queryKey);+ const state = await getAiVisibilityTracker({ data: { projectId } });+ // Answers, trend and sources read while a run was collecting are+ // incomplete, wherever they were read (a hover preload, another tab), so+ // the read that first sees the run finish refreshes them.+ const finished = state.recentRuns.some(+ (run) =>+ !isRunPending(run) &&+ before?.recentRuns.some(+ (prior) => prior.id === run.id && isRunPending(prior),+ ),+ );+ if (finished) {+ void client.invalidateQueries({+ queryKey: [...aiVisibilityKey(projectId), "results"],+ });+ void client.invalidateQueries({+ queryKey: [...aiVisibilityKey(projectId), "sources"],+ });+ }+ return state;+ },+ // Fresh enough that a page mounting right after its loader read it, or+ // after a hover preload, does not read it again.+ staleTime: 10_000,});export const aiResearchSetupQueryOptions = (projectId: string) =>@@ -80,7 +86,9 @@ export const aiRunResultsQueryOptions = (queryOptions({queryKey: [...aiVisibilityKey(projectId), "results", "all", runId],queryFn: async () => {- const result = await fetchAllAiVisibilityResults({ projectId, runId });+ const result = await getAiVisibilityResults({+ data: { projectId, runId, branded: "all" },+ });return result.rows;},enabled: Boolean(runId),@@ -92,13 +100,11 @@ export const aiPromptHistoryQueryOptions = () =>queryOptions({queryKey: [...aiVisibilityKey(projectId), "results", "history", promptId],- // Read all pages of the latest 50 runs so engine ordering cannot hide+ // Read every answer of the latest 50 runs so engine ordering cannot hide// a newer execution from the selector.queryFn: () =>- fetchAllAiVisibilityResults({- projectId,- promptId,- includeHistory: true,+ getAiVisibilityResults({+ data: { projectId, promptId, includeHistory: true, branded: "all" },}),});@@ -114,28 +120,39 @@ export function useAiRunProgress(projectId: string, initialRun: AiRun | null) {queryFn: () => getAiVisibilityRun({ data: { projectId, runId: runId! } }),enabled: Boolean(runId),initialData: initialRun ?? undefined,- staleTime: 0,+ // A finished run never changes, so only an unfinished one is read again.+ staleTime: (current) => (isRunPending(current.state.data) ? 0 : Infinity),refetchInterval: (current) => {const run = current.state.data;- return run && (run.status === "running" || run.status === "queued")+ return run && isRunPending(run)? Math.max(4, run.pollAfterSeconds) * 1000: false;},});const run = query.data ?? initialRun;+ const previous = useRef(run);+ // Refresh what an unfinished run writes as its answers arrive. Once it+ // finishes, re-read the tracker, which sees the finish and refreshes the+ // answers itself. Polls that bring nothing new keep the same run object, and+ // a run that was already finished when the page opened changes nothing, so+ // neither reads anything again.useEffect(() => {- if (!run) return;+ const before = previous.current;+ previous.current = run;+ if (run === before || run?.id !== before?.id || !isRunPending(before))+ return;+ if (!isRunPending(run)) {+ void queryClient.invalidateQueries({+ queryKey: [...aiVisibilityKey(projectId), "tracker"],+ });+ return;+ }void queryClient.invalidateQueries({queryKey: [...aiVisibilityKey(projectId), "results"],});void queryClient.invalidateQueries({queryKey: [...aiVisibilityKey(projectId), "sources"],});- if (run.status !== "running" && run.status !== "queued") {- void queryClient.invalidateQueries({- queryKey: [...aiVisibilityKey(projectId), "tracker"],- });- }}, [projectId, queryClient, run]);return { run, error: query.error };}diff --git a/src/routes/_app/p/$projectId/ai-visibility/index.tsx b/src/routes/_app/p/$projectId/ai-visibility/index.tsxindex b4c850c6..e60f7778 100644--- a/src/routes/_app/p/$projectId/ai-visibility/index.tsx+++ b/src/routes/_app/p/$projectId/ai-visibility/index.tsx@@ -20,7 +20,7 @@ export const Route = createFileRoute("/_app/p/$projectId/ai-visibility/")({// The prompt table reads the latest run's answers, known from a fresh// tracker: a cached one can predate the latest run.void queryClient- .fetchQuery(aiTrackerQueryOptions(projectId))+ .fetchQuery({ ...aiTrackerQueryOptions(projectId), staleTime: 0 }).then((state) => {const runId = state.recentRuns[0]?.id;if (runId)diff --git a/src/server/features/ai-visibility/services/aiVisibilityResults.test.ts b/src/server/features/ai-visibility/services/aiVisibilityResults.test.tsindex 74d339f6..f057b818 100644--- a/src/server/features/ai-visibility/services/aiVisibilityResults.test.ts+++ b/src/server/features/ai-visibility/services/aiVisibilityResults.test.ts@@ -1,8 +1,10 @@import { beforeEach, describe, expect, it, vi } from "vitest";import { AiVisibilityRepository as repo } from "../repositories/AiVisibilityRepository";import type { RunRow } from "../repositories/AiVisibilityRepository";+import { aiPageResultsSchema } from "@/types/schemas/ai-visibility";import {loadAiAnswer,+ loadAiPageResults,loadAiResults,loadAiSources,} from "./aiVisibilityResults";@@ -157,6 +159,20 @@ describe("AI visibility results", () => {expect(results.runId).toBe(baseline);});+ it("gives the app a run's every answer in one read, past the MCP page size", async () => {+ await seedRun(+ "baseline",+ Array.from({ length: 51 }, () => ({ markdown: "x" })),+ );+ // Parsed as the server function parses it, so a default page size shows.+ const input = aiPageResultsSchema.parse({+ projectId: crypto.randomUUID(),+ branded: "all",+ });+ const results = await loadAiPageResults({ ...input, projectId });+ expect(results.rows).toHaveLength(51);+ });+it("finds competitor gaps: a competitor appears where the brand is neither named nor cited", async () => {await seedRun("baseline", [{ markdown: "Ahrefs", mentioned: ["Ahrefs"] },diff --git a/src/server/features/ai-visibility/services/aiVisibilityResults.ts b/src/server/features/ai-visibility/services/aiVisibilityResults.tsindex 2ac88051..3b2ca15f 100644--- a/src/server/features/ai-visibility/services/aiVisibilityResults.ts+++ b/src/server/features/ai-visibility/services/aiVisibilityResults.ts@@ -12,6 +12,7 @@ import type {AiSources,} from "@/shared/ai-visibility";import type {+ AiPageResultsInput,AiResultsInput,AiSourcesInput,} from "@/types/schemas/ai-visibility";@@ -87,7 +88,9 @@ function rowsFor(}));}-async function loadAiResultSet(rawInput: AiResultsInput) {+async function loadAiResultSet(+ rawInput: Omit<AiResultsInput, "cursor" | "limit">,+) {const input = {...rawInput,runId: rawInput.runId ?? undefined,@@ -184,15 +187,18 @@ export async function loadAiResults(input: AiResultsInput): Promise<AiResults> {return resultPage(result, input);}-/** App-only history metadata; the MCP results contract remains unchanged. */-export async function loadAiPageResults(input: AiResultsInput) {+/**+ * App reads: up to limit rows of the bounded set in one call, with history+ * metadata. The MCP results contract remains paged.+ */+export async function loadAiPageResults(input: AiPageResultsInput) {const { result, runs } = await loadAiResultSet(input);return {- ...resultPage(result, input),- historyRuns:- input.includeHistory && !input.cursor- ? runs.map(({ id, createdAt, trigger }) => ({ id, createdAt, trigger }))- : [],+ ...result,+ rows: result.rows.slice(0, input.limit),+ historyRuns: input.includeHistory+ ? runs.map(({ id, createdAt, trigger }) => ({ id, createdAt, trigger }))+ : [],};}diff --git a/src/serverFunctions/ai-visibility.ts b/src/serverFunctions/ai-visibility.tsindex 778ad2b7..7c37cc8e 100644--- a/src/serverFunctions/ai-visibility.ts+++ b/src/serverFunctions/ai-visibility.ts@@ -12,7 +12,7 @@ import {setAiScheduleSchema,runAiCheckSchema,getAiRunSchema,- aiResultsSchema,+ aiPageResultsSchema,aiSourcesSchema,aiAnswerSchema,aiExportSchema,@@ -114,7 +114,7 @@ export const getAiVisibilityRun = createServerFn({ method: "POST" })export const getAiVisibilityResults = createServerFn({ method: "POST" }).middleware(requireProjectContext)- .validator(aiResultsSchema)+ .validator(aiPageResultsSchema).handler(({ data, context }) =>AiVisibilityService.getPageResults({...data,diff --git a/src/types/schemas/ai-visibility.ts b/src/types/schemas/ai-visibility.tsindex b98baf0f..27a017fa 100644--- a/src/types/schemas/ai-visibility.ts+++ b/src/types/schemas/ai-visibility.ts@@ -151,6 +151,13 @@ export const aiResultsSchema = aiProjectSchema.extend({),limit: z.number().int().min(1).max(50).default(25),});+/**+ * App reads take the whole result set in one call: it is bounded by one run's+ * prompts and engines, or one prompt's latest 50 runs. Omit limit for every row.+ */+export const aiPageResultsSchema = aiResultsSchema+ .omit({ cursor: true })+ .extend({ limit: z.number().int().min(1).optional() });export const aiSourcesSchema = aiResultsSchema.extend({groupBy: z.enum(["url", "domain"]).default("url"),ownership: z.enum(["all", "own", "competitor", "other"]).default("all"),@@ -176,6 +183,7 @@ export type EstimateAiCostInput = z.infer<typeof estimateAiCostSchema>;export type SetAiScheduleInput = z.infer<typeof setAiScheduleSchema>;export type RunAiCheckInput = z.infer<typeof runAiCheckSchema>;export type AiResultsInput = z.infer<typeof aiResultsSchema>;+export type AiPageResultsInput = z.infer<typeof aiPageResultsSchema>;export type AiSourcesInput = z.infer<typeof aiSourcesSchema>;export type AiExportInput = z.infer<typeof aiExportSchema>;export type AiTrendInput = z.infer<typeof aiTrendSchema>;