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(action-center): measure opportunity actions on their own basket (#956)
Gökhan Geyika275b5b908f3
diff --git a/server/src/lib/action-center/basket-metrics.js b/server/src/lib/action-center/basket-metrics.jsnew file mode 100644index 000000000..1d691cb05--- /dev/null+++ b/server/src/lib/action-center/basket-metrics.js@@ -0,0 +1,116 @@+/**+ * Measuring an action sent from a content opportunity on its own basket+ * (#857, Phase 4).+ *+ * validate.js measures an action's KPIs over a window before it was raised+ * and one after it closed. For signal-driven actions it reads the whole+ * brand. A content opportunity answers a handful of the brand's prompts, so+ * its action reads the same windows over just those prompts and the pages it+ * worked on — the spec's "measured for the same basket".+ */++import supabaseAdmin from '../../config/supabase.js';++/** What a basket is measured on, and in what unit. Every one reads higher-is-better. */+export const BASKET_KPIS = {+ ai_visibility: 'percent',+ share_of_voice: 'percent',+ // The brand's visibility minus the strongest competitor's; negative while behind.+ competitor_lead: 'points',+ mentions: 'count',+ citations: 'count',+ ai_referral_traffic: 'sessions',+};++const round1 = (n) => Math.round(n * 10) / 10;++/**+ * The pages as the three keys the metrics function matches on: URL without+ * scheme, www., query, fragment or trailing slash; host without www.; and+ * the GA landing-page path.+ */+export function pageScope(urls) {+ const keys = new Set();+ const domains = new Set();+ const paths = new Set();+ for (const raw of urls || []) {+ let url;+ try {+ url = new URL(raw);+ } catch {+ continue;+ }+ const host = url.hostname.toLowerCase().replace(/^www\./, '');+ const path = url.pathname.replace(/\/+$/, '').toLowerCase();+ keys.add(`${host}${path}`);+ domains.add(host);+ paths.add(url.pathname.replace(/\/+$/, '') || '/');+ }+ return { keys: [...keys], domains: [...domains], paths: [...paths] };+}++/**+ * The metrics from one window's raw figures. A metric the window cannot+ * answer is null — no answers for the prompts, no pages to cite, no GA — so+ * it is reported as unmeasured rather than as zero.+ */+export function basketValues(raw, { pageCount }) {+ const cells = Number(raw.cells) || 0;+ const visible = Number(raw.visible) || 0;+ const competitors = Number(raw.competitor_visible_total) || 0;+ const visibility = cells ? (visible / cells) * 100 : null;+ return {+ ai_visibility: visibility === null ? null : round1(visibility),+ share_of_voice:+ visible + competitors > 0 ? round1((visible / (visible + competitors)) * 100) : null,+ competitor_lead:+ visibility === null+ ? null+ : round1(visibility - ((Number(raw.top_competitor_visible) || 0) / cells) * 100),+ mentions: cells ? Number(raw.mention_answers) || 0 : null,+ citations: pageCount ? Number(raw.page_citations) || 0 : null,+ ai_referral_traffic: pageCount && raw.ga_connected ? Number(raw.page_ai_sessions) || 0 : null,+ };+}++/**+ * The prompts and pages an action covers. Actions sent before the payload+ * carried prompt ids take them from the opportunity's clusters as they are now.+ */+export async function basketScope(action) {+ const payload = action.payload || {};+ let promptIds = Array.isArray(payload.promptIds) ? payload.promptIds : [];+ if (!promptIds.length && payload.opportunityId) {+ const { data: opp } = await supabaseAdmin+ .from('content_opportunities')+ .select('cluster_id, related_cluster_ids')+ .eq('id', payload.opportunityId)+ .maybeSingle();+ const clusterIds = [opp?.cluster_id, ...(opp?.related_cluster_ids || [])].filter(Boolean);+ if (clusterIds.length) {+ const { data: members, error } = await supabaseAdmin+ .from('prompt_cluster_members')+ .select('prompt_id')+ .in('cluster_id', clusterIds);+ if (error) throw new Error(error.message);+ promptIds = (members || []).map((m) => m.prompt_id);+ }+ }+ return { promptIds, pages: Array.isArray(payload.pages) ? payload.pages : [] };+}++/** The basket's metrics over one window. */+export async function measureBasket(brandId, scope, from, to) {+ const pages = pageScope(scope.pages);+ const { data, error } = await supabaseAdmin.rpc('opportunity_basket_metrics', {+ p_brand_id: brandId,+ p_prompt_ids: scope.promptIds,+ p_page_keys: pages.keys,+ p_page_domains: pages.domains,+ p_page_paths: pages.paths,+ p_from: from,+ p_to: to,+ });+ if (error) throw new Error(`opportunity_basket_metrics: ${error.message}`);+ return basketValues(data || {}, { pageCount: pages.keys.length });+}diff --git a/server/src/lib/action-center/basket-metrics.test.js b/server/src/lib/action-center/basket-metrics.test.jsnew file mode 100644index 000000000..fad5c880b--- /dev/null+++ b/server/src/lib/action-center/basket-metrics.test.js@@ -0,0 +1,65 @@+import { describe, expect, it, vi } from 'vitest';++vi.mock('../../config/supabase.js', () => ({ default: {} }));++const { BASKET_KPIS, basketValues, pageScope } = await import('./basket-metrics.js');++describe('pageScope', () => {+ it('turns page URLs into citation keys, hosts and GA paths', () => {+ expect(+ pageScope([+ 'https://www.Example.com/Blog/Post/?utm=x#top',+ 'https://docs.example.com/',+ 'not a url',+ ]),+ ).toEqual({+ keys: ['example.com/blog/post', 'docs.example.com'],+ domains: ['example.com', 'docs.example.com'],+ paths: ['/Blog/Post', '/'],+ });+ });+});++describe('basketValues', () => {+ const raw = {+ cells: 40,+ visible: 10,+ mention_answers: 12,+ competitor_visible_total: 30,+ top_competitor_visible: 20,+ page_citations: 7,+ ga_connected: true,+ page_ai_sessions: 55,+ };++ it('measures the basket', () => {+ expect(basketValues(raw, { pageCount: 2 })).toEqual({+ ai_visibility: 25,+ share_of_voice: 25,+ // 25% against the strongest competitor's 50%.+ competitor_lead: -25,+ mentions: 12,+ citations: 7,+ ai_referral_traffic: 55,+ });+ });++ it('leaves unanswerable metrics unmeasured instead of zero', () => {+ const none = basketValues(+ { ...raw, cells: 0, visible: 0, competitor_visible_total: 0 },+ {+ pageCount: 0,+ },+ );+ expect(Object.values(none).every((v) => v === null)).toBe(true);+ expect(+ basketValues({ ...raw, ga_connected: false }, { pageCount: 2 }).ai_referral_traffic,+ ).toBe(null);+ });++ it('covers every basket KPI', () => {+ expect(Object.keys(basketValues(raw, { pageCount: 1 })).sort()).toEqual(+ Object.keys(BASKET_KPIS).sort(),+ );+ });+});diff --git a/server/src/lib/action-center/from-opportunity.js b/server/src/lib/action-center/from-opportunity.jsindex d40c940c2..56ac29b26 100644--- a/server/src/lib/action-center/from-opportunity.js+++ b/server/src/lib/action-center/from-opportunity.js@@ -122,6 +122,18 @@ export async function sendToActionCenter(opportunity, { assetKey = null, userIdconst sd = opportunity.source_data || {};const prompts = sd.prompts || [];+ // The prompts the action is measured on (basket-metrics.js), fixed at send+ // time so a later re-clustering does not change what it is judged by.+ const clusterIds = [opportunity.cluster_id, ...(opportunity.related_cluster_ids || [])].filter(+ Boolean,+ );+ const { data: members, error: membersErr } = clusterIds.length+ ? await supabaseAdmin+ .from('prompt_cluster_members')+ .select('prompt_id')+ .in('cluster_id', clusterIds)+ : { data: [], error: null };+ if (membersErr) throw new Error(membersErr.message);const payload = {source: OPPORTUNITY_ACTION_KIND,opportunityId: opportunity.id,@@ -136,6 +148,7 @@ export async function sendToActionCenter(opportunity, { assetKey = null, userIdtitle,})),pages: [...new Set(chosen.flatMap((a) => (a.pages || []).map((p) => p.url)))],+ promptIds: (members || []).map((m) => m.prompt_id),targetEntity: 'prompts',targetCount: prompts.length,targets: prompts.slice(0, 50),diff --git a/server/src/lib/action-center/validate.js b/server/src/lib/action-center/validate.jsindex 115093575..59567c6f6 100644--- a/server/src/lib/action-center/validate.js+++ b/server/src/lib/action-center/validate.js@@ -27,6 +27,7 @@ import supabaseAdmin from '../../config/supabase.js';import { computeAiVisibilityScore } from '../../config/visibility-score.js';import { logger } from '../logger.js';import { resolve } from '../../config/action-engine.js';+import { BASKET_KPIS, basketScope, measureBasket } from './basket-metrics.js';const DAY_MS = 86_400_000;@@ -233,6 +234,36 @@ export async function validateAction(action, { now = new Date() } = {}) {// action, and would file most recent work as a decline.if (afterWindow.to >= utcDay(now)) return null;+ // An action sent from a content opportunity is measured on its own prompts+ // and pages; the brand-wide numbers would bury a single piece of content.+ if (action.kind === 'content_opportunity') {+ const scope = await basketScope(action);+ const [before, after] = await Promise.all([+ measureBasket(action.brand_id, scope, beforeWindow.from, beforeWindow.to),+ measureBasket(action.brand_id, scope, afterWindow.from, afterWindow.to),+ ]);+ const metrics = Object.entries(BASKET_KPIS).map(([metric, unit]) => ({+ metric,+ unit,+ before: before[metric],+ after: after[metric],+ }));+ const outcome = deriveOutcome(metrics);+ await write(+ action.id,+ {+ measuredAt: now.toISOString(),+ beforeWindow,+ afterWindow,+ metrics,+ scope: { kind: 'basket', prompts: scope.promptIds.length, pages: scope.pages.length },+ },+ outcome,+ now,+ );+ return outcome;+ }+const kpiKeys = (action.kpi_keys ?? []).filter((key) => key in MEASURABLE_KPIS);// An action with no success metrics has nothing to measure. That is a gap@@ -289,7 +320,7 @@ export async function sweepActionValidation({ now = new Date() } = {}) {const cutoff = new Date(now.getTime() - VALIDATION_WAIT_DAYS * DAY_MS).toISOString();const { data, error } = await supabaseAdmin.from('actions')- .select('id, brand_id, kpi_keys, created_at, completed_at')+ .select('id, brand_id, kind, payload, kpi_keys, created_at, completed_at').eq('status', 'completed').eq('outcome', 'pending_measurement').not('completed_at', 'is', null)diff --git a/supabase/migrations/00113_opportunity_basket_metrics.sql b/supabase/migrations/00113_opportunity_basket_metrics.sqlnew file mode 100644index 000000000..c61f6413a--- /dev/null+++ b/supabase/migrations/00113_opportunity_basket_metrics.sql@@ -0,0 +1,91 @@+-- What an action sent from a content opportunity is measured on (#857,+-- Phase 4): the opportunity's own basket, not the whole brand.+--+-- The Action Center measures an action's KPIs over a window before it was+-- raised and one after it closed. For signal-driven actions that reads the+-- whole brand, which is right for them. For a piece of content answering 20+-- of a brand's 700 prompts, the brand-wide numbers bury its effect, so these+-- actions read the same windows over just their prompts and pages.+--+-- One call returns the raw figures for one window; the server turns them+-- into metrics. Prompt figures come from the Insights rollups (00066), page+-- citations from the citation tables, page traffic from GA's AI traffic.+--+-- p_page_keys are page URLs lower-cased without scheme, www., query,+-- fragment or trailing slash; p_page_domains their hosts without www., which+-- narrows citation_urls through its domain index before the key match.+-- p_page_paths are the same pages as GA landing-page paths.++create or replace function public.opportunity_basket_metrics(+ p_brand_id uuid,+ p_prompt_ids uuid[],+ p_page_keys text[],+ p_page_domains text[],+ p_page_paths text[],+ p_from date,+ p_to date+)+returns jsonb+language sql+stable+set search_path = public+as $$+ with cells as (+ select count(*) as cells,+ count(*) filter (where has_mention or has_citation) as visible,+ coalesce(sum(answer_count) filter (where has_mention), 0) as mention_answers+ from insights_prompt_daily+ where brand_id = p_brand_id+ and day between p_from and p_to+ and prompt_id = any(p_prompt_ids)+ ),+ comp as (+ select d.competitor_id, count(*) as visible+ from insights_competitor_prompt_daily d+ join competitors c on c.id::text = d.competitor_id and c.brand_id = p_brand_id+ where d.brand_id = p_brand_id+ and d.day between p_from and p_to+ and d.prompt_id = any(p_prompt_ids)+ group by d.competitor_id+ ),+ urls as (+ select id+ from citation_urls+ where domain = any(p_page_domains)+ and rtrim(+ regexp_replace(split_part(split_part(lower(url), '#', 1), '?', 1), '^https?://(www\.)?', ''),+ '/'+ ) = any(p_page_keys)+ )+ select jsonb_build_object(+ 'cells', (select cells from cells),+ 'visible', (select visible from cells),+ 'mention_answers', (select mention_answers from cells),+ 'competitor_visible_total', (select coalesce(sum(visible), 0) from comp),+ 'top_competitor_visible', (select coalesce(max(visible), 0) from comp),+ 'page_citations', (+ select count(*)+ from prompt_result_citations+ where brand_id = p_brand_id+ and created_at >= p_from+ and created_at < p_to + 1+ and url_id in (select id from urls)+ ),+ 'ga_connected', exists (+ select 1 from ga_ai_traffic_stats+ where brand_id = p_brand_id and date between p_from and p_to+ ),+ 'page_ai_sessions', (+ select coalesce(sum(sessions), 0)+ from ga_ai_traffic_stats+ where brand_id = p_brand_id+ and date between p_from and p_to+ and coalesce(nullif(rtrim(split_part(landing_page, '?', 1), '/'), ''), '/') = any(p_page_paths)+ )+ );+$$;++revoke all on function public.opportunity_basket_metrics(uuid, uuid[], text[], text[], text[], date, date)+ from public, anon, authenticated;+grant execute on function public.opportunity_basket_metrics(uuid, uuid[], text[], text[], text[], date, date)+ to service_role;diff --git a/supabase/schema.sql b/supabase/schema.sqlindex 00eb334cf..726a644e2 100644--- a/supabase/schema.sql+++ b/supabase/schema.sql@@ -13188,3 +13188,98 @@ as $$left join prompt_daily pd on pd.day = bd.day;$$;+-- ─────────────────────────────────────────────────────────────────────────+-- migrations/00113_opportunity_basket_metrics.sql+-- ─────────────────────────────────────────────────────────────────────────+-- What an action sent from a content opportunity is measured on (#857,+-- Phase 4): the opportunity's own basket, not the whole brand.+--+-- The Action Center measures an action's KPIs over a window before it was+-- raised and one after it closed. For signal-driven actions that reads the+-- whole brand, which is right for them. For a piece of content answering 20+-- of a brand's 700 prompts, the brand-wide numbers bury its effect, so these+-- actions read the same windows over just their prompts and pages.+--+-- One call returns the raw figures for one window; the server turns them+-- into metrics. Prompt figures come from the Insights rollups (00066), page+-- citations from the citation tables, page traffic from GA's AI traffic.+--+-- p_page_keys are page URLs lower-cased without scheme, www., query,+-- fragment or trailing slash; p_page_domains their hosts without www., which+-- narrows citation_urls through its domain index before the key match.+-- p_page_paths are the same pages as GA landing-page paths.++create or replace function public.opportunity_basket_metrics(+ p_brand_id uuid,+ p_prompt_ids uuid[],+ p_page_keys text[],+ p_page_domains text[],+ p_page_paths text[],+ p_from date,+ p_to date+)+returns jsonb+language sql+stable+set search_path = public+as $$+ with cells as (+ select count(*) as cells,+ count(*) filter (where has_mention or has_citation) as visible,+ coalesce(sum(answer_count) filter (where has_mention), 0) as mention_answers+ from insights_prompt_daily+ where brand_id = p_brand_id+ and day between p_from and p_to+ and prompt_id = any(p_prompt_ids)+ ),+ comp as (+ select d.competitor_id, count(*) as visible+ from insights_competitor_prompt_daily d+ join competitors c on c.id::text = d.competitor_id and c.brand_id = p_brand_id+ where d.brand_id = p_brand_id+ and d.day between p_from and p_to+ and d.prompt_id = any(p_prompt_ids)+ group by d.competitor_id+ ),+ urls as (+ select id+ from citation_urls+ where domain = any(p_page_domains)+ and rtrim(+ regexp_replace(split_part(split_part(lower(url), '#', 1), '?', 1), '^https?://(www\.)?', ''),+ '/'+ ) = any(p_page_keys)+ )+ select jsonb_build_object(+ 'cells', (select cells from cells),+ 'visible', (select visible from cells),+ 'mention_answers', (select mention_answers from cells),+ 'competitor_visible_total', (select coalesce(sum(visible), 0) from comp),+ 'top_competitor_visible', (select coalesce(max(visible), 0) from comp),+ 'page_citations', (+ select count(*)+ from prompt_result_citations+ where brand_id = p_brand_id+ and created_at >= p_from+ and created_at < p_to + 1+ and url_id in (select id from urls)+ ),+ 'ga_connected', exists (+ select 1 from ga_ai_traffic_stats+ where brand_id = p_brand_id and date between p_from and p_to+ ),+ 'page_ai_sessions', (+ select coalesce(sum(sessions), 0)+ from ga_ai_traffic_stats+ where brand_id = p_brand_id+ and date between p_from and p_to+ and coalesce(nullif(rtrim(split_part(landing_page, '?', 1), '/'), ''), '/') = any(p_page_paths)+ )+ );+$$;++revoke all on function public.opportunity_basket_metrics(uuid, uuid[], text[], text[], text[], date, date)+ from public, anon, authenticated;+grant execute on function public.opportunity_basket_metrics(uuid, uuid[], text[], text[], text[], date, date)+ to service_role;+diff --git a/web/messages/en.json b/web/messages/en.jsonindex 7b6d9b040..89201c4b9 100644--- a/web/messages/en.json+++ b/web/messages/en.json@@ -204,6 +204,10 @@"ai_referral_traffic": {"name": "AI Referral Traffic","description": "Visits arriving from AI platforms"+ },+ "competitor_lead": {+ "name": "Lead over top competitor",+ "description": "Your visibility minus the strongest competitor's on the same prompts, in points"}},"signalCategories": {diff --git a/web/src/components/content/opportunity-basket.tsx b/web/src/components/content/opportunity-basket.tsxindex a338d9a2e..5e1ef84ff 100644--- a/web/src/components/content/opportunity-basket.tsx+++ b/web/src/components/content/opportunity-basket.tsx@@ -330,7 +330,13 @@ export function AssetsCard({const MEASURE_AFTER_DAYS = 31;const formatMetric = (value: number | null, unit: string) =>- value === null ? '—' : unit === 'percent' ? `${Math.round(value * 10) / 10}%` : String(value);+ value === null+ ? '—'+ : unit === 'percent'+ ? `${Math.round(value * 10) / 10}%`+ : unit === 'points'+ ? `${value > 0 ? '+' : ''}${Math.round(value * 10) / 10} pts`+ : String(value);/*** Where the work sent from this opportunity stands, and what it moved once