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.

feat(content): read brand facts again each week in the daily run (CE-047, part b) (#1463)

Cihan6628aed440a5
diff --git a/server/src/lib/brand-facts-sweep.js b/server/src/lib/brand-facts-sweep.js
new file mode 100644
index 000000000..918886861
--- /dev/null
+++ b/server/src/lib/brand-facts-sweep.js
@@ -0,0 +1,134 @@
+import supabaseAdmin from '../config/supabase.js';
+import { isCloud, isSubscriptionActive } from '../config/plans.js';
+import { refreshOnce } from './brand-facts.js';
+import { qualityPhase } from './content-quality.js';
+import { logger } from './logger.js';
+
+/**
+ * A brand's facts read again each week (Quality spec §10, CE-047): the
+ * daily run reads the brands whose site was last read over REFRESH_DAYS
+ * ago, the longest waiting first, SWEEP_LIMIT a run. Only brands read
+ * before (someone opened their facts): a brand no one uses the Content
+ * Editor for costs nothing. A page that hasn't changed isn't read by the
+ * model (refreshBrandFacts, once at a time with the tab's reads); a value
+ * that has is a new pending fact, the to-do. Approved facts gone from the site for GONE_KEEP_DAYS go.
+ */
+
+export const REFRESH_DAYS = 7;
+/** Brands one run reads, so a night's model spend has a ceiling. */
+export const SWEEP_LIMIT = 25;
+/** How long an approved fact gone from the site is kept, shown as gone. */
+export const GONE_KEEP_DAYS = 30;
+
+const DAY_MS = 86_400_000;
+
+/**
+ * Reads the brands due again, one at a time, `limit` of them. A brand
+ * whose workspace isn't subscribed (cloud) or that has no domain left is
+ * marked read so it doesn't stand first in line every night; one whose
+ * read failed is marked failed (read again when someone opens its facts).
+ * A read the AI budget stopped is `paused`: its pages are marked read (by
+ * the read itself) and failed, read again when someone opens its facts or
+ * next week; the workspace's other brands wait for the next run, and
+ * don't count toward `limit`.
+ *
+ * @returns {Promise<{ read: number, paused: number, skipped: number, failed: number } | { skipped: 'off' }>}
+ */
+export async function sweepBrandFacts({
+ now = Date.now(),
+ limit = SWEEP_LIMIT,
+ db = supabaseAdmin,
+ refresh = refreshOnce,
+} = {}) {
+ if (qualityPhase() < 2) return { skipped: 'off' };
+ const nowIso = new Date(now).toISOString();
+ const { data: rows, error } = await db
+ .from('brand_fact_pages')
+ .select('brand_id, checked_at, brands!inner(organization_id, is_active)')
+ .lt('checked_at', new Date(now - REFRESH_DAYS * DAY_MS).toISOString())
+ .eq('brands.is_active', true)
+ .order('checked_at', { ascending: true })
+ .limit(limit * 6);
+ if (error) throw new Error(error.message);
+
+ const brands = [];
+ for (const row of rows ?? []) {
+ if (!brands.some((b) => b.id === row.brand_id)) {
+ brands.push({ id: row.brand_id, orgId: row.brands.organization_id });
+ }
+ }
+ let active = () => true;
+ if (brands.length && isCloud()) {
+ const { data: orgs, error: orgError } = await db
+ .from('organizations')
+ .select('id, subscription_status')
+ .in('id', [...new Set(brands.map((b) => b.orgId))]);
+ if (orgError) throw new Error(orgError.message);
+ const subscribed = new Set(
+ (orgs ?? []).filter((o) => isSubscriptionActive(o.subscription_status)).map((o) => o.id),
+ );
+ active = (orgId) => subscribed.has(orgId);
+ }
+
+ const outcome = { read: 0, paused: 0, skipped: 0, failed: 0 };
+ const spent = new Set();
+ const markRead = [];
+ const markFailed = [];
+ let tried = 0;
+ for (const brand of brands) {
+ if (tried >= limit) break;
+ if (!active(brand.orgId)) {
+ outcome.skipped += 1;
+ markRead.push(brand.id);
+ continue;
+ }
+ if (spent.has(brand.orgId)) continue;
+ tried += 1;
+ try {
+ const result = await refresh(brand.id, { orgId: brand.orgId, now });
+ if (result.noDomain) {
+ outcome.skipped += 1;
+ markRead.push(brand.id);
+ continue;
+ }
+ if (result.paused) {
+ spent.add(brand.orgId);
+ outcome.paused += 1;
+ } else outcome.read += 1;
+ } catch (err) {
+ // One brand's failure isn't the run's, nor first in line tomorrow.
+ outcome.failed += 1;
+ markFailed.push(brand.id);
+ logger.warn(
+ { err: { name: err?.name, message: err?.message }, brandId: brand.id },
+ '[brand-facts] a brand was not read',
+ );
+ }
+ }
+
+ const writes = [
+ db
+ .from('brand_facts')
+ .delete()
+ .eq('status', 'approved')
+ .lt('gone_at', new Date(now - GONE_KEEP_DAYS * DAY_MS).toISOString()),
+ ];
+ if (markRead.length) {
+ writes.push(
+ db.from('brand_fact_pages').update({ checked_at: nowIso }).in('brand_id', markRead),
+ );
+ }
+ if (markFailed.length) {
+ writes.push(
+ db
+ .from('brand_fact_pages')
+ .update({ checked_at: nowIso, status: 'failed' })
+ .in('brand_id', markFailed),
+ );
+ }
+ for (const res of await Promise.all(writes)) {
+ if (res.error) throw new Error(res.error.message);
+ }
+ logger.info(outcome, '[brand-facts] weekly sweep');
+ return outcome;
+}
diff --git a/server/src/lib/brand-facts-sweep.test.js b/server/src/lib/brand-facts-sweep.test.js
new file mode 100644
index 000000000..abcff9364
--- /dev/null
+++ b/server/src/lib/brand-facts-sweep.test.js
@@ -0,0 +1,185 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+/**
+ * A brand's facts read again each week (Quality CE-047): the brands read
+ * before whose site was read over a week ago, a bounded number a night.
+ */
+
+vi.mock('../config/supabase.js', () => ({ default: {} }));
+let cloud;
+vi.mock('../config/plans.js', () => ({
+ isCloud: () => cloud,
+ isSubscriptionActive: (status) => status === 'active' || status === 'trialing',
+}));
+vi.mock('./brand-facts.js', () => ({ refreshOnce: vi.fn() }));
+
+const { GONE_KEEP_DAYS, REFRESH_DAYS, sweepBrandFacts } = await import('./brand-facts-sweep.js');
+
+const NOW = Date.parse('2026-10-24T03:00:00Z');
+const DAY = 86_400_000;
+
+/** The tables read, and each write as it was asked. */
+function fakeDb(tables) {
+ const writes = [];
+ const reads = [];
+ const db = {
+ from: (table) => {
+ const q = { op: 'select', filters: [], payload: null };
+ const chain = {
+ select: (columns) => (reads.push({ table, columns }), chain),
+ eq: (col, value) => (q.filters.push(['eq', col, value]), chain),
+ in: (col, value) => (q.filters.push(['in', col, value]), chain),
+ lt: (col, value) => (q.filters.push(['lt', col, value]), chain),
+ order: () => chain,
+ limit: (n) => (q.filters.push(['limit', n]), chain),
+ update: (payload) => ((q.op = 'update'), (q.payload = payload), chain),
+ delete: () => ((q.op = 'delete'), chain),
+ then: (resolve) => {
+ if (q.op === 'select') {
+ reads.at(-1).filters = q.filters;
+ return resolve({ data: tables[table] ?? [], error: null });
+ }
+ writes.push({ table, op: q.op, payload: q.payload, filters: q.filters });
+ return resolve({ error: null });
+ },
+ };
+ return chain;
+ },
+ };
+ return { db, writes, reads };
+}
+
+const row = (brand, org, daysAgo) => ({
+ brand_id: brand,
+ checked_at: new Date(NOW - daysAgo * DAY).toISOString(),
+ brands: { organization_id: org, is_active: true },
+});
+
+beforeEach(() => {
+ vi.stubEnv('CONTENT_QUALITY_PHASE', '2');
+ cloud = true;
+});
+afterEach(() => vi.unstubAllEnvs());
+
+describe('sweepBrandFacts', () => {
+ it('reads the active brands read over a week ago, each once, the longest waiting first', async () => {
+ const { db, reads } = fakeDb({
+ brand_fact_pages: [
+ row('b1', 'o1', 9),
+ row('b1', 'o1', 9),
+ row('b2', 'o2', 8),
+ row('b3', 'o1', 8),
+ ],
+ organizations: [
+ { id: 'o1', subscription_status: 'active' },
+ { id: 'o2', subscription_status: 'active' },
+ ],
+ });
+ const refresh = vi.fn().mockResolvedValue({ noDomain: false, paused: false });
+ expect(await sweepBrandFacts({ now: NOW, limit: 2, db, refresh })).toEqual({
+ read: 2,
+ paused: 0,
+ skipped: 0,
+ failed: 0,
+ });
+ expect(refresh.mock.calls).toEqual([
+ ['b1', { orgId: 'o1', now: NOW }],
+ ['b2', { orgId: 'o2', now: NOW }],
+ ]);
+ expect(reads[0].filters).toEqual(
+ expect.arrayContaining([
+ ['lt', 'checked_at', new Date(NOW - REFRESH_DAYS * DAY).toISOString()],
+ ['eq', 'brands.is_active', true],
+ ['limit', 12],
+ ]),
+ );
+ });
+
+ it('marks an unsubscribed or domainless brand read, and leaves a workspace whose budget ran out', async () => {
+ const { db, writes } = fakeDb({
+ brand_fact_pages: [
+ row('b1', 'o1', 9),
+ row('b2', 'o2', 9),
+ row('b3', 'o3', 9),
+ row('b4', 'o3', 9),
+ row('b5', 'o4', 9),
+ ],
+ organizations: [
+ { id: 'o1', subscription_status: 'canceled' },
+ { id: 'o2', subscription_status: 'active' },
+ { id: 'o3', subscription_status: 'trialing' },
+ { id: 'o4', subscription_status: 'active' },
+ ],
+ });
+ const refresh = vi.fn(async (brandId) => {
+ if (brandId === 'b2') return { noDomain: true, paused: false };
+ if (brandId === 'b3') return { noDomain: false, paused: true };
+ if (brandId === 'b5') throw new Error('database down');
+ return { noDomain: false, paused: false };
+ });
+ expect(await sweepBrandFacts({ now: NOW, db, refresh })).toEqual({
+ read: 0,
+ paused: 1,
+ skipped: 2,
+ failed: 1,
+ });
+ // b4 shares b3's spent budget: left for the next run, not marked read.
+ expect(refresh.mock.calls.map(([id]) => id)).toEqual(['b2', 'b3', 'b5']);
+ expect(writes.filter((w) => w.table === 'brand_fact_pages')).toEqual([
+ expect.objectContaining({
+ payload: { checked_at: new Date(NOW).toISOString() },
+ filters: [['in', 'brand_id', ['b1', 'b2']]],
+ }),
+ expect.objectContaining({
+ payload: { checked_at: new Date(NOW).toISOString(), status: 'failed' },
+ filters: [['in', 'brand_id', ['b5']]],
+ }),
+ ]);
+ });
+
+ it('counts toward its limit only the brands it tried: a spent workspace’s don’t take the others’ turn', async () => {
+ const { db } = fakeDb({
+ brand_fact_pages: [
+ row('a1', 'o1', 9),
+ row('a2', 'o1', 9),
+ row('a3', 'o1', 9),
+ row('b1', 'o2', 8),
+ ],
+ organizations: [
+ { id: 'o1', subscription_status: 'active' },
+ { id: 'o2', subscription_status: 'active' },
+ ],
+ });
+ const refresh = vi.fn(async (brandId) => ({ noDomain: false, paused: brandId === 'a1' }));
+ await sweepBrandFacts({ now: NOW, limit: 2, db, refresh });
+ expect(refresh.mock.calls.map(([id]) => id)).toEqual(['a1', 'b1']);
+ });
+
+ it('drops approved facts gone from the site for a month', async () => {
+ const { db, writes } = fakeDb({ brand_fact_pages: [] });
+ await sweepBrandFacts({ now: NOW, db, refresh: vi.fn() });
+ expect(writes).toEqual([
+ {
+ table: 'brand_facts',
+ op: 'delete',
+ payload: null,
+ filters: [
+ ['eq', 'status', 'approved'],
+ ['lt', 'gone_at', new Date(NOW - GONE_KEEP_DAYS * DAY).toISOString()],
+ ],
+ },
+ ]);
+ });
+
+ it('reads every brand due when self-hosted, and nothing before phase 2', async () => {
+ cloud = false;
+ const { db } = fakeDb({ brand_fact_pages: [row('b1', 'o1', 9)] });
+ const refresh = vi.fn().mockResolvedValue({ noDomain: false, paused: false });
+ await sweepBrandFacts({ now: NOW, db, refresh });
+ expect(refresh).toHaveBeenCalledTimes(1);
+ vi.stubEnv('CONTENT_QUALITY_PHASE', '1');
+ refresh.mockClear();
+ expect(await sweepBrandFacts({ now: NOW, db, refresh })).toEqual({ skipped: 'off' });
+ expect(refresh).not.toHaveBeenCalled();
+ });
+});
diff --git a/server/src/server.js b/server/src/server.js
index 141078a72..3b32eb189 100644
--- a/server/src/server.js
+++ b/server/src/server.js
@@ -27,6 +27,7 @@ import { rebuildQueuedInsightsRollups, sweepInsightsRollups } from './lib/insigh
import { rebuildQueuedCitationRollups, REBUILD_QUEUE_SCHEDULE } from './lib/citations-rollups.js';
import { sweepActionValidation } from './lib/action-center/validate.js';
import { sweepImproveOutcomes } from './lib/action-center/improve-outcome.js';
+import { sweepBrandFacts } from './lib/brand-facts-sweep.js';
import { parseScraperResponse } from './lib/cloro-scraper.js';
import { handleScraperResult } from './lib/cloro-result-handler.js';
import { verifyCloroWebhook } from './lib/cloro-webhook-verify.js';
@@ -199,6 +200,14 @@ async function runDailyTracking() {
logger.error({ err }, '[improve-outcome] daily sweep crashed');
});
+ // A brand's facts read again each week (CE-047): the brands whose site was
+ // read over a week ago, a bounded number a night; a no-op before Quality's
+ // phase 2. Fire-and-forget: an unread week is a stale fact the person can
+ // read again by hand, not a reason to hold up tracking.
+ sweepBrandFacts().catch((err) => {
+ logger.error({ err }, '[brand-facts] weekly sweep crashed');
+ });
+
// Skip paused brands (is_active = false): the user has explicitly suspended
// tracking for them, so they should not spend Cloro / LLM credits daily.
const { data: brands, error } = await supabaseAdmin