backend-manager 5.11.2 → 5.11.4

package/test/email/campaign-cron-pipeline.js

@@ -6,18 +6,56 @@
  *
  * Covers:
  *   1. One-off campaigns: status changes from 'pending' to 'sent'/'failed'
- *   2. Recurring campaigns: sendAt advances, history doc created
+ *   2. Recurring campaigns: sendAt advances, history doc created, status
+ *      returns to 'pending'
  *   3. Generator campaigns (e.g. newsletter): NOT skipped — the generator
- *      pipeline runs inline and produces a new campaign doc
+ *      pipeline runs inline; when it yields nothing the campaign stays
+ *      pending with generatorAttempts incremented (retry next run)
+ *   4. Claim/lease lifecycle: stale 'processing' leases are reclaimed and
+ *      re-processed; fresh leases are left alone (no double-send)
+ *   5. Unknown campaign types / generators are marked 'failed' (config
+ *      typos must not retry forever)
+ *   6. Generator retry cap: after GENERATOR_MAX_ATTEMPTS empty runs, a
+ *      recurring campaign skips to its next occurrence and a one-off fails
+ *   7. Catch-up-safe advance: a recurring campaign stalled multiple periods
+ *      advances to the next FUTURE occurrence (no catch-up burst)
  *
- * Default mode: seeds campaigns and triggers the cron, verifies doc state
- * changes. The generator test verifies the campaign is attempted (not skipped);
- * if the consumer config has newsletter disabled, the generator returns null
- * and the test confirms the graceful "will retry" path.
- *
- * Extended mode: same, but the newsletter generator runs the full AI pipeline.
+ * Default mode: the newsletter generator is gated by TEST_EXTENDED_MODE and
+ * returns null — the suite verifies the retry bookkeeping deterministically
+ * with zero AI cost. Extended mode: the generator runs the full AI pipeline
+ * and the suite verifies the generated history doc + sendAt advance.
  */
