Open-source agentic AI Search Execution Platform. Track AI visibility, find opportunities, and let agents turn signals into prioritized actions and drafted fixes across ChatGPT, Claude, Gemini, Google AI Overviews, Google AI Mode, Perplexity, Grok, and Microsoft Copilot.
TypeScript aeoai-agentai-searchanswer-engine-optimizationbrand-monitoringchatgptclaudecopilotdockergeminigeogoogle-ai-overviewsgrokmcpnextjsopen-sourceperplexityseosupabasetypescript
feat(signals): show where a page's AI visits come from and its prompts (#1066)
Cihan880d46094109
diff --git a/server/src/lib/signals/library/detect.js b/server/src/lib/signals/library/detect.jsindex 6cc796625..1abe02e87 100644--- a/server/src/lib/signals/library/detect.js+++ b/server/src/lib/signals/library/detect.js@@ -26,6 +26,7 @@ import { resolveBrandSources } from '../../action-center/sources.js';import * as c from './classify.js';import { isTransientDbError } from '../../pulse/metrics.js';import { describeSignal } from '../../audit/rubric.js';+import { TRAFFIC_WINDOW_DAYS } from '../traffic-evidence.js';const { library: t } = resolve();const DAY_MS = 86_400_000;@@ -173,10 +174,10 @@ function context(brandId, now, sources) {once('traffic', () =>rpc('ae_ai_traffic_pages', {p_brand_id: brandId,- p_cur_from: isoDay(now, 13),+ p_cur_from: isoDay(now, TRAFFIC_WINDOW_DAYS - 1),p_cur_to: isoDay(now, 0),- p_prev_from: isoDay(now, 27),- p_prev_to: isoDay(now, 14),+ p_prev_from: isoDay(now, TRAFFIC_WINDOW_DAYS * 2 - 1),+ p_prev_to: isoDay(now, TRAFFIC_WINDOW_DAYS),}),),gsc: () =>diff --git a/server/src/lib/signals/nightly-reads.test.js b/server/src/lib/signals/nightly-reads.test.jsindex 910e8431b..9a5ffe9e2 100644--- a/server/src/lib/signals/nightly-reads.test.js+++ b/server/src/lib/signals/nightly-reads.test.js@@ -22,6 +22,7 @@ const NIGHTLY_MODULES = ['src/lib/signals/lost-citation-evidence.js','src/lib/signals/competitor-evidence.js','src/lib/signals/mention-evidence.js',+ 'src/lib/signals/traffic-evidence.js','src/lib/pulse/metrics.js','src/lib/action-center/generate.js','src/lib/action-center/validate.js',diff --git a/server/src/lib/signals/record-evidence.test.js b/server/src/lib/signals/record-evidence.test.jsindex d867d67c7..a73a1f165 100644--- a/server/src/lib/signals/record-evidence.test.js+++ b/server/src/lib/signals/record-evidence.test.js@@ -43,10 +43,35 @@ vi.mock('./mention-evidence.js', () => ({},}));+let trafficRead = { calls: [], fail: false };+vi.mock('./traffic-evidence.js', () => ({+ TRAFFIC_WINDOW_DAYS: 14,+ trafficEvidence: async (brandId, pages, opts) => {+ trafficRead.calls.push([brandId, pages, opts]);+ if (trafficRead.fail) throw new Error('timeout');+ // Each page is targeted by its own prompt and by a shared one.+ return new Map(+ (pages ?? [null]).map((page) => [+ page,+ {+ referrals: { page, source: 'analytics', sessions: 3, before: 5, platforms: [] },+ prompts: page+ ? [+ { id: `p${page}`, text: `About ${page}` },+ { id: 'shared', text: 'Coffee' },+ ]+ : [],+ },+ ]),+ );+ },+}));+const {attachCompetitorEvidence,attachLostCitationEvidence,attachMentionEvidence,+ attachTrafficEvidence,keepRecordedEvidence,} = await import('./record.js');@@ -70,6 +95,7 @@ beforeEach(() => {read = { calls: [], result: new Map(), fail: false };competitorRead = { calls: [], result: new Map(), fail: false };mentionRead = { calls: [], result: [], fail: false };+ trafficRead = { calls: [], fail: false };});describe('attachLostCitationEvidence', () => {@@ -237,3 +263,76 @@ describe('attachMentionEvidence', () => {expect(candidates[0].payload).toEqual({ promptIds: ['p1', 'p2'], mentions });});});++describe('attachTrafficEvidence', () => {+ const now = new Date('2026-10-15T00:00:00Z');+ const slipping = () => ({+ kind: 'ai_traffic_slipping',+ dedupKey: 'ai_traffic_slipping',+ payload: {+ entity: 'pages',+ targets: ['/a', '/b', '/c', '/d', '/e', '/f'].map((id) => ({ id, label: id })),+ },+ });+ const opportunity = () => ({+ kind: 'page_opportunity',+ dedupKey: 'page_opportunity:/a',+ payload: { landingPage: '/a', valueRank: 3 },+ });++ it("reads every signal's pages at once, the site once, side by side", async () => {+ const candidates = [+ slipping(),+ opportunity(),+ { kind: 'cross_channel_risk', dedupKey: 'cross_channel_risk:site', payload: {} },+ { kind: 'gsc_decline', dedupKey: 'gsc_decline', payload: { targets: [{ id: 'q' }] } },+ ];+ await attachTrafficEvidence('b1', candidates, now);+ // The detector's pages as written, a page opportunity's as a path.+ expect(trafficRead.calls).toEqual([+ ['b1', ['/a', '/b', '/c', '/d', '/e', '/f'], { now, exact: true }],+ ['b1', ['/a'], { now }],+ ['b1', null, { now }],+ ]);+ const [pages, page, site, other] = candidates.map((c) => c.payload);+ // Referrals for the first pages; prompts targeting any of them, each once.+ expect(pages.referrals.map((r) => r.page)).toEqual(['/a', '/b', '/c', '/d', '/e']);+ expect(pages.citablePrompts.map((p) => p.id)).toEqual([+ 'p/a',+ 'shared',+ 'p/b',+ 'p/c',+ 'p/d',+ 'p/e',+ 'p/f',+ ]);+ expect(pages.citablePromptsTotal).toBe(7);+ expect(page).toMatchObject({+ landingPage: '/a',+ referrals: [{ page: '/a', sessions: 3, before: 5 }],+ referralDays: 14,+ citablePrompts: [+ { id: 'p/a', text: 'About /a' },+ { id: 'shared', text: 'Coffee' },+ ],+ });+ expect(site).toEqual({+ referrals: [{ page: null, source: 'analytics', sessions: 3, before: 5, platforms: [] }],+ referralDays: 14,+ });+ expect(other).toEqual({ targets: [{ id: 'q' }] });+ });++ it("records them without evidence when the read fails, keeping an earlier night's", async () => {+ trafficRead.fail = true;+ const candidates = [opportunity()];+ await expect(attachTrafficEvidence('b1', candidates, now)).resolves.toBeUndefined();+ expect(candidates[0].payload).toEqual({ landingPage: '/a', valueRank: 3 });+ const recorded = { referrals: [{ page: '/a' }], referralDays: 14, citablePrompts: [] };+ keepRecordedEvidence(+ candidates,+ new Map([['page_opportunity:/a', { payload: { landingPage: '/a', ...recorded } }]]),+ );+ expect(candidates[0].payload).toEqual({ landingPage: '/a', valueRank: 3, ...recorded });+ });+});diff --git a/server/src/lib/signals/record.js b/server/src/lib/signals/record.jsindex 00030c3c8..ac89bbf8d 100644--- a/server/src/lib/signals/record.js+++ b/server/src/lib/signals/record.js@@ -31,6 +31,7 @@ import { computePulseMetrics, LOST_CITATION_WINDOW_DAYS } from '../pulse/metricsimport { lostCitationEvidence } from './lost-citation-evidence.js';import { competitorEvidence } from './competitor-evidence.js';import { mentionEvidence } from './mention-evidence.js';+import { TRAFFIC_WINDOW_DAYS, trafficEvidence } from './traffic-evidence.js';import { logger } from '../logger.js';import { readAllRpcRows } from '../rpc-pages.js';import { resolve } from '../../config/action-engine.js';@@ -603,6 +604,28 @@ for (const kind of COMPETITOR_KINDS) {}EVIDENCE.uncited_mentions = { marker: 'mentions', fields: ['mentions'] };+// Signals about AI visits: to their pages, to one page, or to the whole site.+const TRAFFIC_PAGE_KINDS = new Set([+ 'ai_traffic_slipping',+ 'ai_traffic_drop',+ 'ai_landing_page_winner',+ 'ai_landing_underperforming',+ 'converting_page_slipping',+]);+const TRAFFIC_SITE_KINDS = new Set(['cross_channel_risk', 'visibility_traffic_loss']);+for (const kind of [...TRAFFIC_PAGE_KINDS, ...TRAFFIC_SITE_KINDS, 'page_opportunity']) {+ EVIDENCE[kind] = {+ marker: 'referrals',+ fields: ['referrals', 'referralDays', 'citablePrompts', 'citablePromptsTotal'],+ };+}++/** Pages a traffic signal's referrals describe: its first ones. */+const TRAFFIC_PAGES_SHOWN = 5;++/** Prompts a traffic signal names it could be cited on. */+const CITABLE_PROMPTS_SHOWN = 10;+/*** A night whose evidence read failed refreshes a signal with its bare* detector payload. Keep what an earlier night recorded instead: it is older,@@ -644,6 +667,83 @@ export async function attachMentionEvidence(brandId, candidates, now) {}}+/** A traffic signal's pages, or its one; null for the site. */+function trafficPagesOf(candidate) {+ if (candidate.kind === 'page_opportunity') {+ const page = candidate.payload?.landingPage;+ return typeof page === 'string' && page ? [page] : [];+ }+ if (TRAFFIC_SITE_KINDS.has(candidate.kind)) return null;+ if (!TRAFFIC_PAGE_KINDS.has(candidate.kind)) return [];+ return (candidate.payload?.targets ?? [])+ .map((target) => target?.id)+ .filter((id) => typeof id === 'string' && id);+}++/** One traffic evidence read; null when it fails, which costs its signals only. */+async function readTraffic(brandId, pages, opts) {+ if (pages?.length === 0) return new Map();+ try {+ return await trafficEvidence(brandId, pages, opts);+ } catch (err) {+ logger.warn({ brandId, err: err.message }, '[signals] traffic evidence unavailable');+ return null;+ }+}++/**+ * Traffic signals arrive naming their pages and a session count. Before they+ * are written they get what the drawer shows (AC-001): for their first pages,+ * the AI visits by platform over the last two windows, and the prompts+ * naming any of their pages as the target. The detector's pages are matched+ * as written, so their numbers are the finding's; a page opportunity's path+ * as a path. Three reads at most, side by side. Best effort, like the other+ * evidence.+ */+export async function attachTrafficEvidence(brandId, candidates, now) {+ const onPages = candidates+ .map((candidate) => ({+ candidate,+ pages: trafficPagesOf(candidate),+ exact: TRAFFIC_PAGE_KINDS.has(candidate.kind),+ }))+ .filter(({ pages }) => pages?.length);+ const onSite = candidates.filter((candidate) => TRAFFIC_SITE_KINDS.has(candidate.kind));+ const pagesOf = (exact) => [+ ...new Set(onPages.filter((o) => o.exact === exact).flatMap((o) => o.pages)),+ ];++ const [asWritten, asPaths, site] = await Promise.all([+ readTraffic(brandId, pagesOf(true), { now, exact: true }),+ readTraffic(brandId, pagesOf(false), { now }),+ onSite.length ? readTraffic(brandId, null, { now }) : null,+ ]);++ for (const { candidate, pages, exact } of onPages) {+ const evidence = exact ? asWritten : asPaths;+ if (!evidence) continue;+ const found = pages.map((page) => evidence.get(page)).filter(Boolean);+ const prompts = [...new Map(found.flatMap((f) => f.prompts).map((p) => [p.id, p])).values()];+ candidate.payload = {+ ...candidate.payload,+ referrals: found.slice(0, TRAFFIC_PAGES_SHOWN).map((f) => f.referrals),+ referralDays: TRAFFIC_WINDOW_DAYS,+ citablePrompts: prompts.slice(0, CITABLE_PROMPTS_SHOWN),+ citablePromptsTotal: prompts.length,+ };+ }+ const whole = site?.get(null);+ if (whole) {+ for (const candidate of onSite) {+ candidate.payload = {+ ...candidate.payload,+ referrals: [whole.referrals],+ referralDays: TRAFFIC_WINDOW_DAYS,+ };+ }+ }+}+/** The competitor a signal is about: the library names it, the others key on it. */function competitorOf(candidate) {const named = candidate.payload?.competitorId;@@ -767,6 +867,7 @@ export async function recordSignalsForBrand(brandId, { now = new Date() } = {}));await attachCompetitorEvidence(brandId, [...candidates, ...overflow], now);await attachMentionEvidence(brandId, candidates, now);+ await attachTrafficEvidence(brandId, [...candidates, ...overflow], now);// Existing rows decide insert vs update vs reopen. A brand's signal set is// small (tens), so reading it whole is cheaper than being clever.diff --git a/server/src/lib/signals/traffic-evidence.js b/server/src/lib/signals/traffic-evidence.jsnew file mode 100644index 000000000..3f13aaebe--- /dev/null+++ b/server/src/lib/signals/traffic-evidence.js@@ -0,0 +1,95 @@+/**+ * Where a traffic signal's AI visits come from, and the prompts its pages+ * could be cited on (AC-001).+ *+ * A traffic signal names its pages and a session count. The panel asks for+ * the AI referrals by platform and the prompts where the page could be+ * cited; this reads both for the pages given, or the site's referrals for a+ * site-wide signal, in one call (`ae_page_traffic_evidence`, 00143).+ */++import supabaseAdmin from '../../config/supabase.js';++const DAY_MS = 86_400_000;++/**+ * The AI-traffic windows: the last 14 days against the 14 before. The+ * detector compares these (library/detect.js), and the evidence reads them.+ */+export const TRAFFIC_WINDOW_DAYS = 14;++const isoDay = (now, daysAgo) =>+ new Date(now.getTime() - daysAgo * DAY_MS).toISOString().slice(0, 10);++/** Rows by the page they were asked for; null for the whole site. */+function byPage(rows) {+ const pages = new Map();+ for (const row of rows ?? []) {+ const page = row.page ?? null;+ const list = pages.get(page);+ if (list) list.push(row);+ else pages.set(page, [row]);+ }+ return pages;+}++/** One page's AI visits by platform, most first, with their totals. */+export function summarizeReferrals(rows) {+ const platforms = rows+ .map((row) => ({+ platform: row.platform ?? 'unknown',+ sessions: Number(row.cur_sessions ?? 0),+ before: Number(row.prev_sessions ?? 0),+ }))+ .filter((p) => p.sessions > 0 || p.before > 0)+ .sort(+ (a, b) =>+ b.sessions - a.sessions || b.before - a.before || a.platform.localeCompare(b.platform),+ );+ return {+ sessions: platforms.reduce((sum, p) => sum + p.sessions, 0),+ before: platforms.reduce((sum, p) => sum + p.before, 0),+ platforms,+ };+}++/**+ * The evidence for `pages`, or for the whole site when `pages` is null, by+ * page. Visits are read from Analytics when it has the page and from the+ * tracking snippet otherwise: the snippet counts the same visits again, so+ * the two are never added, as in the detector. `exact` matches the pages as+ * written, for the detector's own pages; otherwise as paths. The prompts are+ * the active ones naming the page as their target URL.+ */+export async function trafficEvidence(brandId, pages, { now, exact = false }) {+ const { data, error } = await supabaseAdmin.rpc('ae_page_traffic_evidence', {+ p_brand_id: brandId,+ p_pages: pages,+ p_cur_from: isoDay(now, TRAFFIC_WINDOW_DAYS - 1),+ p_cur_to: isoDay(now, 0),+ p_prev_from: isoDay(now, TRAFFIC_WINDOW_DAYS * 2 - 1),+ p_prev_to: isoDay(now, TRAFFIC_WINDOW_DAYS),+ p_exact: exact,+ });+ if (error) throw new Error(`traffic evidence read failed: ${error.message}`);++ const analytics = byPage(data?.analytics);+ const snippet = byPage(data?.snippet);+ const prompts = byPage(data?.prompts);+ return new Map(+ (pages ?? [null]).map((page) => {+ const source = analytics.has(page) ? 'analytics' : snippet.has(page) ? 'snippet' : null;+ const rows = (source === 'analytics' ? analytics : snippet).get(page) ?? [];+ return [+ page,+ {+ referrals: { page, source, ...summarizeReferrals(rows) },+ prompts: (prompts.get(page) ?? []).map((p) => ({+ id: p.prompt_id,+ text: String(p.text ?? '').slice(0, 160),+ })),+ },+ ];+ }),+ );+}diff --git a/server/src/lib/signals/traffic-evidence.test.js b/server/src/lib/signals/traffic-evidence.test.jsnew file mode 100644index 000000000..f45ea5250--- /dev/null+++ b/server/src/lib/signals/traffic-evidence.test.js@@ -0,0 +1,131 @@+import { beforeEach, describe, expect, it, vi } from 'vitest';++/**+ * The evidence of a traffic signal (AC-001): per page, AI visits by platform+ * from one source, and the prompts naming the page as their target.+ */++let result = {};+let calls = [];+vi.mock('../../config/supabase.js', () => ({+ default: {+ rpc: async (name, args) => {+ calls.push({ name, args });+ return result;+ },+ },+}));++const { summarizeReferrals, trafficEvidence } = await import('./traffic-evidence.js');++const row = (over) => ({+ page: '/pricing',+ platform: 'chatgpt.com',+ cur_sessions: 4,+ prev_sessions: 9,+ ...over,+});++describe('summarizeReferrals', () => {+ it('lists the platforms with visits, most first, and totals them', () => {+ expect(+ summarizeReferrals([+ row({ platform: 'perplexity.ai', cur_sessions: 1, prev_sessions: 0 }),+ row(),+ row({ platform: 'claude.ai', cur_sessions: 0, prev_sessions: 0 }),+ row({ platform: null, cur_sessions: 1, prev_sessions: 2 }),+ ]),+ ).toEqual({+ sessions: 6,+ before: 11,+ platforms: [+ { platform: 'chatgpt.com', sessions: 4, before: 9 },+ { platform: 'unknown', sessions: 1, before: 2 },+ { platform: 'perplexity.ai', sessions: 1, before: 0 },+ ],+ });+ });+});++describe('trafficEvidence', () => {+ const now = new Date('2026-10-15T12:00:00Z');++ beforeEach(() => {+ calls = [];+ result = {+ data: {+ analytics: [row()],+ snippet: [+ // Analytics has /pricing: its snippet visits are the same visits.+ row({ platform: 'gemini.google.com', cur_sessions: 50 }),+ row({ page: '/guide', cur_sessions: 2, prev_sessions: 1 }),+ ],+ prompts: [+ { page: '/pricing', prompt_id: 'p1', text: 'Best coffee subscription?' },+ { page: '/pricing', prompt_id: 'p2', text: 'Coffee gifts' },+ ],+ },+ error: null,+ };+ });++ it('reads the two windows once, and picks one source per page', async () => {+ const evidence = await trafficEvidence('b1', ['/pricing', '/guide', '/about'], { now });+ expect(calls).toEqual([+ {+ name: 'ae_page_traffic_evidence',+ args: {+ p_brand_id: 'b1',+ p_pages: ['/pricing', '/guide', '/about'],+ p_cur_from: '2026-10-02',+ p_cur_to: '2026-10-15',+ p_prev_from: '2026-09-18',+ p_prev_to: '2026-10-01',+ p_exact: false,+ },+ },+ ]);+ expect(evidence.get('/pricing')).toEqual({+ referrals: {+ page: '/pricing',+ source: 'analytics',+ sessions: 4,+ before: 9,+ platforms: [{ platform: 'chatgpt.com', sessions: 4, before: 9 }],+ },+ prompts: [+ { id: 'p1', text: 'Best coffee subscription?' },+ { id: 'p2', text: 'Coffee gifts' },+ ],+ });+ expect(evidence.get('/guide').referrals).toMatchObject({ source: 'snippet', sessions: 2 });+ // A page no AI engine sent anyone to says so.+ expect(evidence.get('/about')).toEqual({+ referrals: { page: '/about', source: null, sessions: 0, before: 0, platforms: [] },+ prompts: [],+ });+ });++ it("reads the whole site's visits for a site-wide signal", async () => {+ result.data = { analytics: [], snippet: [row({ page: null })], prompts: [] };+ const evidence = await trafficEvidence('b1', null, { now });+ expect(calls[0].args).toMatchObject({ p_pages: null, p_exact: false });+ expect(evidence.get(null).referrals).toMatchObject({+ page: null,+ source: 'snippet',+ sessions: 4,+ });+ });++ it("matches the detector's own pages as written", async () => {+ await trafficEvidence('b1', ['https://acme.example/pricing?ref=ai'], { now, exact: true });+ expect(calls[0].args.p_exact).toBe(true);+ });++ it('throws when the read fails, for the recorder to keep what it had', async () => {+ result = { data: null, error: { message: 'timeout' } };+ await expect(trafficEvidence('b1', ['/pricing'], { now })).rejects.toThrow(+ 'traffic evidence read failed: timeout',+ );+ });+});diff --git a/supabase/migrations/00143_traffic_signal_evidence.sql b/supabase/migrations/00143_traffic_signal_evidence.sqlnew file mode 100644index 000000000..4680597bb--- /dev/null+++ b/supabase/migrations/00143_traffic_signal_evidence.sql@@ -0,0 +1,117 @@+-- Where a traffic signal's AI visits come from, and the prompts its pages+-- could be cited on (AC-001).+--+-- A traffic signal ("AI traffic slipping on 3 pages", "High-value page+-- without AI traffic") named its pages and a session count, never which AI+-- engines send the visits or which prompts the page answers. The panel is to+-- show both. This reads, for the pages given, AI-referred sessions per+-- platform over two windows from Analytics (ga_ai_traffic_stats) and from the+-- tracking snippet (ai_traffic_logs), and the active prompts that name the+-- page as their target URL. With p_pages null it reads the whole site's+-- sessions per platform, for the site-wide signals.+--+-- Two ways to match a page's visits:+-- - p_exact: as written. The AI-traffic detector's pages are these tables'+-- own landing_page / url values (ae_ai_traffic_pages, 00091), so its+-- signals read the same rows their numbers came from.+-- - otherwise as the page-opportunity read matches them (00075), by+-- lower(normalize_page_path(...)): "/pricing/" in Analytics and a+-- snippet's full URL both name a page opportunity's "/pricing".+-- Target URLs always match the second way: they are typed in full by users.+-- Each row carries the page as it was asked for, so the caller can map it+-- back.+--+-- Both sources are returned as they are: the snippet counts the visits+-- Analytics counts again, so the caller picks one per page and never adds+-- them, as the detector does (mergeTrafficPages).++create or replace function public.ae_page_traffic_evidence(+ p_brand_id uuid,+ p_pages text[],+ p_cur_from date,+ p_cur_to date,+ p_prev_from date,+ p_prev_to date,+ p_exact boolean default false+) returns jsonb+language sql+stable+set search_path = public+as $$+ with pages as (+ select distinct page,+ case when p_exact then page else lower(normalize_page_path(page)) end as match_key,+ lower(normalize_page_path(page)) as page_key+ from unnest(p_pages) as page+ ),+ -- Each visit row's key is computed once, so the join below is an equality+ -- the planner can hash, not a function call per row and page.+ ga_rows as (+ select platform, date, sessions,+ case+ when p_pages is null then null+ when p_exact then landing_page+ else lower(normalize_page_path(landing_page))+ end as match_key+ from ga_ai_traffic_stats+ where brand_id = p_brand_id+ and date between p_prev_from and p_cur_to+ and (p_pages is null or landing_page <> '')+ ),+ log_rows as (+ select source_platform as platform, created_at,+ case+ when p_pages is null then null+ when p_exact then url+ else lower(normalize_page_path(url))+ end as match_key+ from ai_traffic_logs+ where brand_id = p_brand_id+ and created_at >= p_prev_from+ and (p_pages is null or not p_exact or url = any(p_pages))+ ),+ analytics as (+ select pg.page, r.platform,+ coalesce(sum(r.sessions) filter (where r.date between p_cur_from and p_cur_to), 0) as cur_sessions,+ coalesce(sum(r.sessions) filter (where r.date between p_prev_from and p_prev_to), 0) as prev_sessions+ from ga_rows r+ left join pages pg on pg.match_key = r.match_key+ where p_pages is null or pg.page is not null+ group by pg.page, r.platform+ ),+ snippet as (+ select pg.page, r.platform,+ count(*) filter (where r.created_at::date between p_cur_from and p_cur_to) as cur_sessions,+ count(*) filter (where r.created_at::date between p_prev_from and p_prev_to) as prev_sessions+ from log_rows r+ left join pages pg on pg.match_key = r.match_key+ where p_pages is null or pg.page is not null+ group by pg.page, r.platform+ ),+ targeted as (+ -- Explicit targeting only, as in 00075: a URL a customer attached to a+ -- prompt is a fact; "a prompt covers this page's topic" is a guess. A+ -- paused prompt is not asked, so the page can't be cited on it.+ select distinct pg.page, p.id as prompt_id, p.text+ from prompt_target_urls ptu+ join prompts p on p.id = ptu.prompt_id+ join prompt_sets ps on ps.id = p.prompt_set_id+ join pages pg on pg.page_key = lower(normalize_page_path(ptu.url))+ where ps.brand_id = p_brand_id+ and p.is_active+ )+ select jsonb_build_object(+ 'analytics', coalesce((select jsonb_agg(a) from analytics a), '[]'::jsonb),+ 'snippet', coalesce((select jsonb_agg(s) from snippet s), '[]'::jsonb),+ 'prompts', coalesce(+ (select jsonb_agg(t order by t.page, t.text, t.prompt_id) from targeted t),+ '[]'::jsonb+ )+ )+$$;++-- Service-role only, like the other detector reads.+revoke all on function public.ae_page_traffic_evidence(uuid, text[], date, date, date, date, boolean)+ from public, anon, authenticated;+grant execute on function public.ae_page_traffic_evidence(uuid, text[], date, date, date, date, boolean)+ to service_role;diff --git a/supabase/schema.sql b/supabase/schema.sqlindex 228f38fc5..fed05e39a 100644--- a/supabase/schema.sql+++ b/supabase/schema.sql@@ -17761,6 +17761,127 @@ revoke all on function public.ae_competitor_positions(uuid, text[], date, date,grant execute on function public.ae_competitor_positions(uuid, text[], date, date, date, date, integer)to service_role;+-- ─────────────────────────────────────────────────────────────────────────+-- migrations/00143_traffic_signal_evidence.sql+-- ─────────────────────────────────────────────────────────────────────────+-- Where a traffic signal's AI visits come from, and the prompts its pages+-- could be cited on (AC-001).+--+-- A traffic signal ("AI traffic slipping on 3 pages", "High-value page+-- without AI traffic") named its pages and a session count, never which AI+-- engines send the visits or which prompts the page answers. The panel is to+-- show both. This reads, for the pages given, AI-referred sessions per+-- platform over two windows from Analytics (ga_ai_traffic_stats) and from the+-- tracking snippet (ai_traffic_logs), and the active prompts that name the+-- page as their target URL. With p_pages null it reads the whole site's+-- sessions per platform, for the site-wide signals.+--+-- Two ways to match a page's visits:+-- - p_exact: as written. The AI-traffic detector's pages are these tables'+-- own landing_page / url values (ae_ai_traffic_pages, 00091), so its+-- signals read the same rows their numbers came from.+-- - otherwise as the page-opportunity read matches them (00075), by+-- lower(normalize_page_path(...)): "/pricing/" in Analytics and a+-- snippet's full URL both name a page opportunity's "/pricing".+-- Target URLs always match the second way: they are typed in full by users.+-- Each row carries the page as it was asked for, so the caller can map it+-- back.+--+-- Both sources are returned as they are: the snippet counts the visits+-- Analytics counts again, so the caller picks one per page and never adds+-- them, as the detector does (mergeTrafficPages).++create or replace function public.ae_page_traffic_evidence(+ p_brand_id uuid,+ p_pages text[],+ p_cur_from date,+ p_cur_to date,+ p_prev_from date,+ p_prev_to date,+ p_exact boolean default false+) returns jsonb+language sql+stable+set search_path = public+as $$+ with pages as (+ select distinct page,+ case when p_exact then page else lower(normalize_page_path(page)) end as match_key,+ lower(normalize_page_path(page)) as page_key+ from unnest(p_pages) as page+ ),+ -- Each visit row's key is computed once, so the join below is an equality+ -- the planner can hash, not a function call per row and page.+ ga_rows as (+ select platform, date, sessions,+ case+ when p_pages is null then null+ when p_exact then landing_page+ else lower(normalize_page_path(landing_page))+ end as match_key+ from ga_ai_traffic_stats+ where brand_id = p_brand_id+ and date between p_prev_from and p_cur_to+ and (p_pages is null or landing_page <> '')+ ),+ log_rows as (+ select source_platform as platform, created_at,+ case+ when p_pages is null then null+ when p_exact then url+ else lower(normalize_page_path(url))+ end as match_key+ from ai_traffic_logs+ where brand_id = p_brand_id+ and created_at >= p_prev_from+ and (p_pages is null or not p_exact or url = any(p_pages))+ ),+ analytics as (+ select pg.page, r.platform,+ coalesce(sum(r.sessions) filter (where r.date between p_cur_from and p_cur_to), 0) as cur_sessions,+ coalesce(sum(r.sessions) filter (where r.date between p_prev_from and p_prev_to), 0) as prev_sessions+ from ga_rows r+ left join pages pg on pg.match_key = r.match_key+ where p_pages is null or pg.page is not null+ group by pg.page, r.platform+ ),+ snippet as (+ select pg.page, r.platform,+ count(*) filter (where r.created_at::date between p_cur_from and p_cur_to) as cur_sessions,+ count(*) filter (where r.created_at::date between p_prev_from and p_prev_to) as prev_sessions+ from log_rows r+ left join pages pg on pg.match_key = r.match_key+ where p_pages is null or pg.page is not null+ group by pg.page, r.platform+ ),+ targeted as (+ -- Explicit targeting only, as in 00075: a URL a customer attached to a+ -- prompt is a fact; "a prompt covers this page's topic" is a guess. A+ -- paused prompt is not asked, so the page can't be cited on it.+ select distinct pg.page, p.id as prompt_id, p.text+ from prompt_target_urls ptu+ join prompts p on p.id = ptu.prompt_id+ join prompt_sets ps on ps.id = p.prompt_set_id+ join pages pg on pg.page_key = lower(normalize_page_path(ptu.url))+ where ps.brand_id = p_brand_id+ and p.is_active+ )+ select jsonb_build_object(+ 'analytics', coalesce((select jsonb_agg(a) from analytics a), '[]'::jsonb),+ 'snippet', coalesce((select jsonb_agg(s) from snippet s), '[]'::jsonb),+ 'prompts', coalesce(+ (select jsonb_agg(t order by t.page, t.text, t.prompt_id) from targeted t),+ '[]'::jsonb+ )+ )+$$;++-- Service-role only, like the other detector reads.+revoke all on function public.ae_page_traffic_evidence(uuid, text[], date, date, date, date, boolean)+ from public, anon, authenticated;+grant execute on function public.ae_page_traffic_evidence(uuid, text[], date, date, date, date, boolean)+ to service_role;+-- ─────────────────────────────────────────────────────────────────────────-- migrations/00147_insights_same_prompts_definer.sql-- ─────────────────────────────────────────────────────────────────────────diff --git a/web/messages/en.json b/web/messages/en.jsonindex a3bfec545..6cc54a9a2 100644--- a/web/messages/en.json+++ b/web/messages/en.json@@ -349,6 +349,11 @@"status": "Status","viewPrompt": "View prompt","notAvailable": "Not available",+ "none": "None",+ "referrals": {+ "none": "No AI referrals",+ "period": "Visits in the last {days} days, against the {days} before"+ },"allPlatforms": "All tracked platforms","checkEvidence": {"yes": "yes",@@ -444,7 +449,9 @@"points": "{value} pts","periods": {"week_over_week": "Last 7 days against the 7 days before",+ "fortnight_over_fortnight": "Last 14 days against the 14 days before","last_7_days": "Last 7 days",+ "last_fortnight": "Last 14 days","last_14_days": "Days with answers in the last 14 days","latest": "Latest data"},diff --git a/web/src/app/[locale]/(dashboard)/dashboard/traffic/_charts.test.ts b/web/src/app/[locale]/(dashboard)/dashboard/traffic/_charts.test.tsindex 685cd2bc7..208381a2b 100644--- a/web/src/app/[locale]/(dashboard)/dashboard/traffic/_charts.test.ts+++ b/web/src/app/[locale]/(dashboard)/dashboard/traffic/_charts.test.ts@@ -1,5 +1,6 @@import { describe, expect, it } from 'vitest';-import { getPlatformFilterItems, getPlatformName } from './_charts';+import { getPlatformName } from '@/lib/traffic-platforms';+import { getPlatformFilterItems } from './_charts';describe('getPlatformFilterItems', () => {it('starts with the all-platforms option, whose value is empty', () => {diff --git a/web/src/app/[locale]/(dashboard)/dashboard/traffic/_charts.tsx b/web/src/app/[locale]/(dashboard)/dashboard/traffic/_charts.tsxindex 0390e310d..d487f0787 100644--- a/web/src/app/[locale]/(dashboard)/dashboard/traffic/_charts.tsx+++ b/web/src/app/[locale]/(dashboard)/dashboard/traffic/_charts.tsx@@ -1,6 +1,7 @@'use client';import { useRef, useState, useEffect } from 'react';+import { getPlatformName } from '@/lib/traffic-platforms';import {AreaChart,Area,@@ -50,7 +51,8 @@ function ChartContainer({//// Keys must stay in sync with the detection host list in the tracking snippet// (`server/src/public/t.js`): every platform t.js can resolve and store needs a-// label + color here, otherwise it renders as a raw hostname. `unknown` is kept+// color here and a name in `@/lib/traffic-platforms`, otherwise it renders as+// a raw hostname. `unknown` is kept// only for historical rows that predate #288 (null source_platform); new visits// always carry a concrete platform.@@ -71,31 +73,10 @@ const PLATFORM_COLORS: Record<string, string> = {unknown: '#94a3b8',};-const PLATFORM_NAMES: Record<string, string> = {- 'chatgpt.com': 'ChatGPT',- 'chat.openai.com': 'ChatGPT',- 'search.chatgpt.com': 'ChatGPT',- 'perplexity.ai': 'Perplexity',- 'claude.ai': 'Claude',- 'gemini.google.com': 'Gemini',- 'copilot.microsoft.com': 'Copilot',- 'you.com': 'You.com',- 'phind.com': 'Phind',- 'meta.ai': 'Meta AI',- 'poe.com': 'Poe',- 'labs.google': 'Google Labs',- 'bing.com': 'Bing',- unknown: 'Unknown',-};-function getColor(platform: string): string {return PLATFORM_COLORS[platform] ?? '#94a3b8';}-export function getPlatformName(platform: string): string {- return PLATFORM_NAMES[platform] ?? platform;-}-/*** Options of the platform filter, with an empty-valued "all" option first. Base UI's Select can only* show the label of the picked option in its trigger when it is given the options as `items`;diff --git a/web/src/app/[locale]/(dashboard)/dashboard/traffic/page.tsx b/web/src/app/[locale]/(dashboard)/dashboard/traffic/page.tsxindex ff6b691f4..3f2cb2065 100644--- a/web/src/app/[locale]/(dashboard)/dashboard/traffic/page.tsx+++ b/web/src/app/[locale]/(dashboard)/dashboard/traffic/page.tsx@@ -1,7 +1,8 @@'use client';import { useState, useEffect, useCallback, useMemo } from 'react';-import { getPlatformFilterItems, getPlatformName } from './_charts';+import { getPlatformFilterItems } from './_charts';+import { getPlatformName } from '@/lib/traffic-platforms';import dynamic from 'next/dynamic';import { Skeleton } from '@/components/ui/skeleton';import { getPublicApiBaseUrl } from '@/config/api';diff --git a/web/src/components/action-center/signal-detail-blocks.test.tsx b/web/src/components/action-center/signal-detail-blocks.test.tsxindex b348e2be2..9f684e58f 100644--- a/web/src/components/action-center/signal-detail-blocks.test.tsx+++ b/web/src/components/action-center/signal-detail-blocks.test.tsx@@ -380,6 +380,85 @@ describe("a technical finding with its checks' evidence", () => {});});+describe('a traffic signal with its referrals and prompts', () => {+ it('lists the referrals by platform, page by page, and the prompts', () => {+ render(+ <SignalWhereBlock+ signal={signal({+ category: 'traffic',+ kind: 'ai_traffic_slipping',+ currentValue: 2,+ payload: {+ entity: 'pages',+ targets: [+ { id: '/pricing', label: '/pricing' },+ { id: '/guide', label: '/guide' },+ ],+ referrals: [+ {+ page: '/pricing',+ source: 'analytics',+ sessions: 6,+ before: 11,+ platforms: [+ { platform: 'chatgpt.com', sessions: 4, before: 9 },+ { platform: 'perplexity.ai', sessions: 2, before: 2 },+ ],+ },+ { page: '/guide', source: null, sessions: 0, before: 0, platforms: [] },+ ],+ referralDays: 14,+ citablePrompts: [],+ citablePromptsTotal: 0,+ },+ where: NO_WHERE,+ })}+ />,+ );+ const rows = [...container.querySelectorAll('dt')].map(+ (dt) => `${dt.textContent}: ${dt.nextElementSibling?.textContent}`,+ );+ expect(rows).toContain(+ 'AI referrals by platform: /pricingChatGPT 9 → 4 · Perplexity 2 → 2/guideNo AI referrals' ++ 'Visits in the last 14 days, against the 14 before',+ );+ expect(rows).toContain('Prompts it could be cited on: None');+ });++ it("doesn't name the page again when the signal is about one", () => {+ render(+ <SignalWhereBlock+ signal={signal({+ category: 'traffic',+ kind: 'page_opportunity',+ currentValue: 120,+ payload: {+ landingPage: '/pricing',+ referrals: [+ {+ page: '/pricing',+ source: 'analytics',+ sessions: 1,+ before: 0,+ platforms: [{ platform: 'grok.com', sessions: 1, before: 0 }],+ },+ ],+ referralDays: 14,+ },+ where: NO_WHERE,+ })}+ />,+ );+ const rows = [...container.querySelectorAll('dt')].map(+ (dt) => `${dt.textContent}: ${dt.nextElementSibling?.textContent}`,+ );+ expect(rows).toContain('URL: /pricing');+ expect(rows).toContain(+ 'AI referrals by platform: Grok 0 → 1Visits in the last 14 days, against the 14 before',+ );+ });+});+describe('SignalEvidenceBlock', () => {it('links the answers and the action the signal is used by', async () => {getSignalActions.mockResolvedValue([diff --git a/web/src/components/action-center/signal-detail-blocks.tsx b/web/src/components/action-center/signal-detail-blocks.tsxindex 8debef68b..26f7c9c70 100644--- a/web/src/components/action-center/signal-detail-blocks.tsx+++ b/web/src/components/action-center/signal-detail-blocks.tsx@@ -8,6 +8,7 @@ import { AIProviderAvatar } from '@/components/ai-provider-avatar';import { getSignalActions, type Signal, type SignalAction } from '@/lib/actions/signals';import { actionTexts } from '@/lib/action-center/display';import { crawlerName, locationName, platformFamily, platformName } from '@/lib/signals/names';+import { getPlatformName } from '@/lib/traffic-platforms';import {METRIC_UNITS,signalChange,@@ -127,6 +128,7 @@ function WhereValueView({ value }: { value: WhereValue }) {</span>);case 'prompts': {+ if (value.total === 0) return <span>{t('drawer.none')}</span>;if (value.items.length === 0)return <span>{t('affected.prompts', { count: value.total })}</span>;const shown = value.items.slice(0, LIST_LIMIT);@@ -209,6 +211,37 @@ function WhereValueView({ value }: { value: WhereValue }) {);case 'crawlers':return <span>{value.agents.map(crawlerName).join(', ')}</span>;+ case 'referrals': {+ const shown = value.items.slice(0, LIST_LIMIT);+ return (+ <ul className="space-y-2">+ {shown.map((item) => (+ <li key={item.page ?? ''}>+ {/* One page is the one the fields above name already. */}+ {item.page && shown.length > 1 && (+ <span className="block break-all">{item.page}</span>+ )}+ <span className="block text-xs text-muted-foreground">+ {item.platforms.length+ ? item.platforms.map((p, i) => (+ <span key={p.platform}>+ {i > 0 && ' · '}+ <span className="whitespace-nowrap">+ {`${getPlatformName(p.platform)} ${format.number(p.before)} → ${format.number(p.sessions)}`}+ </span>+ </span>+ ))+ : t('drawer.referrals.none')}+ </span>+ </li>+ ))}+ <More shown={shown.length} total={value.items.length} />+ <li className="text-xs text-muted-foreground">+ {t('drawer.referrals.period', { days: value.days })}+ </li>+ </ul>+ );+ }case 'issues': {// Page by page, each failed check with what it found.const byPage = new Map<string, typeof value.items>();diff --git a/web/src/lib/signals/detail.test.ts b/web/src/lib/signals/detail.test.tsindex 45f1361ed..a5776445d 100644--- a/web/src/lib/signals/detail.test.ts+++ b/web/src/lib/signals/detail.test.ts@@ -514,3 +514,96 @@ describe("a technical finding with its checks' evidence", () => {expect(byKey.crawlers).toBeNull();});});++describe('a traffic signal with its referrals and prompts', () => {+ const referrals = {+ page: '/pricing',+ source: 'analytics',+ sessions: 4,+ before: 9,+ platforms: [{ platform: 'chatgpt.com', sessions: 4, before: 9 }],+ };+ const opportunity = signal({+ category: 'traffic',+ kind: 'page_opportunity',+ payload: {+ landingPage: '/pricing',+ valueRank: 3,+ referrals: [referrals],+ referralDays: 14,+ citablePrompts: [{ id: 'p1', text: 'Best coffee subscription?' }],+ citablePromptsTotal: 1,+ },+ currentValue: 120,+ });++ it('gives the AI referrals by platform and the prompts the page could be cited on', () => {+ const byKey = Object.fromEntries(signalWhereFields(opportunity).map((f) => [f.key, f.value]));+ expect(byKey.url).toEqual({ type: 'text', text: '/pricing' });+ expect(byKey.aiReferrals).toEqual({ type: 'referrals', items: [referrals], days: 14 });+ expect(byKey.citablePrompts).toEqual({+ type: 'prompts',+ items: [{ id: 'p1', text: 'Best coffee subscription?' }],+ total: 1,+ });+ expect(signalDetailForApi(opportunity, []).where.ai_referrals).toEqual({+ days: 14,+ items: [+ {+ ...referrals,+ platforms: [{ platform: 'chatgpt.com', name: 'ChatGPT', sessions: 4, before: 9 }],+ },+ ],+ });+ });++ it('says none were found once looked for, and "Not available" before', () => {+ const none = signal({+ ...opportunity,+ payload: {+ landingPage: '/pricing',+ referrals: [],+ citablePrompts: [],+ citablePromptsTotal: 0,+ },+ });+ const byKey = Object.fromEntries(signalWhereFields(none).map((f) => [f.key, f.value]));+ expect(byKey.citablePrompts).toEqual({ type: 'prompts', items: [], total: 0 });+ expect(byKey.aiReferrals).toBeNull();++ const older = signal({ ...opportunity, payload: { landingPage: '/pricing', valueRank: 3 } });+ const fields = Object.fromEntries(signalWhereFields(older).map((f) => [f.key, f.value]));+ expect(fields.aiReferrals).toBeNull();+ expect(fields.citablePrompts).toBeNull();+ });+});++describe('the AI-traffic windows', () => {+ it('says the traffic findings compare 14 days, not 7', () => {+ const slipping = signal({+ category: 'traffic',+ kind: 'ai_traffic_slipping',+ payload: { entity: 'pages', targets: [{ id: '/a' }, { id: '/b' }] },+ currentValue: 2,+ });+ expect(signalChange(slipping)?.period).toBe('last_fortnight');+ const drop = signal({+ ...slipping,+ kind: 'ai_traffic_drop',+ previousValue: 90,+ currentValue: 40,+ });+ expect(signalChange(drop)?.period).toBe('fortnight_over_fortnight');+ });++ it('asks a site-wide finding where its visits come from, not which prompts', () => {+ const site = signal({+ category: 'traffic',+ kind: 'visibility_traffic_loss',+ payload: { entity: 'pages', targets: [{ id: 'site', label: '' }] },+ previousValue: 120,+ currentValue: 80,+ });+ expect(signalWhereFields(site).map((f) => f.key)).toEqual(['scope', 'aiReferrals']);+ });+});diff --git a/web/src/lib/signals/detail.ts b/web/src/lib/signals/detail.tsindex 13610b64b..1609f0138 100644--- a/web/src/lib/signals/detail.ts+++ b/web/src/lib/signals/detail.ts@@ -1,5 +1,6 @@import type { Signal } from './map';import { locationName, platformName } from './names';+import { getPlatformName } from '@/lib/traffic-platforms';import { isLibrarySignalKind, type SignalCategory, type SignalKind } from './registry';/**@@ -95,7 +96,14 @@ export interface SignalFigure {}/** The window the figures cover. The detectors all read 7-day windows. */-export type ChangePeriod = 'week_over_week' | 'last_7_days' | 'last_14_days' | 'latest';+export type ChangePeriod =+ | 'week_over_week'+ /** The AI-traffic detector's windows (server signals/traffic-evidence.js). */+ | 'fortnight_over_fortnight'+ | 'last_7_days'+ | 'last_14_days'+ | 'last_fortnight'+ | 'latest';export interface SignalChange {period: ChangePeriod;@@ -124,6 +132,15 @@ const WEEK_OVER_WEEK: Partial<Record<SignalKind, SignalMetric>> = {cross_channel_risk: 'ai_sessions',};+// Compared over the last 14 days against the 14 before, not by week.+const AI_TRAFFIC_KINDS: ReadonlySet<string> = new Set([+ 'ai_traffic_slipping',+ 'ai_traffic_drop',+ 'ai_landing_page_winner',+ 'ai_landing_underperforming',+ 'converting_page_slipping',+]);+const COUNTED: Record<string, SignalMetric> = {prompts: 'prompts',pages: 'pages',@@ -163,7 +180,10 @@ export function signalChange(signal: Signal): SignalChange | null {{ metric: 'mentions', role: 'after', value: Number(p.mentionsNow ?? 0) },);}- return { period: 'week_over_week', figures };+ return {+ period: AI_TRAFFIC_KINDS.has(signal.kind) ? 'fortnight_over_fortnight' : 'week_over_week',+ figures,+ };}switch (signal.kind) {@@ -317,7 +337,10 @@ export function signalChange(signal: Signal): SignalChange | null {}const counted = COUNTED[entity];if (counted && cur !== null) {- return { period: 'last_7_days', figures: [{ metric: counted, role: 'total', value: cur }] };+ return {+ period: AI_TRAFFIC_KINDS.has(signal.kind) ? 'last_fortnight' : 'last_7_days',+ figures: [{ metric: counted, role: 'total', value: cur }],+ };}return null;}@@ -379,6 +402,8 @@ export type WhereValue =| { type: 'issues'; items: PageIssue[] }/** AI crawlers by robots.txt user agent (`gptbot`). */| { type: 'crawlers'; agents: string[] }+ /** AI visits by platform, per page or for the site, over two windows of `days`. */+ | { type: 'referrals'; items: PageReferrals[]; days: number }| { type: 'locations'; codes: readonly string[] }| { type: 'number'; value: number };@@ -498,6 +523,37 @@ function blockedCrawlers(issues: PageIssue[]): string[] {return [...new Set(agents)];}+/** A page's AI visits (the site's, with no page) by referring platform. */+export interface PageReferrals {+ page: string | null;+ /** Where they were counted: Analytics, or the tracking snippet without it. */+ source: 'analytics' | 'snippet' | null;+ sessions: number;+ before: number;+ /** By the referrer's platform (`chatgpt.com`), most visits first. */+ platforms: { platform: string; sessions: number; before: number }[];+}++function pageReferrals(value: unknown): PageReferrals[] {+ if (!Array.isArray(value)) return [];+ const count = (v: unknown) => (typeof v === 'number' ? v : 0);+ return value+ .filter((r): r is Record<string, unknown> => !!r && typeof r === 'object')+ .map((r) => ({+ page: typeof r.page === 'string' ? r.page : null,+ source: r.source === 'analytics' || r.source === 'snippet' ? r.source : null,+ sessions: count(r.sessions),+ before: count(r.before),+ platforms: (Array.isArray(r.platforms) ? r.platforms : [])+ .filter((p): p is Record<string, unknown> => typeof p?.platform === 'string')+ .map((p) => ({+ platform: p.platform as string,+ sessions: count(p.sessions),+ before: count(p.before),+ })),+ }));+}+export interface WinningSource {domain: string;/** Answers it is cited in, of the answers read that the competitor wins. */@@ -594,6 +650,9 @@ const LAYOUT: Record<SignalCategory, WhereFieldKey[]> = {// Only a blocked crawler has crawlers to name; another technical issue has none.const CRAWLER_LAYOUT: WhereFieldKey[] = ['pages', 'issue', 'crawlers', 'evidence'];+// A site-wide traffic finding has no page to cite: where its AI visits come from.+const SITE_TRAFFIC_LAYOUT: WhereFieldKey[] = ['scope', 'aiReferrals'];+// A first citation is a gain: the page and the prompt, not who replaced it.const FIRST_CITATION_LAYOUT: WhereFieldKey[] = ['url', 'prompt', 'platforms', 'locations'];@@ -657,9 +716,7 @@ function fieldValue(signal: Signal, key: WhereFieldKey): WhereValue | null {if (signal.kind === 'sharp_drop' || signal.kind === 'visibility_slipping') {return { type: 'scope', scope: 'all_prompts' };}- if (str(p, 'entity') === 'pages' && targets[0]?.id === 'site') {- return { type: 'scope', scope: 'site' };- }+ if (isSiteWide(signal)) return { type: 'scope', scope: 'site' };if (entity === 'topics') return { type: 'scope', scope: 'topic' };if (entity === 'platforms' ||@@ -787,6 +844,29 @@ function fieldValue(signal: Signal, key: WhereFieldKey): WhereValue | null {const sources = winningSourcesOf(p.winningSources);return sources.length ? { type: 'sources', items: sources } : null;}+ case 'aiReferrals': {+ const items = pageReferrals(p.referrals);+ return items.length+ ? {+ type: 'referrals',+ items,+ days: typeof p.referralDays === 'number' ? p.referralDays : 14,+ }+ : null;+ }+ case 'citablePrompts': {+ // Read with the referrals: none recorded means not looked at, not none.+ if (!Array.isArray(p.citablePrompts)) return null;+ const items = (p.citablePrompts as Record<string, unknown>[])+ .filter((q) => typeof q?.text === 'string')+ .map((q) => ({ id: typeof q.id === 'string' ? q.id : null, text: q.text as string }));+ const recorded = p.citablePromptsTotal;+ return {+ type: 'prompts',+ items,+ total: typeof recorded === 'number' ? recorded : items.length,+ };+ }case 'issue': {const labels = [...new Set(pageIssues(targets).map((i) => i.label))];return labels.length ? { type: 'list', items: labels, total: labels.length } : null;@@ -832,6 +912,13 @@ function namedPlaces(signal: Signal): { platforms: boolean; locations: boolean }};}+/** A finding about the whole site rather than some of its pages. */+function isSiteWide(signal: Signal): boolean {+ const p = signal.payload ?? {};+ const targets = Array.isArray(p.targets) ? (p.targets as Target[]) : [];+ return str(p, 'entity') === 'pages' && targets[0]?.id === 'site';+}+/** The Where block: the spec's fields for this signal, each with its value or none. */export function signalWhereFields(signal: Signal): WhereField[] {const layout =@@ -841,7 +928,9 @@ export function signalWhereFields(signal: Signal): WhereField[] {? CRAWLER_LAYOUT: CITATION_LOSS.includes(signal.kind)? CITATION_LOSS_LAYOUT- : LAYOUT[signal.category];+ : signal.category === 'traffic' && isSiteWide(signal)+ ? SITE_TRAFFIC_LAYOUT+ : LAYOUT[signal.category];const named = namedPlaces(signal);// A mention's position, sentiment and quote are given per prompt when the// evidence is recorded; asked for on their own only when it is not.@@ -966,6 +1055,22 @@ function apiValue(value: WhereValue): unknown {}));case 'crawlers':return value.agents;+ case 'referrals':+ return {+ days: value.days,+ items: value.items.map((item) => ({+ page: item.page,+ source: item.source,+ sessions: item.sessions,+ before: item.before,+ platforms: item.platforms.map((p) => ({+ platform: p.platform,+ name: getPlatformName(p.platform),+ sessions: p.sessions,+ before: p.before,+ })),+ })),+ };case 'sources':return value.items.map((source) => ({domain: source.domain,diff --git a/web/src/lib/traffic-platforms.ts b/web/src/lib/traffic-platforms.tsnew file mode 100644index 000000000..a0513009a--- /dev/null+++ b/web/src/lib/traffic-platforms.ts@@ -0,0 +1,28 @@+/**+ * AI referrers by the name their platform goes by. Keys are what the+ * tracking snippet (`server/src/public/t.js`) and the Analytics sync+ * (`server/src/lib/ga-sources.js`) store; `unknown` is kept only for+ * historical rows that predate #288 (null source_platform).+ */+const PLATFORM_NAMES: Record<string, string> = {+ 'chatgpt.com': 'ChatGPT',+ 'chat.openai.com': 'ChatGPT',+ 'search.chatgpt.com': 'ChatGPT',+ 'perplexity.ai': 'Perplexity',+ 'claude.ai': 'Claude',+ 'gemini.google.com': 'Gemini',+ 'copilot.microsoft.com': 'Copilot',+ 'you.com': 'You.com',+ 'phind.com': 'Phind',+ 'meta.ai': 'Meta AI',+ 'poe.com': 'Poe',+ 'labs.google': 'Google Labs',+ 'bing.com': 'Bing',+ 'grok.com': 'Grok',+ 'deepseek.com': 'DeepSeek',+ unknown: 'Unknown',+};++export function getPlatformName(platform: string): string {+ return PLATFORM_NAMES[platform] ?? platform;+}