Skip to content

Open source alternative to Semrush and Ahrefs

AI Visibility: competitor Share of Voice + clarity fixes for AI citations (#248)

Ben Senescu8a85b7b7940d
diff --git a/README.md b/README.md
index 415d2ef3..ce17d868 100644
--- a/README.md
+++ b/README.md
@@ -345,6 +345,16 @@ Searching ten pages deep costs 8x more than one page. Tracking both devices cost
- Opening extra tabs like `Referring Domains` or `Top Pages` adds about `+$0.02` each.
- Exact cost can vary slightly based on returned rows and DataForSEO pricing.
+### 6) AI Search — Brand Lookup
+
+- One lookup = 6 DataForSEO AI Optimization calls (`aggregated_metrics` + `top_pages` + `mentions_search` across ChatGPT and Google AI Overview): up to about `$0.85` per lookup.
+ - `aggregated_metrics`: `$0.101` per platform.
+ - `top_pages`: page-ranked cited sources per platform.
+ - `mentions_search`: row-priced; `$0.20` per platform at the app's full 100-row sample (lower-volume brands return fewer rows and cost less).
+- Adding competitors (Share of Voice) adds 2 `cross_aggregated_metrics` calls: about `$0.10` each, `$0.20` total.
+- Results are cached for 24 hours, so repeating the same lookup (same target + competitor set) is free within a day.
+- Re-measure anytime with `pnpm billing:brand-lookup --target=example.com --competitors=a.com,b.com --confirmLive=true`.
+
### Planning examples
- 100 keyword research requests at the default 150 results: `$3.50`
diff --git a/scripts/brand-lookup-cost-profile.ts b/scripts/brand-lookup-cost-profile.ts
index 72959b65..7de8ea75 100644
--- a/scripts/brand-lookup-cost-profile.ts
+++ b/scripts/brand-lookup-cost-profile.ts
@@ -4,11 +4,14 @@ import {
CHATGPT_LANGUAGE_CODE,
CHATGPT_LOCATION_CODE,
fetchLlmAggregatedMetrics,
+ fetchLlmCrossAggregatedMetrics,
fetchLlmMentionsSearch,
fetchLlmTopPages,
type LlmPlatform,
} from "@/server/lib/dataforseo/ai";
import { applyBillingMarkupUsd } from "@/shared/billing";
+import { resolveCompetitorGroups } from "@/server/features/ai-search/services/shareOfVoice";
+import { parseCompetitorList } from "@/types/schemas/ai-search";
import { loadLocalEnv, parseArgs } from "./cli-utils";
loadLocalEnv();
@@ -48,8 +51,22 @@ async function main() {
const userLocationCode = parsePositiveInteger(args.locationCode, 2840);
const userLanguageCode = args.languageCode ?? "en";
const repeat = parsePositiveInteger(args.repeat, 1);
+ // Optional comma-separated competitors — adds the Share of Voice
+ // cross_aggregated_metrics call per platform, mirroring the service.
+ const competitors = parseCompetitorList(args.competitors ?? "");
+ const competitorGroups = resolveCompetitorGroups(target, competitors);
const llmTarget = buildLlmTarget({ type: targetType, value: target });
+ const crossGroups = [
+ { key: target, target: llmTarget },
+ ...competitorGroups.map((competitor) => {
+ const detected = competitor.detected;
+ return {
+ key: competitor.label,
+ target: buildLlmTarget({ type: detected.type, value: detected.value }),
+ };
+ }),
+ ];
const platforms: LlmPlatform[] = ["chat_gpt", "google"];
const allRuns: RunSummary[] = [];
@@ -83,20 +100,42 @@ async function main() {
});
calls.push(toRecord(platform, "top_pages", topPages.billing));
+ // Prompt rows provide examples for the cited-source table.
const mentions = await fetchLlmMentionsSearch({
target: llmTarget,
platform,
locationCode,
languageCode,
- limit: 25,
+ limit: 100,
});
calls.push(toRecord(platform, "mentions_search", mentions.billing));
+
+ if (competitorGroups.length > 0) {
+ const cross = await fetchLlmCrossAggregatedMetrics({
+ groups: crossGroups,
+ platform,
+ locationCode,
+ languageCode,
+ });
+ calls.push(
+ toRecord(platform, "cross_aggregated_metrics", cross.billing),
+ );
+ }
}
const totalRawUsd = sum(calls.map((c) => c.rawUsd));
+ const crossRawUsd = sum(
+ calls
+ .filter((c) => c.endpoint === "cross_aggregated_metrics")
+ .map((c) => c.rawUsd),
+ );
allRuns.push({
run: runIndex + 1,
calls,
+ // Split out so the base "Est. $X" and the "+$Y to compare competitors"
+ // UI constants can each be checked against reality.
+ baseRawUsd: round(totalRawUsd - crossRawUsd),
+ crossRawUsd: round(crossRawUsd),
totalRawUsd: round(totalRawUsd),
totalBilledUsd: applyBillingMarkupUsd(totalRawUsd),
});
@@ -113,6 +152,7 @@ async function main() {
targetType,
userLocationCode,
userLanguageCode,
+ competitors: competitorGroups.map((group) => group.label),
repeat,
},
runs: allRuns,
@@ -140,6 +180,8 @@ type CallRecord = {
type RunSummary = {
run: number;
calls: CallRecord[];
+ baseRawUsd: number;
+ crossRawUsd: number;
totalRawUsd: number;
totalBilledUsd: number;
};
@@ -183,7 +225,7 @@ function round(value: number): number {
function printUsageAndExit(message: string): never {
console.error(message);
console.error(
- "Usage: pnpm billing:brand-lookup --target=example.com --confirmLive=true [--targetType=domain|keyword] [--locationCode=2840] [--languageCode=en] [--repeat=1] [--allowCi=true]",
+ "Usage: pnpm billing:brand-lookup --target=example.com --confirmLive=true [--targetType=domain|keyword] [--competitors=a.com,b.com] [--locationCode=2840] [--languageCode=en] [--repeat=1] [--allowCi=true]",
);
process.exit(1);
}
diff --git a/src/client/features/ai-search/BrandLookupPage.tsx b/src/client/features/ai-search/BrandLookupPage.tsx
index 43c21414..f6eb70d5 100644
--- a/src/client/features/ai-search/BrandLookupPage.tsx
+++ b/src/client/features/ai-search/BrandLookupPage.tsx
@@ -23,24 +23,29 @@ import { AiSearchSetupGate } from "@/client/features/ai-search/components/AiSear
import { AccessGateLoadingState } from "@/client/features/access-gate/AccessGate";
import { useAiSearchAccess } from "@/client/features/ai-search/useAiSearchAccess";
import { useBrandLookupSearchHistory } from "@/client/hooks/useBrandLookupSearchHistory";
-import { BRAND_LOOKUP_MAX_INPUT_LENGTH } from "@/types/schemas/ai-search";
+import {
+ BRAND_LOOKUP_MAX_INPUT_LENGTH,
+ parseCompetitorList,
+} from "@/types/schemas/ai-search";
+import { detectTarget } from "@/shared/targetDetection";
type Props = {
projectId: string;
initialQuery: string;
- onQueryChange: (next: string) => void;
+ initialCompetitors: string[];
+ onSearchChange: (nextQuery: string, nextCompetitors: string[]) => void;
};
const BRAND_LOOKUP_BULLETS = [
{
icon: TrendingUp,
title: "Track AI visibility",
- body: "Count how often ChatGPT and Google AI Overview cite your brand, and watch the trend month over month.",
+ body: "See estimated counts for ChatGPT and Google AI Overview answers that cite your brand, and watch the trend month over month.",
},
{
icon: Quote,
title: "See the prompts",
- body: "View the actual user questions where LLMs reference your domain — the real demand driving AI traffic.",
+ body: "View sample user questions where LLMs reference your brand or domain.",
},
{
icon: BarChart3,
@@ -60,24 +65,38 @@ export function BrandLookupPage(props: Props) {
function BrandLookupPageInner({
projectId,
initialQuery,
- onQueryChange,
+ initialCompetitors,
+ onSearchChange,
planGate,
}: Props & { planGate: HostedPlanGateState }) {
const [query, setQuery] = useState(initialQuery);
- const [validationError, setValidationError] = useState<string | null>(null);
+ // Raw comma-separated competitor text; parsed into a deduped array on submit.
+ const [competitorsInput, setCompetitorsInput] = useState(
+ initialCompetitors.join(", "),
+ );
+ // Field-tagged so the error styling lands on the input that caused it.
+ const [validationError, setValidationError] = useState<{
+ field: "query" | "competitors";
+ message: string;
+ } | null>(null);
const access = useAiSearchAccess(projectId);
const trimmedInitialQuery = initialQuery.trim();
const hasActiveQuery = trimmedInitialQuery.length > 0;
+ // The URL `c` param is the source of truth for the active lookup; the local
+ // `competitorsInput` text only drives the input until the next submit. A
+ // stable string key, since `initialCompetitors` is a fresh array each render.
+ const competitorKey = initialCompetitors.join(",");
const lookupQuery = useQuery({
- queryKey: ["brand-lookup", projectId, trimmedInitialQuery],
+ queryKey: ["brand-lookup", projectId, trimmedInitialQuery, competitorKey],
queryFn: () =>
lookupBrand({
data: {
projectId,
query: trimmedInitialQuery,
+ competitors: initialCompetitors,
locationCode: 2840,
languageCode: "en",
},
@@ -96,38 +115,83 @@ function BrandLookupPageInner({
// Dedup ref prevents repeat adds — `addSearch` identity is not stable
// across renders, so we'd otherwise re-write the same item every render.
- const lastAddedQueryRef = useRef<string | null>(null);
+ // Key on query + competitors so changing competitors records a fresh entry.
+ const lastAddedKeyRef = useRef<string | null>(null);
useEffect(() => {
if (!hasActiveQuery || !lookupQuery.isSuccess) return;
- if (lastAddedQueryRef.current === trimmedInitialQuery) return;
- lastAddedQueryRef.current = trimmedInitialQuery;
- addSearch({ query: trimmedInitialQuery });
- }, [hasActiveQuery, lookupQuery.isSuccess, trimmedInitialQuery, addSearch]);
+ const addedKey = `${trimmedInitialQuery}::${competitorKey}`;
+ if (lastAddedKeyRef.current === addedKey) return;
+ lastAddedKeyRef.current = addedKey;
+ addSearch({
+ query: trimmedInitialQuery,
+ competitors: competitorKey ? competitorKey.split(",") : [],
+ });
+ }, [
+ hasActiveQuery,
+ lookupQuery.isSuccess,
+ trimmedInitialQuery,
+ competitorKey,
+ addSearch,
+ ]);
const handleSubmit = (event: FormEvent) => {
event.preventDefault();
const trimmed = query.trim();
if (trimmed.length === 0) {
- setValidationError("Enter a brand name or domain");
+ setValidationError({
+ field: "query",
+ message: "Enter a brand name or domain",
+ });
return;
}
if (trimmed.length > BRAND_LOOKUP_MAX_INPUT_LENGTH) {
- setValidationError(
- `Keep it under ${BRAND_LOOKUP_MAX_INPUT_LENGTH} characters`,
- );
+ setValidationError({
+ field: "query",
+ message: `Keep it under ${BRAND_LOOKUP_MAX_INPUT_LENGTH} characters`,
+ });
+ return;
+ }
+ const competitors = parseCompetitorList(competitorsInput);
+ // Mirror the server's input schema (per-item max) and its competitor
+ // resolution (a competitor that resolves to the target is dropped) so the
+ // user gets an inline message instead of a generic server error or a
+ // silently missing Share of Voice section.
+ const tooLong = competitors.find(
+ (competitor) => competitor.length > BRAND_LOOKUP_MAX_INPUT_LENGTH,
+ );
+ if (tooLong) {
+ setValidationError({
+ field: "competitors",
+ message: `Keep each competitor under ${BRAND_LOOKUP_MAX_INPUT_LENGTH} characters`,
+ });
+ return;
+ }
+ const targetValue = detectTarget(trimmed).value.toLowerCase();
+ const matchesTarget = competitors.find(
+ (competitor) =>
+ detectTarget(competitor).value.toLowerCase() === targetValue,
+ );
+ if (matchesTarget) {
+ setValidationError({
+ field: "competitors",
+ message: `"${matchesTarget}" matches the brand you're looking up — remove it from competitors`,
+ });
return;
}
setValidationError(null);
- onQueryChange(trimmed);
+ onSearchChange(trimmed, competitors);
};
- // The query input is reset whenever the URL `q` changes — including the
- // browser-back path and Cmd+click navigation. This keeps local form state
- // in sync with the URL source-of-truth.
+ // The form inputs are reset whenever the URL `q`/`c` changes — including the
+ // browser-back path and Cmd+click navigation. This keeps local form state in
+ // sync with the URL source-of-truth. Depend on the stable `competitorKey`
+ // string (not the fresh-each-render `initialCompetitors` array) so typing in
+ // the competitor field isn't clobbered on every render.
useEffect(() => {
setQuery(initialQuery);
+ setCompetitorsInput(competitorKey.split(",").join(", "));
setValidationError(null);
- }, [initialQuery]);
+ }, [initialQuery, competitorKey]);
const isLoading = hasActiveQuery && lookupQuery.isPending;
const errorMessage =
@@ -159,7 +223,7 @@ function BrandLookupPageInner({
) : planGate.isFreePlan ? (
<AiSearchPaidPlanGate
feature="Brand Lookup"
- description="See how ChatGPT and Google AI Overview cite any brand or domain — total mentions, the prompts driving them, and the pages cited alongside yours."
+ description="See how ChatGPT and Google AI Overview cite any brand or domain — total mentions, sample prompts where it appears, and the pages cited alongside it."
bullets={BRAND_LOOKUP_BULLETS}
/>
) : (
@@ -170,6 +234,11 @@ function BrandLookupPageInner({
setQuery(next);
if (validationError) setValidationError(null);
}}
+ competitors={competitorsInput}
+ onCompetitorsChange={(next) => {
+ setCompetitorsInput(next);
+ if (validationError) setValidationError(null);
+ }}
onSubmit={handleSubmit}
isLoading={isLoading}
validationError={validationError}
@@ -194,7 +263,7 @@ function BrandLookupPageInner({
from="/p/$projectId/brand-lookup"
to="/p/$projectId/brand-lookup"
params={{ projectId }}
- search={{ q: undefined }}
+ search={{ q: undefined, c: undefined }}
replace
className="btn btn-ghost btn-sm gap-2 px-0 text-base-content/70 hover:bg-transparent"
>
@@ -202,7 +271,7 @@ function BrandLookupPageInner({
Recent searches
</Link>
</div>
- <BrandLookupResults result={resultData} />
+ <BrandLookupResults result={resultData} projectId={projectId} />
</>
) : !errorMessage ? (
<BrandLookupHistorySection
diff --git a/src/client/features/ai-search/brandLookupFiltering.ts b/src/client/features/ai-search/brandLookupFiltering.ts
index 6664e859..62322a07 100644
--- a/src/client/features/ai-search/brandLookupFiltering.ts
+++ b/src/client/features/ai-search/brandLookupFiltering.ts
@@ -44,7 +44,11 @@ export function filterTopPages(
const excludeTerms = parseTerms(filters.exclude);
return rows.filter((row) => {
- const textFields = [row.url, row.domain]
+ const textFields = [
+ row.url,
+ row.domain,
+ ...row.keywords.map((keyword) => keyword.question),
+ ]
.filter((v): v is string => Boolean(v))
.join(" ");
diff --git a/src/client/features/ai-search/components/BrandLookupCitationTables.tsx b/src/client/features/ai-search/components/BrandLookupCitationTables.tsx
index 5f639590..1f4d92fd 100644
--- a/src/client/features/ai-search/components/BrandLookupCitationTables.tsx
+++ b/src/client/features/ai-search/components/BrandLookupCitationTables.tsx
@@ -1,11 +1,15 @@
+import { useState } from "react";
import { createColumnHelper, type Table } from "@tanstack/react-table";
-import { ExternalLink } from "lucide-react";
+import { Link } from "@tanstack/react-router";
+import { ExternalLink, Sparkles } from "lucide-react";
import { AppDataTable } from "@/client/components/table/AppDataTable";
import { SortableHeader } from "@/client/components/table/SortableHeader";
+import { HeaderHelpLabel } from "@/client/features/keywords/components";
import { numericNullsLast } from "@/client/components/table/nullSafeSort";
import {
formatCount,
- formatPlatformLabel,
+ PLATFORM_DOT_CLASS,
+ PLATFORM_SHORT_LABEL,
} from "@/client/features/ai-search/platformLabels";
import { formatUrlForDisplay } from "@/client/components/table/url";
import type { BrandLookupResult } from "@/types/schemas/ai-search";
@@ -14,105 +18,327 @@ type TopPageRow = BrandLookupResult["topPages"][number];
type TopQueryRow = BrandLookupResult["topQueries"][number];
type PlatformKey = TopPageRow["platform"];
-const PLATFORM_BADGE_CLASS: Record<PlatformKey, string> = {
- chat_gpt: "border-emerald-500/40 bg-emerald-500/10 text-emerald-500",
- google: "border-sky-500/40 bg-sky-500/10 text-sky-500",
-};
+/** Uppercase column header with a hover/focus popover explaining the column. */
+function HeaderWithHelp({
+ label,
+ helpText,
+}: {
+ label: string;
+ helpText: string;
+}) {
+ return (
+ <span className="uppercase tracking-wider">
+ <HeaderHelpLabel label={label} helpText={helpText} />
+ </span>
+ );
+}
-function PlatformBadge({ platform }: { platform: PlatformKey }) {
+const PLATFORM_HELP =
+ "Which AI surface produced the answer — ChatGPT or Google AI Overview.";
+
+/**
+ * Platform indicator used only when a table actually spans >1 platform. A dot +
+ * short label replaces the old full-width pill that repeated identically on
+ * every row.
+ */
+function PlatformCell({ platform }: { platform: PlatformKey }) {
return (
- <span className={`badge badge-sm border ${PLATFORM_BADGE_CLASS[platform]}`}>
- {formatPlatformLabel(platform)}
+ <span className="inline-flex items-center gap-1.5 text-xs text-base-content/70">
+ <span
+ className={`size-1.5 rounded-full ${PLATFORM_DOT_CLASS[platform]}`}
+ />
+ {PLATFORM_SHORT_LABEL[platform]}
</span>
);
}
+function urlPath(rawUrl: string): string {
+ try {
+ const url = new URL(rawUrl);
+ const path = `${url.pathname}${url.search}`;
+ return path === "/" ? "" : path;
+ } catch {
+ return "";
+ }
+}
+
+function normalizeDomain(value: string): string {
+ return value.replace(/^www\./i, "").toLowerCase();
+}
+
+/**
+ * The lookup targets a domain with include_subdomains, so the target's own
+ * pages can surface under any subdomain (docs.acme.com for acme.com) — those
+ * must get the "You" badge too.
+ */
+function isTargetDomain(domain: string, targetDomain: string): boolean {
+ const candidate = normalizeDomain(domain);
+ const target = normalizeDomain(targetDomain);
+ return candidate === target || candidate.endsWith(`.${target}`);
+}
+
+/** Domain-led cited page: bold domain + truncated path, links out. */
+function PageUrlCell({
+ row,
+ targetDomain,
+}: {
+ row: TopPageRow;
+ targetDomain: string | null;
+}) {
+ const path = urlPath(row.url);
+ const isOwn =
+ targetDomain != null &&
+ row.domain != null &&
+ isTargetDomain(row.domain, targetDomain);
+
+ return (
+ <a
+ href={row.url}
+ target="_blank"
+ rel="noreferrer"
+ className="group block max-w-xl"
+ >
+ <span className="inline-flex items-center gap-1.5">
+ <span className="font-medium text-base-content group-hover:underline">
+ {row.domain ?? formatUrlForDisplay(row.url)}
+ </span>
+ {isOwn ? (
+ <span className="badge badge-primary badge-xs border-0">You</span>
+ ) : null}
+ <ExternalLink className="size-3 shrink-0 text-base-content/40" />
+ </span>
+ {path ? (
+ <span className="block truncate text-xs text-base-content/50">
+ {path}
+ </span>
+ ) : null}
+ </a>
+ );
+}
+
+/**
+ * The prompts (keywords) whose answers cited this page. Shows the top 3 inline;
+ * if there are more, a "+N more" toggle reveals the rest. Each prompt links into
+ * Prompt Explorer prefilled with it.
+ */
+function KeywordsCell({
+ keywords,
+ projectId,
+ brand,
+}: {
+ keywords: TopPageRow["keywords"];
+ projectId: string;
+ brand: string;
+}) {
+ const [expanded, setExpanded] = useState(false);
+
+ if (keywords.length === 0) {
+ return <span className="text-base-content/40">—</span>;
+ }
+
+ const visible = expanded ? keywords : keywords.slice(0, 3);
+ const remaining = keywords.length - visible.length;
+
+ return (
+ <div className="space-y-1">
+ <ul className="space-y-0.5">
+ {visible.map((keyword) => (
+ <li key={keyword.question}>
+ <Link
+ to="/p/$projectId/prompt-explorer"
+ params={{ projectId }}
+ search={{ q: keyword.question, hb: brand || undefined }}
+ className="group/kw inline-flex items-baseline gap-2 text-xs"
+ title="Run this prompt in Prompt Explorer"
+ >
+ <span className="text-base-content/80 group-hover/kw:underline">
+ {keyword.question}
+ </span>
+ <span
+ className="shrink-0 tabular-nums text-base-content/40"
+ title="Prompt volume in the fetched sample"
+ >
+ {formatCount(keyword.aiSearchVolume)} vol.
+ </span>
+ </Link>
+ </li>
+ ))}
+ </ul>
+ {keywords.length > 3 ? (
+ <button
+ type="button"
+ onClick={() => setExpanded((current) => !current)}
+ className="text-xs text-base-content/50 hover:text-base-content"
+ >
+ {expanded ? "Show less" : `+${remaining} more`}
+ </button>
+ ) : null}
+ </div>
+ );
+}
+
const pagesHelper = createColumnHelper<TopPageRow>();
const queriesHelper = createColumnHelper<TopQueryRow>();
-export const topPagesColumns = [
- pagesHelper.accessor("url", {
- id: "url",
- header: () => <span className="uppercase tracking-wider">URL</span>,
- enableSorting: false,
- cell: ({ row }) => (
- <>
- <a
- href={row.original.url}
- target="_blank"
- rel="noreferrer"
- className="link link-primary inline-flex items-start gap-1 break-all"
+export function buildTopPagesColumns({
+ showPlatform,
+ targetDomain,
+ projectId,
+ brand,
+}: {
+ showPlatform: boolean;
+ targetDomain: string | null;
+ projectId: string;
+ brand: string;
+}) {
+ return [
+ pagesHelper.accessor("url", {
+ id: "url",
+ header: () => (
+ <HeaderWithHelp
+ label="Source"
+ helpText="A page cited as a source in AI answers where the searched brand or domain appears."
+ />
+ ),
+ enableSorting: false,
+ cell: ({ row }) => (
+ <PageUrlCell row={row.original} targetDomain={targetDomain} />
+ ),
+ }),
+ ...(showPlatform
+ ? [
+ pagesHelper.accessor("platform", {
+ id: "platform",
+ header: () => (
+ <HeaderWithHelp label="Platform" helpText={PLATFORM_HELP} />
+ ),
+ enableSorting: false,
+ cell: ({ getValue }) => <PlatformCell platform={getValue()} />,
+ }),
+ ]
+ : []),
+ pagesHelper.display({
+ id: "keywords",
+ header: () => (
+ <HeaderWithHelp
+ label="Cited for"
+ helpText="Example prompts from the fetched sample where this page was cited."
+ />
+ ),
+ cell: ({ row }) => (
+ <KeywordsCell
+ keywords={row.original.keywords}
+ projectId={projectId}
+ brand={brand}
+ />
+ ),
+ }),
+ pagesHelper.accessor("capturedVolume", {
+ id: "capturedVolume",
+ header: ({ column }) => (
+ <SortableHeader
+ column={column}
+ label="Source vol."
+ helpText="Estimated monthly prompt demand DataForSEO reports for this cited source, across prompts where the searched brand or domain appears."
+ align="right"
+ />
+ ),
+ cell: ({ getValue }) => (
+ <span className="tabular-nums">{formatCount(getValue())}</span>
+ ),
+ sortingFn: numericNullsLast,
+ sortDescFirst: true,
+ }),
+ ];
+}
+
+export function buildTopQueriesColumns({
+ showPlatform,
+ projectId,
+ brand,
+}: {
+ showPlatform: boolean;
+ projectId: string;
+ brand: string;
+}) {
+ return [
+ queriesHelper.accessor("question", {
+ id: "question",
+ header: () => (
+ <HeaderWithHelp
+ label="Query"
+ helpText="A sampled user prompt whose AI answer cited the searched brand or domain in its text or sources. The prompt itself may not name the brand."
+ />
+ ),
+ enableSorting: false,
+ cell: ({ row }) => (
+ <>
+ <p className="break-words font-medium">{row.original.question}</p>
+ {row.original.brandsMentioned.length > 0 ? (
+ <p className="mt-0.5 text-xs text-base-content/50">
+ Brands: {row.original.brandsMentioned.slice(0, 5).join(", ")}
+ </p>
+ ) : null}
+ </>
+ ),
+ }),
+ ...(showPlatform
+ ? [
+ queriesHelper.accessor("platform", {
+ id: "platform",
+ header: () => (
+ <HeaderWithHelp label="Platform" helpText={PLATFORM_HELP} />
+ ),
+ enableSorting: false,
+ cell: ({ getValue }) => <PlatformCell platform={getValue()} />,
+ }),
+ ]
+ : []),
+ queriesHelper.accessor("aiSearchVolume", {
+ id: "aiSearchVolume",
+ header: ({ column }) => (
+ <SortableHeader
+ column={column}
+ label="AI search vol."
+ helpText="Estimated monthly search demand for this prompt's topic. This is prompt demand, not the number of brand mentions."
+ align="right"
+ />
+ ),
+ cell: ({ getValue }) => (
+ <span className="tabular-nums">{formatCount(getValue())}</span>
+ ),
+ sortingFn: numericNullsLast,
+ sortDescFirst: true,
+ }),
+ queriesHelper.display({
+ id: "action",
+ header: () => <span className="sr-only">Actions</span>,
+ meta: { cellClassName: "w-px whitespace-nowrap text-right align-top" },
+ cell: ({ row }) => (
+ <span
+ className="tooltip tooltip-left opacity-0 transition-opacity group-hover:opacity-100 focus-within:opacity-100"
+ data-tip="Run this prompt in Prompt Explorer"
>
- <span className="break-all">
- {formatUrlForDisplay(row.original.url)}
- </span>
- <ExternalLink className="mt-1 size-3 shrink-0" />
- </a>
- {row.original.domain ? (
- <p className="text-xs text-base-content/50">{row.original.domain}</p>
- ) : null}
- </>
- ),
- }),
- pagesHelper.accessor("platform", {
- id: "platform",
- header: () => <span className="uppercase tracking-wider">Platform</span>,
- enableSorting: false,
- cell: ({ getValue }) => <PlatformBadge platform={getValue()} />,
- }),
- pagesHelper.accessor("mentions", {
- id: "mentions",
- header: ({ column }) => (
- <SortableHeader column={column} label="Mentions" align="right" />
- ),
- cell: ({ getValue }) => (
- <span className="tabular-nums">{formatCount(getValue())}</span>
- ),
- sortingFn: numericNullsLast,
- sortDescFirst: true,
- }),
-];
-
-export const topQueriesColumns = [
- queriesHelper.accessor("question", {
- id: "question",
- header: () => <span className="uppercase tracking-wider">Query</span>,
- enableSorting: false,
- cell: ({ row }) => (
- <>
- <p className="break-words font-medium">{row.original.question}</p>
- {row.original.brandsMentioned.length > 0 ? (
- <p className="mt-0.5 text-xs text-base-content/50">
- Brands: {row.original.brandsMentioned.slice(0, 5).join(", ")}
- </p>
- ) : null}
- </>
- ),
- }),
- queriesHelper.accessor("platform", {
- id: "platform",
- header: () => <span className="uppercase tracking-wider">Platform</span>,
- enableSorting: false,
- cell: ({ getValue }) => <PlatformBadge platform={getValue()} />,
- }),
- queriesHelper.accessor("aiSearchVolume", {
- id: "aiSearchVolume",
- header: ({ column }) => (
- <SortableHeader column={column} label="AI search vol." align="right" />
- ),
- cell: ({ getValue }) => (
- <span className="tabular-nums">{formatCount(getValue())}</span>
- ),
- sortingFn: numericNullsLast,
- sortDescFirst: true,
- }),
-];
+ <Link
+ to="/p/$projectId/prompt-explorer"
+ params={{ projectId }}
+ search={{ q: row.original.question, hb: brand || undefined }}
+ className="btn btn-ghost btn-xs gap-1"
+ aria-label="Run this prompt in Prompt Explorer"
+ >
+ <Sparkles className="size-3.5" />
+ </Link>
+ </span>
+ ),
+ }),
+ ];
+}
export function TopPagesTable({ table }: { table: Table<TopPageRow> }) {
if (table.getRowModel().rows.length === 0) {
return (
<p className="p-6 text-center text-sm text-base-content/60">
- No cited pages returned.
+ No cited sources to show.
</p>
);
}
@@ -142,6 +368,7 @@ function BrandLookupTable<T>({
return (
<AppDataTable
table={table}
+ getRowClassName={() => "group transition-colors hover:bg-base-200/40"}
getCellClassName={(_, columnId) =>
cellClassName(
columnId,
@@ -161,6 +388,9 @@ function cellClassName(
if (columnId === urlLikeColumnId) {
return "min-w-80 max-w-2xl align-top";
}
+ if (columnId === "keywords") {
+ return "max-w-lg align-top";
+ }
if (isNumeric) {
return "whitespace-nowrap text-right align-top";
}
diff --git a/src/client/features/ai-search/components/BrandLookupCitationsCard.tsx b/src/client/features/ai-search/components/BrandLookupCitationsCard.tsx
new file mode 100644
index 00000000..821fb7a4
--- /dev/null
+++ b/src/client/features/ai-search/components/BrandLookupCitationsCard.tsx
@@ -0,0 +1,269 @@
+import { useMemo, useState } from "react";
+import { type SortingState } from "@tanstack/react-table";
+import { ChevronDown, Download, Sheet, SlidersHorizontal } from "lucide-react";
+import { useAppTable } from "@/client/components/table/AppDataTable";
+import { exportTableToSheets } from "@/client/lib/exportToSheets";
+import {
+ buildBrandLookupExport,
+ downloadBrandLookupCsv,
+} from "@/client/features/ai-search/components/brandLookupExport";
+import { BrandLookupFilterPanel } from "@/client/features/ai-search/components/BrandLookupFilterPanel";
+import {
+ TopPagesTable,
+ TopQueriesTable,
+ buildTopPagesColumns,
+ buildTopQueriesColumns,
+} from "@/client/features/ai-search/components/BrandLookupCitationTables";
+import {
+ formatPlatformLabel,
+ PLATFORM_DOT_CLASS,
+} from "@/client/features/ai-search/platformLabels";
+import {
+ filterQueries,
+ filterTopPages,
+} from "@/client/features/ai-search/brandLookupFiltering";
+import { useBrandLookupFilters } from "@/client/features/ai-search/useBrandLookupFilters";
+import type { CitationTab } from "@/client/features/ai-search/brandLookupFilterTypes";
+import type { BrandLookupResult } from "@/types/schemas/ai-search";
+
+const DEFAULT_PAGES_SORT: SortingState = [{ id: "capturedVolume", desc: true }];
+const DEFAULT_QUERIES_SORT: SortingState = [
+ { id: "aiSearchVolume", desc: true },
+];
+
+// DaisyUI focus-dropdowns stay open until the active element blurs.
+function closeExportMenu(): void {
+ const active = document.activeElement;
+ if (active instanceof HTMLElement) active.blur();
+}
+
+export function CitationTabsCard({
+ result,
+ projectId,
+}: {
+ result: BrandLookupResult;
+ projectId: string;
+}) {
+ const [activeTab, setActiveTab] = useState<CitationTab>("queries");
+ const [pagesSort, setPagesSort] = useState<SortingState>(DEFAULT_PAGES_SORT);
+ const [queriesSort, setQueriesSort] =
+ useState<SortingState>(DEFAULT_QUERIES_SORT);
+ const filters = useBrandLookupFilters();
+
+ // The platform column only earns its place when a tab actually spans >1
+ // platform; otherwise it repeats one value on every row.
+ const queryPlatforms = [
+ ...new Set(result.topQueries.map((query) => query.platform)),
+ ];
+ const pagePlatforms = [
+ ...new Set(result.topPages.map((page) => page.platform)),
+ ];
+ const showQueryPlatform = queryPlatforms.length > 1;
+ const showPagePlatform = pagePlatforms.length > 1;
+ const targetDomain =
+ result.detectedTargetType === "domain" ? result.resolvedTarget : null;
+
+ const filteredPages = useMemo(
+ () => filterTopPages(result.topPages, filters.pages.values),
+ [result.topPages, filters.pages.values],
+ );
+ const filteredQueries = useMemo(
+ () => filterQueries(result.topQueries, filters.queries.values),
+ [result.topQueries, filters.queries.values],
+ );
+
+ const pagesColumns = useMemo(
+ () =>
+ buildTopPagesColumns({
+ showPlatform: showPagePlatform,
+ targetDomain,
+ projectId,
+ brand: result.resolvedTarget,
+ }),
+ [showPagePlatform, targetDomain, projectId, result.resolvedTarget],
+ );
+ const queriesColumns = useMemo(
+ () =>
+ buildTopQueriesColumns({
+ showPlatform: showQueryPlatform,
+ projectId,
+ brand: result.resolvedTarget,
+ }),
+ [showQueryPlatform, projectId, result.resolvedTarget],
+ );
+
+ const pagesTable = useAppTable({
+ data: filteredPages,
+ columns: pagesColumns,
+ state: { sorting: pagesSort },
+ onSortingChange: setPagesSort,
+ withSorting: true,
+ // Stable identity (default is the array index): KeywordsCell holds
+ // expanded state, which must follow the page when filtering/sorting
+ // reorders rows, not stick to whatever row lands in the same slot.
+ getRowId: (row) => `${row.platform}:${row.url}`,
+ });
+ const queriesTable = useAppTable({
+ data: filteredQueries,
+ columns: queriesColumns,
+ state: { sorting: queriesSort },
+ onSortingChange: setQueriesSort,
+ withSorting: true,
+ });
+
+ // Not memoized: TanStack's `getSortedRowModel()` is internally cached, and
+ // memoing on the table refs alone (which are stable across renders) would
+ // serve stale data when sort or filters change.
+ const exportTable = buildBrandLookupExport(
+ activeTab,
+ pagesTable.getSortedRowModel().rows.map((row) => row.original),
+ queriesTable.getSortedRowModel().rows.map((row) => row.original),
+ );
+
+ const handleExportCsv = () => {
+ downloadBrandLookupCsv(activeTab, result.resolvedTarget, exportTable);
+ closeExportMenu();
+ };
+
+ const handleExportSheets = () => {
+ void exportTableToSheets({
+ headers: exportTable.headers,
+ rows: exportTable.rows,
+ feature: `brand_lookup_${activeTab}`,
+ });
+ closeExportMenu();
+ };
+
+ const canExport = exportTable.rows.length > 0;
+
+ const currentFilterCount = filters[activeTab].activeFilterCount;
+ const queriesActive = activeTab === "queries";
+ const pagesActive = activeTab === "pages";
+
+ // When the active tab's platform column is hidden, surface the lone platform
+ // once here instead of repeating it on every row.
+ const activePlatforms = pagesActive ? pagePlatforms : queryPlatforms;
+ const captionPlatform =
+ activePlatforms.length === 1 ? activePlatforms[0] : null;
+
+ return (
+ <section className="overflow-hidden rounded-xl border border-base-300 bg-base-100">
+ <div className="flex items-center justify-between gap-3 border-b border-base-300 px-4 py-3">
+ <div role="tablist" className="tabs tabs-box w-fit">
+ <button
+ type="button"
+ role="tab"
+ aria-selected={queriesActive}
+ className={`tab ${queriesActive ? "tab-active" : ""}`}
+ onClick={() => setActiveTab("queries")}
+ >
+ Queries
+ </button>
+ <button
+ type="button"
+ role="tab"
+ aria-selected={pagesActive}
+ className={`tab ${pagesActive ? "tab-active" : ""}`}
+ onClick={() => setActiveTab("pages")}
+ >
+ Cited sources
+ </button>
+ </div>
+
+ <div className="dropdown dropdown-end">
+ <div
+ tabIndex={0}
+ role="button"
+ className={`btn btn-ghost btn-sm gap-1.5 ${canExport ? "" : "btn-disabled"}`}
+ >
+ <Download className="size-3.5" />
+ Export
+ <ChevronDown className="size-3.5" />
+ </div>
+ <ul
+ tabIndex={0}
+ className="menu dropdown-content z-10 mt-1 w-48 rounded-box border border-base-300 bg-base-100 p-1 shadow"
+ >
+ <li>
+ <button
+ type="button"
+ onClick={handleExportSheets}
+ disabled={!canExport}
+ >
+ <Sheet className="size-4" />
+ Google Sheets
+ </button>
+ </li>
+ <li>
+ <button
+ type="button"
+ onClick={handleExportCsv}
+ disabled={!canExport}
+ >
+ <Download className="size-4" />
+ CSV
+ </button>
+ </li>
+ </ul>
+ </div>
+ </div>
+
+ <div className="flex items-center gap-2 border-b border-base-300 px-4 py-2">
+ <button
+ type="button"
+ className={`btn btn-ghost btn-sm gap-1.5 ${filters.showFilters ? "btn-active" : ""}`}
+ onClick={() => filters.setShowFilters((current) => !current)}
+ title="Toggle table filters"
+ >
+ <SlidersHorizontal className="size-3.5" />
+ Filters
+ {currentFilterCount > 0 ? (
+ <span className="badge badge-xs badge-primary border-0 text-primary-content">
+ {currentFilterCount}
+ </span>
+ ) : null}
+ </button>
+ </div>
+
+ <div className="flex items-center justify-between gap-3 border-b border-base-300 px-4 py-2 text-xs text-base-content/60">
+ <span>
+ {activeTab === "pages" ? (
+ <>
+ Pages cited alongside{" "}
+ <strong className="text-base-content/80">
+ {result.resolvedTarget}
+ </strong>{" "}
+ in AI answers. Prompt examples come from the fetched sample.
+ </>
+ ) : (
+ <>
+ Fetched sample of prompts whose AI answer cited{" "}
+ <strong className="text-base-content/80">
+ {result.resolvedTarget}
+ </strong>{" "}
+ in its text or sources.
+ </>
+ )}
+ </span>
+ {captionPlatform ? (
+ <span className="inline-flex shrink-0 items-center gap-1.5 text-base-content/70">
+ <span
+ className={`size-1.5 rounded-full ${PLATFORM_DOT_CLASS[captionPlatform]}`}
+ />
+ {formatPlatformLabel(captionPlatform)}
+ </span>
+ ) : null}
+ </div>
+
+ {filters.showFilters ? (
+ <BrandLookupFilterPanel activeTab={activeTab} filters={filters} />
+ ) : null}
+
+ {activeTab === "pages" ? (
+ <TopPagesTable table={pagesTable} />
+ ) : (
+ <TopQueriesTable table={queriesTable} />
+ )}
+ </section>
+ );
+}
diff --git a/src/client/features/ai-search/components/BrandLookupFilterPanel.tsx b/src/client/features/ai-search/components/BrandLookupFilterPanel.tsx
index 57dbfe7a..faccaf60 100644
--- a/src/client/features/ai-search/components/BrandLookupFilterPanel.tsx
+++ b/src/client/features/ai-search/components/BrandLookupFilterPanel.tsx
@@ -146,7 +146,7 @@ function TopPagesFilters({
<div className="min-w-[220px]">
<FilterRangeInputs
form={form}
- title="Mentions"
+ title="Source mentions"
minName="minMentions"
maxName="maxMentions"
/>
diff --git a/src/client/features/ai-search/components/BrandLookupHistorySection.tsx b/src/client/features/ai-search/components/BrandLookupHistorySection.tsx
index 3f396309..292c00d8 100644
--- a/src/client/features/ai-search/components/BrandLookupHistorySection.tsx
+++ b/src/client/features/ai-search/components/BrandLookupHistorySection.tsx
@@ -25,7 +25,13 @@ export function BrandLookupHistorySection({ projectId, ...props }: Props) {
from="/p/$projectId/brand-lookup"
to="/p/$projectId/brand-lookup"
params={{ projectId }}
- search={{ q: item.query }}
+ search={{
+ q: item.query,
+ c:
+ item.competitors.length > 0
+ ? item.competitors.join(",")
+ : undefined,
+ }}
replace
className={HISTORY_ITEM_LINK_CLASS}
>
@@ -33,7 +39,14 @@ export function BrandLookupHistorySection({ projectId, ...props }: Props) {
</Link>
)}
renderItem={(item) => (
- <p className="font-medium text-base-content truncate">{item.query}</p>
+ <div className="min-w-0">
+ <p className="truncate font-medium text-base-content">{item.query}</p>
+ {item.competitors.length > 0 ? (
+ <p className="truncate text-xs text-base-content/50">
+ vs {item.competitors.join(", ")}
+ </p>
+ ) : null}
+ </div>
)}
/>
);
diff --git a/src/client/features/ai-search/components/BrandLookupResults.tsx b/src/client/features/ai-search/components/BrandLookupResults.tsx
index fe7a8a52..a910e224 100644
--- a/src/client/features/ai-search/components/BrandLookupResults.tsx
+++ b/src/client/features/ai-search/components/BrandLookupResults.tsx
@@ -1,45 +1,23 @@
-import { useMemo, useState } from "react";
-import { type SortingState } from "@tanstack/react-table";
-import { Download, Info, SlidersHorizontal } from "lucide-react";
-import { useAppTable } from "@/client/components/table/AppDataTable";
-import { ExportToSheetsButton } from "@/client/components/table/ExportToSheetsButton";
-import {
- buildBrandLookupExport,
- downloadBrandLookupCsv,
-} from "@/client/features/ai-search/components/brandLookupExport";
+import { Info } from "lucide-react";
import { BrandLookupMentionTrendCard } from "@/client/features/ai-search/components/BrandLookupMentionTrendCard";
-import { BrandLookupFilterPanel } from "@/client/features/ai-search/components/BrandLookupFilterPanel";
-import {
- TopPagesTable,
- TopQueriesTable,
- topPagesColumns,
- topQueriesColumns,
-} from "@/client/features/ai-search/components/BrandLookupCitationTables";
+import { BrandLookupShareOfVoice } from "@/client/features/ai-search/components/BrandLookupShareOfVoice";
+import { CitationTabsCard } from "@/client/features/ai-search/components/BrandLookupCitationsCard";
import {
formatCount,
formatPlatformLabel,
+ PLATFORM_DOT_CLASS,
} from "@/client/features/ai-search/platformLabels";
-import {
- filterQueries,
- filterTopPages,
-} from "@/client/features/ai-search/brandLookupFiltering";
-import { useBrandLookupFilters } from "@/client/features/ai-search/useBrandLookupFilters";
-import type { CitationTab } from "@/client/features/ai-search/brandLookupFilterTypes";
import type { BrandLookupResult } from "@/types/schemas/ai-search";
type Props = {
result: BrandLookupResult;
+ projectId: string;
};
type PlatformRow = BrandLookupResult["perPlatform"][number];
-type MetricKey = "mentions" | "aiSearchVolume" | "impressions";
+type MetricKey = "mentions" | "aiSearchVolume";
-const PLATFORM_DOT_CLASS: Record<PlatformRow["platform"], string> = {
- chat_gpt: "bg-emerald-500",
- google: "bg-sky-500",
-};
-
-export function BrandLookupResults({ result }: Props) {
+export function BrandLookupResults({ result, projectId }: Props) {
if (!result.hasData) {
const erroredPlatforms = result.perPlatform.filter(
(p) => p.status === "error",
@@ -76,17 +54,27 @@ export function BrandLookupResults({ result }: Props) {
}
const hasTrendData = result.monthlyVolume.length > 0;
+ const sov = result.shareOfVoice;
return (
- <div className="space-y-6">
+ <div className="space-y-4">
<BrandHeader result={result} />
+
+ {/* One shared grid so the cards align by construction: stats left, trend
+ right, Share of Voice flowing into the next free half-width cell —
+ whichever of trend/SoV is absent, the rest stay column-aligned. A
+ lone stats card keeps full width instead of half a grid. */}
<div
- className={`grid gap-4 ${hasTrendData ? "lg:grid-cols-2" : "grid-cols-1"}`}
+ className={
+ hasTrendData || sov ? "grid gap-4 lg:grid-cols-2" : undefined
+ }
>
- <KpiTiles result={result} />
+ <StatsCard result={result} />
{hasTrendData ? <MentionTrendCard result={result} /> : null}
+ {sov ? <BrandLookupShareOfVoice shareOfVoice={sov} /> : null}
</div>
- <CitationTabsCard result={result} />
+
+ <CitationTabsCard result={result} projectId={projectId} />
</div>
);
}
@@ -109,64 +97,54 @@ function BrandHeader({ result }: { result: BrandLookupResult }) {
);
}
-function KpiTiles({ result }: { result: BrandLookupResult }) {
+function StatsCard({ result }: { result: BrandLookupResult }) {
return (
- <section className="flex flex-col divide-y divide-base-200 rounded-xl border border-base-300 bg-base-100">
- <KpiTile
- label="Total mentions"
- tooltip="Number of LLM answers where your domain appeared in the text or citations."
- total={result.totalMentions}
- perPlatform={result.perPlatform}
- metric="mentions"
- />
- <KpiTile
- label="AI search volume"
- tooltip="Monthly volume of user prompts on topics where your domain shows up in LLM answers."
- total={result.totalAiSearchVolume}
- perPlatform={result.perPlatform}
- metric="aiSearchVolume"
- />
- <KpiTile
- label="Estimated impressions"
- tooltip="How often your domain is shown to users across LLM answers, based on mention frequency and topic search volume."
- total={result.totalImpressions}
- perPlatform={result.perPlatform}
- metric="impressions"
- />
+ <section className="rounded-xl border border-base-300 bg-base-100">
+ <div className="flex h-full flex-col divide-y divide-base-200">
+ <StatBlock
+ label="Mentions"
+ tooltip="Estimated count of AI answers where the searched brand or domain appeared in the answer text or cited sources."
+ value={result.totalMentions}
+ perPlatform={result.perPlatform}
+ metric="mentions"
+ />
+ <StatBlock
+ label="AI search volume"
+ tooltip="Estimated monthly search demand for prompts where the searched brand or domain appears in AI answers. This is prompt demand, not mention count."
+ value={result.totalAiSearchVolume}
+ perPlatform={result.perPlatform}
+ metric="aiSearchVolume"
+ />
+ </div>
</section>
);
}
-function KpiTile({
+function StatBlock({
label,
tooltip,
- total,
+ value,
perPlatform,
metric,
}: {
label: string;
tooltip: string;
- total: number | null;
+ value: number | null;
perPlatform: PlatformRow[];
metric: MetricKey;
}) {
return (
- <div className="flex flex-1 items-center justify-between gap-6 px-5 py-3">
- <div className="min-w-0">
- <p className="inline-flex items-center gap-1 text-xs font-medium uppercase tracking-wider text-base-content/50">
- {label}
- <span
- className="tooltip tooltip-right inline-flex normal-case"
- data-tip={tooltip}
- >
- <Info className="size-3 text-base-content/40" />
- </span>
- </p>
- <p className="mt-1 text-2xl font-semibold tabular-nums">
- {formatCount(total)}
- </p>
- </div>
- <div className="flex shrink-0 flex-col gap-1.5 min-w-[12rem]">
+ <div className="flex flex-1 flex-col justify-center p-4">
+ <p className="inline-flex items-center gap-1 text-xs font-medium uppercase tracking-wider text-base-content/50">
+ {label}
+ <span className="tooltip inline-flex normal-case" data-tip={tooltip}>
+ <Info className="size-3 text-base-content/40" />
+ </span>
+ </p>
+ <p className="mt-1 text-3xl font-semibold tabular-nums">
+ {formatCount(value)}
+ </p>
+ <div className="mt-3 space-y-1 border-t border-base-200 pt-2.5">
{perPlatform.map((row) => (
<PlatformStatRow key={row.platform} row={row} metric={metric} />
))}
@@ -193,7 +171,7 @@ function PlatformStatRow({
{formatPlatformLabel(row.platform)}
{row.platform === "chat_gpt" ? (
<span
- className="tooltip tooltip-right z-20 inline-flex"
+ className="tooltip z-20 inline-flex"
data-tip="DataForSEO indexes ChatGPT mentions for US English only — country selection is not available for this platform."
>
<Info className="size-3 text-base-content/40" />
@@ -225,156 +203,6 @@ function MentionTrendCard({ result }: { result: BrandLookupResult }) {
);
}
-const DEFAULT_PAGES_SORT: SortingState = [{ id: "mentions", desc: true }];
-const DEFAULT_QUERIES_SORT: SortingState = [
- { id: "aiSearchVolume", desc: true },
-];
-
-function CitationTabsCard({ result }: { result: BrandLookupResult }) {
- const [activeTab, setActiveTab] = useState<CitationTab>("queries");
- const [pagesSort, setPagesSort] = useState<SortingState>(DEFAULT_PAGES_SORT);
- const [queriesSort, setQueriesSort] =
- useState<SortingState>(DEFAULT_QUERIES_SORT);
- const filters = useBrandLookupFilters();
-
- const filteredPages = useMemo(
- () => filterTopPages(result.topPages, filters.pages.values),
- [result.topPages, filters.pages.values],
- );
- const filteredQueries = useMemo(
- () => filterQueries(result.topQueries, filters.queries.values),
- [result.topQueries, filters.queries.values],
- );
-
- const pagesTable = useAppTable({
- data: filteredPages,
- columns: topPagesColumns,
- state: { sorting: pagesSort },
- onSortingChange: setPagesSort,
- withSorting: true,
- });
- const queriesTable = useAppTable({
- data: filteredQueries,
- columns: topQueriesColumns,
- state: { sorting: queriesSort },
- onSortingChange: setQueriesSort,
- withSorting: true,
- });
-
- // Not memoized: TanStack's `getSortedRowModel()` is internally cached, and
- // memoing on the table refs alone (which are stable across renders) would
- // serve stale data when sort or filters change.
- const exportTable = buildBrandLookupExport(
- activeTab,
- pagesTable.getSortedRowModel().rows.map((row) => row.original),
- queriesTable.getSortedRowModel().rows.map((row) => row.original),
- );
-
- const handleExport = () =>
- downloadBrandLookupCsv(activeTab, result.resolvedTarget, exportTable);
-
- const canExport = exportTable.rows.length > 0;
-
- const currentFilterCount = filters[activeTab].activeFilterCount;
- const queriesActive = activeTab === "queries";
- const pagesActive = activeTab === "pages";
-
- return (
- <section className="overflow-hidden rounded-xl border border-base-300 bg-base-100">
- <div className="flex items-center justify-between gap-3 border-b border-base-300 px-4 py-3">
- <div role="tablist" className="tabs tabs-box w-fit">
- <button
- type="button"
- role="tab"
- aria-selected={queriesActive}
- className={`tab ${queriesActive ? "tab-active" : ""}`}
- onClick={() => setActiveTab("queries")}
- >
- Queries
- </button>
- <button
- type="button"
- role="tab"
- aria-selected={pagesActive}
- className={`tab ${pagesActive ? "tab-active" : ""}`}
- onClick={() => setActiveTab("pages")}
- >
- Related pages
- </button>
- </div>
-
- <div className="flex items-center gap-2">
- <ExportToSheetsButton
- headers={exportTable.headers}
- rows={exportTable.rows}
- feature={`brand_lookup_${activeTab}`}
- className="btn-sm"
- />
- <button
- type="button"
- className="btn btn-ghost btn-sm gap-1.5"
- onClick={handleExport}
- disabled={!canExport}
- aria-label="Export current tab as CSV"
- >
- <Download className="size-3.5" />
- Export CSV
- </button>
- </div>
- </div>
-
- <div className="flex items-center gap-2 border-b border-base-300 px-4 py-2">
- <button
- type="button"
- className={`btn btn-ghost btn-sm gap-1.5 ${filters.showFilters ? "btn-active" : ""}`}
- onClick={() => filters.setShowFilters((current) => !current)}
- title="Toggle table filters"
- >
- <SlidersHorizontal className="size-3.5" />
- Filters
- {currentFilterCount > 0 ? (
- <span className="badge badge-xs badge-primary border-0 text-primary-content">
- {currentFilterCount}
- </span>
- ) : null}
- </button>
- </div>
-
- <div className="border-b border-base-300 px-4 py-2 text-xs text-base-content/60">
- {activeTab === "pages" ? (
- <>
- Other pages LLMs cited in the same answers that referenced{" "}
- <strong className="text-base-content/80">
- {result.resolvedTarget}
- </strong>
- . Useful for spotting the sources competing for attention alongside
- your domain.
- </>
- ) : (
- <>
- User prompts where the LLM's answer referenced{" "}
- <strong className="text-base-content/80">
- {result.resolvedTarget}
- </strong>{" "}
- in its text or citations. The prompt itself does not have to mention
- your domain.
- </>
- )}
- </div>
-
- {filters.showFilters ? (
- <BrandLookupFilterPanel activeTab={activeTab} filters={filters} />
- ) : null}
-
- {activeTab === "pages" ? (
- <TopPagesTable table={pagesTable} />
- ) : (
- <TopQueriesTable table={queriesTable} />
- )}
- </section>
- );
-}
-
function formatRelative(iso: string): string {
const date = new Date(iso);
if (Number.isNaN(date.getTime())) return "just now";
diff --git a/src/client/features/ai-search/components/BrandLookupSearchCard.tsx b/src/client/features/ai-search/components/BrandLookupSearchCard.tsx
index e5f3c37f..f84e3e97 100644
--- a/src/client/features/ai-search/components/BrandLookupSearchCard.tsx
+++ b/src/client/features/ai-search/components/BrandLookupSearchCard.tsx
@@ -7,72 +7,114 @@ import { BRAND_LOOKUP_MAX_INPUT_LENGTH } from "@/types/schemas/ai-search";
type Props = {
query: string;
onQueryChange: (next: string) => void;
+ competitors: string;
+ onCompetitorsChange: (next: string) => void;
onSubmit: (event: FormEvent) => void;
isLoading: boolean;
- validationError: string | null;
+ validationError: { field: "query" | "competitors"; message: string } | null;
};
/**
- * One brand lookup = 6 DataForSEO calls (3 endpoints × 2 platforms). Measured
- * live at ~$0.634 raw via `pnpm billing:brand-lookup`; rounded up to leave
- * headroom for per-query variance.
+ * One brand lookup = 6 DataForSEO calls (aggregated_metrics + top_pages +
+ * mentions_search × 2 platforms). Rounded up with headroom because
+ * mentions_search is row-priced at the full 100-row sample per platform.
*/
-const BRAND_LOOKUP_RAW_COST_USD = 0.65;
+const BRAND_LOOKUP_RAW_COST_USD = 0.85;
+
+/**
+ * Adding competitors triggers 2 extra cross_aggregated_metrics calls (one per
+ * platform). Measured live (Jun 2026) at $0.101 each — $0.202 total for a
+ * 4-group comparison — via `pnpm billing:brand-lookup --competitors=...`. A
+ * fixed estimate, marked up once at module load exactly like the base.
+ */
+const BRAND_LOOKUP_COMPETITOR_RAW_COST_USD = 0.2;
// Hosted customers are billed the marked-up USD; self-hosted users pay
// DataForSEO directly at the raw rate.
-const BRAND_LOOKUP_DISPLAYED_COST_USD = isHostedClientAuthMode()
- ? applyBillingMarkupUsd(BRAND_LOOKUP_RAW_COST_USD)
- : BRAND_LOOKUP_RAW_COST_USD;
+const markup = (rawUsd: number) =>
+ isHostedClientAuthMode() ? applyBillingMarkupUsd(rawUsd) : rawUsd;
+
+const BRAND_LOOKUP_DISPLAYED_COST_USD = markup(BRAND_LOOKUP_RAW_COST_USD);
+const BRAND_LOOKUP_COMPETITOR_DISPLAYED_COST_USD = markup(
+ BRAND_LOOKUP_COMPETITOR_RAW_COST_USD,
+);
export function BrandLookupSearchCard({
query,
onQueryChange,
+ competitors,
+ onCompetitorsChange,
onSubmit,
isLoading,
validationError,
}: Props) {
+ const hasCompetitors = competitors.trim().length > 0;
+ const queryError = validationError?.field === "query";
+ const competitorsError = validationError?.field === "competitors";
+
return (
<div className="card border border-base-300 bg-base-100">
<div className="card-body gap-4">
- <form
- onSubmit={onSubmit}
- className="flex flex-col gap-3 lg:flex-row lg:items-center"
- >
- <label
- className={`input input-bordered flex flex-1 items-center gap-2 ${
- validationError ? "input-error" : ""
- }`}
- >
- <Search className="size-4 text-base-content/60" />
+ <form onSubmit={onSubmit} className="flex flex-col gap-3">
+ <div className="flex flex-col gap-3 lg:flex-row lg:items-center">
+ <label
+ className={`input input-bordered flex flex-1 items-center gap-2 ${
+ queryError ? "input-error" : ""
+ }`}
+ >
+ <Search className="size-4 text-base-content/60" />
+ <input
+ type="text"
+ placeholder="Enter a brand name or domain"
+ value={query}
+ maxLength={BRAND_LOOKUP_MAX_INPUT_LENGTH}
+ onChange={(event) => onQueryChange(event.target.value)}
+ aria-invalid={queryError || undefined}
+ aria-describedby={
+ queryError ? "brand-lookup-input-error" : undefined
+ }
+ autoComplete="off"
+ spellCheck={false}
+ className="grow"
+ />
+ </label>
+
+ <button
+ type="submit"
+ className="btn btn-primary px-6"
+ disabled={isLoading}
+ >
+ {isLoading ? "Looking up..." : "Look up"}
+ </button>
+ </div>
+
+ <div className="flex flex-col gap-1">
<input
type="text"
- placeholder="Enter a brand name or domain"
- value={query}
- maxLength={BRAND_LOOKUP_MAX_INPUT_LENGTH}
- onChange={(event) => onQueryChange(event.target.value)}
- aria-invalid={validationError ? true : undefined}
- aria-describedby={
- validationError ? "brand-lookup-input-error" : undefined
- }
+ placeholder="Add competitors (comma-separated)"
+ value={competitors}
+ onChange={(event) => onCompetitorsChange(event.target.value)}
autoComplete="off"
spellCheck={false}
- className="grow"
+ className={`input input-bordered w-full ${
+ competitorsError ? "input-error" : ""
+ }`}
+ aria-label="Competitors"
+ aria-invalid={competitorsError || undefined}
+ aria-describedby={
+ competitorsError ? "brand-lookup-input-error" : undefined
+ }
/>
- </label>
-
- <button
- type="submit"
- className="btn btn-primary px-6"
- disabled={isLoading}
- >
- {isLoading ? "Looking up..." : "Look up"}
- </button>
+ <p className="text-xs text-base-content/60">
+ Add up to 5 competitor brands or domains to see your Share of
+ Voice.
+ </p>
+ </div>
</form>
{validationError ? (
<p id="brand-lookup-input-error" className="text-sm text-error">
- {validationError}
+ {validationError.message}
</p>
) : null}
@@ -82,6 +124,14 @@ export function BrandLookupSearchCard({
<span className="font-medium text-base-content/80">
${BRAND_LOOKUP_DISPLAYED_COST_USD.toFixed(2)}
</span>
+ {hasCompetitors ? (
+ <span>
+ {" "}
+ plus ~$
+ {BRAND_LOOKUP_COMPETITOR_DISPLAYED_COST_USD.toFixed(2)} to
+ compare competitors
+ </span>
+ ) : null}
</p>
</div>
</div>
diff --git a/src/client/features/ai-search/components/BrandLookupShareOfVoice.tsx b/src/client/features/ai-search/components/BrandLookupShareOfVoice.tsx
new file mode 100644
index 00000000..0bf8e7af
--- /dev/null
+++ b/src/client/features/ai-search/components/BrandLookupShareOfVoice.tsx
@@ -0,0 +1,110 @@
+import {
+ formatCount,
+ formatPlatformLabel,
+} from "@/client/features/ai-search/platformLabels";
+import type { BrandLookupResult } from "@/types/schemas/ai-search";
+
+type ShareOfVoice = NonNullable<BrandLookupResult["shareOfVoice"]>;
+type ShareEntry = ShareOfVoice["entries"][number];
+
+/**
+ * Competitor Share of Voice leaderboard. The server sorts entries descending by
+ * mentions and flags `isTarget`; this component only renders. Bars are scaled to
+ * the leader (the exact % is shown on every row, so nothing is hidden) so a
+ * dominant competitor reads as a full bar and small shares stay visible.
+ */
+export function BrandLookupShareOfVoice({
+ shareOfVoice,
+}: {
+ shareOfVoice: ShareOfVoice;
+}) {
+ const target = shareOfVoice.entries.find((entry) => entry.isTarget) ?? null;
+ const maxPct = Math.max(
+ 0,
+ ...shareOfVoice.entries.map((entry) => entry.sharePct ?? 0),
+ );
+
+ return (
+ <section className="flex h-full flex-col overflow-hidden rounded-xl border border-base-300 bg-base-100">
+ <div className="flex items-baseline justify-between gap-2 border-b border-base-300 px-4 py-3">
+ <h3 className="text-sm font-semibold">Share of Voice</h3>
+ {target ? (
+ <span className="text-xs text-base-content/50">
+ <span className="font-medium text-base-content/80">
+ {target.label}
+ </span>{" "}
+ {target.sharePct == null
+ ? "· no comparable data"
+ : `· ${Math.round(target.sharePct)}%`}
+ </span>
+ ) : null}
+ </div>
+
+ <ul className="flex-1 divide-y divide-base-200">
+ {shareOfVoice.entries.map((entry, index) => (
+ <LeaderboardRow
+ key={entry.label}
+ entry={entry}
+ rank={index + 1}
+ maxPct={maxPct}
+ />
+ ))}
+ </ul>
+
+ {/* Captions only the platforms actually summed — when one platform's
+ cross_aggregated call failed, the leaderboard must not claim both. */}
+ <p className="border-t border-base-200 px-4 py-2 text-[11px] text-base-content/50">
+ Mentions share across{" "}
+ {shareOfVoice.platforms.map(formatPlatformLabel).join(" and ")} · bars
+ relative to the leader.
+ </p>
+ </section>
+ );
+}
+
+function LeaderboardRow({
+ entry,
+ rank,
+ maxPct,
+}: {
+ entry: ShareEntry;
+ rank: number;
+ maxPct: number;
+}) {
+ const hasData = entry.mentions != null && entry.sharePct != null;
+ const barWidth =
+ hasData && maxPct > 0 ? ((entry.sharePct ?? 0) / maxPct) * 100 : 0;
+
+ return (
+ <li
+ className={`grid grid-cols-[1.25rem_minmax(0,1fr)_2.75rem] items-center gap-3 px-4 py-2.5 ${
+ entry.isTarget ? "bg-primary/5" : ""
+ }`}
+ >
+ <span className="text-xs tabular-nums text-base-content/40">{rank}</span>
+ <div className="min-w-0">
+ <div className="flex items-center gap-2">
+ <span className="truncate text-sm">{entry.label}</span>
+ {entry.isTarget ? (
+ <span className="badge badge-primary badge-xs border-0">You</span>
+ ) : null}
+ <span className="ml-auto shrink-0 text-xs tabular-nums text-base-content/50">
+ {/* Null mentions = "no data"; render a dash, not zero. */}
+ {entry.mentions == null ? "—" : formatCount(entry.mentions)}
+ </span>
+ </div>
+ <div className="mt-1.5 h-1.5 overflow-hidden rounded-full bg-base-200">
+ <div
+ className={`h-full rounded-full ${
+ entry.isTarget ? "bg-primary" : "bg-base-content/25"
+ }`}
+ style={{ width: `${barWidth}%` }}
+ />
+ </div>
+ </div>
+ <span className="text-right text-sm font-medium tabular-nums">
+ {hasData ? `${Math.round(entry.sharePct ?? 0)}%` : "—"}
+ </span>
+ </li>
+ );
+}
diff --git a/src/client/features/ai-search/components/brandLookupExport.ts b/src/client/features/ai-search/components/brandLookupExport.ts
index 6584a85a..a5a8ad07 100644
--- a/src/client/features/ai-search/components/brandLookupExport.ts
+++ b/src/client/features/ai-search/components/brandLookupExport.ts
@@ -14,12 +14,21 @@ export function buildBrandLookupExport(
): { headers: string[]; rows: CsvValue[][] } {
if (tab === "pages") {
return {
- headers: ["URL", "Domain", "Platform", "Mentions"],
+ headers: [
+ "URL",
+ "Domain",
+ "Platform",
+ "Source mentions",
+ "Source AI search volume",
+ "Fetched-sample prompt examples",
+ ],
rows: sortedPages.map((row) => [
row.url,
row.domain ?? "",
formatPlatformLabel(row.platform),
row.mentions ?? "",
+ row.capturedVolume ?? "",
+ row.keywords.map((keyword) => keyword.question).join("; "),
]),
};
}
diff --git a/src/client/features/ai-search/platformLabels.ts b/src/client/features/ai-search/platformLabels.ts
index 5dd27353..e42ddbe4 100644
--- a/src/client/features/ai-search/platformLabels.ts
+++ b/src/client/features/ai-search/platformLabels.ts
@@ -48,6 +48,17 @@ export function formatPlatformLabel(platform: "chat_gpt" | "google"): string {
return MENTION_PLATFORM_LABELS[platform];
}
+/** Shared per-platform accent dot + short label for compact table/KPI rows. */
+export const PLATFORM_DOT_CLASS: Record<"chat_gpt" | "google", string> = {
+ chat_gpt: "bg-emerald-500",
+ google: "bg-sky-500",
+};
+
+export const PLATFORM_SHORT_LABEL: Record<"chat_gpt" | "google", string> = {
+ chat_gpt: "ChatGPT",
+ google: "Google",
+};
+
export function formatModelLabel(model: PromptExplorerModel): string {
return MODEL_LABELS[model];
}
diff --git a/src/client/features/ai-search/useBrandLookupFilters.ts b/src/client/features/ai-search/useBrandLookupFilters.ts
index ad7ed6bb..986fb78c 100644
--- a/src/client/features/ai-search/useBrandLookupFilters.ts
+++ b/src/client/features/ai-search/useBrandLookupFilters.ts
@@ -8,7 +8,10 @@ import {
} from "./brandLookupFilterTypes";
import { countActiveFilters } from "./brandLookupFiltering";
-const STORAGE_KEY_PREFIX = "brand-lookup-filters:";
+// v3: the pages tab returned to provider page-level metrics after a brief
+// sampled-prompt scale. Bump the prefix so local min/max filters do not carry
+// between incompatible metric scales.
+const STORAGE_KEY_PREFIX = "brand-lookup-filters-v3:";
type FilterValues = Record<string, string>;
diff --git a/src/client/hooks/useBrandLookupSearchHistory.ts b/src/client/hooks/useBrandLookupSearchHistory.ts
index 193e608f..9ac41c4d 100644
--- a/src/client/hooks/useBrandLookupSearchHistory.ts
+++ b/src/client/hooks/useBrandLookupSearchHistory.ts
@@ -3,6 +3,8 @@ import { useTimestampedSearchHistory } from "@/client/hooks/useTimestampedSearch
const brandLookupSearchBodySchema = z.object({
query: z.string(),
+ // Optional/defaulted so pre-existing history entries (query only) still parse.
+ competitors: z.array(z.string()).optional().default([]),
});
type BrandLookupSearchBody = z.infer<typeof brandLookupSearchBodySchema>;
@@ -15,6 +17,10 @@ export function useBrandLookupSearchHistory(projectId: string) {
return useTimestampedSearchHistory({
storageKey: `brand-lookup-search-history:${projectId}`,
bodySchema: brandLookupSearchBodySchema,
- isSame: (a, b) => a.query === b.query,
+ // Competitor set is part of the identity: a plain lookup must not replace
+ // the saved (already paid for) Share-of-Voice comparison of the same brand.
+ isSame: (a, b) =>
+ a.query === b.query &&
+ a.competitors.join(",") === b.competitors.join(","),
});
}
diff --git a/src/routes/_project/p/$projectId/brand-lookup.tsx b/src/routes/_project/p/$projectId/brand-lookup.tsx
index 94efbfb4..fa832aec 100644
--- a/src/routes/_project/p/$projectId/brand-lookup.tsx
+++ b/src/routes/_project/p/$projectId/brand-lookup.tsx
@@ -10,17 +10,24 @@ export const Route = createFileRoute("/_project/p/$projectId/brand-lookup")({
function BrandLookupRoute() {
const { projectId } = Route.useParams();
const navigate = useNavigate({ from: Route.fullPath });
- const { q = "" } = Route.useSearch();
+ // `c` is already an opaque competitor string array via the schema transform.
+ const { q = "", c = [] } = Route.useSearch();
return (
<BrandLookupPage
projectId={projectId}
initialQuery={q}
- onQueryChange={(nextQuery) => {
+ initialCompetitors={c}
+ onSearchChange={(nextQuery, nextCompetitors) => {
void navigate({
search: (prev) => ({
...prev,
q: nextQuery.trim() || undefined,
+ // One serialization site: comma-join the competitor list.
+ c:
+ nextCompetitors.length > 0
+ ? nextCompetitors.join(",")
+ : undefined,
}),
replace: true,
});
diff --git a/src/server/features/ai-search/services/brandLookup.test.ts b/src/server/features/ai-search/services/brandLookup.test.ts
new file mode 100644
index 00000000..da70be16
--- /dev/null
+++ b/src/server/features/ai-search/services/brandLookup.test.ts
@@ -0,0 +1,283 @@
+import { describe, expect, it, vi } from "vitest";
+
+vi.mock("cloudflare:workers", () => ({ waitUntil: vi.fn() }));
+
+const { dataforseoClientMock, cacheMock } = vi.hoisted(() => ({
+ dataforseoClientMock: {
+ aiSearch: {
+ aggregatedMetrics: vi.fn(),
+ topPages: vi.fn(),
+ mentionsSearch: vi.fn(),
+ crossAggregatedMetrics: vi.fn(),
+ },
+ },
+ cacheMock: {
+ buildCacheKey: vi.fn(async (_prefix: string, params: unknown) =>
+ JSON.stringify(params),
+ ),
+ getCached: vi.fn(),
+ setCached: vi.fn(async () => undefined),
+ },
+}));
+
+vi.mock("@/server/lib/dataforseo", () => {
+ return {
+ CHATGPT_LANGUAGE_CODE: "en",
+ CHATGPT_LOCATION_CODE: 2840,
+ buildLlmTarget: vi.fn(
+ ({ type, value }: { type: "domain" | "keyword"; value: string }) =>
+ type === "domain" ? { domain: value } : { keyword: value },
+ ),
+ createDataforseoClient: vi.fn(() => dataforseoClientMock),
+ };
+});
+
+vi.mock("@/server/lib/r2-cache", () => cacheMock);
+
+import { getBrandLookup } from "./brandLookup";
+import { shapeResult, type ShapeArgs } from "./brandLookupShaping";
+import { resolveCompetitorGroups } from "./shareOfVoice";
+import { brandLookupSearchSchema } from "@/types/schemas/ai-search";
+import type {
+ LlmMentionItem,
+ LlmTopPagesItem,
+} from "@/server/lib/dataforseoLlmSchemas";
+import type { BillingCustomerContext } from "@/server/billing/subscription";
+
+const billingCustomer: BillingCustomerContext = {
+ organizationId: "org_123",
+ userId: "user_123",
+ userEmail: "[email protected]",
+};
+
+type PlatformBundle = {
+ aggregated: { platform?: Array<Record<string, unknown>> | null };
+ topPages: LlmTopPagesItem[];
+ mentions: LlmMentionItem[];
+ complete: boolean;
+};
+
+function platformBundle(
+ platform: "chat_gpt" | "google",
+ mentions: number | null,
+ aiSearchVolume: number | null,
+): ShapeArgs["platformBundles"][number] {
+ return {
+ platform,
+ status: "success",
+ bundle: {
+ aggregated: {
+ platform: [
+ {
+ key: platform,
+ mentions,
+ ai_search_volume: aiSearchVolume,
+ // Deprecated field still present in upstream payloads; must be
+ // ignored end-to-end.
+ impressions: 999,
+ },
+ ],
+ },
+ topPages: [],
+ mentions: [],
+ complete: true,
+ } as PlatformBundle,
+ };
+}
+
+function baseArgs(overrides: Partial<ShapeArgs>): ShapeArgs {
+ return {
+ query: "acme",
+ detected: { type: "keyword", value: "acme" },
+ platformBundles: [
+ platformBundle("chat_gpt", 10, 100),
+ platformBundle("google", 5, 50),
+ ],
+ crossOutcomes: [],
+ competitorKeys: [],
+ userLocationCode: 2840,
+ userLanguageCode: "en",
+ ...overrides,
+ };
+}
+
+function resetBrandLookupMocks(): void {
+ vi.clearAllMocks();
+ cacheMock.getCached.mockResolvedValue(null);
+ cacheMock.setCached.mockResolvedValue(undefined);
+ dataforseoClientMock.aiSearch.aggregatedMetrics.mockResolvedValue({
+ platform: [{ key: "google", mentions: 5, ai_search_volume: 50 }],
+ });
+ dataforseoClientMock.aiSearch.topPages.mockImplementation(
+ async ({ platform }: { platform: "chat_gpt" | "google" }) => [
+ topPage(`https://${platform}.example/source`, platform, 3, 300),
+ ],
+ );
+ dataforseoClientMock.aiSearch.mentionsSearch.mockImplementation(
+ async ({ platform }: { platform: "chat_gpt" | "google" }) => [
+ citedMention("best source", 100, [`https://${platform}.example/source`]),
+ ],
+ );
+ dataforseoClientMock.aiSearch.crossAggregatedMetrics.mockResolvedValue([]);
+}
+
+describe("getBrandLookup", () => {
+ it("fetches top_pages as part of the base lookup", async () => {
+ resetBrandLookupMocks();
+
+ await getBrandLookup(
+ {
+ projectId: "project_123",
+ query: "acme.com",
+ competitors: [],
+ locationCode: 2840,
+ languageCode: "en",
+ },
+ billingCustomer,
+ );
+
+ expect(dataforseoClientMock.aiSearch.topPages).toHaveBeenCalledTimes(2);
+ expect(dataforseoClientMock.aiSearch.topPages).toHaveBeenCalledWith(
+ expect.objectContaining({
+ platform: "chat_gpt",
+ itemsListLimit: 10,
+ }),
+ );
+ expect(dataforseoClientMock.aiSearch.topPages).toHaveBeenCalledWith(
+ expect.objectContaining({
+ platform: "google",
+ itemsListLimit: 10,
+ }),
+ );
+ expect(cacheMock.setCached).toHaveBeenCalledTimes(1);
+ });
+
+ it("does not cache a renderable partial result when top_pages fails", async () => {
+ resetBrandLookupMocks();
+ const consoleError = vi
+ .spyOn(console, "error")
+ .mockImplementation(() => undefined);
+ dataforseoClientMock.aiSearch.topPages.mockRejectedValueOnce(
+ new Error("top pages failed"),
+ );
+
+ const result = await getBrandLookup(
+ {
+ projectId: "project_123",
+ query: "acme.com",
+ competitors: [],
+ locationCode: 2840,
+ languageCode: "en",
+ },
+ billingCustomer,
+ );
+
+ expect(result.hasData).toBe(true);
+ expect(cacheMock.setCached).not.toHaveBeenCalled();
+ consoleError.mockRestore();
+ });
+
+ it("uses semantic cache keys and reapplies the current display query", async () => {
+ resetBrandLookupMocks();
+ cacheMock.getCached.mockResolvedValueOnce({
+ ...shapeResult(baseArgs({})),
+ query: "Nike",
+ resolvedTarget: "Nike",
+ });
+
+ const result = await getBrandLookup(
+ {
+ projectId: "project_123",
+ query: "nike",
+ competitors: ["ADIDAS"],
+ locationCode: 2840,
+ languageCode: "en",
+ },
+ billingCustomer,
+ );
+
+ expect(result.query).toBe("nike");
+ expect(cacheMock.buildCacheKey).toHaveBeenCalledWith(
+ "ai-search:brand-lookup",
+ expect.objectContaining({
+ targetValue: "nike",
+ competitors: "adidas",
+ }),
+ );
+ expect(
+ dataforseoClientMock.aiSearch.aggregatedMetrics,
+ ).not.toHaveBeenCalled();
+ });
+});
+
+describe("resolveCompetitorGroups", () => {
+ it("dedupes case-insensitively and drops target collisions", () => {
+ // DataForSEO matches keyword targets case-insensitively, so "Nike" and
+ // "nike" would be two paid groups returning identical counts.
+ const groups = resolveCompetitorGroups("Nike", [
+ "nike",
+ "Adidas",
+ "ADIDAS",
+ "puma.com",
+ "www.PUMA.com",
+ ]);
+ expect(groups.map((g) => g.label)).toEqual(["Adidas", "puma.com"]);
+ });
+});
+
+describe("brandLookupSearchSchema — `c` competitor param", () => {
+ it("parses a raw comma-separated string from the URL", () => {
+ expect(brandLookupSearchSchema.parse({ c: "nike, adidas" }).c).toEqual([
+ "nike",
+ "adidas",
+ ]);
+ });
+
+ it("accepts an already-parsed array (TanStack re-validates its own output)", () => {
+ // navigate() feeds the previous transformed output (a string[]) back through
+ // validateSearch — this must not throw "expected string, received array".
+ expect(brandLookupSearchSchema.parse({ c: ["nike", "adidas"] }).c).toEqual([
+ "nike",
+ "adidas",
+ ]);
+ });
+
+ it("dedupes and caps at 5 regardless of input form", () => {
+ const many = ["a", "a", "b", "c", "d", "e", "f"];
+ expect(brandLookupSearchSchema.parse({ c: many }).c).toEqual([
+ "a",
+ "b",
+ "c",
+ "d",
+ "e",
+ ]);
+ });
+
+ it("leaves `c` undefined when absent", () => {
+ expect(brandLookupSearchSchema.parse({}).c).toBeUndefined();
+ });
+});
+
+function citedMention(
+ question: string,
+ aiSearchVolume: number | null,
+ urls: string[],
+): LlmMentionItem {
+ return {
+ question,
+ ai_search_volume: aiSearchVolume,
+ sources: urls.map((url) => ({ url })),
+ };
+}
+
+function topPage(
+ url: string,
+ platform: "chat_gpt" | "google",
+ mentions: number | null,
+ aiSearchVolume: number | null,
+): LlmTopPagesItem {
+ return {
+ key: url,
+ platform: [{ key: platform, mentions, ai_search_volume: aiSearchVolume }],
+ };
+}
diff --git a/src/server/features/ai-search/services/brandLookup.ts b/src/server/features/ai-search/services/brandLookup.ts
index 1dc8e939..260397f1 100644
--- a/src/server/features/ai-search/services/brandLookup.ts
+++ b/src/server/features/ai-search/services/brandLookup.ts
@@ -1,5 +1,4 @@
import { waitUntil } from "cloudflare:workers";
-import { sortBy } from "remeda";
import type { BillingCustomerContext } from "@/server/billing/subscription";
import { createDataforseoClient } from "@/server/lib/dataforseo";
import {
@@ -8,20 +7,25 @@ import {
CHATGPT_LOCATION_CODE,
type LlmPlatform,
} from "@/server/lib/dataforseo";
-import type {
- LlmAggregatedTotal,
- LlmMentionItem,
- LlmTopPagesItem,
-} from "@/server/lib/dataforseoLlmSchemas";
+import type { LlmCrossAggregatedItem } from "@/server/lib/dataforseoLlmSchemas";
import { AppError } from "@/server/lib/errors";
import { buildCacheKey, getCached, setCached } from "@/server/lib/r2-cache";
-import { safeHostname, safeHttpUrl } from "@/server/features/ai-search/safeUrl";
+import {
+ resolveCompetitorGroups,
+ type CompetitorGroup,
+ type CrossOutcome,
+} from "@/server/features/ai-search/services/shareOfVoice";
+import {
+ shapeResult,
+ type PlatformBundle,
+ type PlatformOutcome,
+} from "@/server/features/ai-search/services/brandLookupShaping";
import {
brandLookupResultSchema,
type BrandLookupInput,
type BrandLookupResult,
} from "@/types/schemas/ai-search";
-import { detectTarget } from "@/server/features/ai-search/targetDetection";
+import { detectTarget } from "@/shared/targetDetection";
/**
* Brand Lookup is the AI-search analog of Domain Overview. The user types a
@@ -35,39 +39,77 @@ const BRAND_LOOKUP_TTL_SECONDS = 24 * 60 * 60;
const PLATFORMS: LlmPlatform[] = ["chat_gpt", "google"];
-const TOP_PAGES_PER_PLATFORM = 10;
-const TOP_QUERIES_PER_PLATFORM = 25;
+// Prompt rows supply explainable examples for cited pages. Ranked source rows
+// come from top_pages so the table is not limited to this sample.
+const MENTIONS_PER_PLATFORM = 100;
+const TOP_SOURCES_PER_PLATFORM = 10;
export async function getBrandLookup(
input: BrandLookupInput,
billingCustomer: BillingCustomerContext,
): Promise<BrandLookupResult> {
const detected = detectTarget(input.query);
+ const competitorGroups = resolveCompetitorGroups(
+ detected.value,
+ input.competitors,
+ );
+ // Changing this key's param set orphans every pre-deploy cache entry; with a
+ // 24h TTL that's at most one re-charged lookup per cached target — accepted
+ // rather than maintaining parallel legacy-shape parsing.
const cacheKey = await buildCacheKey("ai-search:brand-lookup", {
organizationId: billingCustomer.organizationId,
projectId: input.projectId,
targetType: detected.type,
- targetValue: detected.value,
+ // Values are lowercased for DataForSEO's matching semantics. Competitors
+ // are canonical detected values too, so equivalent casing/order shares one
+ // paid cache entry.
+ targetValue: detected.value.toLowerCase(),
+ competitors: competitorGroups
+ .map((g) => g.detected.value.toLowerCase())
+ .toSorted()
+ .join("|"),
locationCode: input.locationCode,
languageCode: input.languageCode,
});
const cached = brandLookupResultSchema.safeParse(await getCached(cacheKey));
- if (cached.success) return cached.data;
+ if (cached.success) {
+ return {
+ ...cached.data,
+ query: input.query,
+ resolvedTarget: detected.value,
+ };
+ }
const dataforseo = createDataforseoClient(billingCustomer);
- // Settle each platform independently so a failure in one doesn't discard
- // the other (which the caller already paid for via meterDataforseoCall).
- const settled = await Promise.allSettled(
- PLATFORMS.map((platform) =>
- fetchPlatformData(platform, detected, input, dataforseo),
- ),
- );
+ // Settle each platform independently so a failure in one doesn't discard the
+ // other. Keep the metered DataForSEO calls sequenced: in hosted mode each
+ // call checks balance before execution and records spend after, so parallel
+ // fan-out can overrun a low remaining balance.
+ const settled: Array<PromiseSettledResult<PlatformBundle>> = [];
+ for (const platform of PLATFORMS) {
+ settled.push(
+ await settle(() =>
+ fetchPlatformData(platform, detected, input, dataforseo),
+ ),
+ );
+ }
rethrowIfBlockingAiSearchError(settled);
+ const crossSettled =
+ competitorGroups.length > 0
+ ? await settle(() =>
+ fetchCrossAggregated(detected, competitorGroups, input, dataforseo),
+ )
+ : ({ status: "fulfilled", value: [] } as PromiseFulfilledResult<
+ CrossOutcome[]
+ >);
+ if (crossSettled.status === "rejected") throw crossSettled.reason;
+ const crossOutcomes = crossSettled.value;
+
const platformBundles: PlatformOutcome[] = settled.map((settledResult, i) => {
const platform = PLATFORMS[i];
if (settledResult.status === "fulfilled") {
@@ -84,13 +126,20 @@ export async function getBrandLookup(
query: input.query,
detected,
platformBundles,
+ crossOutcomes,
+ competitorKeys: competitorGroups.map((g) => g.label),
userLocationCode: input.locationCode,
userLanguageCode: input.languageCode,
});
- // Only cache when every platform succeeded — otherwise users would see a
- // stale partial result for 24h and have no way to retry without busting it.
- const allSucceeded = platformBundles.every((b) => b.status === "success");
+ // Only cache when every call succeeded — a platform bundle that swallowed a
+ // failed sub-call into empty fallback data is renderable but must not be
+ // frozen for 24h with no way to retry; same for a partial SoV miss when
+ // competitors were requested.
+ const allSucceeded =
+ platformBundles.every(
+ (b) => b.status === "success" && b.bundle?.complete,
+ ) && crossOutcomes.every((c) => c.status === "success");
if (allSucceeded && result.hasData) {
waitUntil(
setCached(cacheKey, result, BRAND_LOOKUP_TTL_SECONDS).catch((err) => {
@@ -102,23 +151,21 @@ export async function getBrandLookup(
return result;
}
+async function settle<T>(
+ execute: () => Promise<T>,
+): Promise<PromiseSettledResult<T>> {
+ try {
+ return { status: "fulfilled", value: await execute() };
+ } catch (reason) {
+ return { status: "rejected", reason };
+ }
+}
+
type PlatformFetchInput = Pick<
BrandLookupInput,
"locationCode" | "languageCode"
>;
-type PlatformBundle = {
- aggregated: LlmAggregatedTotal;
- topPages: LlmTopPagesItem[];
- mentions: LlmMentionItem[];
-};
-
-type PlatformOutcome = {
- platform: LlmPlatform;
- status: "success" | "error";
- bundle: PlatformBundle | null;
-};
-
async function fetchPlatformData(
platform: LlmPlatform,
detected: ReturnType<typeof detectTarget>,
@@ -136,9 +183,9 @@ async function fetchPlatformData(
const languageCode =
platform === "chat_gpt" ? CHATGPT_LANGUAGE_CODE : input.languageCode;
- // `allSettled` so one sub-call failing doesn't discard the other two we
- // already paid for. Each sub-call is metered independently upstream.
- const [aggregated, topPages, mentions] = await Promise.allSettled([
+ // Settle sub-calls independently so one failure doesn't discard the others we
+ // already paid for, but keep them sequenced for hosted billing checks.
+ const aggregated = await settle(() =>
dataforseo.aiSearch.aggregatedMetrics({
target,
platform,
@@ -146,21 +193,25 @@ async function fetchPlatformData(
languageCode,
internalListLimit: 20,
}),
+ );
+ const topPages = await settle(() =>
dataforseo.aiSearch.topPages({
target,
platform,
locationCode,
languageCode,
- itemsListLimit: TOP_PAGES_PER_PLATFORM,
+ itemsListLimit: TOP_SOURCES_PER_PLATFORM,
}),
+ );
+ const mentions = await settle(() =>
dataforseo.aiSearch.mentionsSearch({
target,
platform,
locationCode,
languageCode,
- limit: TOP_QUERIES_PER_PLATFORM,
+ limit: MENTIONS_PER_PLATFORM,
}),
- ]);
+ );
rethrowIfBlockingAiSearchError([aggregated, topPages, mentions]);
@@ -176,9 +227,76 @@ async function fetchPlatformData(
aggregated: fulfilledOr(aggregated, () => ({}), platform, "aggregated"),
topPages: fulfilledOr(topPages, () => [], platform, "topPages"),
mentions: fulfilledOr(mentions, () => [], platform, "mentions"),
+ complete:
+ aggregated.status === "fulfilled" &&
+ topPages.status === "fulfilled" &&
+ mentions.status === "fulfilled",
};
}
+/**
+ * One cross_aggregated_metrics call per platform (ChatGPT forced to US/en),
+ * each comparing the target against the competitors. Settled per-platform so a
+ * single failure doesn't discard the other — matching the per-platform
+ * fan-out in {@link getBrandLookup}. The target's aggregation_key is the
+ * resolved target value so SoV can flag the target row.
+ */
+async function fetchCrossAggregated(
+ detected: ReturnType<typeof detectTarget>,
+ competitors: CompetitorGroup[],
+ input: PlatformFetchInput,
+ dataforseo: ReturnType<typeof createDataforseoClient>,
+): Promise<CrossOutcome[]> {
+ const groups = [
+ {
+ key: detected.value,
+ target: buildLlmTarget({ type: detected.type, value: detected.value }),
+ },
+ ...competitors.map((competitor) => ({
+ key: competitor.label,
+ target: buildLlmTarget({
+ type: competitor.detected.type,
+ value: competitor.detected.value,
+ }),
+ })),
+ ];
+
+ const settled: Array<PromiseSettledResult<LlmCrossAggregatedItem[]>> = [];
+ for (const platform of PLATFORMS) {
+ settled.push(
+ await settle(() =>
+ dataforseo.aiSearch.crossAggregatedMetrics({
+ groups,
+ platform,
+ // ChatGPT mentions DB only contains US/en data per DataForSEO docs.
+ locationCode:
+ platform === "chat_gpt"
+ ? CHATGPT_LOCATION_CODE
+ : input.locationCode,
+ languageCode:
+ platform === "chat_gpt"
+ ? CHATGPT_LANGUAGE_CODE
+ : input.languageCode,
+ }),
+ ),
+ );
+ }
+
+ rethrowIfBlockingAiSearchError(settled);
+
+ return settled.map((result, i) => {
+ const platform = PLATFORMS[i];
+ if (result.status === "fulfilled") {
+ return { platform, status: "success" as const, items: result.value };
+ }
+ console.error(
+ `ai-search.brand-lookup.${platform}.cross-aggregated.error:`,
+ result.reason,
+ );
+ return { platform, status: "error" as const, items: [] };
+ });
+}
+
function rethrowIfBlockingAiSearchError(
results: Array<PromiseSettledResult<unknown>>,
): void {
@@ -208,197 +326,3 @@ function fulfilledOr<T>(
);
return fallback();
}
-
-type ShapeArgs = {
- query: string;
- detected: ReturnType<typeof detectTarget>;
- platformBundles: PlatformOutcome[];
- userLocationCode: number;
- userLanguageCode: string;
-};
-
-function shapeResult(args: ShapeArgs): BrandLookupResult {
- const successfulBundles = args.platformBundles.filter(
- (b): b is PlatformOutcome & { bundle: PlatformBundle } =>
- b.status === "success" && b.bundle !== null,
- );
-
- // ChatGPT data is always fetched US/en (DataForSEO only indexes that
- // locale), so when the user picks a non-US/en locale we must not fold its
- // numbers into cross-platform totals or the monthly trend — doing so would
- // mix two different datasets under one locale label. Per-platform rows
- // still render ChatGPT separately with the "US-only" tooltip.
- // Match the primary subtag so "en-US"/"en_US" still count as English.
- const primaryLanguage = args.userLanguageCode.toLowerCase().split(/[-_]/)[0];
- const chatGptLocaleMatches =
- args.userLocationCode === CHATGPT_LOCATION_CODE &&
- primaryLanguage === CHATGPT_LANGUAGE_CODE;
-
- const perPlatform = args.platformBundles.map((outcome) => {
- if (outcome.status === "error" || !outcome.bundle) {
- return {
- platform: outcome.platform,
- status: "error" as const,
- mentions: null,
- aiSearchVolume: null,
- impressions: null,
- };
- }
- const platformGroup = outcome.bundle.aggregated.platform?.find(
- (entry) => entry.key === outcome.platform,
- );
- return {
- platform: outcome.platform,
- status: "success" as const,
- mentions: roundOrNull(platformGroup?.mentions),
- aiSearchVolume: roundOrNull(platformGroup?.ai_search_volume),
- impressions: roundOrNull(platformGroup?.impressions),
- };
- });
-
- const aggregatablePlatforms = perPlatform.filter(
- (p) => chatGptLocaleMatches || p.platform !== "chat_gpt",
- );
- const totalMentions = sumNullable(
- aggregatablePlatforms.map((p) => p.mentions),
- );
- const totalAiSearchVolume = sumNullable(
- aggregatablePlatforms.map((p) => p.aiSearchVolume),
- );
- const totalImpressions = sumNullable(
- aggregatablePlatforms.map((p) => p.impressions),
- );
-
- const topPages = sortBy(
- successfulBundles.flatMap((bundle) =>
- bundle.bundle.topPages
- .map((page) => {
- const safeUrl = safeHttpUrl(page.key);
- if (!safeUrl) return null;
- return {
- url: safeUrl,
- domain: safeHostname(safeUrl),
- mentions: roundOrNull(
- page.platform?.find((entry) => entry.key === bundle.platform)
- ?.mentions,
- ),
- platform: bundle.platform,
- };
- })
- .filter((page): page is NonNullable<typeof page> => page !== null),
- ),
- [(page) => page.mentions ?? 0, "desc"],
- ).slice(0, 20);
-
- const topQueries = sortBy(
- successfulBundles.flatMap((bundle) =>
- bundle.bundle.mentions
- .filter(
- (item): item is LlmMentionItem & { question: string } =>
- typeof item.question === "string" && item.question.length > 0,
- )
- .map((item) => ({
- question: item.question,
- platform: bundle.platform,
- aiSearchVolume: roundOrNull(item.ai_search_volume),
- firstSeenAt: item.first_response_at ?? null,
- lastSeenAt: item.last_response_at ?? null,
- citedSources: (item.sources ?? [])
- .map((src) => {
- const safeUrl = safeHttpUrl(src.url);
- if (!safeUrl) return null;
- return {
- url: safeUrl,
- domain: src.domain ?? safeHostname(safeUrl),
- title: src.title ?? null,
- };
- })
- .filter((src): src is NonNullable<typeof src> => src !== null)
- .slice(0, 10),
- brandsMentioned: (item.brand_entities ?? [])
- .map((entity) => entity.title ?? "")
- .filter((title) => title.length > 0)
- .slice(0, 20),
- })),
- ),
- [(query) => query.aiSearchVolume ?? 0, "desc"],
- ).slice(0, 50);
-
- const trendBundles = chatGptLocaleMatches
- ? successfulBundles
- : successfulBundles.filter((b) => b.platform !== "chat_gpt");
- const monthlyVolume = aggregateMonthlyVolume(trendBundles);
-
- const hasData =
- (totalMentions ?? 0) > 0 ||
- topPages.length > 0 ||
- topQueries.length > 0 ||
- monthlyVolume.length > 0;
-
- return {
- query: args.query,
- detectedTargetType: args.detected.type,
- resolvedTarget: args.detected.value,
- fetchedAt: new Date().toISOString(),
- hasData,
- totalMentions,
- totalAiSearchVolume,
- totalImpressions,
- perPlatform,
- topPages,
- topQueries,
- monthlyVolume,
- };
-}
-
-function sumNullable(values: Array<number | null>): number | null {
- let total = 0;
- let hasValue = false;
- for (const value of values) {
- if (value != null) {
- total += value;
- hasValue = true;
- }
- }
- return hasValue ? total : null;
-}
-
-function roundOrNull(value: number | null | undefined): number | null {
- if (value == null) return null;
- return Math.round(value);
-}
-
-/**
- * Sum monthly mention volume across all returned mention items, regardless of
- * platform. Returns the most recent 12 months in chronological order.
- */
-function aggregateMonthlyVolume(
- bundles: Array<PlatformOutcome & { bundle: PlatformBundle }>,
-): BrandLookupResult["monthlyVolume"] {
- const totals = new Map<string, number>();
-
- for (const outcome of bundles) {
- for (const mention of outcome.bundle.mentions) {
- for (const monthly of mention.monthly_searches ?? []) {
- if (monthly.search_volume == null) continue;
- const key = `${monthly.year}-${monthly.month}`;
- totals.set(key, (totals.get(key) ?? 0) + monthly.search_volume);
- }
- }
- }
-
- const entries = Array.from(totals.entries()).map(([key, volume]) => {
- const [yearStr, monthStr] = key.split("-");
- return {
- year: Number(yearStr),
- month: Number(monthStr),
- volume: Math.round(volume),
- };
- });
-
- return sortBy(
- entries,
- [(entry) => entry.year, "asc"],
- [(entry) => entry.month, "asc"],
- ).slice(-12);
-}
diff --git a/src/server/features/ai-search/services/brandLookupShaping.test.ts b/src/server/features/ai-search/services/brandLookupShaping.test.ts
new file mode 100644
index 00000000..1ae368d9
--- /dev/null
+++ b/src/server/features/ai-search/services/brandLookupShaping.test.ts
@@ -0,0 +1,166 @@
+import { describe, expect, it } from "vitest";
+import { shapeResult, type ShapeArgs } from "./brandLookupShaping";
+import type {
+ LlmCrossAggregatedItem,
+ LlmMentionItem,
+ LlmTopPagesItem,
+} from "@/server/lib/dataforseoLlmSchemas";
+import { brandLookupResultSchema } from "@/types/schemas/ai-search";
+
+function platformBundle(
+ platform: "chat_gpt" | "google",
+ mentions: number | null,
+ aiSearchVolume: number | null,
+): ShapeArgs["platformBundles"][number] {
+ return {
+ platform,
+ status: "success",
+ bundle: {
+ aggregated: {
+ platform: [
+ { key: platform, mentions, ai_search_volume: aiSearchVolume },
+ ],
+ },
+ topPages: [],
+ mentions: [],
+ complete: true,
+ },
+ };
+}
+
+function crossItem(
+ key: string,
+ platformMentions: Array<{ key: string; mentions: number | null }>,
+): LlmCrossAggregatedItem {
+ return {
+ key,
+ platform: platformMentions.map((p) => ({
+ key: p.key,
+ mentions: p.mentions,
+ ai_search_volume: null,
+ })),
+ };
+}
+
+function baseArgs(overrides: Partial<ShapeArgs> = {}): ShapeArgs {
+ return {
+ query: "acme",
+ detected: { type: "keyword", value: "acme" },
+ platformBundles: [
+ platformBundle("chat_gpt", 10, 100),
+ platformBundle("google", 5, 50),
+ ],
+ crossOutcomes: [],
+ competitorKeys: [],
+ userLocationCode: 2840,
+ userLanguageCode: "en",
+ ...overrides,
+ };
+}
+
+describe("shapeResult", () => {
+ it("excludes ChatGPT from totals and SoV outside US/en", () => {
+ const result = shapeResult(
+ baseArgs({
+ userLocationCode: 2826,
+ competitorKeys: ["rival"],
+ crossOutcomes: [
+ {
+ platform: "chat_gpt",
+ status: "success",
+ items: [
+ crossItem("acme", [{ key: "chat_gpt", mentions: 90 }]),
+ crossItem("rival", [{ key: "chat_gpt", mentions: 10 }]),
+ ],
+ },
+ {
+ platform: "google",
+ status: "success",
+ items: [
+ crossItem("acme", [{ key: "google", mentions: 10 }]),
+ crossItem("rival", [{ key: "google", mentions: 30 }]),
+ ],
+ },
+ ],
+ }),
+ );
+
+ expect(result.totalMentions).toBe(5);
+ expect(result.shareOfVoice?.platforms).toEqual(["google"]);
+ expect(result.shareOfVoice?.entries[0]).toMatchObject({
+ label: "rival",
+ sharePct: 75,
+ });
+ });
+
+ it("derives top-query cited source domains from urls and caps long output", () => {
+ const longTitle = "x".repeat(400);
+ const result = shapeResult(
+ baseArgs({
+ platformBundles: [
+ {
+ platform: "google",
+ status: "success",
+ bundle: {
+ aggregated: { platform: [] },
+ topPages: [],
+ mentions: [
+ {
+ question: "q".repeat(600),
+ ai_search_volume: 100,
+ sources: [
+ {
+ url: "https://evil.example/path",
+ domain: "customer.example",
+ title: longTitle,
+ },
+ ],
+ brand_entities: [{ title: "b".repeat(300) }],
+ } satisfies LlmMentionItem,
+ ],
+ complete: true,
+ },
+ },
+ ],
+ }),
+ );
+
+ expect(result.topQueries[0].question).toHaveLength(500);
+ expect(result.topQueries[0].citedSources[0]).toMatchObject({
+ url: "https://evil.example/path",
+ domain: "evil.example",
+ title: "x".repeat(300),
+ });
+ expect(result.topQueries[0].brandsMentioned[0]).toHaveLength(200);
+ });
+
+ it("round-trips through the cache schema", () => {
+ const topPage: LlmTopPagesItem = {
+ key: "https://a.com",
+ platform: [{ key: "google", mentions: 3, ai_search_volume: 300 }],
+ };
+ const result = shapeResult(
+ baseArgs({
+ platformBundles: [
+ {
+ platform: "google",
+ status: "success",
+ bundle: {
+ aggregated: { platform: [] },
+ topPages: [topPage],
+ mentions: [],
+ complete: true,
+ },
+ },
+ ],
+ }),
+ );
+
+ expect(result.topPages[0]).toMatchObject({
+ domain: "a.com",
+ mentions: 3,
+ capturedVolume: 300,
+ });
+ expect(brandLookupResultSchema.safeParse(result).success).toBe(true);
+ });
+});
diff --git a/src/server/features/ai-search/services/brandLookupShaping.ts b/src/server/features/ai-search/services/brandLookupShaping.ts
new file mode 100644
index 00000000..236a99fd
--- /dev/null
+++ b/src/server/features/ai-search/services/brandLookupShaping.ts
@@ -0,0 +1,228 @@
+import { sortBy } from "remeda";
+import {
+ CHATGPT_LANGUAGE_CODE,
+ CHATGPT_LOCATION_CODE,
+ type LlmPlatform,
+} from "@/server/lib/dataforseo/ai";
+import type {
+ LlmAggregatedTotal,
+ LlmMentionItem,
+ LlmTopPagesItem,
+} from "@/server/lib/dataforseoLlmSchemas";
+import { safeHostname, safeHttpUrl } from "@/server/features/ai-search/safeUrl";
+import { deriveCitedSources } from "@/server/features/ai-search/services/citedSources";
+import {
+ computeShareOfVoice,
+ roundOrNull,
+ sumNullable,
+ type CrossOutcome,
+} from "@/server/features/ai-search/services/shareOfVoice";
+import type { BrandLookupResult } from "@/types/schemas/ai-search";
+import type { detectTarget } from "@/shared/targetDetection";
+
+const TOP_QUERIES_PER_PLATFORM = 25;
+const TOP_SOURCES_PER_PLATFORM = 10;
+const KEYWORDS_PER_SOURCE = 50;
+const MAX_URL_LENGTH = 2048;
+const MAX_TITLE_LENGTH = 300;
+const MAX_QUESTION_LENGTH = 500;
+const MAX_BRAND_ENTITY_LENGTH = 200;
+
+export type PlatformBundle = {
+ aggregated: LlmAggregatedTotal;
+ topPages: LlmTopPagesItem[];
+ mentions: LlmMentionItem[];
+ /** False when one of the sub-calls failed and fell back to empty data. */
+ complete: boolean;
+};
+
+export type PlatformOutcome = {
+ platform: LlmPlatform;
+ status: "success" | "error";
+ bundle: PlatformBundle | null;
+};
+
+export type ShapeArgs = {
+ query: string;
+ detected: ReturnType<typeof detectTarget>;
+ platformBundles: PlatformOutcome[];
+ crossOutcomes: CrossOutcome[];
+ /** Labels of the resolved competitor groups, as sent to cross_aggregated. */
+ competitorKeys: string[];
+ userLocationCode: number;
+ userLanguageCode: string;
+};
+
+export function shapeResult(args: ShapeArgs): BrandLookupResult {
+ const successfulBundles = args.platformBundles.filter(
+ (b): b is PlatformOutcome & { bundle: PlatformBundle } =>
+ b.status === "success" && b.bundle !== null,
+ );
+
+ const primaryLanguage = args.userLanguageCode.toLowerCase().split(/[-_]/)[0];
+ const chatGptLocaleMatches =
+ args.userLocationCode === CHATGPT_LOCATION_CODE &&
+ primaryLanguage === CHATGPT_LANGUAGE_CODE;
+
+ const perPlatform = args.platformBundles.map((outcome) => {
+ if (outcome.status === "error" || !outcome.bundle) {
+ return {
+ platform: outcome.platform,
+ status: "error" as const,
+ mentions: null,
+ aiSearchVolume: null,
+ };
+ }
+ const platformGroup = outcome.bundle.aggregated.platform?.find(
+ (entry) => entry.key === outcome.platform,
+ );
+ return {
+ platform: outcome.platform,
+ status: "success" as const,
+ mentions: roundOrNull(platformGroup?.mentions),
+ aiSearchVolume: roundOrNull(platformGroup?.ai_search_volume),
+ };
+ });
+
+ const aggregatablePlatforms = perPlatform.filter(
+ (p) => chatGptLocaleMatches || p.platform !== "chat_gpt",
+ );
+ const totalMentions = sumNullable(
+ aggregatablePlatforms.map((p) => p.mentions),
+ );
+ const totalAiSearchVolume = sumNullable(
+ aggregatablePlatforms.map((p) => p.aiSearchVolume),
+ );
+
+ const topPages = deriveCitedSources(
+ successfulBundles.map((bundle) => ({
+ platform: bundle.platform,
+ topPages: bundle.bundle.topPages,
+ mentions: bundle.bundle.mentions,
+ })),
+ {
+ sourcesPerPlatform: TOP_SOURCES_PER_PLATFORM,
+ keywordsPerSource: KEYWORDS_PER_SOURCE,
+ },
+ );
+
+ const topQueries = shapeTopQueries(successfulBundles);
+ const trendBundles = chatGptLocaleMatches
+ ? successfulBundles
+ : successfulBundles.filter((b) => b.platform !== "chat_gpt");
+ const monthlyVolume = aggregateMonthlyVolume(trendBundles);
+ const shareOfVoice = computeShareOfVoice(
+ chatGptLocaleMatches
+ ? args.crossOutcomes
+ : args.crossOutcomes.filter((outcome) => outcome.platform !== "chat_gpt"),
+ args.detected.value,
+ args.competitorKeys,
+ );
+
+ const hasData =
+ (totalMentions ?? 0) > 0 ||
+ topPages.length > 0 ||
+ topQueries.length > 0 ||
+ monthlyVolume.length > 0 ||
+ (shareOfVoice?.entries.some((e) => e.mentions != null) ?? false);
+
+ return {
+ query: args.query,
+ detectedTargetType: args.detected.type,
+ resolvedTarget: args.detected.value,
+ fetchedAt: new Date().toISOString(),
+ hasData,
+ totalMentions,
+ totalAiSearchVolume,
+ perPlatform,
+ shareOfVoice,
+ topPages,
+ topQueries,
+ monthlyVolume,
+ };
+}
+
+function shapeTopQueries(
+ bundles: Array<PlatformOutcome & { bundle: PlatformBundle }>,
+): BrandLookupResult["topQueries"] {
+ return sortBy(
+ bundles.flatMap((bundle) =>
+ sortBy(
+ bundle.bundle.mentions
+ .filter(
+ (item): item is LlmMentionItem & { question: string } =>
+ typeof item.question === "string" && item.question.length > 0,
+ )
+ .map((item) => ({
+ question: truncate(item.question, MAX_QUESTION_LENGTH),
+ platform: bundle.platform,
+ aiSearchVolume: roundOrNull(item.ai_search_volume),
+ firstSeenAt: item.first_response_at ?? null,
+ lastSeenAt: item.last_response_at ?? null,
+ citedSources: shapeQuerySources(item),
+ brandsMentioned: (item.brand_entities ?? [])
+ .map((entity) => entity.title ?? "")
+ .filter((title) => title.length > 0)
+ .map((title) => truncate(title, MAX_BRAND_ENTITY_LENGTH))
+ .slice(0, 20),
+ })),
+ [(query) => query.aiSearchVolume ?? 0, "desc"],
+ ).slice(0, TOP_QUERIES_PER_PLATFORM),
+ ),
+ [(query) => query.aiSearchVolume ?? 0, "desc"],
+ );
+}
+
+function shapeQuerySources(
+ item: LlmMentionItem,
+): BrandLookupResult["topQueries"][number]["citedSources"] {
+ return (item.sources ?? [])
+ .map((src) => {
+ const safeUrl = safeHttpUrl(src.url);
+ if (!safeUrl || safeUrl.length > MAX_URL_LENGTH) return null;
+ return {
+ url: safeUrl,
+ domain: safeHostname(safeUrl),
+ title:
+ typeof src.title === "string"
+ ? truncate(src.title, MAX_TITLE_LENGTH)
+ : null,
+ };
+ })
+ .filter((src): src is NonNullable<typeof src> => src !== null)
+ .slice(0, 10);
+}
+
+function aggregateMonthlyVolume(
+ bundles: Array<PlatformOutcome & { bundle: PlatformBundle }>,
+): BrandLookupResult["monthlyVolume"] {
+ const totals = new Map<string, number>();
+ for (const outcome of bundles) {
+ for (const mention of outcome.bundle.mentions) {
+ for (const monthly of mention.monthly_searches ?? []) {
+ if (monthly.search_volume == null) continue;
+ const key = `${monthly.year}-${monthly.month}`;
+ totals.set(key, (totals.get(key) ?? 0) + monthly.search_volume);
+ }
+ }
+ }
+
+ const entries = Array.from(totals.entries()).map(([key, volume]) => {
+ const [yearStr, monthStr] = key.split("-");
+ return {
+ year: Number(yearStr),
+ month: Number(monthStr),
+ volume: Math.round(volume),
+ };
+ });
+
+ return sortBy(
+ entries,
+ [(entry) => entry.year, "asc"],
+ [(entry) => entry.month, "asc"],
+ ).slice(-12);
+}
+
+function truncate(value: string, maxLength: number): string {
+ return value.length <= maxLength ? value : value.slice(0, maxLength);
+}
diff --git a/src/server/features/ai-search/services/citedSources.test.ts b/src/server/features/ai-search/services/citedSources.test.ts
new file mode 100644
index 00000000..dfcc5eb2
--- /dev/null
+++ b/src/server/features/ai-search/services/citedSources.test.ts
@@ -0,0 +1,97 @@
+import { describe, expect, it } from "vitest";
+import { deriveCitedSources } from "./citedSources";
+import type {
+ LlmMentionItem,
+ LlmTopPagesItem,
+} from "@/server/lib/dataforseoLlmSchemas";
+
+function citedMention(
+ question: string,
+ aiSearchVolume: number | null,
+ urls: string[],
+): LlmMentionItem {
+ return {
+ question,
+ ai_search_volume: aiSearchVolume,
+ sources: urls.map((url) => ({ url })),
+ };
+}
+
+function topPage(
+ url: string,
+ platform: "chat_gpt" | "google",
+ mentions: number | null,
+ aiSearchVolume: number | null,
+): LlmTopPagesItem {
+ return {
+ key: url,
+ platform: [{ key: platform, mentions, ai_search_volume: aiSearchVolume }],
+ };
+}
+
+describe("deriveCitedSources", () => {
+ it("uses top_pages metrics and attaches matching prompt examples", () => {
+ const sources = deriveCitedSources(
+ [
+ {
+ platform: "google",
+ topPages: [
+ topPage("https://a.com/x", "google", 9, 9000),
+ topPage("https://b.com/y", "google", 2, 1000),
+ ],
+ mentions: [
+ citedMention("best seo tools", 1000, [
+ "https://a.com/x",
+ "https://b.com/y",
+ ]),
+ citedMention("cheap seo", 500, ["https://a.com/x"]),
+ ],
+ },
+ ],
+ { sourcesPerPlatform: 20, keywordsPerSource: 50 },
+ );
+
+ expect(sources[0]).toMatchObject({
+ domain: "a.com",
+ mentions: 9,
+ capturedVolume: 9000,
+ });
+ expect(sources[0].keywords.map((k) => k.question).toSorted()).toEqual([
+ "best seo tools",
+ "cheap seo",
+ ]);
+ });
+
+ it("dedupes sampled prompt examples and derives domains from urls", () => {
+ const sources = deriveCitedSources(
+ [
+ {
+ platform: "google",
+ topPages: [topPage("https://evil.example/path", "google", 3, 300)],
+ mentions: [
+ {
+ question: "q",
+ ai_search_volume: 200,
+ sources: [
+ {
+ url: "https://evil.example/path",
+ domain: "customer.example",
+ },
+ { url: "https://evil.example/path" },
+ ],
+ },
+ ],
+ },
+ ],
+ { sourcesPerPlatform: 20, keywordsPerSource: 50 },
+ );
+
+ expect(sources[0]).toMatchObject({
+ url: "https://evil.example/path",
+ domain: "evil.example",
+ });
+ expect(sources[0].keywords).toEqual([
+ { question: "q", aiSearchVolume: 200 },
+ ]);
+ });
+});
diff --git a/src/server/features/ai-search/services/citedSources.ts b/src/server/features/ai-search/services/citedSources.ts
new file mode 100644
index 00000000..8e9e6ddd
--- /dev/null
+++ b/src/server/features/ai-search/services/citedSources.ts
@@ -0,0 +1,118 @@
+import { sortBy } from "remeda";
+import type { LlmPlatform } from "@/server/lib/dataforseo";
+import type {
+ LlmMentionItem,
+ LlmTopPagesItem,
+} from "@/server/lib/dataforseoLlmSchemas";
+import { safeHostname, safeHttpUrl } from "@/server/features/ai-search/safeUrl";
+import { roundOrNull } from "@/server/features/ai-search/services/shareOfVoice";
+import type { BrandLookupResult } from "@/types/schemas/ai-search";
+
+type Bundle = {
+ platform: LlmPlatform;
+ topPages: LlmTopPagesItem[];
+ mentions: LlmMentionItem[];
+};
+
+type PromptExamples = Map<string, Map<string, number | null>>;
+
+const MAX_URL_LENGTH = 2048;
+const MAX_QUESTION_LENGTH = 500;
+
+/**
+ * Use DataForSEO top_pages for the ranked cited-source rows, then attach prompt
+ * examples from the mentions sample when the exact cited URL appears there.
+ * The page metrics stay authoritative while the prompt examples remain plainly
+ * sample-based.
+ */
+export function deriveCitedSources(
+ bundles: Bundle[],
+ limits: { sourcesPerPlatform: number; keywordsPerSource: number },
+): BrandLookupResult["topPages"] {
+ const promptExamples = buildPromptExamples(bundles);
+
+ const rows = bundles.flatMap((bundle) =>
+ bundle.topPages
+ .map((page) => {
+ const url = safeHttpUrl(page.key);
+ if (!url || url.length > MAX_URL_LENGTH) return null;
+ const platformGroup = page.platform?.find(
+ (entry) => entry.key === bundle.platform,
+ );
+ const key = sourceKey(bundle.platform, url);
+ const examples =
+ promptExamples.get(key) ?? new Map<string, number | null>();
+ return {
+ url,
+ domain: safeHostname(url),
+ platform: bundle.platform,
+ mentions: roundOrNull(platformGroup?.mentions),
+ capturedVolume: roundOrNull(platformGroup?.ai_search_volume),
+ keywords: sortBy(
+ Array.from(examples.entries()).map(
+ ([question, aiSearchVolume]) => ({
+ question,
+ aiSearchVolume,
+ }),
+ ),
+ [(keyword) => keyword.aiSearchVolume ?? 0, "desc"],
+ ).slice(0, limits.keywordsPerSource),
+ };
+ })
+ .filter((row): row is NonNullable<typeof row> => row !== null),
+ );
+
+ // Keep the top sources PER PLATFORM so a high-volume platform (Google) can't
+ // crowd out a sparse one (ChatGPT, US/en only) entirely. Then order the
+ // combined set by captured volume for a sensible default.
+ const byPlatform = new Map<LlmPlatform, typeof rows>();
+ for (const row of rows) {
+ const list = byPlatform.get(row.platform) ?? [];
+ list.push(row);
+ byPlatform.set(row.platform, list);
+ }
+ const capped = Array.from(byPlatform.values()).flatMap((list) =>
+ sortBy(list, [(row) => row.capturedVolume ?? 0, "desc"]).slice(
+ 0,
+ limits.sourcesPerPlatform,
+ ),
+ );
+
+ return sortBy(
+ capped,
+ [(row) => row.capturedVolume ?? 0, "desc"],
+ [(row) => row.mentions ?? 0, "desc"],
+ );
+}
+
+function buildPromptExamples(bundles: Bundle[]): PromptExamples {
+ const examples: PromptExamples = new Map();
+ for (const bundle of bundles) {
+ for (const mention of bundle.mentions) {
+ const question =
+ typeof mention.question === "string"
+ ? truncate(mention.question, MAX_QUESTION_LENGTH)
+ : "";
+ if (question.length === 0) continue;
+ const volume = roundOrNull(mention.ai_search_volume);
+
+ for (const source of mention.sources ?? []) {
+ const url = safeHttpUrl(source.url);
+ if (!url) continue;
+ const key = sourceKey(bundle.platform, url);
+ const existing = examples.get(key) ?? new Map<string, number | null>();
+ if (!existing.has(question)) existing.set(question, volume);
+ examples.set(key, existing);
+ }
+ }
+ }
+ return examples;
+}
+
+function sourceKey(platform: LlmPlatform, url: string): string {
+ return `${platform}::${url}`;
+}
+
+function truncate(value: string, maxLength: number): string {
+ return value.length <= maxLength ? value : value.slice(0, maxLength);
+}
diff --git a/src/server/features/ai-search/services/shareOfVoice.test.ts b/src/server/features/ai-search/services/shareOfVoice.test.ts
new file mode 100644
index 00000000..791b79ed
--- /dev/null
+++ b/src/server/features/ai-search/services/shareOfVoice.test.ts
@@ -0,0 +1,80 @@
+import { describe, expect, it } from "vitest";
+import {
+ computeShareOfVoice,
+ resolveCompetitorGroups,
+ type CrossOutcome,
+} from "./shareOfVoice";
+import type { LlmCrossAggregatedItem } from "@/server/lib/dataforseoLlmSchemas";
+
+function crossItem(
+ key: string,
+ platformMentions: Array<{ key: string; mentions: number | null }>,
+): LlmCrossAggregatedItem {
+ return {
+ key,
+ platform: platformMentions.map((p) => ({
+ key: p.key,
+ mentions: p.mentions,
+ ai_search_volume: null,
+ })),
+ };
+}
+
+describe("computeShareOfVoice", () => {
+ it("sums requested rows, excludes nulls, and ignores unrequested provider rows", () => {
+ const outcomes: CrossOutcome[] = [
+ {
+ platform: "google",
+ status: "success",
+ items: [
+ crossItem("acme", [{ key: "google", mentions: 30 }]),
+ crossItem("rival", [{ key: "google", mentions: 10 }]),
+ crossItem("ghost", [{ key: "google", mentions: null }]),
+ crossItem("unexpected", [{ key: "google", mentions: 60 }]),
+ ],
+ },
+ ];
+
+ const entries = computeShareOfVoice(outcomes, "acme", [
+ "rival",
+ "ghost",
+ ])!.entries;
+
+ expect(entries.map((entry) => entry.label)).toEqual([
+ "acme",
+ "rival",
+ "ghost",
+ ]);
+ expect(entries[0]).toMatchObject({ label: "acme", sharePct: 75 });
+ expect(entries[1]).toMatchObject({ label: "rival", sharePct: 25 });
+ expect(entries[2]).toMatchObject({ mentions: null, sharePct: null });
+ });
+
+ it("returns null with no competitors or no successful calls", () => {
+ expect(computeShareOfVoice([], "acme", [])).toBe(null);
+ expect(
+ computeShareOfVoice(
+ [
+ { platform: "chat_gpt", status: "error", items: [] },
+ { platform: "google", status: "error", items: [] },
+ ],
+ "acme",
+ ["rival"],
+ ),
+ ).toBe(null);
+ });
+});
+
+describe("resolveCompetitorGroups", () => {
+ it("dedupes case-insensitively and drops target collisions", () => {
+ const groups = resolveCompetitorGroups("Nike", [
+ "nike",
+ "Adidas",
+ "ADIDAS",
+ "puma.com",
+ "www.PUMA.com",
+ ]);
+
+ expect(groups.map((g) => g.label)).toEqual(["Adidas", "puma.com"]);
+ });
+});
diff --git a/src/server/features/ai-search/services/shareOfVoice.ts b/src/server/features/ai-search/services/shareOfVoice.ts
new file mode 100644
index 00000000..f8ed9773
--- /dev/null
+++ b/src/server/features/ai-search/services/shareOfVoice.ts
@@ -0,0 +1,132 @@
+import { sortBy } from "remeda";
+import type { LlmCrossAggregatedItem } from "@/server/lib/dataforseoLlmSchemas";
+import type { LlmPlatform } from "@/server/lib/dataforseo";
+import type { BrandLookupResult } from "@/types/schemas/ai-search";
+import { detectTarget } from "@/shared/targetDetection";
+
+export type CrossOutcome = {
+ platform: LlmPlatform;
+ status: "success" | "error";
+ items: LlmCrossAggregatedItem[];
+};
+
+export type CompetitorGroup = {
+ label: string;
+ detected: ReturnType<typeof detectTarget>;
+};
+
+/**
+ * Resolve raw competitor inputs into comparison groups: detect each one's
+ * target type, dedupe by resolved value, and drop any that collide with the
+ * target — a duplicate aggregation group adds a redundant leaderboard row and
+ * wastes a paid comparison slot. Dedupe is case-insensitive: domains are
+ * already lowercased by detectTarget, but keyword targets preserve case while
+ * DataForSEO matches them case-insensitively, so "Nike" and "nike" would be
+ * two paid groups returning the same counts.
+ */
+export function resolveCompetitorGroups(
+ targetValue: string,
+ competitors: string[],
+): CompetitorGroup[] {
+ const seen = new Set<string>([targetValue.toLowerCase()]);
+ const groups: CompetitorGroup[] = [];
+ for (const competitor of competitors) {
+ const detected = detectTarget(competitor);
+ const dedupeKey = detected.value.toLowerCase();
+ if (seen.has(dedupeKey)) continue;
+ seen.add(dedupeKey);
+ groups.push({ label: detected.value, detected });
+ }
+ return groups;
+}
+
+/**
+ * Build Share of Voice from the per-platform cross_aggregated calls. For each
+ * brand (item.key), sum mentions across the platforms the calls returned.
+ *
+ * Every requested group (target + competitors) is seeded as a row up front, so
+ * a brand the API returned no item for renders as "no data" instead of
+ * silently vanishing from a leaderboard the user paid to compare it on. Echoed
+ * aggregation_keys are matched back to requested keys case-insensitively so
+ * vendor normalization can't orphan a row or the target's isTarget flag.
+ *
+ * US/en assumption: today the only locale that exists for both platforms is
+ * US/en (the UI hardcodes locationCode 2840 / languageCode en and has no locale
+ * selector), so we sum every returned platform. If a locale selector ships,
+ * gate chat_gpt here the same way the single-brand totals do in shapeResult —
+ * do not duplicate the chatGptLocaleMatches branch into this path.
+ *
+ * Null vs zero: a brand whose summed mentions is null is "no data" (excluded
+ * from the denominator, sharePct null); a brand with mentions 0 is known-zero
+ * and counts. sharePct = mentions / denominator * 100, guarded against
+ * divide-by-zero. Returns null when there are no competitors or both calls
+ * failed (so the UI omits the section rather than blanking the page).
+ */
+export function computeShareOfVoice(
+ crossOutcomes: CrossOutcome[],
+ targetKey: string,
+ competitorKeys: string[],
+): BrandLookupResult["shareOfVoice"] {
+ if (competitorKeys.length === 0) return null;
+ const successful = crossOutcomes.filter((c) => c.status === "success");
+ if (successful.length === 0) return null;
+
+ const requestedKeys = [targetKey, ...competitorKeys];
+ const labelByKey = new Map(
+ requestedKeys.map((key) => [key.toLowerCase(), key]),
+ );
+ const mentionsByKey = new Map<string, number | null>(
+ requestedKeys.map((key) => [key.toLowerCase(), null]),
+ );
+
+ for (const outcome of successful) {
+ for (const item of outcome.items) {
+ if (item.key == null) continue;
+ const key = item.key.toLowerCase();
+ // The provider should echo only requested aggregation keys. If it ever
+ // returns extra rows, do not let them alter requested share percentages.
+ if (!labelByKey.has(key)) continue;
+ const platformMentions = sumNullable(
+ (item.platform ?? []).map((entry) => roundOrNull(entry.mentions)),
+ );
+ const prior = mentionsByKey.get(key) ?? null;
+ // null + null stays null ("no data"); null + n = n; m + n = m + n.
+ mentionsByKey.set(key, sumNullable([prior, platformMentions]));
+ }
+ }
+
+ const denominator = sumNullable(Array.from(mentionsByKey.values())) ?? 0;
+ const targetLower = targetKey.toLowerCase();
+
+ const entries = sortBy(
+ Array.from(mentionsByKey.entries()).map(([key, mentions]) => ({
+ label: labelByKey.get(key) ?? key,
+ isTarget: key === targetLower,
+ mentions,
+ sharePct:
+ mentions == null || denominator <= 0
+ ? null
+ : (mentions / denominator) * 100,
+ })),
+ [(entry) => entry.mentions ?? -1, "desc"],
+ );
+
+ return { platforms: successful.map((outcome) => outcome.platform), entries };
+}
+
+export function sumNullable(values: Array<number | null>): number | null {
+ let total = 0;
+ let hasValue = false;
+ for (const value of values) {
+ if (value != null) {
+ total += value;
+ hasValue = true;
+ }
+ }
+ return hasValue ? total : null;
+}
+
+export function roundOrNull(value: number | null | undefined): number | null {
+ if (value == null) return null;
+ return Math.round(value);
+}
diff --git a/src/server/lib/dataforseo/ai.ts b/src/server/lib/dataforseo/ai.ts
index 2792eae5..104f052c 100644
--- a/src/server/lib/dataforseo/ai.ts
+++ b/src/server/lib/dataforseo/ai.ts
@@ -3,9 +3,11 @@ import {
AiOptimizationChatGptLlmResponsesLiveRequestInfo,
AiOptimizationClaudeLlmResponsesLiveRequestInfo,
AiOptimizationGeminiLlmResponsesLiveRequestInfo,
+ AiOptimizationLLmMentionsCrossAggregateMetricsTargetInfo,
AiOptimizationLLmMentionsDomainElement,
AiOptimizationLLmMentionsKeywordElement,
AiOptimizationLlmMentionsAggregatedMetricsLiveRequestInfo,
+ AiOptimizationLlmMentionsCrossAggregatedMetricsLiveRequestInfo,
AiOptimizationLlmMentionsSearchLiveRequestInfo,
AiOptimizationLlmMentionsTopPagesLiveRequestInfo,
type BaseAiOptimizationLLmMentionsTargetElement,
@@ -13,10 +15,12 @@ import {
} from "dataforseo-client";
import {
llmAggregatedTotalSchema,
+ llmCrossAggregatedItemSchema,
llmMentionItemSchema,
llmResponseResultSchema,
llmTopPagesItemSchema,
type LlmAggregatedTotal,
+ type LlmCrossAggregatedItem,
type LlmMentionItem,
type LlmResponseResult,
type LlmTopPagesItem,
@@ -240,6 +244,66 @@ export async function fetchLlmTopPages(
return { data: items.data, billing: buildTaskBilling(task) };
}
+// ---------------------------------------------------------------------------
+// LLM Mentions Cross-Aggregated Metrics
+// Compares 2..10 aggregation groups (target + competitors) in one call and
+// returns one item per group, keyed by its aggregation_key (brand label).
+// ---------------------------------------------------------------------------
+
+type LlmCrossAggregatedMetricsInput = {
+ groups: Array<{ key: string; target: LlmTarget }>;
+ platform: LlmPlatform;
+ locationCode: number;
+ languageCode: string;
+ internalListLimit?: number;
+};
+
+export async function fetchLlmCrossAggregatedMetrics(
+ input: LlmCrossAggregatedMetricsInput,
+): Promise<DataforseoApiResponse<LlmCrossAggregatedItem[]>> {
+ if (input.groups.length < 2 || input.groups.length > 10) {
+ throw new AppError(
+ "VALIDATION_ERROR",
+ "DataForSEO llm_mentions/cross_aggregated_metrics requires 2 to 10 target groups",
+ );
+ }
+
+ const response = await aiOptimizationApi(
+ classifyAiSearchError,
+ ).llmMentionsCrossAggregatedMetricsLive([
+ new AiOptimizationLlmMentionsCrossAggregatedMetricsLiveRequestInfo({
+ targets: input.groups.map(
+ (group) =>
+ new AiOptimizationLLmMentionsCrossAggregateMetricsTargetInfo({
+ aggregation_key: group.key,
+ target: targetList(group.target),
+ }),
+ ),
+ platform: input.platform,
+ location_code: input.locationCode,
+ language_code: input.languageCode,
+ internal_list_limit: clampLimit(input.internalListLimit ?? 5, 1, 10),
+ }),
+ ]);
+ const task = assertOk(
+ response,
+ assertOptions(
+ "/v3/ai_optimization/llm_mentions/cross_aggregated_metrics/live",
+ ),
+ );
+
+ const items = z
+ .array(llmCrossAggregatedItemSchema)
+ .safeParse(firstResult(task)?.items ?? []);
+ if (!items.success) {
+ throw new AppError(
+ "INTERNAL_ERROR",
+ "DataForSEO llm_mentions/cross_aggregated_metrics returned an invalid shape",
+ );
+ }
+ return { data: items.data, billing: buildTaskBilling(task) };
+}
+
// ---------------------------------------------------------------------------
// LLM Responses (per-model)
// ---------------------------------------------------------------------------
diff --git a/src/server/lib/dataforseo/client.test.ts b/src/server/lib/dataforseo/client.test.ts
index fcdf0dbf..d6c373ed 100644
--- a/src/server/lib/dataforseo/client.test.ts
+++ b/src/server/lib/dataforseo/client.test.ts
@@ -80,6 +80,7 @@ vi.mock("@/server/lib/dataforseo/ai", () => ({
fetchLlmMentionsSearch: vi.fn(),
fetchLlmAggregatedMetrics: vi.fn(),
fetchLlmTopPages: vi.fn(),
+ fetchLlmCrossAggregatedMetrics: vi.fn(),
fetchLlmResponse: vi.fn(),
}));
diff --git a/src/server/lib/dataforseo/client.ts b/src/server/lib/dataforseo/client.ts
index 2ef37689..81f48fa9 100644
--- a/src/server/lib/dataforseo/client.ts
+++ b/src/server/lib/dataforseo/client.ts
@@ -41,6 +41,7 @@ import {
import { fetchLighthouseResult } from "@/server/lib/dataforseo/lighthouse";
import {
fetchLlmAggregatedMetrics,
+ fetchLlmCrossAggregatedMetrics,
fetchLlmMentionsSearch,
fetchLlmResponse,
fetchLlmTopPages,
@@ -125,6 +126,7 @@ export function createDataforseoClient(customer: BillingCustomerContext) {
mentionsSearch: meter(customer, fetchLlmMentionsSearch),
aggregatedMetrics: meter(customer, fetchLlmAggregatedMetrics),
topPages: meter(customer, fetchLlmTopPages),
+ crossAggregatedMetrics: meter(customer, fetchLlmCrossAggregatedMetrics),
llmResponse: meter(customer, fetchLlmResponse),
},
} as const;
diff --git a/src/server/lib/dataforseo/endpoints.test.ts b/src/server/lib/dataforseo/endpoints.test.ts
index 0881bb48..9233d2e0 100644
--- a/src/server/lib/dataforseo/endpoints.test.ts
+++ b/src/server/lib/dataforseo/endpoints.test.ts
@@ -8,6 +8,7 @@ import { fetchQuestionsAnswers } from "@/server/lib/dataforseo/business";
import {
buildLlmTarget,
fetchLlmAggregatedMetrics,
+ fetchLlmCrossAggregatedMetrics,
fetchLlmMentionsSearch,
fetchLlmResponse,
fetchLlmTopPages,
@@ -83,7 +84,7 @@ describe("DataForSEO SDK-backed endpoints", () => {
});
});
- it("serializes LLM mentions domain targets for all live endpoints", async () => {
+ it("serializes LLM mentions domain targets for search, top pages, and aggregated endpoints", async () => {
const fetchMock = vi.fn<typeof fetch>().mockImplementation((url) => {
const path =
typeof url === "string" || url instanceof URL
@@ -132,8 +133,8 @@ describe("DataForSEO SDK-backed endpoints", () => {
platform: "google",
locationCode: 2840,
languageCode: "en",
+ itemsListLimit: 10,
});
-
const expectedTarget = [
{
search_scope: ["any"],
@@ -179,6 +180,79 @@ describe("DataForSEO SDK-backed endpoints", () => {
]);
});
+ it("serializes cross-aggregated target groups", async () => {
+ const fetchMock = vi.fn<typeof fetch>().mockResolvedValue(
+ Response.json({
+ status_code: 20000,
+ tasks: [
+ {
+ status_code: 20000,
+ path: [
+ "v3",
+ "ai_optimization",
+ "llm_mentions",
+ "cross_aggregated_metrics",
+ "live",
+ ],
+ cost: 0.0001,
+ result_count: 1,
+ result: [{ items: [] }],
+ },
+ ],
+ }),
+ );
+ vi.stubGlobal("fetch", fetchMock);
+
+ await fetchLlmCrossAggregatedMetrics({
+ groups: [
+ {
+ key: "example.com",
+ target: buildLlmTarget({ type: "domain", value: "example.com" }),
+ },
+ {
+ key: "Acme Storage",
+ target: buildLlmTarget({ type: "keyword", value: "Acme Storage" }),
+ },
+ ],
+ platform: "google",
+ locationCode: 2840,
+ languageCode: "en",
+ });
+
+ expect(parseDataforseoRequestBody(fetchMock.mock.calls[0]?.[1])).toEqual([
+ {
+ targets: [
+ {
+ aggregation_key: "example.com",
+ target: [
+ {
+ search_scope: ["any"],
+ search_filter: "include",
+ domain: "example.com",
+ include_subdomains: true,
+ },
+ ],
+ },
+ {
+ aggregation_key: "Acme Storage",
+ target: [
+ {
+ search_scope: ["any", "brand_entities"],
+ search_filter: "include",
+ keyword: "Acme Storage",
+ match_type: "word_match",
+ },
+ ],
+ },
+ ],
+ location_code: 2840,
+ language_code: "en",
+ platform: "google",
+ internal_list_limit: 5,
+ },
+ ]);
+ });
+
it("serializes LLM mentions keyword targets", async () => {
const fetchMock = vi.fn<typeof fetch>().mockResolvedValue(
Response.json({
diff --git a/src/server/lib/dataforseoLlmSchemas.ts b/src/server/lib/dataforseoLlmSchemas.ts
index 486fe9cf..6cd5df7e 100644
--- a/src/server/lib/dataforseoLlmSchemas.ts
+++ b/src/server/lib/dataforseoLlmSchemas.ts
@@ -90,6 +90,27 @@ export const llmTopPagesItemSchema = z
export type LlmTopPagesItem = z.infer<typeof llmTopPagesItemSchema>;
+// ---------------------------------------------------------------------------
+// LLM Mentions Cross-Aggregated Metrics — `/v3/ai_optimization/llm_mentions/cross_aggregated_metrics/live`
+// One item per requested aggregation group (target + competitors).
+// `.passthrough()` because the real item also carries location, language,
+// sources_domain, and brand_entities arrays we intentionally ignore.
+// ---------------------------------------------------------------------------
+
+export const llmCrossAggregatedItemSchema = z
+ .object({
+ // The shared SDK type AiOptimizationLlmMentionssLiveItem documents `key` as
+ // the URL of a found page, but for cross_aggregated `key` is the request
+ // aggregation_key (the brand label).
+ key: z.string().nullable().optional(),
+ platform: z.array(groupElementSchema).nullable().optional(),
+ })
+ .passthrough();
+
+export type LlmCrossAggregatedItem = z.infer<
+ typeof llmCrossAggregatedItemSchema
+>;
+
// ---------------------------------------------------------------------------
// LLM Responses — shared between ChatGPT/Claude/Gemini/Perplexity
// All four model endpoints return the same envelope shape.
diff --git a/src/server/features/ai-search/targetDetection.test.ts b/src/shared/targetDetection.test.ts
similarity index 100%
rename from src/server/features/ai-search/targetDetection.test.ts
rename to src/shared/targetDetection.test.ts
diff --git a/src/server/features/ai-search/targetDetection.ts b/src/shared/targetDetection.ts
similarity index 100%
rename from src/server/features/ai-search/targetDetection.ts
rename to src/shared/targetDetection.ts
diff --git a/src/types/schemas/ai-search.ts b/src/types/schemas/ai-search.ts
index 735bac3e..09e27e85 100644
--- a/src/types/schemas/ai-search.ts
+++ b/src/types/schemas/ai-search.ts
@@ -22,9 +22,34 @@ export const aiSearchProjectSchema = z.object({
/** Maximum allowed length for a free-text brand or domain search input. */
export const BRAND_LOOKUP_MAX_INPUT_LENGTH = 250;
+/** Maximum number of competitors compared in one Share-of-Voice lookup. */
+const BRAND_LOOKUP_MAX_COMPETITORS = 5;
+
+/**
+ * Canonicalize raw comma-separated competitor text: split, trim, drop empties,
+ * dedupe, cap. Shared by the `c` URL-param transform and the page form so the
+ * two never diverge.
+ */
+export function parseCompetitorList(raw: string): string[] {
+ return Array.from(
+ new Set(
+ raw
+ .split(",")
+ .map((part) => part.trim())
+ .filter((part) => part.length > 0),
+ ),
+ ).slice(0, BRAND_LOOKUP_MAX_COMPETITORS);
+}
+
export const brandLookupInputSchema = z.object({
projectId: z.string().min(1),
query: z.string().trim().min(1).max(BRAND_LOOKUP_MAX_INPUT_LENGTH),
+ // Optional competitor brands/domains to compare Share of Voice against.
+ // cross_aggregated_metrics caps groups at 10 (target + 9); we cap at 5.
+ competitors: z
+ .array(z.string().trim().min(1).max(BRAND_LOOKUP_MAX_INPUT_LENGTH))
+ .max(BRAND_LOOKUP_MAX_COMPETITORS)
+ .default([]),
locationCode: z.number().int().positive().default(2840),
languageCode: z.string().min(2).max(8).default("en"),
});
@@ -36,18 +61,42 @@ const brandPlatformBreakdownSchema = z.object({
status: z.enum(["success", "error"]),
mentions: z.number().int().nonnegative().nullable(),
aiSearchVolume: z.number().int().nonnegative().nullable(),
- impressions: z.number().int().nonnegative().nullable(),
+});
+
+const brandShareOfVoiceSchema = z.object({
+ // The platforms whose cross_aggregated call succeeded and are summed into
+ // the entries — so the UI can caption a single-platform leaderboard honestly
+ // when the other platform's call failed.
+ platforms: z.array(z.enum(["chat_gpt", "google"])),
+ entries: z.array(
+ z.object({
+ label: z.string().max(BRAND_LOOKUP_MAX_INPUT_LENGTH),
+ isTarget: z.boolean(),
+ mentions: z.number().int().nonnegative().nullable(),
+ sharePct: z.number().nullable(),
+ }),
+ ),
+});
+
+const brandTopPageKeywordSchema = z.object({
+ question: z.string().max(500),
+ aiSearchVolume: z.number().int().nonnegative().nullable(),
});
const brandTopPageSchema = z.object({
- url: z.string(),
- domain: z.string().nullable(),
- mentions: z.number().int().nonnegative().nullable(),
+ url: z.string().max(2048),
+ domain: z.string().max(253).nullable(),
platform: z.enum(["chat_gpt", "google"]),
+ // Page-level citation mentions from DataForSEO top_pages.
+ mentions: z.number().int().nonnegative().nullable(),
+ // Page-level AI search volume from DataForSEO top_pages.
+ capturedVolume: z.number().int().nonnegative().nullable(),
+ // Example prompts from the fetched mentions sample that cited this page.
+ keywords: z.array(brandTopPageKeywordSchema).max(50),
});
const brandTopQuerySchema = z.object({
- question: z.string(),
+ question: z.string().max(500),
platform: z.enum(["chat_gpt", "google"]),
aiSearchVolume: z.number().int().nonnegative().nullable(),
firstSeenAt: z.string().nullable(),
@@ -55,13 +104,13 @@ const brandTopQuerySchema = z.object({
citedSources: z
.array(
z.object({
- url: z.string(),
- domain: z.string().nullable(),
- title: z.string().nullable(),
+ url: z.string().max(2048),
+ domain: z.string().max(253).nullable(),
+ title: z.string().max(300).nullable(),
}),
)
.max(10),
- brandsMentioned: z.array(z.string()).max(20),
+ brandsMentioned: z.array(z.string().max(200)).max(20),
});
const brandMonthlyVolumeSchema = z.object({
@@ -78,9 +127,13 @@ export const brandLookupResultSchema = z.object({
hasData: z.boolean(),
totalMentions: z.number().int().nonnegative().nullable(),
totalAiSearchVolume: z.number().int().nonnegative().nullable(),
- totalImpressions: z.number().int().nonnegative().nullable(),
perPlatform: z.array(brandPlatformBreakdownSchema),
- topPages: z.array(brandTopPageSchema).max(20),
+ // Competitor Share of Voice — null when no competitors were supplied or both
+ // cross_aggregated calls failed. No legacy-cache shim: pre-SoV cache entries
+ // are unreachable anyway (the cache key's param set changed), see the
+ // buildCacheKey comment in brandLookup.ts.
+ shareOfVoice: brandShareOfVoiceSchema.nullable(),
+ topPages: z.array(brandTopPageSchema).max(40),
topQueries: z.array(brandTopQuerySchema).max(50),
monthlyVolume: z.array(brandMonthlyVolumeSchema),
});
@@ -205,9 +258,23 @@ export type PromptExplorerResult = z.infer<typeof promptExplorerResultSchema>;
// URL search params
// ---------------------------------------------------------------------------
-/** /p/$projectId/brand-lookup query params — `q` keeps the lookup shareable. */
+/**
+ * /p/$projectId/brand-lookup query params. `q` keeps the lookup shareable; `c`
+ * is a comma-joined competitor list (route + page treat the parsed result as an
+ * opaque string array). `c` accepts a raw string (from the URL) OR an array
+ * (TanStack Router re-validates its own transformed output on navigate) — same
+ * union pattern as `models` below.
+ */
export const brandLookupSearchSchema = z.object({
q: z.string().optional(),
+ c: z
+ .union([z.string(), z.array(z.string())])
+ .optional()
+ .transform((value) =>
+ value === undefined
+ ? undefined
+ : parseCompetitorList(Array.isArray(value) ? value.join(",") : value),
+ ),
});
/**