Skip to content

Open-source agentic AI Search Execution Platform. Track AI visibility, find opportunities, and let agents turn signals into prioritized actions and drafted fixes across ChatGPT, Claude, Gemini, Google AI Overviews, Google AI Mode, Perplexity, Grok, and Microsoft Copilot.

fix(citations): hostname-based citation_count + auto-recount when brand domains change (#433)

Gökhan Geyik169f23d40b8a
diff --git a/server/src/lib/citation-recount.js b/server/src/lib/citation-recount.js
new file mode 100644
index 000000000..8852de1f9
--- /dev/null
+++ b/server/src/lib/citation-recount.js
@@ -0,0 +1,67 @@
+/**
+ * Recompute `prompt_results.citation_count` for a brand from the stored
+ * citations JSONB and the brand's CURRENT domain list.
+ *
+ * citation_count is computed at tracking time and frozen into the row, so a
+ * later change to `brand_domains` silently desyncs it from what the
+ * Citations page computes live — the same "own citations" metric then shows
+ * different numbers on different surfaces. The web layer calls this through
+ * `/api/internal/recount-citations` whenever a brand's domain list changes.
+ *
+ * `visibility_score` is intentionally NOT recomputed: it is a point-in-time
+ * heuristic, and rewriting it would retroactively reshape historical trend
+ * charts. Only the citation tally is brought in line.
+ */
+
+import supabaseAdmin from '../config/supabase.js';
+import { countOwnDomainCitations } from './response-parser.js';
+import logger from './logger.js';
+
+const RECOUNT_PAGE_SIZE = 1000;
+const RECOUNT_MAX_ROWS = 200_000;
+
+export async function recountBrandCitations(brandId) {
+ const { data: domainRows, error: domainErr } = await supabaseAdmin
+ .from('brand_domains')
+ .select('domain')
+ .eq('brand_id', brandId);
+ if (domainErr) throw new Error(domainErr.message);
+ const domains = (domainRows || []).map((r) => r.domain);
+
+ let scanned = 0;
+ let updated = 0;
+
+ for (let offset = 0; offset < RECOUNT_MAX_ROWS; offset += RECOUNT_PAGE_SIZE) {
+ const { data: rows, error } = await supabaseAdmin
+ .from('prompt_results')
+ .select('id, citations, citation_count')
+ .eq('brand_id', brandId)
+ // Deterministic order so .range() pages don't shuffle between requests
+ // (citation_count updates don't touch the ordering columns).
+ .order('created_at', { ascending: true })
+ .order('id', { ascending: true })
+ .range(offset, offset + RECOUNT_PAGE_SIZE - 1);
+ if (error) throw new Error(error.message);
+
+ const batch = rows || [];
+ scanned += batch.length;
+
+ for (const row of batch) {
+ const citations = Array.isArray(row.citations) ? row.citations : [];
+ const fresh = countOwnDomainCitations(citations, domains);
+ if (fresh !== row.citation_count) {
+ const { error: updateErr } = await supabaseAdmin
+ .from('prompt_results')
+ .update({ citation_count: fresh })
+ .eq('id', row.id);
+ if (updateErr) throw new Error(updateErr.message);
+ updated++;
+ }
+ }
+
+ if (batch.length < RECOUNT_PAGE_SIZE) break;
+ }
+
+ logger.info({ brandId, scanned, updated }, '[citations] recount complete');
+ return { scanned, updated };
+}
diff --git a/server/src/lib/response-parser.js b/server/src/lib/response-parser.js
index 60b66a60e..0f08b1afa 100644
--- a/server/src/lib/response-parser.js
+++ b/server/src/lib/response-parser.js
@@ -24,6 +24,54 @@ function countOccurrences(text, term) {
return (text.match(regex) || []).length;
}
+/**
+ * Normalized hostname of a URL ("https://www.FOO.com/bar" → "foo.com").
+ * Mirrors extractHostname in web/src/lib/citations/classify.ts — keep the two
+ * in sync: citation_count must agree with the Citations page's read-time
+ * classification, or the same metric shows different numbers per surface.
+ */
+export function extractHostname(rawUrl) {
+ if (!rawUrl) return null;
+ try {
+ const url = new URL(String(rawUrl).trim());
+ let host = url.hostname.toLowerCase();
+ if (host.startsWith('www.')) host = host.slice(4);
+ return host || null;
+ } catch {
+ const match = String(rawUrl).match(/^(?:https?:\/\/)?(?:www\.)?([^/\s?#]+)/i);
+ return match ? match[1].toLowerCase() : null;
+ }
+}
+
+/**
+ * Count the citations that point at one of the brand's own domains: exact
+ * host or subdomain match, same rule as the web classifier's 'you' category.
+ * The old substring check (url.includes(domain)) also matched the brand's
+ * domain inside another site's path or query string, and disagreed with the
+ * Citations page over www/subdomain variants.
+ */
+export function countOwnDomainCitations(citations, brandDomains) {
+ const normalized = (brandDomains || [])
+ .map(
+ (d) =>
+ extractHostname(d) ??
+ String(d ?? '')
+ .trim()
+ .toLowerCase(),
+ )
+ .filter(Boolean);
+ if (normalized.length === 0) return 0;
+
+ let count = 0;
+ for (const cite of citations || []) {
+ const host = extractHostname(cite?.url || '');
+ if (host && normalized.some((d) => host === d || host.endsWith(`.${d}`))) {
+ count++;
+ }
+ }
+ return count;
+}
+
/**
* Count how many times the brand (name or any of its domains) is mentioned
* in an AI response. URL-stripped to avoid double-counting citations.
@@ -57,17 +105,8 @@ export function parseResponse(response, brand, sentiment = 'neutral', competitor
mentionCount += countOccurrences(cleanText, domain);
}
- // --- Brand citation count ---
- let citationCount = 0;
- for (const cite of citations) {
- const url = (cite.url || '').toLowerCase();
- for (const domain of brand.domains) {
- if (url.includes(domain.toLowerCase())) {
- citationCount++;
- break;
- }
- }
- }
+ // --- Brand citation count (hostname-based, see countOwnDomainCitations) ---
+ const citationCount = countOwnDomainCitations(citations, brand.domains);
// --- Visibility Score (0-100) ---
const visibilityScore = computeVisibilityScore({
diff --git a/server/src/lib/response-parser.test.js b/server/src/lib/response-parser.test.js
index 070261b17..832d87b6f 100644
--- a/server/src/lib/response-parser.test.js
+++ b/server/src/lib/response-parser.test.js
@@ -61,21 +61,42 @@ describe('response-parser', () => {
});
describe('citation count', () => {
- it('should count case-insensitive domain matches against citations[].url', () => {
+ it('should count case-insensitive hostname matches against citations[].url', () => {
const response = {
text: 'Acme is featured in these links.',
citations: [
{ url: 'https://ACME.com/page1', title: 'Page 1' },
- { url: 'https://other.com/acme-corp.com/info', title: 'Page 2' },
+ { url: 'https://www.acme-corp.com/info', title: 'Page 2' },
],
};
const result = parseResponse(response, brand, 'neutral');
- // acme.com matches ACME.com/page1
- // acme-corp.com matches other.com/acme-corp.com/info
- // total brand citations = 2
+ // acme.com matches ACME.com/page1; acme-corp.com matches the www variant.
expect(result.citationCount).toBe(2);
});
+ it('should count subdomains of a brand domain', () => {
+ const response = {
+ text: 'Acme docs.',
+ citations: [{ url: 'https://docs.acme.com/setup', title: 'Docs' }],
+ };
+ const result = parseResponse(response, brand, 'neutral');
+ expect(result.citationCount).toBe(1);
+ });
+
+ it('should NOT count a brand domain appearing in another site path or query', () => {
+ const response = {
+ text: 'Acme is referenced.',
+ citations: [
+ { url: 'https://other.com/acme-corp.com/info', title: 'Path lookalike' },
+ { url: 'https://other.com/?ref=acme.com', title: 'Query lookalike' },
+ ],
+ };
+ const result = parseResponse(response, brand, 'neutral');
+ // The hostname is other.com in both — matches the Citations page's
+ // classification, which the stored count must agree with.
+ expect(result.citationCount).toBe(0);
+ });
+
it('should count a citation once even if multiple brand domains match it', () => {
const response = {
text: 'Acme link.',
diff --git a/server/src/server.js b/server/src/server.js
index d6d2882f7..0b212dfde 100644
--- a/server/src/server.js
+++ b/server/src/server.js
@@ -26,6 +26,7 @@ import { verifyCloroWebhook } from './lib/cloro-webhook-verify.js';
import { generateBriefForOpportunity } from './routes/content.js';
import { startSiteAuditForBrand } from './routes/audits.js';
import { getSiteAuditQuotaStatus } from './lib/plan-guard.js';
+import { recountBrandCitations } from './lib/citation-recount.js';
import supabaseAdmin from './config/supabase.js';
import { getPlan, hasFeature, isCloud, isSubscriptionActive } from './config/plans.js';
@@ -296,6 +297,31 @@ app.get('/api/internal/site-audit-quota', async (req, res) => {
}
});
+// --- Internal citation-recount endpoint (CRON_SECRET auth, called by the web
+// layer whenever a brand's domain list changes) ---
+// Recomputes prompt_results.citation_count for the brand against its current
+// domain list so the stored tally never diverges from the Citations page's
+// live classification. See lib/citation-recount.js.
+app.post('/api/internal/recount-citations', async (req, res) => {
+ const secret = req.headers.authorization?.replace('Bearer ', '');
+ if (!process.env.CRON_SECRET || secret !== process.env.CRON_SECRET) {
+ return res.status(401).json({ success: false, message: 'Unauthorized' });
+ }
+
+ const { brandId } = req.body || {};
+ if (!brandId) {
+ return res.status(400).json({ success: false, message: 'brandId is required' });
+ }
+
+ try {
+ const result = await recountBrandCitations(brandId);
+ return res.json({ success: true, ...result });
+ } catch (err) {
+ req.log.error({ err, brandId }, 'internal recount-citations error');
+ return res.status(500).json({ success: false, message: err.message });
+ }
+});
+
// --- Internal trigger-tracking endpoint (CRON_SECRET auth, called by Stripe success route) ---
app.post('/api/internal/trigger-tracking', async (req, res) => {
const secret = req.headers.authorization?.replace('Bearer ', '');
diff --git a/web/src/lib/actions/brand-domain.ts b/web/src/lib/actions/brand-domain.ts
index 4212a3501..9d5b14e40 100644
--- a/web/src/lib/actions/brand-domain.ts
+++ b/web/src/lib/actions/brand-domain.ts
@@ -2,7 +2,36 @@
import { createClient } from '@/lib/supabase/server';
import { revalidatePath } from 'next/cache';
+import { after } from 'next/server';
import type { BrandDomain } from '@/types';
+import { API_BASE_URL } from '@/config/api';
+
+/**
+ * `prompt_results.citation_count` is computed at tracking time against the
+ * brand's domain list of that moment and frozen into the row. When the list
+ * changes, the stored tallies silently diverge from what the Citations page
+ * classifies live — the same "own citations" metric then shows different
+ * numbers on different surfaces. Kick the server-side recount after the
+ * response is sent; a failed recount self-heals on the next domain change.
+ */
+function scheduleCitationRecount(brandId: string) {
+ const cronSecret = process.env.CRON_SECRET;
+ if (!cronSecret) return;
+ after(async () => {
+ try {
+ await fetch(`${API_BASE_URL}/api/internal/recount-citations`, {
+ method: 'POST',
+ headers: {
+ 'Content-Type': 'application/json',
+ Authorization: `Bearer ${cronSecret}`,
+ },
+ body: JSON.stringify({ brandId }),
+ });
+ } catch (err) {
+ console.error('[brand-domain] citation recount failed', err);
+ }
+ });
+}
function mapDomainRow(d: Record<string, unknown>): BrandDomain {
return {
@@ -33,6 +62,7 @@ export async function addDomain(
if (error || !domain) throw new Error(error?.message ?? 'Failed to add domain');
+ scheduleCitationRecount(brandId);
revalidatePath('/dashboard/brands');
return mapDomainRow(domain as Record<string, unknown>);
}
@@ -57,6 +87,10 @@ export async function updateDomain(
if (error || !domain) throw new Error(error?.message ?? 'Failed to update domain');
+ // Only a change to the domain string itself affects citation counts.
+ if (data.domain !== undefined) {
+ scheduleCitationRecount((domain as Record<string, unknown>).brand_id as string);
+ }
revalidatePath('/dashboard/brands');
return mapDomainRow(domain as Record<string, unknown>);
}
@@ -64,9 +98,15 @@ export async function updateDomain(
export async function removeDomain(id: string): Promise<void> {
const supabase = await createClient();
- const { error } = await supabase.from('brand_domains').delete().eq('id', id);
+ const { data: removed, error } = await supabase
+ .from('brand_domains')
+ .delete()
+ .eq('id', id)
+ .select('brand_id')
+ .maybeSingle();
if (error) throw new Error(error.message);
+ if (removed?.brand_id) scheduleCitationRecount(removed.brand_id as string);
revalidatePath('/dashboard/brands');
}
@@ -83,6 +123,7 @@ export async function syncDomains(
await supabase.from('brand_domains').delete().eq('brand_id', brandId);
if (domains.length === 0) {
+ scheduleCitationRecount(brandId);
revalidatePath('/dashboard/brands');
return [];
}
@@ -101,6 +142,7 @@ export async function syncDomains(
if (error) throw new Error(error.message);
+ scheduleCitationRecount(brandId);
revalidatePath('/dashboard/brands');
return ((inserted as Record<string, unknown>[]) ?? []).map(mapDomainRow);
}