Skip to content

Open source alternative to Semrush and Ahrefs

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.tsx
index 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.ts
new file mode 100644
index 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.tsx
index 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.tsx
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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>;