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(server): record competitor mention positions on tracking results (#572)
Gökhan Geyikc130c9755679
diff --git a/server/src/lib/response-parser.js b/server/src/lib/response-parser.jsindex 5631a5e6e..95e5ee857 100644--- a/server/src/lib/response-parser.js+++ b/server/src/lib/response-parser.js@@ -97,16 +97,23 @@ function firstOccurrenceIndex(text, term) {}/**- * Where the brand lands in the answer's mention order, among the brand and- * its tracked competitors. Deterministic: earliest word-boundary occurrence- * of each entity's name/domain in the URL-stripped answer text.+ * Where each tracked entity (the brand and its competitors) lands in the+ * answer's mention order. Deterministic: earliest word-boundary occurrence+ * of each entity's name/domain in the URL-stripped answer text; an entity's+ * rank is 1 + the number of other mentioned entities named before it.*- * @returns {{ mentionPosition: number | null, mentionedEntityCount: number }}+ * @returns {{+ * mentionPosition: number | null,+ * mentionedEntityCount: number,+ * competitorPositions: Map<string, number>,+ * }}* mentionPosition — 1-based rank of the brand's first mention (1 = named* first), null when the brand isn't mentioned at all.- * mentionedEntityCount — how many of the tracked entities (brand +- * competitors) the answer mentions; 0 marks "computed, nothing found",- * while NULL in the database means "not computed yet" (backfill marker).+ * mentionedEntityCount — how many of the tracked entities the answer+ * mentions; 0 marks "computed, nothing found", while NULL in the database+ * means "not computed yet" (backfill marker).+ * competitorPositions — competitor id → 1-based rank, only for+ * competitors the answer actually mentions.*/export function computeMentionPosition(text, brand, competitors = []) {const cleanText = stripUrls(text);@@ -121,15 +128,24 @@ export function computeMentionPosition(text, brand, competitors = []) {};const brandIndex = entityFirstIndex([brand.brandName, ...(brand.domains || [])]);- const competitorIndexes = (competitors || [])- .map((comp) => entityFirstIndex([comp.name, ...(comp.domain ? [comp.domain] : [])]))- .filter((idx) => idx >= 0);+ const mentionedCompetitors = (competitors || [])+ .map((comp) => ({+ id: comp.id,+ index: entityFirstIndex([comp.name, ...(comp.domain ? [comp.domain] : [])]),+ }))+ .filter((comp) => comp.index >= 0);- const mentionedEntityCount = competitorIndexes.length + (brandIndex >= 0 ? 1 : 0);- if (brandIndex < 0) return { mentionPosition: null, mentionedEntityCount };+ const allIndexes = [+ ...mentionedCompetitors.map((comp) => comp.index),+ ...(brandIndex >= 0 ? [brandIndex] : []),+ ];+ const rankOf = (index) => allIndexes.filter((other) => other < index).length + 1;- const namedBefore = competitorIndexes.filter((idx) => idx < brandIndex).length;- return { mentionPosition: namedBefore + 1, mentionedEntityCount };+ return {+ mentionPosition: brandIndex >= 0 ? rankOf(brandIndex) : null,+ mentionedEntityCount: allIndexes.length,+ competitorPositions: new Map(mentionedCompetitors.map((comp) => [comp.id, rankOf(comp.index)])),+ };}/**@@ -162,6 +178,13 @@ export function parseResponse(response, brand, sentiment = 'neutral', competitorsentiment,});+ // --- Mention order among brand + competitors (position signal) ---+ const { mentionPosition, mentionedEntityCount, competitorPositions } = computeMentionPosition(+ text,+ brand,+ competitors,+ );+// --- Competitor mentions (on URL-stripped text) ---const competitorMentions = competitors.map((comp) => {let compMentions = countOccurrences(cleanText, comp.name);@@ -193,16 +216,10 @@ export function parseResponse(response, brand, sentiment = 'neutral', competitormention_count: compMentions,citation_count: compCitations,visibility_score: compScore,+ mention_position: competitorPositions.get(comp.id) ?? null,};});- // --- Mention order among brand + competitors (position signal) ---- const { mentionPosition, mentionedEntityCount } = computeMentionPosition(- text,- brand,- competitors,- );-return {mentionCount,citationCount,diff --git a/server/src/lib/response-parser.test.js b/server/src/lib/response-parser.test.jsindex 995a3f932..1c97b0294 100644--- a/server/src/lib/response-parser.test.js+++ b/server/src/lib/response-parser.test.js@@ -273,7 +273,7 @@ describe('response-parser', () => {it('ranks the brand first when it is named before every competitor', () => {const text = 'Acme leads the market, ahead of Globex and Initech.';- expect(computeMentionPosition(text, brand, competitors)).toEqual({+ expect(computeMentionPosition(text, brand, competitors)).toMatchObject({mentionPosition: 1,mentionedEntityCount: 3,});@@ -281,7 +281,7 @@ describe('response-parser', () => {it('ranks the brand by how many competitors are named before it', () => {const text = 'Top picks: Globex, Initech, and also Acme as a budget option.';- expect(computeMentionPosition(text, brand, competitors)).toEqual({+ expect(computeMentionPosition(text, brand, competitors)).toMatchObject({mentionPosition: 3,mentionedEntityCount: 3,});@@ -289,7 +289,7 @@ describe('response-parser', () => {it('returns a null position when the brand is not mentioned', () => {const text = 'Globex and Umbrella dominate this space.';- expect(computeMentionPosition(text, brand, competitors)).toEqual({+ expect(computeMentionPosition(text, brand, competitors)).toMatchObject({mentionPosition: null,mentionedEntityCount: 2,});@@ -297,7 +297,7 @@ describe('response-parser', () => {it('counts a domain occurrence as a brand mention for positioning', () => {const text = 'Globex is popular, but acme.com has the best docs.';- expect(computeMentionPosition(text, brand, competitors)).toEqual({+ expect(computeMentionPosition(text, brand, competitors)).toMatchObject({mentionPosition: 2,mentionedEntityCount: 2,});@@ -305,14 +305,14 @@ describe('response-parser', () => {it('ignores names that only appear inside URLs', () => {const text = 'Initech is the leader. See [comparison](https://acme.com/vs) for details.';- expect(computeMentionPosition(text, brand, competitors)).toEqual({+ expect(computeMentionPosition(text, brand, competitors)).toMatchObject({mentionPosition: null,mentionedEntityCount: 1,});});it('reports zero entities for an answer that names nobody', () => {- expect(computeMentionPosition('Nothing relevant here.', brand, competitors)).toEqual({+ expect(computeMentionPosition('Nothing relevant here.', brand, competitors)).toMatchObject({mentionPosition: null,mentionedEntityCount: 0,});@@ -320,10 +320,46 @@ describe('response-parser', () => {it("uses each entity's earliest occurrence, not its last", () => {const text = 'Globex... later Acme appears. Globex again at the end.';- expect(computeMentionPosition(text, brand, competitors)).toEqual({+ expect(computeMentionPosition(text, brand, competitors)).toMatchObject({mentionPosition: 2,mentionedEntityCount: 2,});});++ it('ranks each mentioned competitor among all mentioned entities', () => {+ const text = 'Globex leads, then Acme, with Umbrella as a distant third.';+ const result = computeMentionPosition(text, brand, competitors);+ expect(result.mentionPosition).toBe(2);+ expect(result.competitorPositions.get('c1')).toBe(1); // Globex+ expect(result.competitorPositions.get('c3')).toBe(3); // Umbrella+ expect(result.competitorPositions.has('c2')).toBe(false); // Initech absent+ });++ it('ranks competitors even when the brand is not mentioned', () => {+ const text = 'Initech and Globex dominate here.';+ const result = computeMentionPosition(text, brand, competitors);+ expect(result.mentionPosition).toBeNull();+ expect(result.competitorPositions.get('c2')).toBe(1); // Initech+ expect(result.competitorPositions.get('c1')).toBe(2); // Globex+ });+ });++ describe('competitor mention positions in parseResponse', () => {+ it('embeds each competitor rank into competitor_mentions entries', () => {+ const brand = { brandName: 'Acme', domains: ['acme.com'] };+ const competitors = [+ { id: 'c1', name: 'Globex', domain: 'globex.com' },+ { id: 'c2', name: 'Initech', domain: 'initech.com' },+ ];+ const response = {+ text: 'Globex is first here, Acme second, and nobody mentions the rest.',+ citations: [],+ };+ const result = parseResponse(response, brand, 'neutral', competitors);+ const byId = new Map(result.competitorMentions.map((c) => [c.competitor_id, c]));+ expect(byId.get('c1').mention_position).toBe(1);+ expect(byId.get('c2').mention_position).toBeNull();+ expect(result.mentionPosition).toBe(2);+ });});});diff --git a/server/src/scripts/backfill-mention-position.js b/server/src/scripts/backfill-mention-position.jsindex 3d7dc80c2..227940f13 100644--- a/server/src/scripts/backfill-mention-position.js+++ b/server/src/scripts/backfill-mention-position.js@@ -1,6 +1,9 @@/**- * Backfill mention_position / mentioned_entity_count on historical- * prompt_results from the stored answer text (00038).+ * Backfill mention-position signals on historical prompt_results from the+ * stored answer text (00038):+ *+ * - mention_position / mentioned_entity_count columns (own brand)+ * - mention_position inside each competitor_mentions entry (competitors)** Run: `node src/scripts/backfill-mention-position.js [--days N] [--brand <id>] [--dry-run]`*@@ -8,9 +11,9 @@* (churned orgs' data never surfaces in any dashboard, so recomputing it is* wasted work). Narrow further with --brand, or --days to limit history.*- * Idempotent: only rows with `mentioned_entity_count IS NULL` are touched —- * that column is the "computed" marker (0 = computed, nothing found), so- * re-running skips everything already processed. Batches are small and+ * Idempotent: rows whose columns are set AND whose competitor entries all+ * carry a mention_position key are skipped, so re-running only processes+ * what's missing. Batches are small, concurrent in bounded chunks, and* paced so the shared database stays responsive.** Positions are computed against the brand's CURRENT competitor roster —@@ -21,8 +24,22 @@ import 'dotenv/config';import supabaseAdmin from '../config/supabase.js';import { computeMentionPosition } from '../lib/response-parser.js';-const BATCH_SIZE = 500;+const BATCH_SIZE = 250;const BATCH_PAUSE_MS = 250;+const CONCURRENCY = 20;++/** Retry transient network failures (connection resets on long walks). */+async function withRetry(fn, label) {+ for (let attempt = 1; ; attempt++) {+ try {+ return await fn();+ } catch (err) {+ if (attempt >= 4) throw err;+ console.warn(` retry ${attempt}/3 after error in ${label}: ${err.message}`);+ await sleep(attempt * 2000);+ }+ }+}const args = process.argv.slice(2);const dryRun = args.includes('--dry-run');@@ -63,48 +80,67 @@ async function brandContext(brand) {};}+function rowNeedsWork(row) {+ if (row.mentioned_entity_count == null) return true;+ const entries = Array.isArray(row.competitor_mentions) ? row.competitor_mentions : [];+ return entries.some((entry) => !('mention_position' in entry));+}+async function backfillBrand(brand) {const { brandInfo, competitors } = await brandContext(brand);let updated = 0;+ let skipped = 0;- for (;;) {- let query = supabaseAdmin- .from('prompt_results')- .select('id, response')- .eq('brand_id', brand.id)- .is('mentioned_entity_count', null)- .not('response', 'is', null)- .order('created_at', { ascending: false })- .limit(BATCH_SIZE);- if (daysArg) {- query = query.gte('created_at', new Date(Date.now() - daysArg * 86_400_000).toISOString());- }+ // Offset paging over a stable ordering: updates never change which rows+ // the filter selects, so pages stay consistent across the walk.+ for (let offset = 0; ; offset += BATCH_SIZE) {+ const fetchPage = () => {+ let query = supabaseAdmin+ .from('prompt_results')+ .select('id, response, competitor_mentions, mentioned_entity_count')+ .eq('brand_id', brand.id)+ .not('response', 'is', null)+ .order('created_at', { ascending: false })+ .order('id', { ascending: true })+ .range(offset, offset + BATCH_SIZE - 1);+ if (daysArg) {+ query = query.gte('created_at', new Date(Date.now() - daysArg * 86_400_000).toISOString());+ }+ return query;+ };- const { data: rows, error } = await query;+ const { data: rows, error } = await withRetry(fetchPage, 'page fetch');if (error) throw new Error(error.message);if (!rows?.length) break;- // Update in small concurrent chunks: one-by-one round-trips would take- // hours over the full history, while unbounded concurrency would hammer- // the shared database.- const CONCURRENCY = 20;for (let i = 0; i < rows.length; i += CONCURRENCY) {const chunk = rows.slice(i, i + CONCURRENCY);await Promise.all(chunk.map(async (row) => {- const { mentionPosition, mentionedEntityCount } = computeMentionPosition(- row.response ?? '',- brandInfo,- competitors,- );+ if (!rowNeedsWork(row)) {+ skipped++;+ return;+ }+ const { mentionPosition, mentionedEntityCount, competitorPositions } =+ computeMentionPosition(row.response ?? '', brandInfo, competitors);+ const entries = Array.isArray(row.competitor_mentions) ? row.competitor_mentions : [];+ const annotated = entries.map((entry) => ({+ ...entry,+ mention_position: competitorPositions.get(entry.competitor_id) ?? null,+ }));if (!dryRun) {- const { error: updateErr } = await supabaseAdmin- .from('prompt_results')- .update({- mention_position: mentionPosition,- mentioned_entity_count: mentionedEntityCount,- })- .eq('id', row.id);+ const { error: updateErr } = await withRetry(+ () =>+ supabaseAdmin+ .from('prompt_results')+ .update({+ mention_position: mentionPosition,+ mentioned_entity_count: mentionedEntityCount,+ competitor_mentions: annotated,+ })+ .eq('id', row.id),+ 'row update',+ );if (updateErr) throw new Error(updateErr.message);}updated++;@@ -112,8 +148,7 @@ async function backfillBrand(brand) {);}- console.log(` ${brand.name}: ${updated} rows${dryRun ? ' (dry run)' : ''}`);- if (dryRun) break; // dry run would loop forever — nothing gets marked+ console.log(` ${brand.name}: ${updated} updated, ${skipped} already done`);if (rows.length < BATCH_SIZE) break;await sleep(BATCH_PAUSE_MS);}@@ -131,5 +166,5 @@ let total = 0;for (const brand of brands) {total += await backfillBrand(brand);}-console.log(`Done. ${total} row(s) ${dryRun ? 'would be' : ''} updated.`);+console.log(`Done. ${total} row(s) ${dryRun ? 'would be ' : ''}updated.`);process.exit(0);