Skip to content

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.

feat(analytics): say why a valuable page gets no AI traffic (#787)

Gökhan Geyikf88548c3b45a
diff --git a/server/src/lib/page-opportunities.js b/server/src/lib/page-opportunities.js
index be1820691..f64a1f628 100644
--- a/server/src/lib/page-opportunities.js
+++ b/server/src/lib/page-opportunities.js
@@ -1,10 +1,11 @@
/**
* Page opportunity detection (#719, Phase 5).
*
- * Answers one question per brand: which pages carry commercial weight, and
- * get nothing from AI engines. Both halves come from tables the GA sync
- * (#704) already aggregates, so detection is arithmetic over a few hundred
- * rows — no model, no page fetching, and nothing that scans result citations.
+ * Answers two questions per brand: which pages carry commercial weight and
+ * get nothing from AI engines, and — for each of those — why. The figures
+ * come from `ga_page_ai_visibility`, which aggregates the tables the GA sync
+ * (#704) writes and joins the brand's own citations and prompt targeting to
+ * them. No model runs in this path and no page is fetched.
*
* The ranking signal is chosen from what the property actually reports rather
* than assumed. A shop with ecommerce ranks on money; a site with no
@@ -12,9 +13,16 @@
* every finding, because a surface that calls an engagement rank "your most
* valuable page" is making a true statement about the wrong thing.
*
- * Deliberately not here: LLM enrichment, clustering, and the full opportunity
- * lifecycle. Those need more volume than this produces today, and a finding
- * nobody can verify is worse than one that is merely narrow.
+ * Ranking and the exclusion list stay here rather than moving into SQL with
+ * the aggregation: `isExcludedPath` is shared with the prompt suggestion
+ * generator (#705), and a second copy of it in the RPC would drift from this
+ * one the first time either is extended. The cost is that every page travels,
+ * which is what the paginated read below exists to survive.
+ *
+ * Deliberately not here: LLM enrichment, clustering, and the acted-on half of
+ * the opportunity lifecycle. Those need more volume than one connected
+ * property produces, and a finding nobody can verify is worse than one that
+ * is merely narrow.
*/
import supabaseAdmin from '../config/supabase.js';
@@ -35,6 +43,28 @@ const MIN_SESSIONS = 10;
/** How far up its own site a page must rank before it is worth raising. */
const MIN_PERCENTILE = 70;
+/**
+ * PostgREST returns at most 1000 rows per request whatever range is asked
+ * for, so the read is paged rather than trusted to come back whole.
+ *
+ * This is the #427/#450/#464 trap, and detection was standing on it: it read
+ * 28 days of `ga_page_stats` un-paginated, and ga-sync keeps up to 5000 pages
+ * per day. Truncation there does not merely lose findings — the AI-traffic
+ * half truncates too, and a page missing from that lookup is raised as
+ * receiving no AI traffic when it received some. Today's only property
+ * produces 743 rows and fits under the cap, which is the only reason nothing
+ * has gone wrong yet.
+ */
+const READ_PAGE_SIZE = 1000;
+
+/**
+ * Stop after this many pages of rows. A site large enough to reach it has
+ * something wrong with it, and the run is logged rather than left to walk a
+ * table for minutes — but it is logged, not silently trimmed, because a
+ * ranking computed over part of a site is exactly the failure above.
+ */
+const MAX_READ_PAGES = 50;
+
/**
* Ranking signals in order of how directly they express commercial value.
* The first one the property actually reports wins.
@@ -66,6 +96,31 @@ function signalValue(page, signalName) {
return signal ? (signal.of(page) ?? 0) : 0;
}
+/**
+ * Why a page that earns gets nothing from AI engines.
+ *
+ * Three states, because they need three different actions and lumping them
+ * together points two thirds of the customers at the wrong fix:
+ *
+ * cited answers do cite this page and it still earns no visit
+ * targeted_not_cited a prompt points here and no answer cites it
+ * not_targeted nothing we track points here at all
+ *
+ * The last one is a coverage gap, and on a large site it is the common case:
+ * URL-level AI visibility exists for a three-digit number of pages, so
+ * "invisible" is the default state rather than a discovery. Saying which kind
+ * of invisible is the whole value of the classification.
+ *
+ * `targeted` means a prompt carries this URL as a target (#642), not that a
+ * prompt covers the page's topic — that is not something arithmetic can
+ * decide, and inventing it would put a made-up reason on a finding.
+ */
+export function classifyCitationState({ citations = 0, targetingPrompts = 0 } = {}) {
+ if (citations > 0) return 'cited';
+ if (targetingPrompts > 0) return 'targeted_not_cited';
+ return 'not_targeted';
+}
+
/**
* Rank pages within their own site, so a small B2B site and a large shop are
* judged on the same scale.
@@ -103,8 +158,12 @@ export function scorePages(pages, signalName) {
* without a floor hands every site the same number of findings; the floor
* without a percentile buries a small site's best page under a large one's
* long tail.
+ *
+ * The citation state explains a finding, it does not gate one: a page cited
+ * 104 times that still earns no AI visit is as real a problem as one nothing
+ * points to, and dropping it would hide the more surprising of the two.
*/
-export function detectPageOpportunities({ pages, aiByPage, windowDays = WINDOW_DAYS }) {
+export function detectPageOpportunities({ pages, windowDays = WINDOW_DAYS }) {
const signal = pickValueSignal(pages);
const scored = scorePages(pages, signal);
@@ -112,7 +171,7 @@ export function detectPageOpportunities({ pages, aiByPage, windowDays = WINDOW_D
.filter((page) => page.sessions >= MIN_SESSIONS)
.filter((page) => page.value > 0)
.filter((page) => page.valuePercentile >= MIN_PERCENTILE)
- .filter((page) => !(aiByPage?.get(page.landingPage)?.sessions > 0))
+ .filter((page) => !(page.aiSessions > 0))
.map((page) => ({
landing_page: page.landingPage,
kind: 'no_ai_traffic',
@@ -127,86 +186,76 @@ export function detectPageOpportunities({ pages, aiByPage, windowDays = WINDOW_D
engagement_seconds: page.engagementSeconds,
ai_sessions: 0,
ai_platforms: [],
+ citation_state: classifyCitationState(page),
+ citations: page.citations ?? 0,
+ citing_prompts: page.citingPrompts ?? 0,
+ targeting_prompts: page.targetingPrompts ?? 0,
window_days: windowDays,
}));
}
-/** Sum the per-day GA rows into one row per landing page. */
-export function aggregatePages(rows) {
- const byPage = new Map();
- for (const row of rows ?? []) {
- const page = row.landing_page ?? '';
- if (isExcludedPath(page)) continue;
- const acc = byPage.get(page) ?? {
- landingPage: page,
- sessions: 0,
- engagedSessions: 0,
- keyEvents: 0,
- transactions: 0,
- revenue: 0,
- engagementSeconds: 0,
- };
- acc.sessions += Number(row.sessions) || 0;
- acc.engagedSessions += Number(row.engaged_sessions) || 0;
- acc.keyEvents += Number(row.key_events) || 0;
- acc.transactions += Number(row.transactions) || 0;
- acc.revenue += Number(row.purchase_revenue) || 0;
- acc.engagementSeconds += Number(row.engagement_duration_seconds) || 0;
- byPage.set(page, acc);
- }
- return [...byPage.values()];
+/**
+ * RPC rows in the shape the scoring above reads.
+ *
+ * Excluded paths are dropped here rather than after ranking, so they are out
+ * of the denominator too: /checkout carries a shop's revenue, and leaving it
+ * in the population would push every real page's percentile down.
+ */
+export function mapVisibilityRows(rows) {
+ return (rows ?? [])
+ .filter((row) => !isExcludedPath(row.landing_page ?? ''))
+ .map((row) => ({
+ landingPage: row.landing_page ?? '',
+ sessions: Number(row.sessions) || 0,
+ engagedSessions: Number(row.engaged_sessions) || 0,
+ keyEvents: Number(row.key_events) || 0,
+ transactions: Number(row.transactions) || 0,
+ revenue: Number(row.revenue) || 0,
+ engagementSeconds: Number(row.engagement_seconds) || 0,
+ aiSessions: Number(row.ai_sessions) || 0,
+ aiPlatforms: row.ai_platforms ?? [],
+ citations: Number(row.citations) || 0,
+ citingPrompts: Number(row.citing_prompts) || 0,
+ targetingPrompts: Number(row.targeting_prompts) || 0,
+ }));
}
/**
- * AI-referred sessions and platforms per landing page.
+ * Every page of the brand's window, read a thousand rows at a time.
*
- * A plain lookup, with no scope filtering: the candidate set is decided when
- * pages are aggregated, and filtering here as well would only hide the answer
- * to "does this page already get AI traffic".
+ * Ordered by landing page rather than left to the planner: `range` without an
+ * order is a promise the database never made, and two requests could return
+ * the same row twice while another is never seen at all.
*/
-export function aggregateAiTraffic(rows) {
- const byPage = new Map();
- for (const row of rows ?? []) {
- const page = row.landing_page ?? '';
- if (!page) continue;
- const acc = byPage.get(page) ?? { sessions: 0, platforms: new Set() };
- acc.sessions += Number(row.sessions) || 0;
- if (row.platform) acc.platforms.add(row.platform);
- byPage.set(page, acc);
+async function readVisibilityRows(brandId, since) {
+ const rows = [];
+
+ for (let page = 0; page < MAX_READ_PAGES; page++) {
+ const from = page * READ_PAGE_SIZE;
+ const { data, error } = await supabaseAdmin
+ .rpc('ga_page_ai_visibility', { p_brand_id: brandId, p_since: since })
+ .order('landing_page', { ascending: true })
+ .range(from, from + READ_PAGE_SIZE - 1);
+
+ if (error) throw new Error(error.message);
+ rows.push(...(data ?? []));
+ if (!data || data.length < READ_PAGE_SIZE) return rows;
}
- return new Map(
- [...byPage].map(([page, acc]) => [
- page,
- { sessions: acc.sessions, platforms: [...acc.platforms] },
- ]),
+
+ logger.warn(
+ { brandId, read: rows.length },
+ '[page-opportunities] page limit reached; ranking covers only what was read',
);
+ return rows;
}
async function detectForBrand(brandId) {
const since = new Date(Date.now() - WINDOW_DAYS * 86_400_000).toISOString().slice(0, 10);
- const [{ data: pageRows, error: pageErr }, { data: aiRows, error: aiErr }] = await Promise.all([
- supabaseAdmin
- .from('ga_page_stats')
- .select(
- 'landing_page, sessions, engaged_sessions, key_events, transactions, purchase_revenue, engagement_duration_seconds',
- )
- .eq('brand_id', brandId)
- .gte('date', since),
- supabaseAdmin
- .from('ga_ai_traffic_stats')
- .select('landing_page, platform, sessions')
- .eq('brand_id', brandId)
- .gte('date', since),
- ]);
- if (pageErr) throw new Error(pageErr.message);
- if (aiErr) throw new Error(aiErr.message);
- if (!pageRows?.length) return { found: 0, resolved: 0 };
+ const pages = mapVisibilityRows(await readVisibilityRows(brandId, since));
+ if (!pages.length) return { found: 0, resolved: 0 };
- const findings = detectPageOpportunities({
- pages: aggregatePages(pageRows),
- aiByPage: aggregateAiTraffic(aiRows),
- });
+ const findings = detectPageOpportunities({ pages });
const now = new Date().toISOString();
if (findings.length > 0) {
@@ -237,7 +286,11 @@ async function detectForBrand(brandId) {
.lt('last_detected_at', now);
if (resolveErr) throw new Error(resolveErr.message);
- return { found: findings.length, signal: findings[0]?.value_signal ?? null };
+ return {
+ found: findings.length,
+ signal: findings[0]?.value_signal ?? null,
+ cited: findings.filter((f) => f.citation_state === 'cited').length,
+ };
}
/**
diff --git a/server/src/lib/page-opportunities.test.js b/server/src/lib/page-opportunities.test.js
index 6a078abcb..ca75189ec 100644
--- a/server/src/lib/page-opportunities.test.js
+++ b/server/src/lib/page-opportunities.test.js
@@ -5,9 +5,9 @@ import { describe, expect, it, vi } from 'vitest';
vi.mock('../config/supabase.js', () => ({ default: {} }));
import {
- aggregateAiTraffic,
- aggregatePages,
+ classifyCitationState,
detectPageOpportunities,
+ mapVisibilityRows,
pickValueSignal,
scorePages,
} from './page-opportunities.js';
@@ -31,6 +31,11 @@ const page = (over = {}) => ({
transactions: 0,
revenue: 0,
engagementSeconds: 1000,
+ aiSessions: 0,
+ aiPlatforms: [],
+ citations: 0,
+ citingPrompts: 0,
+ targetingPrompts: 0,
...over,
});
@@ -139,7 +144,7 @@ describe('detectPageOpportunities', () => {
);
it('raises a valuable page with no AI traffic', () => {
- const found = detectPageOpportunities({ pages: many(), aiByPage: new Map() });
+ const found = detectPageOpportunities({ pages: many() });
expect(found.length).toBeGreaterThan(0);
expect(found[0].kind).toBe('no_ai_traffic');
expect(found[0].value_signal).toBe('revenue');
@@ -147,19 +152,18 @@ describe('detectPageOpportunities', () => {
it('does not raise a page AI engines already send traffic to', () => {
const pages = many();
- const top = pages[pages.length - 1].landingPage;
- const found = detectPageOpportunities({
- pages,
- aiByPage: new Map([[top, { sessions: 4, platforms: ['chatgpt.com'] }]]),
- });
- expect(found.map((f) => f.landing_page)).not.toContain(top);
+ const top = pages[pages.length - 1];
+ top.aiSessions = 4;
+ top.aiPlatforms = ['chatgpt.com'];
+ const found = detectPageOpportunities({ pages });
+ expect(found.map((f) => f.landing_page)).not.toContain(top.landingPage);
});
it('ignores a page with too little traffic to argue from', () => {
// The absolute floor. A page can rank first on its site and still be one
// visit; raising it would be a finding about nothing.
const pages = [page({ landingPage: '/tiny', revenue: 999, sessions: 2 })];
- expect(detectPageOpportunities({ pages, aiByPage: new Map() })).toEqual([]);
+ expect(detectPageOpportunities({ pages })).toEqual([]);
});
it('ignores a page with no value on the chosen signal', () => {
@@ -167,7 +171,7 @@ describe('detectPageOpportunities', () => {
...many(),
page({ landingPage: '/zero', revenue: 0, sessions: 5000, engagementSeconds: 99999 }),
];
- const found = detectPageOpportunities({ pages, aiByPage: new Map() });
+ const found = detectPageOpportunities({ pages });
expect(found.map((f) => f.landing_page)).not.toContain('/zero');
});
@@ -182,8 +186,8 @@ describe('detectPageOpportunities', () => {
page({ landingPage: `/q${i}`, revenue: 1, sessions: 2 }),
),
];
- const busyFound = detectPageOpportunities({ pages: busy, aiByPage: new Map() });
- const quietFound = detectPageOpportunities({ pages: quiet, aiByPage: new Map() });
+ const busyFound = detectPageOpportunities({ pages: busy });
+ const quietFound = detectPageOpportunities({ pages: quiet });
expect(quietFound.length).toBeLessThan(busyFound.length);
expect(quietFound).toHaveLength(1);
});
@@ -194,7 +198,7 @@ describe('detectPageOpportunities', () => {
const pages = Array.from({ length: 10 }, (_, i) =>
page({ landingPage: `/e${i}`, engagementSeconds: (i + 1) * 100 }),
);
- const found = detectPageOpportunities({ pages, aiByPage: new Map() });
+ const found = detectPageOpportunities({ pages });
expect(found.length).toBeGreaterThan(0);
expect(found.every((f) => f.value_signal === 'engagement')).toBe(true);
expect(found.every((f) => f.revenue === 0)).toBe(true);
@@ -213,46 +217,130 @@ describe('detectPageOpportunities', () => {
});
it('returns nothing for a brand with no pages', () => {
- expect(detectPageOpportunities({ pages: [], aiByPage: new Map() })).toEqual([]);
+ expect(detectPageOpportunities({ pages: [] })).toEqual([]);
});
});
-describe('aggregatePages', () => {
- it('sums a page across its daily rows', () => {
- const rows = [
- { landing_page: '/a', sessions: 3, purchase_revenue: 10.5, key_events: 1 },
- { landing_page: '/a', sessions: 4, purchase_revenue: 4.5, key_events: 0 },
- ];
- const [a] = aggregatePages(rows);
+describe('classifyCitationState', () => {
+ it('calls a page cited when answers cite it, whatever else is true', () => {
+ // The surprising finding, and the one the surface got wrong: a page can
+ // be cited 104 times in a window and still earn no AI visit. That is a
+ // click-through problem, and telling the customer nothing points at the
+ // page would send them to fix the wrong thing.
+ expect(classifyCitationState({ citations: 104, targetingPrompts: 0 })).toBe('cited');
+ expect(classifyCitationState({ citations: 1, targetingPrompts: 3 })).toBe('cited');
+ });
+
+ it('separates a page a prompt points at from one nothing points at', () => {
+ expect(classifyCitationState({ citations: 0, targetingPrompts: 2 })).toBe('targeted_not_cited');
+ expect(classifyCitationState({ citations: 0, targetingPrompts: 0 })).toBe('not_targeted');
+ });
+
+ it('defaults to not_targeted rather than throwing on a page with no counts', () => {
+ expect(classifyCitationState({})).toBe('not_targeted');
+ expect(classifyCitationState()).toBe('not_targeted');
+ });
+});
+
+describe('detectPageOpportunities citation state', () => {
+ const ten = (over) =>
+ Array.from({ length: 10 }, (_, i) =>
+ page({ landingPage: `/p${i}`, revenue: i + 1, sessions: 100, ...over }),
+ );
+
+ it('records the state and the counts it was decided from', () => {
+ const pages = ten();
+ pages[9].citations = 104;
+ pages[9].citingPrompts = 1;
+ const found = detectPageOpportunities({ pages });
+ const top = found[0];
+ expect(top.citation_state).toBe('cited');
+ expect(top.citations).toBe(104);
+ expect(top.citing_prompts).toBe(1);
+ });
+
+ it('still raises a cited page — the state explains a finding, it does not gate one', () => {
+ const pages = ten({ citations: 5, citingPrompts: 1 });
+ expect(detectPageOpportunities({ pages }).length).toBeGreaterThan(0);
+ });
+
+ it('classifies every finding, so no surface has to guess', () => {
+ const pages = ten();
+ pages[9].citations = 3;
+ pages[8].targetingPrompts = 2;
+ const states = detectPageOpportunities({ pages }).map((f) => f.citation_state);
+ expect(states).toContain('cited');
+ expect(states).toContain('targeted_not_cited');
+ expect(states).toContain('not_targeted');
+ expect(states.every(Boolean)).toBe(true);
+ });
+});
+
+describe('mapVisibilityRows', () => {
+ const row = (over = {}) => ({
+ landing_page: '/a',
+ sessions: 10,
+ engaged_sessions: 5,
+ key_events: 0,
+ transactions: 0,
+ revenue: 0,
+ engagement_seconds: 100,
+ ai_sessions: 0,
+ ai_platforms: [],
+ citations: 0,
+ citing_prompts: 0,
+ targeting_prompts: 0,
+ ...over,
+ });
+
+ it('reads the RPC row into the shape scoring expects', () => {
+ const [a] = mapVisibilityRows([
+ row({ sessions: 7, revenue: 15, citations: 2, citing_prompts: 1, targeting_prompts: 4 }),
+ ]);
+ expect(a.landingPage).toBe('/a');
expect(a.sessions).toBe(7);
expect(a.revenue).toBe(15);
- expect(a.keyEvents).toBe(1);
+ expect(a.citations).toBe(2);
+ expect(a.citingPrompts).toBe(1);
+ expect(a.targetingPrompts).toBe(4);
+ });
+
+ it('reads a count that arrived as a string, which bigint columns do', () => {
+ const [a] = mapVisibilityRows([row({ sessions: '4200', citations: '104' })]);
+ expect(a.sessions).toBe(4200);
+ expect(a.citations).toBe(104);
+ });
+
+ it('drops excluded paths before ranking, so they are out of the denominator', () => {
+ // /checkout carries a shop's revenue. Leaving it in the population would
+ // push every real page's percentile down, which is a different answer,
+ // not a cosmetic one.
+ const rows = [row({ landing_page: '/checkout' }), row({ landing_page: '/pricing' })];
+ expect(mapVisibilityRows(rows).map((p) => p.landingPage)).toEqual(['/pricing']);
});
it('drops rows GA could not attribute to a page', () => {
- expect(aggregatePages([{ landing_page: '', sessions: 9 }])).toEqual([]);
+ expect(mapVisibilityRows([row({ landing_page: '(not set)' })])).toEqual([]);
+ });
+
+ it('keeps the path exactly as Analytics spelled it', () => {
+ // The RPC matches on a lowercased path and returns the observed one,
+ // because folding the case here would turn /blog/YmVzdC10b2 into a URL
+ // that 404s — and the finding is shown to a customer who will click it.
+ const [a] = mapVisibilityRows([row({ landing_page: '/blog/YmVzdC10b2' })]);
+ expect(a.landingPage).toBe('/blog/YmVzdC10b2');
});
it('treats missing metrics as zero rather than NaN', () => {
- const [a] = aggregatePages([{ landing_page: '/a' }]);
+ const [a] = mapVisibilityRows([{ landing_page: '/a' }]);
expect(a.sessions).toBe(0);
expect(a.revenue).toBe(0);
- });
-});
-
-describe('aggregateAiTraffic', () => {
- it('sums AI sessions and collects the platforms per page', () => {
- const map = aggregateAiTraffic([
- { landing_page: '/a', platform: 'chatgpt.com', sessions: 3 },
- { landing_page: '/a', platform: 'claude.ai', sessions: 2 },
- ]);
- expect(map.get('/a').sessions).toBe(5);
- expect(map.get('/a').platforms.sort()).toEqual(['chatgpt.com', 'claude.ai']);
+ expect(a.citations).toBe(0);
+ expect(a.aiPlatforms).toEqual([]);
});
- it('counts sessions from an unclassified source, which still arrived', () => {
- const map = aggregateAiTraffic([{ landing_page: '/a', platform: null, sessions: 4 }]);
- expect(map.get('/a').sessions).toBe(4);
- expect(map.get('/a').platforms).toEqual([]);
+ it('handles no rows at all', () => {
+ expect(mapVisibilityRows(null)).toEqual([]);
+ expect(mapVisibilityRows([])).toEqual([]);
});
});
diff --git a/supabase/migrations/00075_page_opportunity_citation_state.sql b/supabase/migrations/00075_page_opportunity_citation_state.sql
new file mode 100644
index 000000000..cccb33079
--- /dev/null
+++ b/supabase/migrations/00075_page_opportunity_citation_state.sql
@@ -0,0 +1,272 @@
+-- Why a valuable page gets nothing from AI engines (#719).
+--
+-- Detection (#724) answers "which pages carry weight and receive no AI
+-- referral". It cannot answer why, and the three reasons need different
+-- actions:
+--
+-- cited answers do cite this page, and it still earns no
+-- visit — a click-through problem, not a coverage one
+-- targeted_not_cited a prompt we track points at this page and no answer
+-- cites it — a genuine visibility loss
+-- not_targeted nothing we track points here at all — a coverage gap,
+-- and the most common finding on a large site
+--
+-- Measured before building, on the only property connected today: of 16 open
+-- findings, 5 are cited — one of them 104 times in 28 days. The surface calls
+-- all 16 "pages AI engines aren't sending traffic to", which is true and, for
+-- those 5, points at the wrong fix.
+--
+-- Two things this migration also repairs. Detection read 28 days of
+-- ga_page_stats with an un-paginated select, and PostgREST caps that at 1000
+-- rows (the #427/#450/#464 trap). ga-sync keeps up to PAGE_DAILY_LIMIT = 5000
+-- pages per day, so a property with more than ~36 pages taking traffic on an
+-- average day overflows it. Today's single property produces 743 rows and
+-- fits, which is why nothing has gone wrong yet. The failure is worse than
+-- missing findings: the AI-traffic read truncates the same way, so a page
+-- that did receive AI traffic can fall out of the lookup and be raised as a
+-- finding that is simply false. Aggregating here collapses page × day into
+-- one row per page, and the caller pages through what is left.
+
+-- ─── Percent-decoding that cannot take the run down ─────────────────────────
+--
+-- 12.7% of the cited URLs on brands' own domains are percent-encoded (2,647
+-- of 20,896) — non-ASCII paths, which is most of this customer base. Matching
+-- them against GA's decoded paths without decoding would classify a page that
+-- IS cited as one nothing points to, which is the exact error this migration
+-- exists to remove.
+--
+-- The decode has to be total, not correct-on-good-input: real citation URLs
+-- in the database contain sequences that decode to invalid UTF-8 (0x80 was
+-- found by running this over them). convert_from raises on those, and an
+-- exception inside the aggregate would abort detection for the whole brand,
+-- so a URL that cannot be decoded is returned as it came instead.
+create or replace function public.url_decode_safe(p_value text)
+returns text
+language plpgsql
+immutable
+parallel safe
+set search_path to 'public'
+as $$
+begin
+ -- Nothing to do for the overwhelming majority, and this keeps the
+ -- per-character regexp off every path that has no escape in it.
+ if p_value is null or p_value not like '%\%%' then
+ return p_value;
+ end if;
+
+ return (
+ select convert_from(
+ cast(
+ e'\\x' || string_agg(
+ case
+ when length(m[1]) = 1 then encode(convert_to(m[1], 'UTF8'), 'hex')
+ else substring(m[1] from 2 for 2)
+ end,
+ ''
+ ) as bytea
+ ),
+ 'UTF8'
+ )
+ from regexp_matches(p_value, '%[0-9a-fA-F][0-9a-fA-F]|.', 'g') as m
+ );
+exception
+ when others then
+ return p_value;
+end;
+$$;
+
+comment on function public.url_decode_safe(text) is
+ 'Percent-decode a URL, returning the input unchanged when it cannot be decoded (#719). Total by design: real citation URLs contain sequences that are not valid UTF-8.';
+
+-- ─── One spelling of "the same page" ────────────────────────────────────────
+--
+-- Four sources have to agree on it: GA landing pages (a path), citation URLs
+-- (absolute, from the provider), prompt target URLs (typed by a person, so
+-- anything), and the findings already stored. Scheme and host go, the query
+-- string and fragment go, and a trailing slash goes.
+--
+-- Case is matched on but never rewritten, and the difference is not academic.
+-- Folding the path to lower case turned a real slug — /blog/YmVzdC10b2 — into
+-- /blog/ymvzdc10b2, a URL that does not exist on the site. The finding would
+-- have carried it into the surface, where a customer clicking the page they
+-- were told to fix would get a 404. The RPC below therefore groups on the
+-- lowercased path and reports the spelling Analytics actually observed:
+-- /Pricing and /pricing stay one page, and the one shown is a page that
+-- resolves.
+--
+-- Decoding happens after the query string is cut, not before: an encoded %3F
+-- inside a path is part of the path, and decoding first would let it split
+-- the URL somewhere it does not split.
+create or replace function public.normalize_page_path(p_url text)
+returns text
+language sql
+immutable
+parallel safe
+set search_path to 'public'
+as $$
+ select coalesce(
+ nullif(
+ rtrim(
+ public.url_decode_safe(
+ split_part(
+ split_part(
+ regexp_replace(coalesce(p_url, ''), '^[a-zA-Z][a-zA-Z0-9+.-]*://[^/]*', ''),
+ '?', 1
+ ),
+ '#', 1
+ )
+ ),
+ '/'
+ ),
+ ''
+ ),
+ '/'
+ );
+$$;
+
+comment on function public.normalize_page_path(text) is
+ 'A URL or path reduced to the page it names (#719): host, query, fragment and trailing slash removed, percent escapes decoded where possible. Case is preserved — callers lower() it to match, and keep this value to display.';
+
+-- ─── One row per page, with everything the engine needs to judge it ─────────
+--
+-- The citation half is written to be read through citation_urls first. The
+-- obvious direction — walk the brand's citations and keep the ones on its own
+-- domain — scans every citation the brand has (609,496 rows in 28 days for
+-- the property measured, 2.17s). Starting from the domain index and looking
+-- the citations up by url_id turns that into 445 index probes and 59ms, for
+-- the same 45 pages.
+create or replace function public.ga_page_ai_visibility(p_brand_id uuid, p_since date)
+returns table (
+ landing_page text,
+ sessions bigint,
+ engaged_sessions bigint,
+ key_events bigint,
+ transactions bigint,
+ revenue double precision,
+ engagement_seconds bigint,
+ ai_sessions bigint,
+ ai_platforms text[],
+ citations bigint,
+ citing_prompts bigint,
+ targeting_prompts bigint
+)
+language sql
+stable
+security invoker
+set search_path to 'public'
+as $$
+ with own_domains as (
+ select lower(regexp_replace(bd.domain, '^www\.', '')) as domain
+ from public.brand_domains bd
+ where bd.brand_id = p_brand_id
+ ),
+ own_urls as (
+ -- citation_urls.domain is already stored lowercased and without www, so
+ -- this is an index probe rather than a scan.
+ select cu.id, lower(public.normalize_page_path(cu.url)) as page_key
+ from public.citation_urls cu
+ where cu.domain in (select domain from own_domains)
+ ),
+ cited as (
+ select
+ ou.page_key,
+ count(*)::bigint as citations,
+ count(distinct pr.prompt_id)::bigint as citing_prompts
+ from own_urls ou
+ join public.prompt_result_citations prc
+ on prc.url_id = ou.id
+ and prc.brand_id = p_brand_id
+ and prc.created_at >= p_since
+ join public.prompt_results pr on pr.id = prc.prompt_result_id
+ group by ou.page_key
+ ),
+ targeted as (
+ -- Explicit targeting only. "A prompt covers this page's topic" is not
+ -- something SQL can decide, and guessing it would put a made-up reason on
+ -- a finding; a URL a customer attached to a prompt is a fact.
+ select
+ lower(public.normalize_page_path(ptu.url)) as page_key,
+ count(distinct ptu.prompt_id)::bigint as targeting_prompts
+ from public.prompt_target_urls ptu
+ join public.prompts p on p.id = ptu.prompt_id
+ join public.prompt_sets ps on ps.id = p.prompt_set_id
+ where ps.brand_id = p_brand_id
+ group by 1
+ ),
+ pages as (
+ select
+ lower(public.normalize_page_path(gps.landing_page)) as page_key,
+ min(public.normalize_page_path(gps.landing_page)) as landing_page,
+ sum(gps.sessions)::bigint as sessions,
+ sum(gps.engaged_sessions)::bigint as engaged_sessions,
+ sum(gps.key_events)::bigint as key_events,
+ sum(gps.transactions)::bigint as transactions,
+ sum(gps.purchase_revenue) as revenue,
+ sum(gps.engagement_duration_seconds)::bigint as engagement_seconds
+ from public.ga_page_stats gps
+ where gps.brand_id = p_brand_id
+ and gps.date >= p_since
+ group by 1
+ ),
+ ai as (
+ select
+ lower(public.normalize_page_path(gat.landing_page)) as page_key,
+ sum(gat.sessions)::bigint as ai_sessions,
+ array_remove(array_agg(distinct gat.platform), null) as ai_platforms
+ from public.ga_ai_traffic_stats gat
+ where gat.brand_id = p_brand_id
+ and gat.date >= p_since
+ and gat.landing_page <> ''
+ group by 1
+ )
+ select
+ p.landing_page,
+ p.sessions,
+ p.engaged_sessions,
+ p.key_events,
+ p.transactions,
+ p.revenue,
+ p.engagement_seconds,
+ coalesce(a.ai_sessions, 0),
+ coalesce(a.ai_platforms, '{}'::text[]),
+ coalesce(c.citations, 0),
+ coalesce(c.citing_prompts, 0),
+ coalesce(t.targeting_prompts, 0)
+ from pages p
+ left join ai a on a.page_key = p.page_key
+ left join cited c on c.page_key = p.page_key
+ left join targeted t on t.page_key = p.page_key;
+$$;
+
+revoke all on function public.ga_page_ai_visibility(uuid, date) from public;
+grant execute on function public.ga_page_ai_visibility(uuid, date) to service_role;
+
+comment on function public.ga_page_ai_visibility(uuid, date) is
+ 'Per landing page for one brand (#719): Analytics totals, AI-referred sessions, own-domain citations and prompt targeting. Feeds nightly detection; the surface reads the findings it produces, not this.';
+
+-- ─── What the finding now records ───────────────────────────────────────────
+--
+-- citation_state is nullable rather than defaulted, because a default would
+-- be a claim. The findings already stored were raised before any of this was
+-- measured, and stamping them 'not_targeted' would tell a customer nothing
+-- points at a page that five of sixteen times is cited. Null means "not
+-- classified yet"; the next nightly run fills it and the surface says nothing
+-- until then.
+alter table public.page_opportunities
+ add column if not exists citation_state text,
+ add column if not exists citations integer not null default 0,
+ add column if not exists citing_prompts integer not null default 0,
+ add column if not exists targeting_prompts integer not null default 0;
+
+alter table public.page_opportunities
+ drop constraint if exists page_opportunities_citation_state_check;
+
+alter table public.page_opportunities
+ add constraint page_opportunities_citation_state_check
+ check (
+ citation_state is null
+ or citation_state = any (array['cited'::text, 'targeted_not_cited'::text, 'not_targeted'::text])
+ );
+
+comment on column public.page_opportunities.citation_state is
+ 'Why this page gets no AI traffic (#719): cited anyway, targeted by a prompt and not cited, or not targeted at all. Null until the first run that classifies it.';
diff --git a/supabase/schema.sql b/supabase/schema.sql
index 7118ef804..c2e89be95 100644
--- a/supabase/schema.sql
+++ b/supabase/schema.sql
@@ -8656,3 +8656,279 @@ grant execute on function public.apply_prompt_locations(jsonb) to authenticated,
comment on function public.apply_prompt_locations(jsonb) is
'Bulk-writes prompt tracking locations from [{id, regions}] (#691), one statement so a batch cannot land half-applied. Security invoker: RLS decides which prompts the caller may retarget.';
+-- ─────────────────────────────────────────────────────────────────────────
+-- migrations/00075_page_opportunity_citation_state.sql
+-- ─────────────────────────────────────────────────────────────────────────
+-- Why a valuable page gets nothing from AI engines (#719).
+--
+-- Detection (#724) answers "which pages carry weight and receive no AI
+-- referral". It cannot answer why, and the three reasons need different
+-- actions:
+--
+-- cited answers do cite this page, and it still earns no
+-- visit — a click-through problem, not a coverage one
+-- targeted_not_cited a prompt we track points at this page and no answer
+-- cites it — a genuine visibility loss
+-- not_targeted nothing we track points here at all — a coverage gap,
+-- and the most common finding on a large site
+--
+-- Measured before building, on the only property connected today: of 16 open
+-- findings, 5 are cited — one of them 104 times in 28 days. The surface calls
+-- all 16 "pages AI engines aren't sending traffic to", which is true and, for
+-- those 5, points at the wrong fix.
+--
+-- Two things this migration also repairs. Detection read 28 days of
+-- ga_page_stats with an un-paginated select, and PostgREST caps that at 1000
+-- rows (the #427/#450/#464 trap). ga-sync keeps up to PAGE_DAILY_LIMIT = 5000
+-- pages per day, so a property with more than ~36 pages taking traffic on an
+-- average day overflows it. Today's single property produces 743 rows and
+-- fits, which is why nothing has gone wrong yet. The failure is worse than
+-- missing findings: the AI-traffic read truncates the same way, so a page
+-- that did receive AI traffic can fall out of the lookup and be raised as a
+-- finding that is simply false. Aggregating here collapses page × day into
+-- one row per page, and the caller pages through what is left.
+
+-- ─── Percent-decoding that cannot take the run down ─────────────────────────
+--
+-- 12.7% of the cited URLs on brands' own domains are percent-encoded (2,647
+-- of 20,896) — non-ASCII paths, which is most of this customer base. Matching
+-- them against GA's decoded paths without decoding would classify a page that
+-- IS cited as one nothing points to, which is the exact error this migration
+-- exists to remove.
+--
+-- The decode has to be total, not correct-on-good-input: real citation URLs
+-- in the database contain sequences that decode to invalid UTF-8 (0x80 was
+-- found by running this over them). convert_from raises on those, and an
+-- exception inside the aggregate would abort detection for the whole brand,
+-- so a URL that cannot be decoded is returned as it came instead.
+create or replace function public.url_decode_safe(p_value text)
+returns text
+language plpgsql
+immutable
+parallel safe
+set search_path to 'public'
+as $$
+begin
+ -- Nothing to do for the overwhelming majority, and this keeps the
+ -- per-character regexp off every path that has no escape in it.
+ if p_value is null or p_value not like '%\%%' then
+ return p_value;
+ end if;
+
+ return (
+ select convert_from(
+ cast(
+ e'\\x' || string_agg(
+ case
+ when length(m[1]) = 1 then encode(convert_to(m[1], 'UTF8'), 'hex')
+ else substring(m[1] from 2 for 2)
+ end,
+ ''
+ ) as bytea
+ ),
+ 'UTF8'
+ )
+ from regexp_matches(p_value, '%[0-9a-fA-F][0-9a-fA-F]|.', 'g') as m
+ );
+exception
+ when others then
+ return p_value;
+end;
+$$;
+
+comment on function public.url_decode_safe(text) is
+ 'Percent-decode a URL, returning the input unchanged when it cannot be decoded (#719). Total by design: real citation URLs contain sequences that are not valid UTF-8.';
+
+-- ─── One spelling of "the same page" ────────────────────────────────────────
+--
+-- Four sources have to agree on it: GA landing pages (a path), citation URLs
+-- (absolute, from the provider), prompt target URLs (typed by a person, so
+-- anything), and the findings already stored. Scheme and host go, the query
+-- string and fragment go, and a trailing slash goes.
+--
+-- Case is matched on but never rewritten, and the difference is not academic.
+-- Folding the path to lower case turned a real slug — /blog/YmVzdC10b2 — into
+-- /blog/ymvzdc10b2, a URL that does not exist on the site. The finding would
+-- have carried it into the surface, where a customer clicking the page they
+-- were told to fix would get a 404. The RPC below therefore groups on the
+-- lowercased path and reports the spelling Analytics actually observed:
+-- /Pricing and /pricing stay one page, and the one shown is a page that
+-- resolves.
+--
+-- Decoding happens after the query string is cut, not before: an encoded %3F
+-- inside a path is part of the path, and decoding first would let it split
+-- the URL somewhere it does not split.
+create or replace function public.normalize_page_path(p_url text)
+returns text
+language sql
+immutable
+parallel safe
+set search_path to 'public'
+as $$
+ select coalesce(
+ nullif(
+ rtrim(
+ public.url_decode_safe(
+ split_part(
+ split_part(
+ regexp_replace(coalesce(p_url, ''), '^[a-zA-Z][a-zA-Z0-9+.-]*://[^/]*', ''),
+ '?', 1
+ ),
+ '#', 1
+ )
+ ),
+ '/'
+ ),
+ ''
+ ),
+ '/'
+ );
+$$;
+
+comment on function public.normalize_page_path(text) is
+ 'A URL or path reduced to the page it names (#719): host, query, fragment and trailing slash removed, percent escapes decoded where possible. Case is preserved — callers lower() it to match, and keep this value to display.';
+
+-- ─── One row per page, with everything the engine needs to judge it ─────────
+--
+-- The citation half is written to be read through citation_urls first. The
+-- obvious direction — walk the brand's citations and keep the ones on its own
+-- domain — scans every citation the brand has (609,496 rows in 28 days for
+-- the property measured, 2.17s). Starting from the domain index and looking
+-- the citations up by url_id turns that into 445 index probes and 59ms, for
+-- the same 45 pages.
+create or replace function public.ga_page_ai_visibility(p_brand_id uuid, p_since date)
+returns table (
+ landing_page text,
+ sessions bigint,
+ engaged_sessions bigint,
+ key_events bigint,
+ transactions bigint,
+ revenue double precision,
+ engagement_seconds bigint,
+ ai_sessions bigint,
+ ai_platforms text[],
+ citations bigint,
+ citing_prompts bigint,
+ targeting_prompts bigint
+)
+language sql
+stable
+security invoker
+set search_path to 'public'
+as $$
+ with own_domains as (
+ select lower(regexp_replace(bd.domain, '^www\.', '')) as domain
+ from public.brand_domains bd
+ where bd.brand_id = p_brand_id
+ ),
+ own_urls as (
+ -- citation_urls.domain is already stored lowercased and without www, so
+ -- this is an index probe rather than a scan.
+ select cu.id, lower(public.normalize_page_path(cu.url)) as page_key
+ from public.citation_urls cu
+ where cu.domain in (select domain from own_domains)
+ ),
+ cited as (
+ select
+ ou.page_key,
+ count(*)::bigint as citations,
+ count(distinct pr.prompt_id)::bigint as citing_prompts
+ from own_urls ou
+ join public.prompt_result_citations prc
+ on prc.url_id = ou.id
+ and prc.brand_id = p_brand_id
+ and prc.created_at >= p_since
+ join public.prompt_results pr on pr.id = prc.prompt_result_id
+ group by ou.page_key
+ ),
+ targeted as (
+ -- Explicit targeting only. "A prompt covers this page's topic" is not
+ -- something SQL can decide, and guessing it would put a made-up reason on
+ -- a finding; a URL a customer attached to a prompt is a fact.
+ select
+ lower(public.normalize_page_path(ptu.url)) as page_key,
+ count(distinct ptu.prompt_id)::bigint as targeting_prompts
+ from public.prompt_target_urls ptu
+ join public.prompts p on p.id = ptu.prompt_id
+ join public.prompt_sets ps on ps.id = p.prompt_set_id
+ where ps.brand_id = p_brand_id
+ group by 1
+ ),
+ pages as (
+ select
+ lower(public.normalize_page_path(gps.landing_page)) as page_key,
+ min(public.normalize_page_path(gps.landing_page)) as landing_page,
+ sum(gps.sessions)::bigint as sessions,
+ sum(gps.engaged_sessions)::bigint as engaged_sessions,
+ sum(gps.key_events)::bigint as key_events,
+ sum(gps.transactions)::bigint as transactions,
+ sum(gps.purchase_revenue) as revenue,
+ sum(gps.engagement_duration_seconds)::bigint as engagement_seconds
+ from public.ga_page_stats gps
+ where gps.brand_id = p_brand_id
+ and gps.date >= p_since
+ group by 1
+ ),
+ ai as (
+ select
+ lower(public.normalize_page_path(gat.landing_page)) as page_key,
+ sum(gat.sessions)::bigint as ai_sessions,
+ array_remove(array_agg(distinct gat.platform), null) as ai_platforms
+ from public.ga_ai_traffic_stats gat
+ where gat.brand_id = p_brand_id
+ and gat.date >= p_since
+ and gat.landing_page <> ''
+ group by 1
+ )
+ select
+ p.landing_page,
+ p.sessions,
+ p.engaged_sessions,
+ p.key_events,
+ p.transactions,
+ p.revenue,
+ p.engagement_seconds,
+ coalesce(a.ai_sessions, 0),
+ coalesce(a.ai_platforms, '{}'::text[]),
+ coalesce(c.citations, 0),
+ coalesce(c.citing_prompts, 0),
+ coalesce(t.targeting_prompts, 0)
+ from pages p
+ left join ai a on a.page_key = p.page_key
+ left join cited c on c.page_key = p.page_key
+ left join targeted t on t.page_key = p.page_key;
+$$;
+
+revoke all on function public.ga_page_ai_visibility(uuid, date) from public;
+grant execute on function public.ga_page_ai_visibility(uuid, date) to service_role;
+
+comment on function public.ga_page_ai_visibility(uuid, date) is
+ 'Per landing page for one brand (#719): Analytics totals, AI-referred sessions, own-domain citations and prompt targeting. Feeds nightly detection; the surface reads the findings it produces, not this.';
+
+-- ─── What the finding now records ───────────────────────────────────────────
+--
+-- citation_state is nullable rather than defaulted, because a default would
+-- be a claim. The findings already stored were raised before any of this was
+-- measured, and stamping them 'not_targeted' would tell a customer nothing
+-- points at a page that five of sixteen times is cited. Null means "not
+-- classified yet"; the next nightly run fills it and the surface says nothing
+-- until then.
+alter table public.page_opportunities
+ add column if not exists citation_state text,
+ add column if not exists citations integer not null default 0,
+ add column if not exists citing_prompts integer not null default 0,
+ add column if not exists targeting_prompts integer not null default 0;
+
+alter table public.page_opportunities
+ drop constraint if exists page_opportunities_citation_state_check;
+
+alter table public.page_opportunities
+ add constraint page_opportunities_citation_state_check
+ check (
+ citation_state is null
+ or citation_state = any (array['cited'::text, 'targeted_not_cited'::text, 'not_targeted'::text])
+ );
+
+comment on column public.page_opportunities.citation_state is
+ 'Why this page gets no AI traffic (#719): cited anyway, targeted by a prompt and not cited, or not targeted at all. Null until the first run that classifies it.';
+
diff --git a/web/src/app/[locale]/(dashboard)/dashboard/traffic/_opportunities-card.tsx b/web/src/app/[locale]/(dashboard)/dashboard/traffic/_opportunities-card.tsx
index b0f704842..a5d2c4689 100644
--- a/web/src/app/[locale]/(dashboard)/dashboard/traffic/_opportunities-card.tsx
+++ b/web/src/app/[locale]/(dashboard)/dashboard/traffic/_opportunities-card.tsx
@@ -62,6 +62,36 @@ const SIGNAL_COPY: Record<
},
};
+/**
+ * Why a page that earns gets nothing from AI engines.
+ *
+ * The three states need three different actions, and the card exists to say
+ * which. A page cited a hundred times that still earns no visit is a
+ * click-through problem; a page nothing points at is a coverage gap; a page a
+ * prompt targets and no answer cites is a visibility loss. Presenting them
+ * identically — which this card did until the engine could tell them apart —
+ * sends two customers in three to fix the wrong thing.
+ */
+const CITATION_COPY: Record<
+ Exclude<PageOpportunity['citationState'], null>,
+ { label: string; detail: (row: PageOpportunity) => string }
+> = {
+ cited: {
+ label: 'Cited',
+ detail: (row) =>
+ `${row.citations.toLocaleString()} citation${row.citations === 1 ? '' : 's'} in answers`,
+ },
+ targeted_not_cited: {
+ label: 'Not cited',
+ detail: (row) =>
+ `${row.targetingPrompts} prompt${row.targetingPrompts === 1 ? '' : 's'} target this page`,
+ },
+ not_targeted: {
+ label: 'No prompt',
+ detail: () => 'nothing you track points here',
+ },
+};
+
function signalValue(row: PageOpportunity): string {
if (row.valueSignal === 'revenue') return row.revenue.toLocaleString();
if (row.valueSignal === 'transactions') return row.transactions.toLocaleString();
@@ -115,7 +145,9 @@ export function PageOpportunitiesCard({ brandId }: { brandId: string }) {
</Badge>
</div>
<p className="text-xs text-muted-foreground">
- {copy.explain} None of these received a visit from an AI assistant in the window.
+ {copy.explain} None of these received a visit from an AI assistant in the window, and{' '}
+ <span className="font-medium">AI visibility</span> says why: whether answers already cite
+ the page, whether a prompt you track points at it, or whether nothing does.
</p>
</CardHeader>
<CardContent className="p-0">
@@ -123,6 +155,7 @@ export function PageOpportunitiesCard({ brandId }: { brandId: string }) {
<TableHeader>
<TableRow>
<TableHead className="pl-6">Page</TableHead>
+ <TableHead>AI visibility</TableHead>
<TableHead className="text-right">Sessions</TableHead>
<TableHead className="text-right">{copy.column}</TableHead>
<TableHead className="text-right pr-6">Rank {copy.label}</TableHead>
@@ -136,6 +169,26 @@ export function PageOpportunitiesCard({ brandId }: { brandId: string }) {
{row.landingPage}
</span>
</TableCell>
+ <TableCell>
+ {/* Null on findings raised before the classification landed:
+ the next nightly run fills them, and saying nothing beats
+ guessing which of the three they are. */}
+ {row.citationState ? (
+ <div className="space-y-0.5">
+ <Badge
+ variant={row.citationState === 'cited' ? 'secondary' : 'outline'}
+ className="text-xs"
+ >
+ {CITATION_COPY[row.citationState].label}
+ </Badge>
+ <div className="text-[10px] text-muted-foreground">
+ {CITATION_COPY[row.citationState].detail(row)}
+ </div>
+ </div>
+ ) : (
+ <span className="text-xs text-muted-foreground">&mdash;</span>
+ )}
+ </TableCell>
<TableCell className="text-right tabular-nums text-sm">
{row.sessions.toLocaleString()}
</TableCell>
diff --git a/web/src/lib/actions/traffic.ts b/web/src/lib/actions/traffic.ts
index dc3b19f9b..3ee28ad30 100644
--- a/web/src/lib/actions/traffic.ts
+++ b/web/src/lib/actions/traffic.ts
@@ -360,6 +360,15 @@ export interface PageOpportunity {
engagementSeconds: number;
windowDays: number;
firstDetectedAt: string;
+ /**
+ * Why this page gets nothing from AI engines — cited anyway, targeted by a
+ * prompt and not cited, or not targeted at all. Null on findings raised
+ * before the classification existed; the next nightly run fills them.
+ */
+ citationState: 'cited' | 'targeted_not_cited' | 'not_targeted' | null;
+ citations: number;
+ citingPrompts: number;
+ targetingPrompts: number;
}
export async function getPageOpportunities(
@@ -370,7 +379,7 @@ export async function getPageOpportunities(
const { data, error } = await supabase
.from('page_opportunities')
.select(
- 'landing_page, value_signal, value_percentile, value_rank, sessions, engaged_sessions, key_events, transactions, revenue, engagement_seconds, window_days, first_detected_at',
+ 'landing_page, value_signal, value_percentile, value_rank, sessions, engaged_sessions, key_events, transactions, revenue, engagement_seconds, window_days, first_detected_at, citation_state, citations, citing_prompts, targeting_prompts',
)
.eq('brand_id', brandId)
.is('resolved_at', null)
@@ -392,5 +401,9 @@ export async function getPageOpportunities(
engagementSeconds: Number(row.engagement_seconds) || 0,
windowDays: Number(row.window_days) || 0,
firstDetectedAt: row.first_detected_at as string,
+ citationState: row.citation_state as PageOpportunity['citationState'],
+ citations: Number(row.citations) || 0,
+ citingPrompts: Number(row.citing_prompts) || 0,
+ targetingPrompts: Number(row.targeting_prompts) || 0,
}));
}
diff --git a/web/src/types/supabase.ts b/web/src/types/supabase.ts
index 42e810930..ab7d1df23 100644
--- a/web/src/types/supabase.ts
+++ b/web/src/types/supabase.ts
@@ -1314,6 +1314,9 @@ export type Database = {
ai_platforms: string[]
ai_sessions: number
brand_id: string
+ citation_state: string | null
+ citations: number
+ citing_prompts: number
engaged_sessions: number
engagement_seconds: number
first_detected_at: string
@@ -1325,6 +1328,7 @@ export type Database = {
resolved_at: string | null
revenue: number
sessions: number
+ targeting_prompts: number
transactions: number
value_percentile: number
value_rank: number
@@ -1335,6 +1339,9 @@ export type Database = {
ai_platforms?: string[]
ai_sessions?: number
brand_id: string
+ citation_state?: string | null
+ citations?: number
+ citing_prompts?: number
engaged_sessions?: number
engagement_seconds?: number
first_detected_at?: string
@@ -1346,6 +1353,7 @@ export type Database = {
resolved_at?: string | null
revenue?: number
sessions?: number
+ targeting_prompts?: number
transactions?: number
value_percentile: number
value_rank: number
@@ -1356,6 +1364,9 @@ export type Database = {
ai_platforms?: string[]
ai_sessions?: number
brand_id?: string
+ citation_state?: string | null
+ citations?: number
+ citing_prompts?: number
engaged_sessions?: number
engagement_seconds?: number
first_detected_at?: string
@@ -1367,6 +1378,7 @@ export type Database = {
resolved_at?: string | null
revenue?: number
sessions?: number
+ targeting_prompts?: number
transactions?: number
value_percentile?: number
value_rank?: number
@@ -2651,6 +2663,23 @@ export type Database = {
isSetofReturn: true
}
}
+ ga_page_ai_visibility: {
+ Args: { p_brand_id: string; p_since: string }
+ Returns: {
+ ai_platforms: string[]
+ ai_sessions: number
+ citations: number
+ citing_prompts: number
+ engaged_sessions: number
+ engagement_seconds: number
+ key_events: number
+ landing_page: string
+ revenue: number
+ sessions: number
+ targeting_prompts: number
+ transactions: number
+ }[]
+ }
gsc_candidate_queries: {
Args: { p_brand_id: string; p_min_impressions: number; p_since: string }
Returns: {
@@ -2691,6 +2720,10 @@ export type Database = {
regions: string[]
}[]
}
+ normalize_page_path: {
+ Args: { p_url: string }
+ Returns: string
+ }
org_prompt_location_usage: {
Args: { p_organization_id: string }
Returns: {
@@ -2887,6 +2920,10 @@ export type Database = {
}
Returns: number
}
+ url_decode_safe: {
+ Args: { p_value: string }
+ Returns: string
+ }
visibility_rate_trend: {
Args: {
p_brand_id: string