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
fix(pulse): never send two Daily Pulse emails for the same tracking window (#717)
Gökhan Geyik73b6dcbdf39c
diff --git a/server/src/lib/pulse/engine.js b/server/src/lib/pulse/engine.jsindex f83bfa438..b5ea7a799 100644--- a/server/src/lib/pulse/engine.js+++ b/server/src/lib/pulse/engine.js@@ -101,6 +101,29 @@ async function waitForCloroDrain(brandId) {}}+/**+ * The dedupe key for a computed digest: the end of the window it describes+ * (#701).+ *+ * `pulse_date` alone cannot express "these two mails say the same thing".+ * The daily KPI window is anchored to the tracking-run ledger, so two pulses+ * fired on different calendar days repeat each other verbatim whenever the+ * anchor has not moved between them — which is exactly what happened when the+ * catch-up sweep recovered a missed day at the start of a cycle and the+ * brand's own run pulsed an hour later, and again on every following day for a+ * brand whose runs had stopped stamping.+ *+ * Returns null for windows that are not run-anchored (weekly digests, and+ * brands with no completed run yet). Their `to` is the wall clock, which is+ * different on every call and would make this check a no-op anyway — better to+ * say so than to compare values that can never match.+ */+export function pulseWindowKey(metrics) {+ const window = metrics?.window;+ if (!window?.runAnchored) return null;+ return window.to ?? null;+}+/** Warning keys already sent for this brand in the last 7 days. */async function recentWarningKeys(brandId, now) {const since = new Date(now.getTime() - 7 * 86_400_000).toISOString();@@ -175,6 +198,32 @@ export async function generatePulseForBrand(brandId, { pulseDate: pulseDateOverr// Skip brands with no fresh tracking results in the window.if (metrics.kpis.totalResults === 0) return { skipped: 'no_fresh_results' };+ // Never mail the same window twice, whichever path fired (#701). The+ // pulse_date slot claimed above cannot see this: a recovery pulse dated to+ // the missed day and today's own pulse hold different dates while+ // describing the identical tracking run.+ const windowKey = pulseWindowKey(metrics);+ if (windowKey) {+ const { data: samePulse, error: sameErr } = await supabaseAdmin+ .from('sent_pulses')+ .select('id, pulse_date')+ .eq('brand_id', brandId)+ .eq('payload->window->>to', windowKey)+ .limit(1)+ .maybeSingle();+ // A failed read must not suppress a pulse — the insert below still has+ // the unique index as the final guard.+ if (sameErr) {+ logger.warn({ err: sameErr, brandId, windowKey }, 'pulse window lookup failed');+ } else if (samePulse) {+ logger.info(+ { brandId, windowKey, alreadySentFor: samePulse.pulse_date },+ 'skipping daily pulse — this window was already sent',+ );+ return { skipped: 'window_already_sent' };+ }+ }+// Warning cooldown: don't repeat the same warning for the same subject// within 7 days.const cooldown = await recentWarningKeys(brandId, now);@@ -198,8 +247,9 @@ export async function generatePulseForBrand(brandId, { pulseDate: pulseDateOverr.select('id').single();if (insertError) {- // 23505 = another worker claimed today's pulse between our check and- // this insert.+ // 23505 = another worker claimed this pulse between our checks and the+ // insert — either today's date slot or, via the window index, the same+ // tracking window under a different date.if (insertError.code === '23505') return { skipped: 'already_sent' };throw new Error(insertError.message);}@@ -266,7 +316,12 @@ export async function generatePulseForBrand(brandId, { pulseDate: pulseDateOverr* This sweep runs at the start of the daily cycle: any brand whose latest* completed run (last 36h) has no pulse row created after it gets a recovery* pulse, dated to that run's completion day so today's real pulse keeps its- * own dedupe slot. The sent_pulses unique key makes double-sends impossible.+ * own dedupe slot.+ *+ * Two guards keep that from turning into a duplicate mail: the sent_pulses+ * (brand_id, pulse_date) key stops the same day being sent twice, and the+ * window key (#701) stops the recovery pulse repeating a run that today's own+ * pulse is about to report — the two dates disagree, the data does not.*/export async function runPulseCatchUp() {try {diff --git a/server/src/lib/pulse/engine.test.js b/server/src/lib/pulse/engine.test.jsnew file mode 100644index 000000000..8d1c55b4d--- /dev/null+++ b/server/src/lib/pulse/engine.test.js@@ -0,0 +1,57 @@+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 { pulseWindowKey } from './engine.js';++/**+ * Pulse window dedupe (#701).+ *+ * Two mails an hour apart carried identical figures because the daily KPI+ * window anchors to the tracking-run ledger while the dedupe slot is keyed on+ * the calendar date. The window key is what lets the second one recognise+ * itself as a repeat.+ */+describe('pulseWindowKey', () => {+ const anchored = (to) => ({ window: { from: '2026-08-10T05:15:56Z', to, runAnchored: true } });++ it('keys a run-anchored digest on the end of its window', () => {+ expect(pulseWindowKey(anchored('2026-08-10T05:15:57.682Z'))).toBe('2026-08-10T05:15:57.682Z');+ });++ it('gives two digests of the same run the same key, whatever date they are filed under', () => {+ // The production pair: a recovery pulse dated to the missed day and the+ // brand's own pulse dated to today, both computed from the run that+ // completed at 05:15:57.+ const recovery = anchored('2026-08-10T05:15:57.682Z');+ const ownRun = anchored('2026-08-10T05:15:57.682Z');++ expect(pulseWindowKey(recovery)).toBe(pulseWindowKey(ownRun));+ });++ it('gives digests of different runs different keys', () => {+ expect(pulseWindowKey(anchored('2026-08-10T05:15:57.682Z'))).not.toBe(+ pulseWindowKey(anchored('2026-08-11T04:02:11.104Z')),+ );+ });++ it('returns null for a clock-anchored window, which could never match', () => {+ // Weekly digests and brands with no completed run end their window at+ // `now`, so comparing them would suppress nothing and only risk+ // suppressing something it should not.+ expect(+ pulseWindowKey({ window: { from: '2026-08-06T00:00:00Z', to: '2026-08-13T00:00:00Z' } }),+ ).toBeNull();+ });++ it('returns null when the digest predates the window field', () => {+ expect(pulseWindowKey({ windowDays: 1, kpis: { totalResults: 12 } })).toBeNull();+ expect(pulseWindowKey(undefined)).toBeNull();+ });++ it('returns null when a run-anchored window has no end, rather than a false match', () => {+ expect(pulseWindowKey({ window: { runAnchored: true } })).toBeNull();+ });+});diff --git a/server/src/lib/pulse/metrics.js b/server/src/lib/pulse/metrics.jsindex 89e567a12..cad1683fa 100644--- a/server/src/lib/pulse/metrics.js+++ b/server/src/lib/pulse/metrics.js@@ -372,10 +372,12 @@ export async function computePulseMetrics(brandId, { windowDays = 1, now = new Dlet curFrom = new Date(now.getTime() - windowDays * DAY_MS);let prevTo = curFrom;let prevFrom = new Date(now.getTime() - 2 * windowDays * DAY_MS);+ let runAnchored = false;if (windowDays === 1) {const [latest, prev, prevPrev] = await latestCompletedRunTimes(brandId, 3);if (latest) {+ runAnchored = true;curTo = latest;curFrom = new Date(Math.max(latest.getTime() - DAY_MS, prev ? prev.getTime() + 1 : 0));prevTo = prev ?? curFrom;@@ -543,6 +545,15 @@ export async function computePulseMetrics(brandId, { windowDays = 1, now = new Dreturn {windowDays,computedAt: now.toISOString(),+ // The window these numbers describe, recorded so a second pulse can tell+ // that it would repeat an already-sent one (#701). `runAnchored` marks the+ // case where `to` is a tracking-run stamp rather than the wall clock —+ // only then is the value stable enough to dedupe on.+ window: {+ from: curFrom.toISOString(),+ to: curTo.toISOString(),+ runAnchored,+ },kpis,highlights,warnings,diff --git a/supabase/migrations/00052_sent_pulses_window_dedupe.sql b/supabase/migrations/00052_sent_pulses_window_dedupe.sqlnew file mode 100644index 000000000..af14abbeb--- /dev/null+++ b/supabase/migrations/00052_sent_pulses_window_dedupe.sql@@ -0,0 +1,21 @@+-- One Daily Pulse per brand per tracking window (#701).+--+-- sent_pulses already has a unique (brand_id, pulse_date) key, but the daily+-- KPI window is anchored to the tracking-run ledger rather than to the+-- calendar: two pulses filed under different dates repeat each other verbatim+-- whenever the anchor has not moved between them. That is how the catch-up+-- sweep's recovery mail and the brand's own end-of-run mail went out an hour+-- apart with identical numbers, and how a brand whose runs stopped stamping+-- received the same figures again on each following day.+--+-- The engine checks for a matching window before it computes, so this index is+-- the race guard rather than the primary mechanism — same role the date key+-- plays for same-day double-fires.+--+-- Partial on the extracted path so rows written before this migration — which+-- carry no payload->window at all — are excluded instead of colliding on NULL.+-- Weekly digests and brands with no completed run are indexed but can never+-- conflict: their window ends at the wall clock, which differs on every call.+CREATE UNIQUE INDEX IF NOT EXISTS sent_pulses_brand_window_key+ ON public.sent_pulses (brand_id, ((payload -> 'window' ->> 'to')))+ WHERE (payload -> 'window' ->> 'to') IS NOT NULL;diff --git a/supabase/schema.sql b/supabase/schema.sqlindex b87e7ca61..7148945b7 100644--- a/supabase/schema.sql+++ b/supabase/schema.sql@@ -5254,3 +5254,28 @@ GRANT EXECUTE ON FUNCTION public.content_opportunity_aggregates(ALTER TABLE public.brands ADD COLUMN ga_property_id text;+-- ─────────────────────────────────────────────────────────────────────────+-- migrations/00052_sent_pulses_window_dedupe.sql+-- ─────────────────────────────────────────────────────────────────────────+-- One Daily Pulse per brand per tracking window (#701).+--+-- sent_pulses already has a unique (brand_id, pulse_date) key, but the daily+-- KPI window is anchored to the tracking-run ledger rather than to the+-- calendar: two pulses filed under different dates repeat each other verbatim+-- whenever the anchor has not moved between them. That is how the catch-up+-- sweep's recovery mail and the brand's own end-of-run mail went out an hour+-- apart with identical numbers, and how a brand whose runs stopped stamping+-- received the same figures again on each following day.+--+-- The engine checks for a matching window before it computes, so this index is+-- the race guard rather than the primary mechanism — same role the date key+-- plays for same-day double-fires.+--+-- Partial on the extracted path so rows written before this migration — which+-- carry no payload->window at all — are excluded instead of colliding on NULL.+-- Weekly digests and brands with no completed run are indexed but can never+-- conflict: their window ends at the wall clock, which differs on every call.+CREATE UNIQUE INDEX IF NOT EXISTS sent_pulses_brand_window_key+ ON public.sent_pulses (brand_id, ((payload -> 'window' ->> 'to')))+ WHERE (payload -> 'window' ->> 'to') IS NOT NULL;+