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: feed prompt suggestions with real Search Console demand (#650)
Gökhan Geyikd789562237d5
diff --git a/server/src/lib/gsc-suggestions.js b/server/src/lib/gsc-suggestions.jsnew file mode 100644index 000000000..5b720b695--- /dev/null+++ b/server/src/lib/gsc-suggestions.js@@ -0,0 +1,229 @@+/**+ * GSC-fed suggestion candidates (#648).+ *+ * Mines the brand's real Google queries (gsc_query_stats) for demand the+ * brand does not track in AI answers yet. Everything up to the LLM handoff+ * is deterministic: SQL aggregation → token-overlap coverage filter →+ * head + long-tail composition → click-based rationale badges → cached+ * DataForSEO competition enrichment. Any failure returns [] so the base+ * suggestion flow never degrades; brands without GSC data short-circuit on+ * the first (empty) query.+ */++import supabaseAdmin from '../config/supabase.js';+import { getSearchVolumes } from './dataforseo.js';+import { regionToLocationCode, languageToCode } from './dataforseo-codes.js';+import { logger } from './logger.js';++const WINDOW_DAYS = 28;+const MIN_IMPRESSIONS = 30;+const LONGTAIL_MIN_IMPRESSIONS = 10;+const LONGTAIL_MIN_WORDS = 4;+const HEAD_SLOTS = 10;+const LONGTAIL_SLOTS = 10;+export const MAX_CANDIDATES = HEAD_SLOTS + LONGTAIL_SLOTS;+const PROTECT_MIN_CLICKS = 10;+const CAPTURE_MIN_IMPRESSIONS = 100;+const CAPTURE_MAX_CTR = 0.01;+const LOW_COMPETITION_MAX_INDEX = 33;+const CACHE_TTL_DAYS = 30;+// Token-overlap ratio above which a query counts as already tracked.+const COVERAGE_OVERLAP = 0.6;++const STOPWORDS = new Set([+ 'a',+ 'an',+ 'the',+ 'and',+ 'or',+ 'of',+ 'for',+ 'to',+ 'in',+ 'on',+ 'at',+ 'is',+ 'are',+ 'was',+ 'be',+ 'do',+ 'does',+ 'how',+ 'what',+ 'which',+ 'who',+ 'why',+ 'when',+ 'where',+ 'can',+ 'i',+ 'my',+ 'your',+ 'with',+ 'vs',+ 'best',+]);++export function normalizeTokens(text) {+ return (text || '')+ .toLowerCase()+ .replace(/[^\p{L}\p{N}\s]/gu, ' ')+ .split(/\s+/)+ .filter((t) => t && !STOPWORDS.has(t));+}++/** True when the query's meaningful tokens are mostly present in one prompt. */+export function isCoveredByPrompts(query, promptTexts) {+ const queryTokens = normalizeTokens(query);+ if (queryTokens.length === 0) return true; // stopwords-only — nothing to track+ return promptTexts.some((text) => {+ const promptTokens = new Set(normalizeTokens(text));+ const hits = queryTokens.filter((t) => promptTokens.has(t)).length;+ return hits / queryTokens.length >= COVERAGE_OVERLAP;+ });+}++/** Click-based rationale: protect what earns traffic, capture what doesn't convert. */+export function classifyCandidate(c) {+ if (c.clicks >= PROTECT_MIN_CLICKS) return 'protect_traffic';+ const ctr = c.impressions > 0 ? c.clicks / c.impressions : 0;+ if (c.impressions >= CAPTURE_MIN_IMPRESSIONS && ctr < CAPTURE_MAX_CTR) return 'capture_demand';+ return null;+}++/**+ * Coverage-filter and slice the aggregated rows: top head demand plus+ * long-tail quick wins, capped at MAX_CANDIDATES. `excludedQueries` holds+ * normalized queries the user recently dismissed — GSC candidates are+ * deterministic, so without this a dismissed suggestion would resurrect on+ * every refresh.+ */+export function composeCandidates(rows, existingPromptTexts, excludedQueries = new Set()) {+ const open = (rows || [])+ .filter(+ (r) =>+ r.query &&+ !excludedQueries.has(r.query.trim().toLowerCase()) &&+ !isCoveredByPrompts(r.query, existingPromptTexts),+ )+ .map((r) => ({+ query: r.query,+ impressions: Number(r.impressions) || 0,+ clicks: Number(r.clicks) || 0,+ avgPosition: r.avg_position != null ? Math.round(r.avg_position * 10) / 10 : null,+ }));++ const head = open.slice(0, HEAD_SLOTS);+ const inHead = new Set(head.map((c) => c.query));+ const longtail = open+ .filter(+ (c) =>+ !inHead.has(c.query) &&+ c.impressions >= LONGTAIL_MIN_IMPRESSIONS &&+ c.query.trim().split(/\s+/).length >= LONGTAIL_MIN_WORDS,+ )+ .slice(0, LONGTAIL_SLOTS);++ return [...head, ...longtail].map((c) => ({ ...c, badge: classifyCandidate(c) }));+}++/** Attach competitionIndex via a 30-day cache + at most ONE batched call. */+async function enrichCompetition(candidates, brand) {+ if (process.env.GSC_SUGGESTION_ENRICHMENT === 'off') return candidates;+ if (candidates.length === 0) return candidates;++ const locationCode = (brand.region ? regionToLocationCode(brand.region) : 0) || 0;+ const languageCode = (brand.language ? languageToCode(brand.language) : '') || '';+ const keywords = candidates.map((c) => c.query);+ const cutoff = new Date(Date.now() - CACHE_TTL_DAYS * 24 * 60 * 60 * 1000).toISOString();++ const { data: cached } = await supabaseAdmin+ .from('dataforseo_competition_cache')+ .select('keyword, competition_index, competition')+ .in('keyword', keywords)+ .eq('location_code', locationCode)+ .eq('language_code', languageCode)+ .gte('fetched_at', cutoff);++ const byKeyword = new Map((cached || []).map((r) => [r.keyword, r]));+ const misses = keywords.filter((k) => !byKeyword.has(k));++ if (misses.length > 0) {+ const volumes = await getSearchVolumes(misses, {+ locationCode: locationCode || undefined,+ languageCode: languageCode || undefined,+ });+ const rows = misses.map((k) => ({+ keyword: k,+ location_code: locationCode,+ language_code: languageCode,+ competition_index: volumes[k]?.competitionIndex ?? null,+ competition: volumes[k]?.competition ?? null,+ fetched_at: new Date().toISOString(),+ }));+ await supabaseAdmin+ .from('dataforseo_competition_cache')+ .upsert(rows, { onConflict: 'keyword,location_code,language_code' });+ for (const r of rows) byKeyword.set(r.keyword, r);+ }++ return candidates.map((c) => {+ const hit = byKeyword.get(c.query);+ const competitionIndex = hit?.competition_index ?? null;+ const badge =+ c.badge ??+ (competitionIndex !== null && competitionIndex <= LOW_COMPETITION_MAX_INDEX+ ? 'low_competition'+ : null);+ return { ...c, competitionIndex, competition: hit?.competition ?? null, badge };+ });+}++/**+ * Candidate list for the suggestion generator. Empty array (never a throw)+ * for brands without GSC data or on any upstream failure.+ */+export async function getGscSuggestionCandidates(brandId, brand, existingPromptTexts) {+ try {+ const since = new Date(Date.now() - WINDOW_DAYS * 24 * 60 * 60 * 1000)+ .toISOString()+ .slice(0, 10);+ const { data: rows, error } = await supabaseAdmin.rpc('gsc_candidate_queries', {+ p_brand_id: brandId,+ p_since: since,+ p_min_impressions: MIN_IMPRESSIONS,+ });+ if (error) throw new Error(error.message);+ if (!rows || rows.length === 0) return [];++ // Queries behind recently dismissed GSC suggestions stay off the table.+ const dismissedCutoff = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString();+ const { data: dismissed } = await supabaseAdmin+ .from('prompt_suggestions')+ .select('source_data')+ .eq('brand_id', brandId)+ .eq('source', 'gsc')+ .eq('status', 'dismissed')+ .gte('updated_at', dismissedCutoff);+ const excludedQueries = new Set(+ (dismissed || [])+ .map((d) => d.source_data?.query)+ .filter(Boolean)+ .map((q) => q.trim().toLowerCase()),+ );++ const composed = composeCandidates(rows, existingPromptTexts, excludedQueries);+ if (composed.length === 0) return [];++ try {+ return await enrichCompetition(composed, brand);+ } catch (err) {+ // Enrichment is optional garnish — candidates ship without badges.+ logger.warn({ err, brandId }, '[gsc-suggestions] competition enrichment failed');+ return composed;+ }+ } catch (err) {+ logger.error({ err, brandId }, '[gsc-suggestions] candidate mining failed');+ return [];+ }+}diff --git a/server/src/lib/gsc-suggestions.test.js b/server/src/lib/gsc-suggestions.test.jsnew file mode 100644index 000000000..e16d02c80--- /dev/null+++ b/server/src/lib/gsc-suggestions.test.js@@ -0,0 +1,108 @@+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 {+ normalizeTokens,+ isCoveredByPrompts,+ classifyCandidate,+ composeCandidates,+ MAX_CANDIDATES,+} from './gsc-suggestions.js';++describe('normalizeTokens', () => {+ it('lowercases, strips punctuation, and drops stopwords', () => {+ expect(normalizeTokens('How to improve ChatGPT visibility?')).toEqual([+ 'improve',+ 'chatgpt',+ 'visibility',+ ]);+ });++ it('keeps unicode letters (non-English queries)', () => {+ expect(normalizeTokens('yapay zekâ görünürlük aracı')).toEqual([+ 'yapay',+ 'zekâ',+ 'görünürlük',+ 'aracı',+ ]);+ });+});++describe('isCoveredByPrompts', () => {+ const prompts = ['What are the best AI visibility tracking tools?'];++ it('marks a query covered when its tokens appear in a tracked prompt', () => {+ expect(isCoveredByPrompts('ai visibility tracking tool', prompts)).toBe(true);+ });++ it('leaves genuinely untracked intents open', () => {+ expect(isCoveredByPrompts('how to improve chatgpt visibility', prompts)).toBe(false);+ });++ it('treats stopword-only queries as covered (nothing to track)', () => {+ expect(isCoveredByPrompts('how to do the best', prompts)).toBe(true);+ });+});++describe('classifyCandidate', () => {+ it('flags traffic-earning queries as protect_traffic', () => {+ expect(classifyCandidate({ impressions: 500, clicks: 40 })).toBe('protect_traffic');+ });++ it('flags high-impression zero-click queries as capture_demand', () => {+ expect(classifyCandidate({ impressions: 400, clicks: 1 })).toBe('capture_demand');+ });++ it('returns null when neither rationale applies', () => {+ expect(classifyCandidate({ impressions: 50, clicks: 3 })).toBeNull();+ });+});++describe('composeCandidates', () => {+ const row = (query, impressions, clicks = 0) => ({+ query,+ impressions,+ clicks,+ avg_position: 12.34,+ });++ it('filters covered queries and keeps head demand ordered by impressions', () => {+ const rows = [+ row('ai visibility tracking tool', 900, 20), // covered → dropped+ row('answer engine optimization guide', 800, 30),+ row('llm brand monitoring pricing', 300),+ ];+ const out = composeCandidates(rows, ['What are the best AI visibility tracking tools?']);+ expect(out.map((c) => c.query)).toEqual([+ 'answer engine optimization guide',+ 'llm brand monitoring pricing',+ ]);+ expect(out[0].badge).toBe('protect_traffic');+ expect(out[0].avgPosition).toBe(12.3);+ });++ it('excludes recently dismissed queries (normalized) so they cannot resurrect', () => {+ const rows = [row('answer engine optimization guide', 800), row('llm monitoring pricing', 300)];+ const excluded = new Set(['answer engine optimization guide']);+ const out = composeCandidates(rows, [], excluded);+ expect(out.map((c) => c.query)).toEqual(['llm monitoring pricing']);+ // Matching is case/whitespace-insensitive on the candidate side too.+ const out2 = composeCandidates([row(' Answer Engine Optimization Guide ', 800)], [], excluded);+ expect(out2).toEqual([]);+ });++ it('adds a long-tail slice beyond the head without duplicates', () => {+ const rows = [];+ for (let i = 0; i < 12; i++) rows.push(row(`headterm${i} tools`, 1000 - i));+ rows.push(row('how does answer engine optimization work for startups', 15));+ const out = composeCandidates(rows, []);+ expect(out.length).toBeLessThanOrEqual(MAX_CANDIDATES);+ expect(out.some((c) => c.query.startsWith('how does answer engine'))).toBe(true);+ // Short or too-quiet tail rows don't make the long-tail slice.+ const out2 = composeCandidates([...rows, row('tiny query', 15)], []);+ expect(out2.some((c) => c.query === 'tiny query')).toBe(false);+ });+});diff --git a/server/src/lib/gsc-sync.js b/server/src/lib/gsc-sync.jsindex 61d491508..425d23f12 100644--- a/server/src/lib/gsc-sync.js+++ b/server/src/lib/gsc-sync.js@@ -127,6 +127,16 @@ export async function runGscSync({ organizationId } = {}) {}}+ // Retention (#648): the suggestion pipeline reads a 28-day window; 90 days+ // keeps room for trend features without unbounded growth.+ const { error: pruneError } = await supabaseAdmin+ .from('gsc_query_stats')+ .delete()+ .lt('date', utcDateString(90));+ if (pruneError) {+ logger.warn({ err: pruneError }, '[gsc-sync] retention prune failed');+ }+logger.info({ synced, skipped, total: (brands || []).length }, '[gsc-sync] completed');return { synced, skipped, results };}diff --git a/server/src/routes/prompts.js b/server/src/routes/prompts.jsindex 52103dab9..e88cd4df1 100644--- a/server/src/routes/prompts.js+++ b/server/src/routes/prompts.js@@ -7,6 +7,7 @@ import { classifyPromptIntent } from '../lib/intent-extraction.js';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';const router = Router();@@ -41,7 +42,11 @@ async function loadSuggestionContext(brandId) {{ data: existingTopics },{ data: recentResults },] = await Promise.all([- supabaseAdmin.from('brands').select('name, description, language').eq('id', brandId).single(),+ supabaseAdmin+ .from('brands')+ .select('name, description, language, region')+ .eq('id', brandId)+ .single(),supabaseAdmin.from('prompts').select('id, text, prompt_sets!inner(brand_id), prompt_volumes(est_ai_volume, intent)')@@ -149,6 +154,13 @@ const newSuggestionSchema = z.object({// and retrying can't help. Out-of-range protection is a clamp at the// insert site instead.estVolume: z.number().int().min(0).describe('Estimated monthly AI search volume (rough)'),+ sourceQuery: z+ .string()+ .max(200)+ .optional()+ .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.',+ ),}),).min(6)@@ -162,6 +174,14 @@ async function generateSuggestions(brandId) {const langName = getLanguageName(ctx.brand.language);const currentYear = new Date().getFullYear();+ // Real Search Console demand (#648) — [] for brands without GSC, which+ // keeps every prompt block below byte-identical to the pre-GSC behavior.+ const gscCandidates = await getGscSuggestionCandidates(+ brandId,+ ctx.brand,+ 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:@@ -172,7 +192,12 @@ RULES:- Volume bias: prioritize prompt ideas that resemble (in topic and intent) the HIGH-volume prompts already tracked. Avoid suggesting prompts close in topic to LOW-volume ones unless there is a strong competitor gap.- estVolume must be a realistic monthly AI search volume; calibrate it against the volume samples shown — do not output flat round numbers like 1000 for everything.- Reasons must be concrete: cite the gap, the trend, or the competitor activity. Avoid generic platitudes.-- Diversity: mix comparison, how-to, best-of, recommendation, and problem-solving intents.`;+- Diversity: mix comparison, how-to, best-of, recommendation, and problem-solving intents.${+ gscCandidates.length+ ? `+- 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.`+ : ''+ }`;const v = ctx.volume;const volumeBlock =@@ -199,7 +224,19 @@ ${ctx.existingTopicNames.length ? ctx.existingTopicNames.join(', ') : '(none)'}Top competitors currently cited in this brand's tracked AI responses:${ctx.topCompetitors.length ? ctx.topCompetitors.join(', ') : '(no data yet)'}-${volumeBlock}+${volumeBlock}${+ gscCandidates.length+ ? `++Real Google Search Console queries for this brand (last 28 days, NOT tracked yet — proven demand):+${gscCandidates+ .map(+ (c) =>+ ` • "${c.query}" — ${c.impressions.toLocaleString('en-US')} impressions, ${c.clicks.toLocaleString('en-US')} clicks${c.avgPosition != null ? `, avg position ${c.avgPosition}` : ''}`,+ )+ .join('\n')}`+ : ''+ }Suggest the next 8 prompts this brand should start tracking, with topic, reason and a calibrated monthly AI search volume (estVolume).`;@@ -221,7 +258,7 @@ Suggest the next 8 prompts this brand should start tracking, with topic, reason{ attempts: 3, baseDelayMs: 500, label: 'suggestion-refresh' },);- return object.suggestions;+ return { suggestions: object.suggestions, gscCandidates };}async function findOrCreateTopic(brandId, topicName) {@@ -249,7 +286,7 @@ router.post(async (req, res) => {try {await assertBrandAccess(req.params.brandId, req.user.id);- const suggestions = await generateSuggestions(req.params.brandId);+ const { suggestions, gscCandidates } = await generateSuggestions(req.params.brandId);await supabaseAdmin.from('prompt_suggestions')@@ -259,9 +296,20 @@ router.post(const expiresAt = new Date(Date.now() + SUGGESTION_TTL_HOURS * 60 * 60 * 1000).toISOString();+ // Provenance: a suggestion is 'gsc' only when its sourceQuery matches a+ // provided candidate — a hallucinated sourceQuery degrades to a plain+ // 'llm' row instead of carrying fabricated metrics. Matching is+ // case/whitespace-normalized so a cosmetic LLM rewrite doesn't silently+ // drop real provenance.+ const normalizeQuery = (q) => q.trim().toLowerCase();+ const candidateByQuery = new Map(gscCandidates.map((c) => [normalizeQuery(c.query), c]));+const rows = [];for (const s of suggestions) {const topicId = await findOrCreateTopic(req.params.brandId, s.topic);+ const candidate = s.sourceQuery+ ? candidateByQuery.get(normalizeQuery(s.sourceQuery))+ : undefined;rows.push({brand_id: req.params.brandId,suggested_text: s.text,@@ -271,7 +319,17 @@ 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: 'llm',+ source: candidate ? 'gsc' : 'llm',+ source_data: candidate+ ? {+ query: candidate.query,+ impressions: candidate.impressions,+ clicks: candidate.clicks,+ avgPosition: candidate.avgPosition,+ badge: candidate.badge,+ competitionIndex: candidate.competitionIndex ?? null,+ }+ : null,status: 'new',expires_at: expiresAt,});diff --git a/supabase/migrations/00048_gsc_suggestion_support.sql b/supabase/migrations/00048_gsc_suggestion_support.sqlnew file mode 100644index 000000000..9af64ed4d--- /dev/null+++ b/supabase/migrations/00048_gsc_suggestion_support.sql@@ -0,0 +1,51 @@+-- GSC-fed prompt suggestions (#648).+--+-- 1. prompt_suggestions.source_data — provenance for 'gsc'-sourced rows+-- (original query, impressions, clicks, rationale badge, competition).+-- 2. gsc_candidate_queries() — server-side aggregation of the candidate+-- mining window so the app never ships tens of thousands of daily rows+-- over the wire just to group them.+-- 3. dataforseo_competition_cache — 30-day cache for competition lookups so+-- repeat suggestion refreshes cost zero new DataForSEO calls. Service+-- role only (RLS enabled, no policies).++ALTER TABLE public.prompt_suggestions ADD COLUMN source_data jsonb;++-- The live table's source check predates 'gsc' — extend it.+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]));++CREATE FUNCTION public.gsc_candidate_queries(+ p_brand_id uuid,+ p_since date,+ p_min_impressions integer+)+RETURNS TABLE(query text, impressions bigint, clicks bigint, avg_position double precision)+LANGUAGE sql+STABLE+AS $$+ SELECT s.query,+ sum(s.impressions) AS impressions,+ sum(s.clicks) AS clicks,+ avg(s.position) AS avg_position+ FROM public.gsc_query_stats s+ WHERE s.brand_id = p_brand_id+ AND s.date >= p_since+ GROUP BY s.query+ HAVING sum(s.impressions) >= p_min_impressions+ ORDER BY sum(s.impressions) DESC+ LIMIT 200;+$$;++CREATE TABLE public.dataforseo_competition_cache (+ keyword text NOT NULL,+ location_code integer NOT NULL DEFAULT 0,+ language_code text NOT NULL DEFAULT '',+ competition_index integer,+ competition text,+ fetched_at timestamptz NOT NULL DEFAULT now(),+ PRIMARY KEY (keyword, location_code, language_code)+);++ALTER TABLE public.dataforseo_competition_cache ENABLE ROW LEVEL SECURITY;diff --git a/supabase/schema.sql b/supabase/schema.sqlindex 153f18f81..a96e78f25 100644--- a/supabase/schema.sql+++ b/supabase/schema.sql@@ -5007,3 +5007,58 @@ CREATE POLICY "gsc_query_stats: member select" ON public.gsc_query_statsGRANT SELECT ON public.gsc_query_stats TO authenticated;+-- ─────────────────────────────────────────────────────────────────────────+-- migrations/00048_gsc_suggestion_support.sql+-- ─────────────────────────────────────────────────────────────────────────+-- GSC-fed prompt suggestions (#648).+--+-- 1. prompt_suggestions.source_data — provenance for 'gsc'-sourced rows+-- (original query, impressions, clicks, rationale badge, competition).+-- 2. gsc_candidate_queries() — server-side aggregation of the candidate+-- mining window so the app never ships tens of thousands of daily rows+-- over the wire just to group them.+-- 3. dataforseo_competition_cache — 30-day cache for competition lookups so+-- repeat suggestion refreshes cost zero new DataForSEO calls. Service+-- role only (RLS enabled, no policies).++ALTER TABLE public.prompt_suggestions ADD COLUMN source_data jsonb;++-- The live table's source check predates 'gsc' — extend it.+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]));++CREATE FUNCTION public.gsc_candidate_queries(+ p_brand_id uuid,+ p_since date,+ p_min_impressions integer+)+RETURNS TABLE(query text, impressions bigint, clicks bigint, avg_position double precision)+LANGUAGE sql+STABLE+AS $$+ SELECT s.query,+ sum(s.impressions) AS impressions,+ sum(s.clicks) AS clicks,+ avg(s.position) AS avg_position+ FROM public.gsc_query_stats s+ WHERE s.brand_id = p_brand_id+ AND s.date >= p_since+ GROUP BY s.query+ HAVING sum(s.impressions) >= p_min_impressions+ ORDER BY sum(s.impressions) DESC+ LIMIT 200;+$$;++CREATE TABLE public.dataforseo_competition_cache (+ keyword text NOT NULL,+ location_code integer NOT NULL DEFAULT 0,+ language_code text NOT NULL DEFAULT '',+ competition_index integer,+ competition text,+ fetched_at timestamptz NOT NULL DEFAULT now(),+ PRIMARY KEY (keyword, location_code, language_code)+);++ALTER TABLE public.dataforseo_competition_cache ENABLE ROW LEVEL SECURITY;+diff --git a/web/src/app/[locale]/(dashboard)/dashboard/prompts/_suggestions-card.tsx b/web/src/app/[locale]/(dashboard)/dashboard/prompts/_suggestions-card.tsxindex 3f65bd284..ae374a20f 100644--- a/web/src/app/[locale]/(dashboard)/dashboard/prompts/_suggestions-card.tsx+++ b/web/src/app/[locale]/(dashboard)/dashboard/prompts/_suggestions-card.tsx@@ -1,6 +1,7 @@'use client';-import { useEffect, useState, useCallback, useTransition } from 'react';+import { useEffect, useState, useCallback, useTransition, useRef } from 'react';+import { createPortal } from 'react-dom';import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';import { Badge } from '@/components/ui/badge';import { Button } from '@/components/ui/button';@@ -16,6 +17,7 @@ import {ChevronDown,ChevronRight,AlertTriangle,+ SearchCheck,} from 'lucide-react';import { toast } from 'sonner';import {@@ -24,8 +26,72 @@ import {acceptSuggestion,dismissSuggestion,type PromptSuggestion,+ type GscSuggestionBadge,} from '@/lib/actions/prompt-suggestions';+const GSC_BADGES: Record<GscSuggestionBadge, { label: string; tooltip: string }> = {+ protect_traffic: {+ label: 'Protect traffic',+ tooltip:+ 'This query drives real clicks to your site today. People increasingly ask AI assistants the same questions — track it so AI answers don\u2019t erode traffic you already earn.',+ },+ capture_demand: {+ label: 'Capture demand',+ tooltip:+ 'People search this heavily on Google and you appear in results, but almost nobody clicks through. Being cited in AI answers is a second chance to capture this proven demand.',+ },+ low_competition: {+ label: 'Low competition',+ tooltip:+ 'Advertiser competition on this term is low \u2014 becoming the answer AI assistants cite is a cheap win here.',+ },+};++/**+ * Portal-based hover/focus tooltip (same pattern as the Insights InfoTip) —+ * native title attributes are delayed and unreliable, which read as broken.+ */+function HoverTip({ content, children }: { content: string; children: React.ReactNode }) {+ const [pos, setPos] = useState<{ x: number; y: number } | null>(null);+ const ref = useRef<HTMLSpanElement>(null);++ function show() {+ const r = ref.current?.getBoundingClientRect();+ if (r) setPos({ x: r.left + r.width / 2, y: r.bottom + 6 });+ }+ const hide = () => setPos(null);++ return (+ <>+ <span+ ref={ref}+ tabIndex={0}+ className="inline-flex cursor-help rounded-sm focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"+ onMouseEnter={show}+ onMouseLeave={hide}+ onFocus={show}+ onBlur={hide}+ onKeyDown={(e) => {+ if (e.key === 'Escape') hide();+ }}+ >+ {children}+ </span>+ {pos &&+ createPortal(+ <div+ role="tooltip"+ style={{ left: pos.x, top: pos.y, transform: 'translateX(-50%)' }}+ className="pointer-events-none fixed z-[9999] w-64 rounded-md border bg-popover px-3 py-2 text-xs text-popover-foreground shadow-md"+ >+ {content}+ </div>,+ document.body,+ )}+ </>+ );+}+interface Props {brandId: string;onAccepted?: () => void;@@ -273,11 +339,35 @@ export function SuggestionsCard({ brandId, onAccepted }: Props) {{s.topicName}</Badge>)}- {s.estVolume != null && s.estVolume > 0 && (+ {/* GSC rows carry real impressions — showing the modeled+ estimate next to measured data reads as a contradiction. */}+ {s.estVolume != null && s.estVolume > 0 && s.source !== 'gsc' && (<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 && (+ <>+ <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.`}+ >+ <Badge+ variant="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+ </Badge>+ </HoverTip>+ {s.sourceData.badge && (+ <HoverTip content={GSC_BADGES[s.sourceData.badge].tooltip}>+ <Badge variant="outline" className="text-xs">+ {GSC_BADGES[s.sourceData.badge].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 f7eaa747d..4ce914094 100644--- a/web/src/lib/actions/prompt-suggestions.ts+++ b/web/src/lib/actions/prompt-suggestions.ts@@ -7,6 +7,17 @@ import { API_BASE_URL } from '@/config/api';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;@@ -15,7 +26,8 @@ export interface PromptSuggestion {topicId: string | null;reason: string | null;estVolume: number | null;- source: 'llm' | 'heuristic';+ source: 'llm' | 'heuristic' | 'gsc';+ sourceData: GscSuggestionSourceData | null;status: 'new' | 'added' | 'dismissed';generatedAt: string;expiresAt: string;@@ -29,7 +41,8 @@ interface SuggestionRow {topic_id: string | null;reason: string | null;est_volume: number | null;- source: 'llm' | 'heuristic';+ source: 'llm' | 'heuristic' | 'gsc';+ source_data: GscSuggestionSourceData | null;status: 'new' | 'added' | 'dismissed';generated_at: string;expires_at: string;@@ -45,6 +58,7 @@ function mapRow(row: SuggestionRow): PromptSuggestion {reason: row.reason,estVolume: row.est_volume,source: row.source,+ sourceData: row.source_data ?? null,status: row.status,generatedAt: row.generated_at,expiresAt: row.expires_at,diff --git a/web/src/types/supabase.ts b/web/src/types/supabase.tsindex 8dd0930df..d66907fa4 100644--- a/web/src/types/supabase.ts+++ b/web/src/types/supabase.ts@@ -444,6 +444,33 @@ export type Database = {},];};+ dataforseo_competition_cache: {+ Row: {+ competition: string | null;+ competition_index: number | null;+ fetched_at: string;+ keyword: string;+ language_code: string;+ location_code: number;+ };+ Insert: {+ competition?: string | null;+ competition_index?: number | null;+ fetched_at?: string;+ keyword: string;+ language_code?: string;+ location_code?: number;+ };+ Update: {+ competition?: string | null;+ competition_index?: number | null;+ fetched_at?: string;+ keyword?: string;+ language_code?: string;+ location_code?: number;+ };+ Relationships: [];+ };gsc_query_stats: {Row: {brand_id: string;@@ -913,6 +940,7 @@ export type Database = {id: string;reason: string | null;source: string;+ source_data: Json | null;status: string;suggested_text: string;topic_id: string | null;@@ -929,6 +957,7 @@ export type Database = {id?: string;reason?: string | null;source?: string;+ source_data?: Json | null;status?: string;suggested_text: string;topic_id?: string | null;@@ -945,6 +974,7 @@ export type Database = {id?: string;reason?: string | null;source?: string;+ source_data?: Json | null;status?: string;suggested_text?: string;topic_id?: string | null;