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(prompts): suggest prompts from the pages analytics says are worth it (#720)
Gökhan Geyik7c528f4145ab
diff --git a/server/src/lib/ga-suggestions.js b/server/src/lib/ga-suggestions.jsnew file mode 100644index 000000000..a367b2115--- /dev/null+++ b/server/src/lib/ga-suggestions.js@@ -0,0 +1,348 @@+/**+ * Analytics-fed suggestion candidates (#705).+ *+ * Search Console answers "what are people typing into a search box". The+ * traffic pipeline (#704) answers two questions it structurally cannot:+ *+ * revenue_blind_spot pages that earn money and no tracked prompt would surface+ * ai_momentum pages an AI engine already sends visitors to+ *+ * The first finds what is missing, the second finds what is already working.+ * Everything up to the LLM handoff is deterministic: SQL aggregation →+ * transactional-page exclusion → ranking → page read → coverage filter. Any+ * failure returns [] so the base suggestion flow never degrades, and brands+ * without synced traffic short-circuit on the first (empty) query.+ */++import * as cheerio from 'cheerio';+import supabaseAdmin from '../config/supabase.js';+import { fetchViaScrapeDo } from './audit/fetcher.js';+import { isCoveredByPrompts } from './gsc-suggestions.js';+import { logger } from './logger.js';++const WINDOW_DAYS = 28;+/** Candidates handed to the model. Deliberately small — each one is a page read. */+export const MAX_CANDIDATES = 8;+/**+ * Pages ranked before the coverage filter runs. Reading a page costs a proxy+ * credit, so the filter runs on a shortlist rather than on everything, and the+ * headroom absorbs the ones that turn out to be already covered.+ */+const SHORTLIST = 14;+/** Page reads in flight at once. */+const READ_CONCURRENCY = 4;+/** Below this a page has too little behind it to argue from. */+const MIN_SESSIONS = 5;+const MIN_AI_SESSIONS = 3;++/**+ * Paths that produce revenue attribution but no answerable question.+ *+ * A GA4 purchase event fires on the confirmation page, so without this the+ * highest-revenue "page" in most shops is the checkout — and no prompt exists+ * that a person would ask an AI to arrive there. Matched on path segments so+ * `/cart` and `/en/cart/` hit while `/cartography-guides` does not.+ */+const TRANSACTIONAL_SEGMENTS = new Set([+ 'checkout',+ 'cart',+ 'basket',+ 'order',+ 'orders',+ 'order-confirmation',+ 'confirmation',+ 'thank-you',+ 'thanks',+ 'payment',+ 'pay',+ 'login',+ 'signin',+ 'sign-in',+ 'signup',+ 'sign-up',+ 'register',+ 'logout',+ 'account',+ 'my-account',+ 'profile',+ 'dashboard',+ 'admin',+ 'wishlist',+ 'favorites',+ 'search',+ 'cookie-policy',+ 'privacy',+ 'privacy-policy',+ 'terms',+ 'terms-of-service',+ 'legal',+ 'unsubscribe',+]);++/**+ * True for a page that cannot yield a sensible prompt.+ *+ * Also excludes GA4's own placeholders: a blank or "(not set)" landing page is+ * an unattributed session, not a page anyone can be sent to.+ */+export function isTransactionalPath(path) {+ const raw = String(path ?? '').trim();+ if (!raw || raw === '(not set)' || raw === '(other)') return true;+ const withoutQuery = raw.split(/[?#]/)[0];+ return withoutQuery+ .split('/')+ .filter(Boolean)+ .some((segment) => TRANSACTIONAL_SEGMENTS.has(segment.toLowerCase()));+}++/** Sum the per-day rows of one table into one row per landing page. */+export function aggregateByPage(rows, fields) {+ const byPage = new Map();+ for (const row of rows || []) {+ const page = row.landing_page ?? '';+ if (isTransactionalPath(page)) continue;+ const acc = byPage.get(page) ?? { landing_page: page };+ for (const field of fields) acc[field] = (acc[field] ?? 0) + (Number(row[field]) || 0);+ byPage.set(page, acc);+ }+ return [...byPage.values()];+}++/** Platform names seen referring traffic to each page, busiest first. */+export function aiPlatformsByPage(rows) {+ const byPage = new Map();+ for (const row of rows || []) {+ const page = row.landing_page ?? '';+ const platform = row.platform;+ if (!platform) continue;+ const acc = byPage.get(page) ?? new Map();+ acc.set(platform, (acc.get(platform) ?? 0) + (Number(row.sessions) || 0));+ byPage.set(page, acc);+ }+ return new Map(+ [...byPage].map(([page, platforms]) => [+ page,+ [...platforms].sort((a, b) => b[1] - a[1]).map(([name]) => name),+ ]),+ );+}++/**+ * Rank and interleave the two signals into one candidate list.+ *+ * Interleaved rather than concatenated: taking the top N of a combined sort+ * would let a shop with real revenue crowd out every momentum candidate, and+ * a brand with no ecommerce would produce nothing from the revenue side at+ * all. Alternating keeps both questions represented whatever the property+ * reports.+ *+ * Revenue ranks on money where the property has it and on key events where it+ * does not, which is what makes this work without ecommerce tracking.+ */+export function composeGaCandidates({+ pageRows,+ aiRows,+ excludedPages = new Set(),+ limit = SHORTLIST,+}) {+ const pages = aggregateByPage(pageRows, [+ 'sessions',+ 'key_events',+ 'transactions',+ 'purchase_revenue',+ ]);+ const ai = aggregateByPage(aiRows, ['sessions']);+ const platforms = aiPlatformsByPage(aiRows);+ const pageBySlug = new Map(pages.map((p) => [p.landing_page, p]));++ const excluded = (page) => excludedPages.has(page);++ const revenue = pages+ .filter((p) => !excluded(p.landing_page))+ .filter((p) => p.purchase_revenue > 0 || p.transactions > 0 || p.key_events > 0)+ .filter((p) => p.sessions >= MIN_SESSIONS)+ .sort(+ (a, b) =>+ b.purchase_revenue - a.purchase_revenue ||+ b.transactions - a.transactions ||+ b.key_events - a.key_events ||+ b.sessions - a.sessions,+ )+ .map((p, i) => ({+ landingPage: p.landing_page,+ kind: 'revenue_blind_spot',+ rank: i + 1,+ sessions: p.sessions,+ keyEvents: p.key_events,+ transactions: p.transactions,+ revenue: Math.round(p.purchase_revenue * 100) / 100,+ aiSessions: ai.find((a) => a.landing_page === p.landing_page)?.sessions ?? 0,+ aiPlatforms: platforms.get(p.landing_page) ?? [],+ }));++ const momentum = ai+ .filter((a) => !excluded(a.landing_page))+ .filter((a) => a.sessions >= MIN_AI_SESSIONS)+ .sort((a, b) => b.sessions - a.sessions)+ .map((a, i) => {+ const page = pageBySlug.get(a.landing_page);+ return {+ landingPage: a.landing_page,+ kind: 'ai_momentum',+ rank: i + 1,+ sessions: page?.sessions ?? 0,+ keyEvents: page?.key_events ?? 0,+ transactions: page?.transactions ?? 0,+ revenue: Math.round((page?.purchase_revenue ?? 0) * 100) / 100,+ aiSessions: a.sessions,+ aiPlatforms: platforms.get(a.landing_page) ?? [],+ };+ });++ const out = [];+ const seen = new Set();+ for (let i = 0; out.length < limit && (i < revenue.length || i < momentum.length); i++) {+ for (const candidate of [revenue[i], momentum[i]]) {+ if (!candidate || seen.has(candidate.landingPage) || out.length >= limit) continue;+ seen.add(candidate.landingPage);+ out.push(candidate);+ }+ }+ return out;+}++/** Absolute URL for a landing-page path on the brand's own domain. */+export function toAbsoluteUrl(domain, path) {+ const host = String(domain || '')+ .trim()+ .replace(/^https?:\/\//i, '')+ .replace(/\/+$/, '');+ if (!host) return null;+ const suffix = String(path || '/');+ return `https://${host}${suffix.startsWith('/') ? suffix : `/${suffix}`}`;+}++/**+ * What the page is about, in the words of the page itself.+ *+ * This is the step that makes the suggestions usable. A URL slug or a product+ * name is usually an SKU nobody asks an AI about; the answerable question+ * lives at the category and need level, and reading the page is how we get+ * there — which is also why this works with no product catalogue at all.+ */+export function extractPageSummary(html) {+ const $ = cheerio.load(html || '');+ const clean = (value) =>+ String(value || '')+ .replace(/\s+/g, ' ')+ .trim();+ const headings = $('h2, h3')+ .slice(0, 6)+ .map((_, el) => clean($(el).text()))+ .get()+ .filter(Boolean);++ return {+ title: clean($('title').first().text()) || null,+ description:+ clean($('meta[name="description"]').attr('content')) ||+ clean($('meta[property="og:description"]').attr('content')) ||+ null,+ h1: clean($('h1').first().text()) || null,+ headings,+ };+}++/** The page's own words, as one string for the coverage check and the model. */+export function summaryText(summary) {+ return [summary?.title, summary?.h1, summary?.description, ...(summary?.headings ?? [])]+ .filter(Boolean)+ .join(' — ');+}++async function readPage(url) {+ try {+ const res = await fetchViaScrapeDo(url, { render: false, retries: 0 });+ if (!res.ok || !res.html) return null;+ return extractPageSummary(res.html);+ } catch {+ return null;+ }+}++/** Landing pages behind recently dismissed GA suggestions stay off the table. */+async function recentlyDismissedPages(brandId) {+ const cutoff = new Date(Date.now() - 30 * 86_400_000).toISOString();+ const { data } = await supabaseAdmin+ .from('prompt_suggestions')+ .select('source_data')+ .eq('brand_id', brandId)+ .eq('source', 'ga')+ .eq('status', 'dismissed')+ .gte('updated_at', cutoff);+ return new Set((data || []).map((d) => d.source_data?.landingPage).filter(Boolean));+}++/**+ * Candidate list for the suggestion generator. Empty array (never a throw) for+ * brands without synced traffic or on any upstream failure.+ */+export async function getGaSuggestionCandidates(brandId, existingPromptTexts) {+ try {+ 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, key_events, transactions, purchase_revenue')+ .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 && !aiRows?.length) return [];++ const excludedPages = await recentlyDismissedPages(brandId);+ const shortlist = composeGaCandidates({ pageRows, aiRows, excludedPages });+ if (shortlist.length === 0) return [];++ // Reading the page needs a domain to resolve the path against; without one+ // there is nothing to read and a slug-derived suggestion is exactly what+ // this generator exists to avoid.+ const { data: domains } = await supabaseAdmin+ .from('brand_domains')+ .select('domain')+ .eq('brand_id', brandId)+ .limit(1);+ const domain = domains?.[0]?.domain;+ if (!domain) return [];++ const withSummaries = [];+ for (let i = 0; i < shortlist.length; i += READ_CONCURRENCY) {+ if (withSummaries.length >= MAX_CANDIDATES) break;+ const batch = shortlist.slice(i, i + READ_CONCURRENCY);+ const summaries = await Promise.all(+ batch.map((c) => readPage(toAbsoluteUrl(domain, c.landingPage))),+ );+ batch.forEach((candidate, j) => {+ const summary = summaries[j];+ const text = summaryText(summary);+ // A page we could not read, or one already covered by a tracked+ // prompt, is dropped rather than passed on with a slug for the model+ // to guess from.+ if (!text || isCoveredByPrompts(text, existingPromptTexts)) return;+ withSummaries.push({ ...candidate, page: summary, pageText: text });+ });+ }++ return withSummaries.slice(0, MAX_CANDIDATES);+ } catch (err) {+ logger.error({ err, brandId }, '[ga-suggestions] candidate mining failed');+ return [];+ }+}diff --git a/server/src/lib/ga-suggestions.test.js b/server/src/lib/ga-suggestions.test.jsnew file mode 100644index 000000000..5ac781676--- /dev/null+++ b/server/src/lib/ga-suggestions.test.js@@ -0,0 +1,237 @@+import { describe, expect, it, vi } from 'vitest';++// The module imports the supabase admin client, whose config hard-exits when+// SUPABASE_* env is absent (as in CI) — stub it before the import chain.+vi.mock('../config/supabase.js', () => ({ default: {} }));++import {+ aggregateByPage,+ aiPlatformsByPage,+ composeGaCandidates,+ extractPageSummary,+ isTransactionalPath,+ summaryText,+ toAbsoluteUrl,+} from './ga-suggestions.js';++/**+ * Analytics-fed suggestion candidates (#705).+ *+ * The deterministic half: which pages become candidates, why, and what the+ * model is told about them. Getting this wrong produces suggestions that look+ * plausible and are grounded in nothing — the failure mode a customer notices+ * once and never trusts again.+ */++describe('isTransactionalPath', () => {+ it('excludes the pages that carry revenue but answer no question', () => {+ // A GA4 purchase fires on the confirmation page, so without this the+ // top-revenue "page" in most shops is the checkout.+ for (const path of [+ '/checkout',+ '/cart/',+ '/en/order-confirmation',+ '/thank-you',+ '/account/orders',+ '/login',+ '/tr/sepet/../cart',+ ]) {+ expect(isTransactionalPath(path), path).toBe(true);+ }+ });++ it('matches whole path segments, not substrings', () => {+ // /cartography-guides is a content page that a naive `includes('cart')`+ // would silently delete from the candidate pool.+ expect(isTransactionalPath('/cartography-guides')).toBe(false);+ expect(isTransactionalPath('/blog/accountability-in-ai')).toBe(false);+ expect(isTransactionalPath('/products/searchlight-3000')).toBe(false);+ });++ it('excludes GA placeholders and blanks, which are not pages at all', () => {+ expect(isTransactionalPath('')).toBe(true);+ expect(isTransactionalPath('(not set)')).toBe(true);+ expect(isTransactionalPath(undefined)).toBe(true);+ });++ it('keeps ordinary content and category pages', () => {+ expect(isTransactionalPath('/')).toBe(false);+ expect(isTransactionalPath('/pricing')).toBe(false);+ expect(isTransactionalPath('/collections/headphones')).toBe(false);+ });+});++describe('aggregateByPage', () => {+ it('sums the per-day rows of one page', () => {+ const rows = [+ { landing_page: '/a', sessions: 3, key_events: 1 },+ { landing_page: '/a', sessions: 4, key_events: 0 },+ { landing_page: '/b', sessions: 2, key_events: 5 },+ ];+ expect(aggregateByPage(rows, ['sessions', 'key_events'])).toEqual([+ { landing_page: '/a', sessions: 7, key_events: 1 },+ { landing_page: '/b', sessions: 2, key_events: 5 },+ ]);+ });++ it('drops transactional pages before they can rank', () => {+ const rows = [+ { landing_page: '/checkout', sessions: 900 },+ { landing_page: '/guides', sessions: 4 },+ ];+ expect(aggregateByPage(rows, ['sessions'])).toEqual([{ landing_page: '/guides', sessions: 4 }]);+ });+});++describe('aiPlatformsByPage', () => {+ it('lists the platforms per page, busiest first', () => {+ const rows = [+ { landing_page: '/a', platform: 'chatgpt.com', sessions: 4 },+ { landing_page: '/a', platform: 'claude.ai', sessions: 9 },+ { landing_page: '/a', platform: 'chatgpt.com', sessions: 6 },+ ];+ expect(aiPlatformsByPage(rows).get('/a')).toEqual(['chatgpt.com', 'claude.ai']);+ });++ it('ignores rows whose source could not be classified', () => {+ const rows = [{ landing_page: '/a', platform: null, sessions: 4 }];+ expect(aiPlatformsByPage(rows).get('/a')).toBeUndefined();+ });+});++describe('composeGaCandidates', () => {+ const pageRows = [+ {+ landing_page: '/money',+ sessions: 100,+ key_events: 9,+ transactions: 9,+ purchase_revenue: 900,+ },+ { landing_page: '/small', sessions: 40, key_events: 2, transactions: 2, purchase_revenue: 200 },+ { landing_page: '/quiet', sessions: 60, key_events: 0, transactions: 0, purchase_revenue: 0 },+ {+ landing_page: '/checkout',+ sessions: 80,+ key_events: 50,+ transactions: 50,+ purchase_revenue: 9999,+ },+ ];+ const aiRows = [+ { landing_page: '/quiet', platform: 'chatgpt.com', sessions: 30 },+ { landing_page: '/tiny', platform: 'claude.ai', sessions: 1 },+ ];++ it('raises both a revenue blind spot and an AI momentum page', () => {+ const out = composeGaCandidates({ pageRows, aiRows });+ const kinds = out.map((c) => c.kind);+ expect(kinds).toContain('revenue_blind_spot');+ expect(kinds).toContain('ai_momentum');+ });++ it('interleaves the two signals so neither can crowd the other out', () => {+ // Concatenating would let a shop with real revenue fill every slot and+ // leave no room for what AI engines are already sending traffic to.+ const out = composeGaCandidates({ pageRows, aiRows, limit: 2 });+ expect(out.map((c) => c.kind)).toEqual(['revenue_blind_spot', 'ai_momentum']);+ });++ it('never surfaces a transactional page however much revenue it carries', () => {+ const out = composeGaCandidates({ pageRows, aiRows });+ expect(out.map((c) => c.landingPage)).not.toContain('/checkout');+ });++ it('ranks a page with conversions but no revenue, so properties without ecommerce still produce candidates', () => {+ const noEcommerce = [+ { landing_page: '/demo', sessions: 50, key_events: 12, transactions: 0, purchase_revenue: 0 },+ ];+ const [candidate] = composeGaCandidates({ pageRows: noEcommerce, aiRows: [] });+ expect(candidate.landingPage).toBe('/demo');+ expect(candidate.revenue).toBe(0);+ expect(candidate.keyEvents).toBe(12);+ });++ it('carries the AI evidence onto a revenue candidate and vice versa', () => {+ const out = composeGaCandidates({ pageRows, aiRows });+ const quiet = out.find((c) => c.landingPage === '/quiet');+ expect(quiet.aiSessions).toBe(30);+ expect(quiet.aiPlatforms).toEqual(['chatgpt.com']);+ expect(quiet.sessions).toBe(60);+ });++ it('skips pages with too little behind them to argue from', () => {+ const out = composeGaCandidates({ pageRows, aiRows });+ expect(out.map((c) => c.landingPage)).not.toContain('/tiny');+ });++ it('keeps a dismissed page from resurfacing', () => {+ const out = composeGaCandidates({+ pageRows,+ aiRows,+ excludedPages: new Set(['/money']),+ });+ expect(out.map((c) => c.landingPage)).not.toContain('/money');+ });++ it('lists a page once even when both signals raise it', () => {+ const out = composeGaCandidates({+ pageRows: [+ {+ landing_page: '/both',+ sessions: 50,+ key_events: 5,+ transactions: 5,+ purchase_revenue: 500,+ },+ ],+ aiRows: [{ landing_page: '/both', platform: 'chatgpt.com', sessions: 20 }],+ });+ expect(out).toHaveLength(1);+ });+});++describe('toAbsoluteUrl', () => {+ it('joins a bare domain and a path', () => {+ expect(toAbsoluteUrl('example.com', '/pricing')).toBe('https://example.com/pricing');+ });++ it('tolerates a stored scheme or trailing slash', () => {+ expect(toAbsoluteUrl('https://example.com/', '/a')).toBe('https://example.com/a');+ });++ it('returns null without a domain, since there is nothing to read', () => {+ expect(toAbsoluteUrl('', '/a')).toBeNull();+ });+});++describe('extractPageSummary', () => {+ const html = `+ <html><head>+ <title>Noise-cancelling headphones | Shop</title>+ <meta name="description" content="Over-ear headphones for travel and commuting." />+ </head><body>+ <h1>ANS-2400 Pro Black</h1>+ <h2>Battery life</h2><h3>Comfort</h3>+ </body></html>`;++ it('reads what the page says it is about', () => {+ const summary = extractPageSummary(html);+ expect(summary.title).toBe('Noise-cancelling headphones | Shop');+ expect(summary.description).toBe('Over-ear headphones for travel and commuting.');+ expect(summary.h1).toBe('ANS-2400 Pro Black');+ expect(summary.headings).toEqual(['Battery life', 'Comfort']);+ });++ it('gives the model the category words, not just the model number', () => {+ // The whole point of reading the page: "ANS-2400 Pro Black" is an SKU+ // nobody asks an AI about; the answerable question lives in the title and+ // description around it.+ expect(summaryText(extractPageSummary(html))).toContain('Noise-cancelling headphones');+ });++ it('survives empty or unparseable markup', () => {+ expect(summaryText(extractPageSummary(''))).toBe('');+ expect(extractPageSummary('<html>').title).toBeNull();+ });+});diff --git a/server/src/routes/prompts.js b/server/src/routes/prompts.jsindex e88cd4df1..c01134db4 100644--- a/server/src/routes/prompts.js+++ b/server/src/routes/prompts.js@@ -8,6 +8,7 @@ import { getLanguageName } from '../lib/languages.js';import { requireFeature } from '../lib/plan-guard.js';import { withRetry } from '../lib/retry.js';import { getGscSuggestionCandidates } from '../lib/gsc-suggestions.js';+import { getGaSuggestionCandidates } from '../lib/ga-suggestions.js';const router = Router();@@ -161,6 +162,13 @@ const newSuggestionSchema = z.object({.describe('ONLY when this suggestion was derived from one of the provided Search Console queries: the EXACT original query string, verbatim. Omit for all other suggestions.',),+ sourcePage: z+ .string()+ .max(500)+ .optional()+ .describe(+ 'ONLY when this suggestion was derived from one of the provided Analytics pages: the EXACT landing page path, verbatim. Omit for all other suggestions.',+ ),}),).min(6)@@ -182,6 +190,11 @@ async function generateSuggestions(brandId) {ctx.existingPromptTexts,);+ // The brand's own analytics (#705) — [] without a mapped GA4 property or+ // synced traffic, which keeps every prompt block below unchanged for+ // brands that have neither.+ const gaCandidates = await getGaSuggestionCandidates(brandId, ctx.existingPromptTexts);+const system = `You are an AEO (Answer Engine Optimization) strategist. You suggest NEW search prompts a brand should track in AI engines (ChatGPT, Perplexity, Gemini, Claude). Current year: ${currentYear}.RULES:@@ -197,6 +210,11 @@ RULES:? `- REAL SEARCH DEMAND: a list of actual Google Search Console queries for this brand is provided — proven demand the brand does not track yet. Derive at least ${Math.min(4, gscCandidates.length)} suggestions from those queries: rephrase each raw query as a natural question a user would ask an AI assistant, preserving its intent exactly (never invent a different topic). For each such suggestion set sourceQuery to the EXACT original query string, verbatim. Never set sourceQuery on suggestions that did not come from that list.`: ''+ }${+ gaCandidates.length+ ? `+- THE BRAND'S OWN ANALYTICS: a list of pages from this brand's Google Analytics is provided, each with what the page itself says it is about. Derive at least ${Math.min(3, gaCandidates.length)} suggestions from those pages. Write the prompt at the level of the need the page serves, NOT the page's product name or URL — a model number nobody types into an AI assistant becomes the category question that leads to it ("best noise-cancelling headphones", not "ANS-2400 Pro Black"). For each such suggestion set sourcePage to the EXACT landing page path, verbatim. Never set sourcePage on suggestions that did not come from that list, and never set both sourceQuery and sourcePage on the same suggestion.`+ : ''}`;const v = ctx.volume;@@ -234,6 +252,21 @@ ${gscCandidates(c) =>` • "${c.query}" — ${c.impressions.toLocaleString('en-US')} impressions, ${c.clicks.toLocaleString('en-US')} clicks${c.avgPosition != null ? `, avg position ${c.avgPosition}` : ''}`,)+ .join('\n')}`+ : ''+ }${+ gaCandidates.length+ ? `++Pages from this brand's own Google Analytics (last 28 days, none covered by a tracked prompt):+${gaCandidates+ .map((c) => {+ const evidence =+ c.kind === 'revenue_blind_spot'+ ? `#${c.rank} by ${c.revenue > 0 ? 'revenue' : 'conversions'} (${c.revenue > 0 ? `${c.revenue.toLocaleString('en-US')} revenue, ` : ''}${c.transactions || c.keyEvents} conversions, ${c.sessions.toLocaleString('en-US')} sessions)`+ : `${c.aiSessions.toLocaleString('en-US')} AI-referred sessions${c.aiPlatforms.length ? ` from ${c.aiPlatforms.join(', ')}` : ''}`;+ return ` • ${c.landingPage} — ${evidence}\n the page says: ${c.pageText.slice(0, 300)}`;+ }).join('\n')}`: ''}@@ -258,7 +291,7 @@ Suggest the next 8 prompts this brand should start tracking, with topic, reason{ attempts: 3, baseDelayMs: 500, label: 'suggestion-refresh' },);- return { suggestions: object.suggestions, gscCandidates };+ return { suggestions: object.suggestions, gscCandidates, gaCandidates };}async function findOrCreateTopic(brandId, topicName) {@@ -286,7 +319,9 @@ router.post(async (req, res) => {try {await assertBrandAccess(req.params.brandId, req.user.id);- const { suggestions, gscCandidates } = await generateSuggestions(req.params.brandId);+ const { suggestions, gscCandidates, gaCandidates } = await generateSuggestions(+ req.params.brandId,+ );await supabaseAdmin.from('prompt_suggestions')@@ -303,6 +338,7 @@ router.post(// drop real provenance.const normalizeQuery = (q) => q.trim().toLowerCase();const candidateByQuery = new Map(gscCandidates.map((c) => [normalizeQuery(c.query), c]));+ const candidateByPage = new Map(gaCandidates.map((c) => [normalizeQuery(c.landingPage), c]));const rows = [];for (const s of suggestions) {@@ -310,6 +346,13 @@ router.post(const candidate = s.sourceQuery? candidateByQuery.get(normalizeQuery(s.sourceQuery)): undefined;+ // Search Console wins a tie: it is proven demand for a phrasing, while+ // the page is an inference about what would lead there. A suggestion+ // claiming both is claiming something the generators never offered.+ const gaCandidate =+ !candidate && s.sourcePage+ ? candidateByPage.get(normalizeQuery(s.sourcePage))+ : undefined;rows.push({brand_id: req.params.brandId,suggested_text: s.text,@@ -319,7 +362,7 @@ router.post(// Sanity clamp replacing the removed schema ceiling — one absurd// estimate must cap out, not reject the whole generated batch.est_volume: Math.min(s.estVolume, 10_000_000),- source: candidate ? 'gsc' : 'llm',+ source: candidate ? 'gsc' : gaCandidate ? 'ga' : 'llm',source_data: candidate? {query: candidate.query,@@ -329,7 +372,20 @@ router.post(badge: candidate.badge,competitionIndex: candidate.competitionIndex ?? null,}- : null,+ : gaCandidate+ ? {+ landingPage: gaCandidate.landingPage,+ kind: gaCandidate.kind,+ rank: gaCandidate.rank,+ sessions: gaCandidate.sessions,+ keyEvents: gaCandidate.keyEvents,+ transactions: gaCandidate.transactions,+ revenue: gaCandidate.revenue,+ aiSessions: gaCandidate.aiSessions,+ aiPlatforms: gaCandidate.aiPlatforms,+ pageTitle: gaCandidate.page?.title ?? null,+ }+ : null,status: 'new',expires_at: expiresAt,});diff --git a/supabase/migrations/00054_prompt_suggestions_ga_source.sql b/supabase/migrations/00054_prompt_suggestions_ga_source.sqlnew file mode 100644index 000000000..a5c021ce0--- /dev/null+++ b/supabase/migrations/00054_prompt_suggestions_ga_source.sql@@ -0,0 +1,8 @@+-- Google Analytics as a prompt-suggestion source (#705).+--+-- The check constraint predates the Analytics pipeline; without 'ga' the+-- suggestion insert fails outright rather than degrading, so this has to land+-- with the generator that produces those rows.+ALTER TABLE public.prompt_suggestions DROP CONSTRAINT prompt_suggestions_source_check;+ALTER TABLE public.prompt_suggestions ADD CONSTRAINT prompt_suggestions_source_check+ CHECK (source = ANY (ARRAY['llm'::text, 'heuristic'::text, 'gsc'::text, 'ga'::text]));diff --git a/supabase/schema.sql b/supabase/schema.sqlindex dd72f6b8a..01a0ce83b 100644--- a/supabase/schema.sql+++ b/supabase/schema.sql@@ -5439,3 +5439,15 @@ GRANT SELECT ON public.ga_ai_traffic_stats TO authenticated;GRANT SELECT ON public.ga_page_stats TO authenticated;GRANT SELECT ON public.ga_item_stats TO authenticated;+-- ─────────────────────────────────────────────────────────────────────────+-- migrations/00054_prompt_suggestions_ga_source.sql+-- ─────────────────────────────────────────────────────────────────────────+-- Google Analytics as a prompt-suggestion source (#705).+--+-- The check constraint predates the Analytics pipeline; without 'ga' the+-- suggestion insert fails outright rather than degrading, so this has to land+-- with the generator that produces those rows.+ALTER TABLE public.prompt_suggestions DROP CONSTRAINT prompt_suggestions_source_check;+ALTER TABLE public.prompt_suggestions ADD CONSTRAINT prompt_suggestions_source_check+ CHECK (source = ANY (ARRAY['llm'::text, 'heuristic'::text, 'gsc'::text, 'ga'::text]));+diff --git a/web/src/app/[locale]/(dashboard)/dashboard/prompts/_suggestions-card.tsx b/web/src/app/[locale]/(dashboard)/dashboard/prompts/_suggestions-card.tsxindex ae374a20f..c21b86426 100644--- a/web/src/app/[locale]/(dashboard)/dashboard/prompts/_suggestions-card.tsx+++ b/web/src/app/[locale]/(dashboard)/dashboard/prompts/_suggestions-card.tsx@@ -18,6 +18,8 @@ import {ChevronRight,AlertTriangle,SearchCheck,+ BarChart3,+ Sparkle,} from 'lucide-react';import { toast } from 'sonner';import {@@ -26,8 +28,36 @@ import {acceptSuggestion,dismissSuggestion,type PromptSuggestion,- type GscSuggestionBadge,} from '@/lib/actions/prompt-suggestions';+import {+ gaSourceData,+ gscSourceData,+ type GaSuggestionSourceData,+ type GscSuggestionBadge,+} from '@/lib/prompt-suggestion-source';++/**+ * Analytics evidence, in the customer's own numbers (#705). A blind spot is+ * argued from money, momentum from the engines already sending visitors —+ * showing the wrong one would make a true statement about the wrong thing.+ */+function gaEvidence(d: GaSuggestionSourceData): { label: string; tooltip: string } {+ if (d.kind === 'ai_momentum') {+ const engines = d.aiPlatforms.length ? d.aiPlatforms.join(', ') : 'AI assistants';+ return {+ label: `AI traffic · ${d.aiSessions.toLocaleString()} sessions`,+ tooltip: `${engines} already sent ${d.aiSessions.toLocaleString()} visits to ${d.landingPage} in the last 28 days. That topic is demonstrably answerable by an AI engine and you are already a candidate source for it — tracking a prompt around it turns an accident into a measured position.`,+ };+ }+ const earns =+ d.revenue > 0+ ? `${d.revenue.toLocaleString()} in revenue`+ : `${d.keyEvents.toLocaleString()} conversions`;+ return {+ label: `#${d.rank} by ${d.revenue > 0 ? 'revenue' : 'conversions'}`,+ tooltip: `${d.landingPage} produced ${earns} from ${d.sessions.toLocaleString()} sessions in the last 28 days, and nothing you track would surface it in an AI answer. Anyone asking an assistant about this has no way to find you.`,+ };+}const GSC_BADGES: Record<GscSuggestionBadge, { label: string; tooltip: string }> = {protect_traffic: {@@ -325,6 +355,11 @@ export function SuggestionsCard({ brandId, onAccepted }: Props) {<ul className="space-y-2">{suggestions.map((s) => {const busy = pendingId === s.id;+ // Narrow the evidence payload to the shape its source promises,+ // so a row whose `source` and payload disagree renders as a+ // plain suggestion instead of reading fields that are not there.+ const gsc = gscSourceData(s);+ const ga = gaSourceData(s);return (<likey={s.id}@@ -341,33 +376,57 @@ export function SuggestionsCard({ brandId, onAccepted }: Props) {)}{/* GSC rows carry real impressions — showing the modeledestimate next to measured data reads as a contradiction. */}- {s.estVolume != null && s.estVolume > 0 && s.source !== 'gsc' && (+ {s.estVolume != null && s.estVolume > 0 && !gsc && !ga && (<Badge variant="outline" className="gap-1 text-xs tabular-nums"><TrendingUp className="h-3 w-3" />~{s.estVolume.toLocaleString()}/mo</Badge>)}- {s.source === 'gsc' && s.sourceData && (+ {gsc && (<><HoverTip- content={`From your Google Search Console data \u2014 the query "${s.sourceData.query}" got ${s.sourceData.impressions.toLocaleString()} impressions in the last 28 days.`}+ content={`From your Google Search Console data \u2014 the query "${gsc.query}" got ${gsc.impressions.toLocaleString()} impressions in the last 28 days.`}><Badgevariant="outline"className="gap-1 text-xs border-blue-500/30 bg-blue-500/10 text-blue-600 dark:text-blue-400"><SearchCheck className="h-3 w-3" />- Search Console · {s.sourceData.impressions.toLocaleString()} impr/mo+ Search Console · {gsc.impressions.toLocaleString()} impr/mo</Badge></HoverTip>- {s.sourceData.badge && (- <HoverTip content={GSC_BADGES[s.sourceData.badge].tooltip}>+ {gsc.badge && (+ <HoverTip content={GSC_BADGES[gsc.badge].tooltip}><Badge variant="outline" className="text-xs">- {GSC_BADGES[s.sourceData.badge].label}+ {GSC_BADGES[gsc.badge].label}</Badge></HoverTip>)}</>)}+ {ga && (+ <>+ <HoverTip+ content={`From your Google Analytics — derived from ${ga.pageTitle ? `"${ga.pageTitle}" (${ga.landingPage})` : ga.landingPage}, read from the page itself rather than from its URL or product name.`}+ >+ <Badge+ variant="outline"+ className="gap-1 text-xs border-amber-500/30 bg-amber-500/10 text-amber-600 dark:text-amber-400"+ >+ {ga.kind === 'ai_momentum' ? (+ <Sparkle className="h-3 w-3" />+ ) : (+ <BarChart3 className="h-3 w-3" />+ )}+ Analytics · {ga.landingPage}+ </Badge>+ </HoverTip>+ <HoverTip content={gaEvidence(ga).tooltip}>+ <Badge variant="outline" className="text-xs tabular-nums">+ {gaEvidence(ga).label}+ </Badge>+ </HoverTip>+ </>+ )}</div>{s.reason && (<p className="text-xs text-muted-foreground leading-relaxed">{s.reason}</p>diff --git a/web/src/lib/actions/prompt-suggestions.ts b/web/src/lib/actions/prompt-suggestions.tsindex 4ce914094..4ef87d067 100644--- a/web/src/lib/actions/prompt-suggestions.ts+++ b/web/src/lib/actions/prompt-suggestions.ts@@ -4,20 +4,12 @@ import { revalidatePath } from 'next/cache';import { createClient } from '@/lib/supabase/server';import { addPromptToSet } from '@/lib/actions/prompt';import { API_BASE_URL } from '@/config/api';+// Types only — this file is `'use server'`, so the guards that go with them+// live in a plain module (every runtime export here must be a server action).+import type { PromptSuggestionSource, SuggestionSourceData } from '@/lib/prompt-suggestion-source';const AEO_SERVER_URL = API_BASE_URL;-export type GscSuggestionBadge = 'protect_traffic' | 'capture_demand' | 'low_competition';--export interface GscSuggestionSourceData {- query: string;- impressions: number;- clicks: number;- avgPosition: number | null;- badge: GscSuggestionBadge | null;- competitionIndex: number | null;-}-export interface PromptSuggestion {id: string;brandId: string;@@ -26,8 +18,8 @@ export interface PromptSuggestion {topicId: string | null;reason: string | null;estVolume: number | null;- source: 'llm' | 'heuristic' | 'gsc';- sourceData: GscSuggestionSourceData | null;+ source: PromptSuggestionSource;+ sourceData: SuggestionSourceData | null;status: 'new' | 'added' | 'dismissed';generatedAt: string;expiresAt: string;@@ -41,8 +33,8 @@ interface SuggestionRow {topic_id: string | null;reason: string | null;est_volume: number | null;- source: 'llm' | 'heuristic' | 'gsc';- source_data: GscSuggestionSourceData | null;+ source: PromptSuggestionSource;+ source_data: SuggestionSourceData | null;status: 'new' | 'added' | 'dismissed';generated_at: string;expires_at: string;diff --git a/web/src/lib/prompt-suggestion-source.ts b/web/src/lib/prompt-suggestion-source.tsnew file mode 100644index 000000000..6d9354ad5--- /dev/null+++ b/web/src/lib/prompt-suggestion-source.ts@@ -0,0 +1,61 @@+/**+ * Shapes and guards for the evidence behind a prompt suggestion.+ *+ * A plain module rather than part of `lib/actions/prompt-suggestions.ts`,+ * because that file is `'use server'` and every runtime export of a server+ * module has to be an async server action — a synchronous helper there fails+ * the production build, not the type check.+ */++export type GscSuggestionBadge = 'protect_traffic' | 'capture_demand' | 'low_competition';++export interface GscSuggestionSourceData {+ query: string;+ impressions: number;+ clicks: number;+ avgPosition: number | null;+ badge: GscSuggestionBadge | null;+ competitionIndex: number | null;+}++/**+ * Evidence behind an Analytics-derived suggestion (#705): either a page that+ * earns and has no prompt coverage, or one an AI engine already refers to.+ */+export interface GaSuggestionSourceData {+ landingPage: string;+ kind: 'revenue_blind_spot' | 'ai_momentum';+ rank: number;+ sessions: number;+ keyEvents: number;+ transactions: number;+ revenue: number;+ aiSessions: number;+ aiPlatforms: string[];+ pageTitle: string | null;+}++export type SuggestionSourceData = GscSuggestionSourceData | GaSuggestionSourceData;++export type PromptSuggestionSource = 'llm' | 'heuristic' | 'gsc' | 'ga';++interface SourceCarrier {+ source: PromptSuggestionSource;+ sourceData: SuggestionSourceData | null;+}++/**+ * Narrow `sourceData` to the shape its source promises.+ *+ * The `source` column and the payload are written together but read apart, so+ * these check both. A row whose source says one thing and whose payload says+ * another renders as a plain suggestion instead of reading fields that are not+ * there.+ */+export function gscSourceData(s: SourceCarrier): GscSuggestionSourceData | null {+ return s.source === 'gsc' && s.sourceData && 'query' in s.sourceData ? s.sourceData : null;+}++export function gaSourceData(s: SourceCarrier): GaSuggestionSourceData | null {+ return s.source === 'ga' && s.sourceData && 'landingPage' in s.sourceData ? s.sourceData : null;+}