-const { getNextOccurrence } = require('../../src/manager/libraries/email/constants.js');
+const {
+  getNextOccurrence,
+  getNextFutureOccurrence,
+} = require('../../src/manager/libraries/email/constants.js');
+const {
+  PROCESSING_LEASE_SECONDS,
+  GENERATOR_MAX_ATTEMPTS,
+} = require('../../src/manager/events/cron/frequent/marketing-campaigns.js');
+
+const WEEK = 7 * 86400;
+
+function stamp(now) {
+  return { timestamp: new Date(now * 1000).toISOString(), timestampUNIX: now };
+}
+
+function emailSettings(name) {
+  return {
+    name,
+    subject: `${name} subject`,
+    preheader: `${name} preheader`,
+    template: 'card',
+    data: {
+      content: {
+        title: name,
+        message: `${name} body`,
+        button: { text: 'Click', url: 'https://example.com' },
+      },
+    },
+    test: true,
+  };
+}
 
 module.exports = {
   description: 'Campaign cron pipeline (frequent cron processes all campaign types)',
@@ -25,6 +63,42 @@ module.exports = {
   timeout: 60000,
 
   tests: [
+    {
+      name: 'get-next-future-occurrence-pure',
+      auth: 'none',
+
+      async run({ assert }) {
+        const now = Math.round(Date.now() / 1000);
+        const weekly = { pattern: 'weekly', hour: 10, minute: 0, day: 1 };
+
+        // Near-past sendAt: single-step advance already lands in the future
+        const recent = now - 600;
+        assert.equal(
+          getNextFutureOccurrence(recent, weekly, now),
+          getNextOccurrence(recent, weekly),
+          'Single-step advance is preserved when it lands in the future',
+        );
+
+        // Stalled 3 weeks: all missed occurrences are skipped
+        const stale = now - (3 * WEEK) - 600;
+        const next = getNextFutureOccurrence(stale, weekly, now);
+        assert.ok(next > now, `Advance from a 3-week-stale anchor must be in the future (got ${next}, now ${now})`);
+
+        let manual = stale;
+        for (let i = 0; i < 4; i++) {
+          manual = getNextOccurrence(manual, weekly);
+        }
+        assert.equal(next, manual, 'Skips exactly the missed occurrences (4 weekly steps)');
+
+        // Daily pattern stalled 5 days: lands within the next 24h
+        const daily = { pattern: 'daily', hour: 0, minute: 0 };
+        const staleDaily = now - (5 * 86400) - 60;
+        const nextDaily = getNextFutureOccurrence(staleDaily, daily, now);
+        assert.ok(nextDaily > now, 'Daily advance is in the future');
+        assert.ok(nextDaily <= now + 86400, 'Daily advance lands within one period of now');
+      },
+    },
+
     {
       name: 'seed-campaigns',
       auth: 'none',
@@ -32,30 +106,21 @@ module.exports = {
       async run({ firestore, state }) {
         const now = Math.round(Date.now() / 1000);
         const pastSendAt = now - 600;
+        const staleSendAt = now - (3 * WEEK) - 600;
+
+        state.now = now;
+        state.pastSendAt = pastSendAt;
+        state.staleSendAt = staleSendAt;
+
+        const meta = { created: stamp(now), updated: stamp(now) };
 
         // One-off email campaign (sendAt 10 min ago)
         await firestore.set('marketing-campaigns/_test-oneoff', {
           status: 'pending',
           type: 'email',
           sendAt: pastSendAt,
-          settings: {
-            name: '[TEST] One-off blast',
-            subject: 'Test subject',
-            preheader: 'Test preheader',
-            template: 'card',
-            data: {
-              content: {
-                title: 'Test',
-                message: 'Test campaign body',
-                button: { text: 'Click', url: 'https://example.com' },
-              },
-            },
-            test: true,
-          },
-          metadata: {
-            created: { timestamp: new Date().toISOString(), timestampUNIX: now },
-            updated: { timestamp: new Date().toISOString(), timestampUNIX: now },
-          },
+          settings: emailSettings('[TEST] One-off blast'),
+          metadata: meta,
         });
 
         // Recurring email campaign (sendAt 10 min ago, weekly recurrence)
@@ -63,30 +128,20 @@ module.exports = {
           status: 'pending',
           type: 'email',
           sendAt: pastSendAt,
-          recurrence: {
-            pattern: 'weekly',
-            hour: 10,
-            minute: 0,
-            day: 1,
-          },
-          settings: {
-            name: '[TEST] Weekly digest',
-            subject: 'Weekly digest',
-            preheader: 'Your weekly summary',
-            template: 'card',
-            data: {
-              content: {
-                title: 'Weekly Digest',
-                message: 'Here is your weekly digest.',
-                button: { text: 'Read more', url: 'https://example.com' },
-              },
-            },
-            test: true,
-          },
-          metadata: {
-            created: { timestamp: new Date().toISOString(), timestampUNIX: now },
-            updated: { timestamp: new Date().toISOString(), timestampUNIX: now },
-          },
+          recurrence: { pattern: 'weekly', hour: 10, minute: 0, day: 1 },
+          settings: emailSettings('[TEST] Weekly digest'),
+          metadata: meta,
+        });
+
+        // Recurring email campaign stalled for 3 weeks — must advance to a
+        // FUTURE occurrence in one step (no catch-up burst)
+        await firestore.set('marketing-campaigns/_test-recurring-stale', {
+          status: 'pending',
+          type: 'email',
+          sendAt: staleSendAt,
+          recurrence: { pattern: 'weekly', hour: 10, minute: 0, day: 1 },
+          settings: emailSettings('[TEST] Stale weekly digest'),
+          metadata: meta,
         });
 
         // Generator campaign (newsletter — sendAt 10 min ago)
@@ -95,12 +150,7 @@ module.exports = {
           type: 'email',
           generator: 'newsletter',
           sendAt: pastSendAt,
-          recurrence: {
-            pattern: 'weekly',
-            hour: 17,
-            minute: 30,
-            day: 2,
-          },
+          recurrence: { pattern: 'weekly', hour: 17, minute: 30, day: 2 },
           settings: {
             name: '{brand.name} Newsletter — {date.month} {date.year}',
             subject: '',
@@ -108,13 +158,79 @@ module.exports = {
             sender: 'newsletter',
             providers: ['newsletter'],
           },
-          metadata: {
-            created: { timestamp: new Date().toISOString(), timestampUNIX: now },
-            updated: { timestamp: new Date().toISOString(), timestampUNIX: now },
-          },
+          metadata: meta,
         });
 
-        state.pastSendAt = pastSendAt;
+        // Unknown generator — a config typo must be marked failed, not
+        // retried every 10 minutes forever
+        await firestore.set('marketing-campaigns/_test-unknown-generator', {
+          status: 'pending',
+          type: 'email',
+          generator: 'doesnotexist',
+          sendAt: pastSendAt,
+          settings: emailSettings('[TEST] Unknown generator'),
+          metadata: meta,
+        });
+
+        // Unknown campaign type — same treatment
+        await firestore.set('marketing-campaigns/_test-unknown-type', {
+          status: 'pending',
+          type: 'carrier-pigeon',
+          sendAt: pastSendAt,
+          settings: emailSettings('[TEST] Unknown type'),
+          metadata: meta,
+        });
+
+        // Stale processing lease (crashed run) — must be reclaimed and
+        // processed in the same cron run
+        await firestore.set('marketing-campaigns/_test-stale-processing', {
+          status: 'processing',
+          processingStartedAt: now - PROCESSING_LEASE_SECONDS - 600,
+          type: 'email',
+          sendAt: pastSendAt,
+          settings: emailSettings('[TEST] Stale processing reclaim'),
+          metadata: meta,
+        });
+
+        // Fresh processing lease (another run is mid-flight) — must be left
+        // completely alone
+        await firestore.set('marketing-campaigns/_test-fresh-processing', {
+          status: 'processing',
+          processingStartedAt: now - 60,
+          type: 'email',
+          sendAt: pastSendAt,
+          settings: emailSettings('[TEST] Fresh processing lease'),
+          metadata: meta,
+        });
+
+        // Retry-cap seeds run the real generator in extended mode, so they
+        // are DEFAULT-MODE ONLY (the generator nulls instantly via the
+        // test-mode gate, letting us exercise the cap deterministically).
+        if (!process.env.TEST_EXTENDED_MODE) {
+          // One-off generator at the attempts cap → must be marked failed
+          await firestore.set('marketing-campaigns/_test-gen-cap-oneoff', {
+            status: 'pending',
+            type: 'email',
+            generator: 'newsletter',
+            sendAt: pastSendAt,
+            generatorAttempts: GENERATOR_MAX_ATTEMPTS - 1,
+            settings: emailSettings('[TEST] Generator cap one-off'),
+            metadata: meta,
+          });
+
+          // Recurring generator at the attempts cap, stalled 3 weeks → must
+          // skip to the next FUTURE occurrence and reset the counter
+          await firestore.set('marketing-campaigns/_test-gen-cap-recurring', {
+            status: 'pending',
+            type: 'email',
+            generator: 'newsletter',
+            sendAt: staleSendAt,
+            generatorAttempts: GENERATOR_MAX_ATTEMPTS - 1,
+            recurrence: { pattern: 'weekly', hour: 10, minute: 0, day: 1 },
+            settings: emailSettings('[TEST] Generator cap recurring'),
+            metadata: meta,
+          });
+        }
       },
     },
 
@@ -126,14 +242,25 @@ module.exports = {
       async run({ pubsub, waitFor, firestore, state }) {
         await pubsub.trigger('bm_cronFrequent');
 
-        // Wait for BOTH the one-off and recurring campaigns to be processed.
-        // The cron processes all campaigns in parallel via Promise.allSettled,
-        // but individual Firestore writes may land at different times.
+        // Wait for the fast (non-generator) campaigns to reach a terminal
+        // state. The cron processes campaigns in parallel via
+        // Promise.allSettled, but individual Firestore writes land at
+        // different times.
         await waitFor(
           async () => {
             const oneoff = await firestore.get('marketing-campaigns/_test-oneoff');
             const recurring = await firestore.get('marketing-campaigns/_test-recurring');
-            return oneoff?.status !== 'pending' && recurring?.sendAt !== state.pastSendAt;
+            const recurringStale = await firestore.get('marketing-campaigns/_test-recurring-stale');
+            const staleProcessing = await firestore.get('marketing-campaigns/_test-stale-processing');
+            const unknownGenerator = await firestore.get('marketing-campaigns/_test-unknown-generator');
+            const unknownType = await firestore.get('marketing-campaigns/_test-unknown-type');
+
+            return oneoff?.status !== 'pending'
+              && recurring?.sendAt !== state.pastSendAt
+              && recurringStale?.sendAt !== state.staleSendAt
+              && ['sent', 'failed'].includes(staleProcessing?.status)
+              && unknownGenerator?.status === 'failed'
+              && unknownType?.status === 'failed';
           },
           90000,
           1000,
@@ -165,14 +292,14 @@ module.exports = {
         const doc = await firestore.get('marketing-campaigns/_test-recurring');
 
         assert.ok(doc, 'Recurring campaign doc should exist');
-        assert.equal(doc.status, 'pending', 'Recurring campaign status stays pending');
+        assert.equal(doc.status, 'pending', 'Recurring campaign status returns to pending');
 
-        const expectedNext = getNextOccurrence(state.pastSendAt, {
+        const expectedNext = getNextFutureOccurrence(state.pastSendAt, {
           pattern: 'weekly',
           hour: 10,
           minute: 0,
           day: 1,
-        });
+        }, state.now);
         assert.equal(doc.sendAt, expectedNext, 'sendAt should advance to next occurrence');
       },
     },
@@ -199,26 +326,102 @@ module.exports = {
     },
 
     {
-      name: 'generator-campaign-not-skipped',
+      name: 'stalled-recurring-skips-to-future-occurrence',
       auth: 'none',
 
-      async run({ firestore, assert, state, config }) {
-        const doc = await firestore.get('marketing-campaigns/_test-generator');
-        assert.ok(doc, 'Generator campaign doc should still exist');
+      async run({ firestore, assert, state }) {
+        const doc = await firestore.get('marketing-campaigns/_test-recurring-stale');
+
+        assert.ok(doc, 'Stale recurring campaign doc should exist');
+        assert.equal(doc.status, 'pending', 'Status returns to pending');
+        assert.ok(
+          doc.sendAt > state.now,
+          `sendAt must land in the FUTURE (no catch-up burst) — got ${doc.sendAt}, now ${state.now}`,
+        );
+
+        const expectedNext = getNextFutureOccurrence(state.staleSendAt, {
+          pattern: 'weekly',
+          hour: 10,
+          minute: 0,
+          day: 1,
+        }, state.now);
+        assert.equal(doc.sendAt, expectedNext, 'Skips all missed occurrences in one advance');
+      },
+    },
+
+    {
+      name: 'stale-processing-lease-reclaimed-and-processed',
+      auth: 'none',
+
+      async run({ firestore, assert }) {
+        const doc = await firestore.get('marketing-campaigns/_test-stale-processing');
+
+        assert.ok(doc, 'Stale-processing campaign doc should exist');
+        assert.ok(
+          doc.status === 'sent' || doc.status === 'failed',
+          `Reclaimed campaign should be processed to sent/failed, got: ${doc.status}`,
+        );
+      },
+    },
 
+    {
+      name: 'fresh-processing-lease-untouched',
+      auth: 'none',
+
+      async run({ firestore, assert, state }) {
+        const doc = await firestore.get('marketing-campaigns/_test-fresh-processing');
+
+        assert.ok(doc, 'Fresh-processing campaign doc should exist');
+        assert.equal(doc.status, 'processing', 'A fresh lease is honored — no reclaim, no double-send');
+        assert.equal(doc.processingStartedAt, state.now - 60, 'processingStartedAt is untouched');
+      },
+    },
+
+    {
+      name: 'unknown-generator-and-type-marked-failed',
+      auth: 'none',
+
+      async run({ firestore, assert }) {
+        const unknownGenerator = await firestore.get('marketing-campaigns/_test-unknown-generator');
+        const unknownType = await firestore.get('marketing-campaigns/_test-unknown-type');
+
+        assert.equal(unknownGenerator?.status, 'failed', 'Unknown generator is marked failed (not retried forever)');
+        assert.ok(/doesnotexist/.test(unknownGenerator?.error || ''), 'Error names the unknown generator');
+        assert.equal(unknownType?.status, 'failed', 'Unknown type is marked failed (not retried forever)');
+        assert.ok(/carrier-pigeon/.test(unknownType?.error || ''), 'Error names the unknown type');
+      },
+    },
+
+    {
+      name: 'generator-campaign-not-skipped',
+      auth: 'none',
+      timeout: 600000,
+
+      async run({ firestore, assert, state, config, waitFor }) {
         const newsletterEnabled = config.marketing?.newsletter?.enabled;
 
         if (newsletterEnabled && process.env.TEST_EXTENDED_MODE) {
-          // Extended mode with newsletter enabled: generator should have
-          // generated + sent in one shot, created a history doc, and
-          // advanced sendAt
-          const expectedNext = getNextOccurrence(state.pastSendAt, {
+          // Extended mode with newsletter enabled: the generator runs the
+          // full AI pipeline inline (minutes) — wait for the sendAt advance
+          // that marks completion, then verify the history doc.
+          await waitFor(
+            async () => {
+              const doc = await firestore.get('marketing-campaigns/_test-generator');
+              return doc?.sendAt !== state.pastSendAt;
+            },
+            570000,
+            5000,
+          );
+
+          const doc = await firestore.get('marketing-campaigns/_test-generator');
+          const expectedNext = getNextFutureOccurrence(state.pastSendAt, {
             pattern: 'weekly',
             hour: 17,
             minute: 30,
             day: 2,
-          });
+          }, state.now);
           assert.equal(doc.sendAt, expectedNext, 'Generator campaign sendAt should advance');
+          assert.equal(doc.status, 'pending', 'Recurring generator returns to pending');
 
           const histSnapshot = await firestore.collection('marketing-campaigns')
             .where('generatedFrom', '==', '_test-generator')
@@ -231,40 +434,96 @@ module.exports = {
             'History doc status should be sent or failed',
           );
           assert.ok(!histDoc.generator, 'History doc should NOT have a generator field');
+          assert.ok(!histDoc.settings?.article, 'History settings should NOT carry the full article payload');
         } else {
-          // Non-extended or newsletter disabled: generator returns null,
-          // sendAt stays unchanged (will retry next run). The critical
-          // assertion is that the campaign was ATTEMPTED, not skipped —
-          // verified by the cron logs showing "Running generator" and
-          // "returned no content" instead of "Skipping generator campaign".
-          assert.equal(doc.status, 'pending', 'Status stays pending when generator returns null');
+          // Default mode: the generator is gated by TEST_EXTENDED_MODE and
+          // returns null instantly. The campaign must be ATTEMPTED (claimed,
+          // generator run) and then released back to pending with the
+          // attempts counter incremented — the deterministic retry path.
+          await waitFor(
+            async () => {
+              const doc = await firestore.get('marketing-campaigns/_test-generator');
+              return doc?.status === 'pending' && (doc?.generatorAttempts || 0) >= 1;
+            },
+            30000,
+            500,
+          );
+
+          const doc = await firestore.get('marketing-campaigns/_test-generator');
+          assert.equal(doc.status, 'pending', 'Status returns to pending when generator returns null');
           assert.equal(doc.sendAt, state.pastSendAt, 'sendAt stays unchanged for retry when generator returns null');
+          assert.equal(doc.generatorAttempts, 1, 'generatorAttempts is incremented for the retry cap');
         }
       },
     },
 
+    {
+      name: 'generator-retry-cap-fails-oneoff-and-skips-recurring',
+      auth: 'none',
+
+      async run({ firestore, assert, state, waitFor }) {
+        // Default-mode only: extended mode would run the real pipeline for
+        // these seeds, so they are not created there.
+        if (process.env.TEST_EXTENDED_MODE) {
+          return;
+        }
+
+        await waitFor(
+          async () => {
+            const oneoff = await firestore.get('marketing-campaigns/_test-gen-cap-oneoff');
+            const recurring = await firestore.get('marketing-campaigns/_test-gen-cap-recurring');
+            return oneoff?.status === 'failed' && recurring?.sendAt !== state.staleSendAt;
+          },
+          30000,
+          500,
+        );
+
+        const oneoff = await firestore.get('marketing-campaigns/_test-gen-cap-oneoff');
+        assert.equal(oneoff.status, 'failed', 'One-off generator at the cap is marked failed');
+        assert.ok(/attempts/.test(oneoff.error || ''), 'Error explains the attempts cap');
+
+        const recurring = await firestore.get('marketing-campaigns/_test-gen-cap-recurring');
+        assert.equal(recurring.status, 'pending', 'Recurring generator at the cap stays pending');
+        assert.ok(recurring.sendAt > state.now, 'Recurring generator at the cap skips to a FUTURE occurrence');
+        assert.ok(!recurring.generatorAttempts, 'Attempts counter resets after skipping the occurrence');
+      },
+    },
+
     {
       name: 'cleanup',
       auth: 'none',
 
       async run({ firestore }) {
-        await firestore.delete('marketing-campaigns/_test-oneoff');
-        await firestore.delete('marketing-campaigns/_test-recurring');
-        await firestore.delete('marketing-campaigns/_test-generator');
+        const docs = [
+          '_test-oneoff',
+          '_test-recurring',
+          '_test-recurring-stale',
+          '_test-generator',
+          '_test-unknown-generator',
+          '_test-unknown-type',
+          '_test-stale-processing',
+          '_test-fresh-processing',
+          '_test-gen-cap-oneoff',
+          '_test-gen-cap-recurring',
+        ];
 
-        // Clean up history docs (from both recurring and generator campaigns)
-        const recurringHist = await firestore.collection('marketing-campaigns')
-          .where('recurringId', '==', '_test-recurring')
-          .get();
-        for (const doc of recurringHist.docs) {
-          await doc.ref.delete();
+        for (const id of docs) {
+          await firestore.delete(`marketing-campaigns/${id}`);
         }
 
-        const generatorHist = await firestore.collection('marketing-campaigns')
-          .where('generatedFrom', '==', '_test-generator')
-          .get();
-        for (const doc of generatorHist.docs) {
-          await doc.ref.delete();
+        // Clean up history docs (from recurring and generator campaigns)
+        for (const [field, value] of [
+          ['recurringId', '_test-recurring'],
+          ['recurringId', '_test-recurring-stale'],
+          ['recurringId', '_test-stale-processing'],
+          ['generatedFrom', '_test-generator'],
+        ]) {
+          const snapshot = await firestore.collection('marketing-campaigns')
+            .where(field, '==', value)
+            .get();
+          for (const doc of snapshot.docs) {
+            await doc.ref.delete();
+          }
         }
       },
     },

package/test/email/newsletter-generate.js

@@ -474,6 +474,18 @@ module.exports = {
     assert.ok(result.contentMarkdown, 'Generator returned contentMarkdown');
     assert.ok(result.structure?.sections?.length >= 2, 'Has at least 2 sections');
 
+    // Regression guard: with NEWSLETTER_CREATE_ARTICLE=1 the linked article
+    // must actually PUBLISH (commit to the website repo) and the CTA must be
+    // injected. Catches publish-path failures that generate-only runs mask
+    // (e.g. the v5.11.0 `sources` scope bug that silently failed every
+    // production publish inside buildLinkedArticle's try/catch).
+    if (env.NEWSLETTER_CREATE_ARTICLE && result.article) {
+      assert.ok(result.article.published === true,
+        `Linked article must be published when NEWSLETTER_CREATE_ARTICLE=1 (url: ${result.article.url})`);
+      assert.ok(result.structure.sections[0]?.cta?.url === result.article.url,
+        'Lead section CTA must point at the published article');
+    }
+
     // --- Write outputs ---
     const previewPath = path.join(runDir, 'newsletter.html');
     jetpack.write(previewPath, result.contentHtml);

package/test/helpers/content/blog-auto-publisher.js

@@ -38,6 +38,19 @@ module.exports = {
       },
     },
 
+    {
+      name: 'isURL-rejects-colon-prefixed-text-and-non-http-schemes',
+      async run({ assert }) {
+        // "AI:" parses as a URL scheme via new URL() — these are text seeds,
+        // not URLs, and must NOT be fetched (the fetch fails and the seed is
+        // silently lost)
+        assert.equal(isURL('AI: the future of work'), false);
+        assert.equal(isURL('Growth: 10 tactics for creators'), false);
+        assert.equal(isURL('mailto:someone@example.com'), false);
+        assert.equal(isURL('ftp://example.com/file'), false);
+      },
+    },
+
     {
       name: 'isURL-rejects-empty-and-null',
       async run({ assert }) {