backend-manager 5.9.27 → 5.10.1

package/docs/marketing-campaigns.md

@@ -43,16 +43,18 @@ Recurrence patterns: `daily`, `weekly`, `monthly`, `monthly-weekday`, `quarterly
 
 The `monthly-weekday` pattern targets the Nth weekday of each month (e.g., 2nd Wednesday). Requires `nth` (1-4) and `day` (0=Sun–6=Sat) in the recurrence object. All other patterns use simple interval addition from the current `sendAt`.
 
-All scheduling helpers live in `constants.js` (SSOT): `nextWeekday()`, `nextNthWeekday()`, `nextMonthDay()`, `getNextOccurrence()`. Both cron jobs import from there — no duplicated logic.
+All scheduling helpers live in `constants.js` (SSOT): `nextWeekday()`, `nextNthWeekday()`, `nextMonthDay()`, `getNextOccurrence()`. The cron job imports from there — no duplicated logic.
 
 ## Generator Campaigns
 
-Campaigns with a `generator` field don't send directly. A daily cron pre-generates content 24 hours before `sendAt`:
-1. Daily cron finds generator campaigns due within 24 hours
+Campaigns with a `generator` field (e.g. `generator: 'newsletter'`) are handled by the frequent cron inline — generate content and send in one shot when `sendAt` is due:
+1. Frequent cron finds the generator campaign past its `sendAt`
 2. Runs the generator module (e.g., `generators/newsletter.js`)
-3. Creates a NEW standalone `pending` campaign with generated content
-4. Advances the recurring template's `sendAt`
-5. Generated campaign appears on calendar for review, sent by frequent cron when due
+3. Sends the generated content immediately
+4. Stores a history record with generated content + send results
+5. Advances the recurring template's `sendAt` to the next occurrence
+
+In production, Beehiiv posts are published (`status: 'confirmed'`). In testing, they're forced to draft (`status: 'draft'`). If Beehiiv upload fails, a fallback alert email is sent to `alerts@{brandDomain}` with all asset links for manual upload.
 
 ## Email Rendering
 
@@ -229,16 +231,19 @@ AI provider defaults live in code (openai for structure, anthropic for SVG — e
 
 ## Asset hosting (production cron flow)
 
-The daily cron uploads per-section PNGs + the rendered `newsletter.html` + `newsletter.md` + `summary.md` to the public `itw-creative-works/newsletter-assets` repo as two atomic Git Trees commits per issue (PNGs first so URLs exist for embedding, then HTML/MD/summary in a second commit). Folder layout:
+The frequent cron uploads per-section PNGs + the rendered `newsletter.html` + `newsletter.md` + `summary.md` to the public `itw-creative-works/newsletter-assets` repo. Each brand pushes to its own branch (branch name = brandId) — zero contention when multiple brands upload concurrently. New brand branches are created automatically as empty orphans on first upload. Folder layout:
 
 ```
-{brandId}/{campaignId}/
-  section-N.png       — per-section illustration (embedded in HTML)
-  newsletter.html     — final rendered email-safe HTML
-  newsletter.md       — programmatic markdown view (per-section ## blocks, ready for Beehiiv paste)
-  summary.md          — short editorial recap (2-3 sentences)
+Branch: {brandId}
+  content/{campaignId}/
+    section-N.png       — per-section illustration (embedded in HTML)
+    newsletter.html     — final rendered email-safe HTML
+    newsletter.md       — programmatic markdown view (per-section ## blocks, ready for Beehiiv paste)
+    summary.md          — short editorial recap (2-3 sentences)
 ```
 
+The `main` branch is a viewer hub (GitHub Pages) — no newsletter content.
+
 `newsletter.md` is built programmatically from the same `structure` JSON the HTML is rendered from (no AI cost) by `lib/markdown-renderer.js`. Each section/dispatch becomes a standalone `## heading` block — drop it into the Beehiiv editor one block at a time and insert ad blocks between dispatches.
 
 The `campaignId` is the same Firestore doc ID the cron uses for the generated `marketing-campaigns/{newId}` doc, reserved up front so the GitHub URLs and the Firestore doc always match.
@@ -250,7 +255,7 @@ marketing-campaigns/{newId}: {
   settings:    { subject, preheader, contentHtml, ... },
   assets: {
     campaignId,           // same as the doc id
-    folderUrl,            // https://github.com/itw-creative-works/newsletter-assets/tree/main/{brandId}/{campaignId}
+    folderUrl,            // https://github.com/itw-creative-works/newsletter-assets/tree/{brandId}/content/{campaignId}
     htmlUrl,              // https://raw.githubusercontent.com/.../newsletter.html  — paste this into Beehiiv as one block
     markdownUrl,          // https://raw.githubusercontent.com/.../newsletter.md    — per-section blocks (ads between)
     summaryUrl,           // https://raw.githubusercontent.com/.../summary.md       — share-snippet recap
@@ -366,7 +371,6 @@ marketing: {
 | SendGrid provider | `src/manager/libraries/email/providers/sendgrid.js` |
 | Beehiiv provider | `src/manager/libraries/email/providers/beehiiv.js` |
 | Campaign routes | `src/manager/routes/marketing/campaign/{get,post,put,delete}.js` |
-| Campaign cron | `src/manager/cron/frequent/marketing-campaigns.js` |
-| Newsletter pre-gen cron | `src/manager/cron/daily/marketing-newsletter-generate.js` |
-| Pruning cron | `src/manager/cron/daily/marketing-prune.js` |
+| Campaign + newsletter cron | `src/manager/events/cron/frequent/marketing-campaigns.js` |
+| Pruning cron | `src/manager/events/cron/daily/marketing-prune.js` |
 | Seed campaigns | `src/cli/commands/setup-tests/helpers/seed-campaigns.js` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backend-manager",
-  "version": "5.9.27",
+  "version": "5.10.1",
   "description": "Quick tools for developing Firebase functions",
   "main": "src/manager/index.js",
   "files": [

package/src/manager/events/cron/frequent/marketing-campaigns.js

@@ -6,6 +6,12 @@
  *   - email: fires through mailer.sendCampaign()
  *   - push: fires through notification.send()
  *
+ * Generator campaigns (has `generator` field, e.g. 'newsletter'):
+ *   - Runs the content generation pipeline (AI content, images, uploads)
+ *   - Sends the generated content immediately
+ *   - Stores a history record with the generated content + send results
+ *   - Advances the recurring template's sendAt to the next occurrence
+ *
  * Recurring campaigns (has `recurrence` field):
  *   - Creates a history doc in the same collection with results
  *   - Advances the recurring doc's sendAt to the next occurrence
@@ -46,9 +52,81 @@ module.exports = async ({ Manager, assistant, libraries }) => {
 
     assistant.log(`Processing campaign ${campaignId} (${type}): ${settings.name}`);
 
-    // --- Generator campaigns are handled by the daily pre-generation cron, not here ---
+    // --- Generator campaigns: generate content + send in one shot ---
     if (generator) {
-      assistant.log(`Skipping generator campaign ${campaignId} — handled by daily pre-generation cron`);
+      const generators = {
+        newsletter: require('../../../libraries/email/generators/newsletter.js'),
+      };
+
+      if (!generators[generator]) {
+        assistant.log(`Unknown generator "${generator}" on ${campaignId}, skipping`);
+        return;
+      }
+
+      assistant.log(`Running generator "${generator}" for ${campaignId}...`);
+
+      const generatedId = pushid();
+      const generated = await generators[generator].generate(Manager, assistant, settings, {
+        campaignId: generatedId,
+        imageHost: 'github',
+        publishArticle: Manager.isProduction(),
+      });
+
+      if (!generated) {
+        assistant.log(`Generator "${generator}" returned no content for ${campaignId}, will retry next run`);
+        return;
+      }
+
+      const {
+        images: _images,
+        mjml: _mjml,
+        structure: _structure,
+        contentMarkdown: _contentMarkdown,
+        assets,
+        meta,
+        ...generatedSettings
+      } = generated;
+
+      assistant.log(`Generated content for ${campaignId}: "${generated.subject}"`);
+
+      // Send immediately
+      const campaignResults = await email.sendCampaign({ ...generatedSettings, sendAt: 'now' });
+      const success = Object.values(campaignResults).some(r => r.success || r.sent > 0);
+
+      const nowISO = new Date().toISOString();
+      const nowUNIX = Math.round(Date.now() / 1000);
+
+      // Store history record
+      const historyId = pushid();
+      await admin.firestore().doc(`marketing-campaigns/${historyId}`).set({
+        settings: generatedSettings,
+        assets: assets || null,
+        meta: meta || null,
+        type,
+        sendAt: data.sendAt,
+        status: success ? 'sent' : 'failed',
+        results: campaignResults,
+        generatedFrom: campaignId,
+        metadata: {
+          created: { timestamp: nowISO, timestampUNIX: nowUNIX },
+          updated: { timestamp: nowISO, timestampUNIX: nowUNIX },
+        },
+      });
+
+      // Advance sendAt to next occurrence
+      if (recurrence) {
+        const nextSendAt = getNextOccurrence(data.sendAt, recurrence);
+        await doc.ref.set({
+          sendAt: nextSendAt,
+          metadata: {
+            updated: { timestamp: nowISO, timestampUNIX: nowUNIX },
+          },
+        }, { merge: true });
+        assistant.log(`${success ? 'Sent' : 'Failed'} generator campaign ${campaignId}, next: ${moment.unix(nextSendAt).toISOString()}`);
+      } else {
+        assistant.log(`${success ? 'Sent' : 'Failed'} generator campaign ${campaignId} (one-off)`);
+      }
+
       return;
     }
 

package/src/manager/libraries/email/generators/lib/image-host.js

@@ -3,18 +3,23 @@
  * rendered `newsletter.html`) to the public `itw-creative-works/newsletter-assets`
  * GitHub repo as a single atomic commit.
  *
+ * Each brand pushes to its own branch (branch name = brandId). This
+ * eliminates race conditions — 30+ brands can upload concurrently with
+ * zero contention. The `main` branch hosts only the viewer page
+ * (index.html on GitHub Pages) for browser-renderable previews.
+ *
  * Returns publicly resolvable URLs:
- *   - Image URLs (`raw.githubusercontent.com`): embedded in the HTML via
- *     <img src=...> so Beehiiv / SendGrid / any inbox can render them
+ *   - Image URLs (`raw.githubusercontent.com/{owner}/{repo}/{brandId}/...`):
+ *     embedded in the HTML via <img src=...>
  *   - HTML URL (`raw.githubusercontent.com`): download link for manual paste
- *     into Beehiiv (and a stable archive of every issue's final rendered form)
- *   - Preview URL (`*.github.io`): browser-renderable HTML via GitHub Pages
+ *   - Preview URL (`*.github.io/?path=...`): viewer page that fetches and
+ *     renders the newsletter HTML in-browser
  *
  * Public-safety guarantees baked in:
  *   - Only accepts PNG buffers for images — verified by magic-byte check
  *   - HTML must be a non-empty string (no buffers, no other types)
  *   - Path validated against a strict allowlist regex per file kind
- *   - Repo / branch hardcoded (no env override) so a misconfigured caller
+ *   - Repo owner hardcoded (no env override) so a misconfigured caller
  *     can't redirect uploads elsewhere
  *   - One atomic commit per newsletter (Git Trees API)
  *
@@ -25,19 +30,18 @@ const { Octokit } = require('@octokit/rest');
 
 const REPO_OWNER = 'itw-creative-works';
 const REPO_NAME  = 'newsletter-assets';
-const REPO_BRANCH = 'main';
 
-const RAW_BASE = `https://raw.githubusercontent.com/${REPO_OWNER}/${REPO_NAME}/${REPO_BRANCH}`;
 const PAGES_BASE = `https://${REPO_OWNER}.github.io/${REPO_NAME}`;
 
-// `{brandId}/{campaignId}/section-N.png` — both ids are kebab/alphanumeric
-const IMAGE_PATH_REGEX = /^[a-z0-9-]+\/[A-Za-z0-9_-]+\/section-\d+\.png$/;
-// `{brandId}/{campaignId}/newsletter.html` — fixed file name, same folder
-const HTML_PATH_REGEX  = /^[a-z0-9-]+\/[A-Za-z0-9_-]+\/newsletter\.html$/;
-// `{brandId}/{campaignId}/newsletter.md` — markdown view, same folder
-const MARKDOWN_PATH_REGEX = /^[a-z0-9-]+\/[A-Za-z0-9_-]+\/newsletter\.md$/;
-// `{brandId}/{campaignId}/summary.md` — short editorial recap, same folder
-const SUMMARY_PATH_REGEX  = /^[a-z0-9-]+\/[A-Za-z0-9_-]+\/summary\.md$/;
+// Fallback RAW_BASE for callers that don't have a brand context
+const RAW_BASE = `https://raw.githubusercontent.com/${REPO_OWNER}/${REPO_NAME}/main`;
+
+// `content/{campaignId}/section-N.png` — brand is the branch, not the path
+const CONTENT_DIR = 'content';
+const IMAGE_PATH_REGEX = /^content\/[A-Za-z0-9_-]+\/section-\d+\.png$/;
+const HTML_PATH_REGEX  = /^content\/[A-Za-z0-9_-]+\/newsletter\.html$/;
+const MARKDOWN_PATH_REGEX = /^content\/[A-Za-z0-9_-]+\/newsletter\.md$/;
+const SUMMARY_PATH_REGEX  = /^content\/[A-Za-z0-9_-]+\/summary\.md$/;
 
 // PNG magic bytes: 89 50 4E 47 0D 0A 1A 0A
 const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
@@ -50,11 +54,11 @@ const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
  *                                                Optional — pass an empty array or omit if
  *                                                you only want to upload the HTML (rare).
  * @param {string} [args.html] - The final rendered newsletter HTML. Uploaded as
- *                                `{brandId}/{campaignId}/newsletter.html`.
+ *                                `content/{campaignId}/newsletter.html`.
  * @param {string} [args.markdown] - Programmatic markdown view of the newsletter.
- *                                    Uploaded as `{brandId}/{campaignId}/newsletter.md`.
+ *                                    Uploaded as `content/{campaignId}/newsletter.md`.
  * @param {string} [args.summary] - Short editorial recap (2-3 sentences). Uploaded
- *                                   as `{brandId}/{campaignId}/summary.md`.
+ *                                   as `content/{campaignId}/summary.md`.
  * @param {string} args.brandId - lowercase brand slug (e.g. 'somiibo')
  * @param {string} args.campaignId - Consumer-side `marketing-campaigns/{id}` Firestore doc ID.
  *                                   Folder names use this verbatim — stable forever.
@@ -86,13 +90,17 @@ async function uploadAssets({ images, html, markdown, summary, brandId, campaign
 
   const log = (msg) => assistant?.log ? assistant.log(`[image-host] ${msg}`) : null;
 
+  // Brand branch — each brand gets its own branch, zero cross-brand contention
+  const branch = brandId;
+  const rawBase = `https://raw.githubusercontent.com/${REPO_OWNER}/${REPO_NAME}/${branch}`;
+
   // 1. Build the list of files to commit. Validate each before we touch GitHub.
   const files = [];
 
   if (hasImages) {
     for (let i = 0; i < images.length; i++) {
       const img = images[i];
-      const path = `${brandId}/${campaignId}/section-${i + 1}.png`;
+      const path = `${CONTENT_DIR}/${campaignId}/section-${i + 1}.png`;
 
       if (!IMAGE_PATH_REGEX.test(path)) {
         throw new Error(`image-host: refusing to upload — invalid image path "${path}"`);
@@ -115,7 +123,7 @@ async function uploadAssets({ images, html, markdown, summary, brandId, campaign
   }
 
   if (hasHtml) {
-    const path = `${brandId}/${campaignId}/newsletter.html`;
+    const path = `${CONTENT_DIR}/${campaignId}/newsletter.html`;
 
     if (!HTML_PATH_REGEX.test(path)) {
       throw new Error(`image-host: refusing to upload — invalid html path "${path}"`);
@@ -129,7 +137,7 @@ async function uploadAssets({ images, html, markdown, summary, brandId, campaign
   }
 
   if (hasMarkdown) {
-    const path = `${brandId}/${campaignId}/newsletter.md`;
+    const path = `${CONTENT_DIR}/${campaignId}/newsletter.md`;
 
     if (!MARKDOWN_PATH_REGEX.test(path)) {
       throw new Error(`image-host: refusing to upload — invalid markdown path "${path}"`);
@@ -143,7 +151,7 @@ async function uploadAssets({ images, html, markdown, summary, brandId, campaign
   }
 
   if (hasSummary) {
-    const path = `${brandId}/${campaignId}/summary.md`;
+    const path = `${CONTENT_DIR}/${campaignId}/summary.md`;
 
     if (!SUMMARY_PATH_REGEX.test(path)) {
       throw new Error(`image-host: refusing to upload — invalid summary path "${path}"`);
@@ -164,26 +172,41 @@ async function uploadAssets({ images, html, markdown, summary, brandId, campaign
     hasSummary ? 'summary.md' : null,
   ].filter(Boolean).join(' + ');
 
-  log(`uploading ${fileSummary} to ${REPO_OWNER}/${REPO_NAME} → ${brandId}/${campaignId}/`);
+  log(`uploading ${fileSummary} to ${REPO_OWNER}/${REPO_NAME}:${branch} → ${CONTENT_DIR}/${campaignId}/`);
 
   const octokit = new Octokit({ auth: githubToken });
 
-  // 2. Get current main branch ref + tree
-  const { data: refData } = await octokit.rest.git.getRef({
-    owner: REPO_OWNER,
-    repo: REPO_NAME,
-    ref: `heads/${REPO_BRANCH}`,
-  });
-
-  const baseCommitSha = refData.object.sha;
-
-  const { data: baseCommit } = await octokit.rest.git.getCommit({
-    owner: REPO_OWNER,
-    repo: REPO_NAME,
-    commit_sha: baseCommitSha,
-  });
+  // 2. Ensure the brand branch exists. New branches start empty (orphan
+  //    commit with an empty tree) — no files from main, no shared history.
+  let branchSha;
+  try {
+    const { data } = await octokit.rest.git.getRef({ owner: REPO_OWNER, repo: REPO_NAME, ref: `heads/${branch}` });
+    branchSha = data.object.sha;
+  } catch (e) {
+    if (e.status === 404) {
+      // Create an empty tree → orphan commit → brand branch
+      const { data: emptyTree } = await octokit.rest.git.createTree({
+        owner: REPO_OWNER, repo: REPO_NAME, tree: [],
+      });
+      const { data: orphanCommit } = await octokit.rest.git.createCommit({
+        owner: REPO_OWNER, repo: REPO_NAME,
+        message: `Initialize ${branch} branch`,
+        tree: emptyTree.sha,
+        parents: [],
+      });
+      await octokit.rest.git.createRef({
+        owner: REPO_OWNER, repo: REPO_NAME,
+        ref: `refs/heads/${branch}`,
+        sha: orphanCommit.sha,
+      });
+      branchSha = orphanCommit.sha;
+      log(`created empty branch "${branch}"`);
+    } else {
+      throw e;
+    }
+  }
 
-  // 3. Create a blob per file
+  // 3. Create blobs (content-addressed — safe to reuse if we ever add retries)
   const treeItems = [];
 
   for (const file of files) {
@@ -202,7 +225,13 @@ async function uploadAssets({ images, html, markdown, summary, brandId, campaign
     });
   }
 
-  // 4. Build new tree on top of base
+  // 4. Build tree on top of the branch tip
+  const { data: baseCommit } = await octokit.rest.git.getCommit({
+    owner: REPO_OWNER,
+    repo: REPO_NAME,
+    commit_sha: branchSha,
+  });
+
   const { data: newTree } = await octokit.rest.git.createTree({
     owner: REPO_OWNER,
     repo: REPO_NAME,
@@ -210,8 +239,7 @@ async function uploadAssets({ images, html, markdown, summary, brandId, campaign
     tree: treeItems,
   });
 
-  // 5. Commit. Default message format: "[brand] campaignId — Subject" so
-  //    `git log` doubles as a human-readable index of the (opaque) folder names.
+  // 5. Commit
   const defaultSubject = subject ? subject.trim() : `${files.length} newsletter asset${files.length === 1 ? '' : 's'}`;
   const message = commitMessage || `[${brandId}] ${campaignId} — ${defaultSubject}`;
 
@@ -220,14 +248,17 @@ async function uploadAssets({ images, html, markdown, summary, brandId, campaign
     repo: REPO_NAME,
     message,
     tree: newTree.sha,
-    parents: [baseCommitSha],
+    parents: [branchSha],
   });
 
-  // 6. Update branch ref
+  // 6. Update brand branch ref. Since each brand has its own branch,
+  //    the only possible race is the SAME brand uploading images and HTML
+  //    at the same time — which is sequential in the newsletter pipeline.
+  //    No retry/jitter needed.
   await octokit.rest.git.updateRef({
     owner: REPO_OWNER,
     repo: REPO_NAME,
-    ref: `heads/${REPO_BRANCH}`,
+    ref: `heads/${branch}`,
     sha: newCommit.sha,
   });
 
@@ -238,29 +269,29 @@ async function uploadAssets({ images, html, markdown, summary, brandId, campaign
   const summaryFile = files.find((f) => f.kind === 'summary');
 
   const result = {
-    urls: imageFiles.map((f) => `${RAW_BASE}/${f.path}`),
+    urls: imageFiles.map((f) => `${rawBase}/${f.path}`),
     paths: imageFiles.map((f) => f.path),
-    folderUrl: `https://github.com/${REPO_OWNER}/${REPO_NAME}/tree/${REPO_BRANCH}/${brandId}/${campaignId}`,
+    folderUrl: `https://github.com/${REPO_OWNER}/${REPO_NAME}/tree/${branch}/${CONTENT_DIR}/${campaignId}`,
     commitSha: newCommit.sha,
   };
 
   if (htmlFile) {
-    result.htmlUrl = `${RAW_BASE}/${htmlFile.path}`;
+    result.htmlUrl = `${rawBase}/${htmlFile.path}`;
     result.htmlPath = htmlFile.path;
-    result.previewUrl = `${PAGES_BASE}/${htmlFile.path}`;
+    result.previewUrl = `${PAGES_BASE}/?path=${encodeURIComponent(htmlFile.path)}&branch=${encodeURIComponent(branch)}`;
   }
 
   if (markdownFile) {
-    result.markdownUrl = `${RAW_BASE}/${markdownFile.path}`;
+    result.markdownUrl = `${rawBase}/${markdownFile.path}`;
     result.markdownPath = markdownFile.path;
   }
 
   if (summaryFile) {
-    result.summaryUrl = `${RAW_BASE}/${summaryFile.path}`;
+    result.summaryUrl = `${rawBase}/${summaryFile.path}`;
     result.summaryPath = summaryFile.path;
   }
 
-  log(`committed ${newCommit.sha.slice(0, 7)} — folder: ${result.folderUrl}`);
+  log(`committed ${newCommit.sha.slice(0, 7)} to ${branch} — folder: ${result.folderUrl}`);
 
   return result;
 }
@@ -281,7 +312,6 @@ module.exports = {
   uploadAssets,
   REPO_OWNER,
   REPO_NAME,
-  REPO_BRANCH,
   RAW_BASE,
   PAGES_BASE,
 };

package/src/manager/libraries/email/generators/newsletter.js

@@ -1,7 +1,7 @@
 /**
  * Newsletter generator — pulls content from parent server and assembles a branded newsletter.
  *
- * Called by the daily pre-generation cron (and the iteration test) when a campaign has
+ * Called by the frequent cron (and the iteration test) when a campaign has
  * `generator: 'newsletter'`. Produces a fully rendered email-safe HTML newsletter ready
  * to ship to Beehiiv / SendGrid.
  *
@@ -267,14 +267,14 @@ async function generate(Manager, assistant, settings, opts = {}) {
 
   const [, articleResult] = await Promise.all([buildImages(), buildArticle()]);
 
-  // Inject the "Read the full article" CTA onto the lead section BEFORE render.
-  // sectionCard (MJML) renders section.cta = { label, url } automatically; the
-  // markdown renderer emits it too. The URL is the post's public blog URL —
-  // present whether the article was actually published or only generated
-  // (derived from the title slug), so the newsletter links correctly either way.
-  if (articleResult?.url) {
+  // Inject the "Read the full article" CTA onto the lead section BEFORE render,
+  // but ONLY if the article was actually published. A CTA pointing to a
+  // non-existent post is worse than no CTA at all.
+  if (articleResult?.url && articleResult.published) {
     structure.sections[0].cta = { label: 'Read the full article', url: articleResult.url };
-    assistant.log(`Newsletter generator: linked article ${articleResult.published ? 'published' : 'generated (not published)'} — ${articleResult.url}`);
+    assistant.log(`Newsletter generator: linked article published — ${articleResult.url}`);
+  } else if (articleResult?.url) {
+    assistant.log(`Newsletter generator: linked article generated (not published, CTA omitted) — ${articleResult.url}`);
   }
 
   // 3. MJML → HTML
@@ -337,13 +337,10 @@ async function generate(Manager, assistant, settings, opts = {}) {
     }
   }
 
-  // 3c. Upload to Beehiiv as a draft. Uses the same complete HTML with
-  //     CDN image URLs already embedded. Today this will fail (Beehiiv's
-  //     post-creation API requires Enterprise plan), but we ship it anyway
-  //     so the day we upgrade to Enterprise it Just Works. Failure is logged,
-  //     never thrown — the rest of the pipeline (GH archive, Firestore doc)
-  //     succeeds regardless. newsletterRoleConfig was already resolved at the top
-  //     of the function for the initial enabled-check.
+  // 3c. Upload to Beehiiv. Published in production, forced to draft in
+  //     testing so real subscribers never receive test newsletters. Failure
+  //     is logged, never thrown — the rest of the pipeline (GH archive,
+  //     Firestore doc) succeeds regardless.
   let beehiivPostId = null;
   let beehiivFailureReason = null;
 
@@ -351,22 +348,21 @@ async function generate(Manager, assistant, settings, opts = {}) {
     try {
       const beehiivProvider = require('../providers/beehiiv.js');
       const result = await beehiivProvider.createPost({
-        publicationId: newsletterRoleConfig.publicationId,  // explicit — avoids singleton-Manager dependency
+        publicationId: newsletterRoleConfig.publicationId,
         title:         structure.subject,
         subject:       structure.subject,
         preheader:     structure.preheader,
         content:       html,
         contentTags:   Array.isArray(structure.tags) ? structure.tags : [],
-        status:        'draft',
+        status:        assistant.isTesting() ? 'draft' : 'confirmed',
       });
 
       if (result?.success && result.id) {
         beehiivPostId = result.id;
-        assistant.log(`Newsletter generator: Beehiiv draft created — ${beehiivPostId}`);
+        assistant.log(`Newsletter generator: Beehiiv ${assistant.isTesting() ? 'draft' : 'post'} created — ${beehiivPostId}`);
       } else {
-        // Expected today until Enterprise plan — log, do not throw.
         beehiivFailureReason = result?.error || 'unknown error';
-        assistant.log(`Newsletter generator: Beehiiv draft upload skipped/failed — ${beehiivFailureReason}`);
+        assistant.log(`Newsletter generator: Beehiiv upload failed — ${beehiivFailureReason}`);
       }
     } catch (e) {
       beehiivFailureReason = e.message;
@@ -750,4 +746,4 @@ function generatePushId() {
   return id;
 }
 
-module.exports = { generate, fetchSources, generatePushId };
+module.exports = { generate, generatePushId };

package/src/mcp/tools.js

@@ -459,7 +459,7 @@ module.exports = [
   // --- Hooks ---
   {
     name: 'run_hook',
-    description: 'Execute a hook or BEM cron job by path. Searches: BEM internal crons (e.g. "cron/daily/blog-auto-publisher", "cron/daily/marketing-newsletter-generate"), consumer hooks/ directory, and consumer project root. Supports both function exports and class-based hooks.',
+    description: 'Execute a hook or BEM cron job by path. Searches: BEM internal crons (e.g. "cron/daily/blog-auto-publisher", "cron/daily/reset-usage"), consumer hooks/ directory, and consumer project root. Supports both function exports and class-based hooks.',
     role: 'admin',
     method: 'POST',
     path: 'admin/hook',
@@ -467,7 +467,7 @@ module.exports = [
     inputSchema: {
       type: 'object',
       properties: {
-        path: { type: 'string', description: 'Hook path (e.g. "cron/daily/blog-auto-publisher", "cron/daily/marketing-newsletter-generate", "cron/daily/reset-usage", "cron/frequent/marketing-campaigns", or a consumer hook path)' },
+        path: { type: 'string', description: 'Hook path (e.g. "cron/daily/blog-auto-publisher", "cron/daily/reset-usage", "cron/frequent/marketing-campaigns", or a consumer hook path)' },
       },
       required: ['path'],
     },

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

@@ -0,0 +1,272 @@
+/**
+ * Test: Campaign cron pipeline
+ *
+ * Verifies that bm_cronFrequent correctly picks up and processes campaigns
+ * from the marketing-campaigns collection when their sendAt is past due.
+ *
+ * Covers:
+ *   1. One-off campaigns: status changes from 'pending' to 'sent'/'failed'
+ *   2. Recurring campaigns: sendAt advances, history doc created
+ *   3. Generator campaigns (e.g. newsletter): NOT skipped — the generator
+ *      pipeline runs inline and produces a new campaign doc
+ *
+ * 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.
+ */
+const { getNextOccurrence } = require('../../src/manager/libraries/email/constants.js');
+
+module.exports = {
+  description: 'Campaign cron pipeline (frequent cron processes all campaign types)',
+  type: 'suite',
+  timeout: 60000,
+
+  tests: [
+    {
+      name: 'seed-campaigns',
+      auth: 'none',
+
+      async run({ firestore, state }) {
+        const now = Math.round(Date.now() / 1000);
+        const pastSendAt = now - 600;
+
+        // 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 },
+          },
+        });
+
+        // Recurring email campaign (sendAt 10 min ago, weekly recurrence)
+        await firestore.set('marketing-campaigns/_test-recurring', {
+          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 },
+          },
+        });
+
+        // Generator campaign (newsletter — sendAt 10 min ago)
+        await firestore.set('marketing-campaigns/_test-generator', {
+          status: 'pending',
+          type: 'email',
+          generator: 'newsletter',
+          sendAt: pastSendAt,
+          recurrence: {
+            pattern: 'weekly',
+            hour: 17,
+            minute: 30,
+            day: 2,
+          },
+          settings: {
+            name: '{brand.name} Newsletter — {date.month} {date.year}',
+            subject: '',
+            preheader: '',
+            sender: 'newsletter',
+            providers: ['newsletter'],
+          },
+          metadata: {
+            created: { timestamp: new Date().toISOString(), timestampUNIX: now },
+            updated: { timestamp: new Date().toISOString(), timestampUNIX: now },
+          },
+        });
+
+        state.pastSendAt = pastSendAt;
+      },
+    },
+
+    {
+      name: 'trigger-frequent-cron',
+      auth: 'none',
+      timeout: 120000,
+
+      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.
+        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;
+          },
+          90000,
+          1000,
+        );
+      },
+    },
+
+    {
+      name: 'oneoff-campaign-processed',
+      auth: 'none',
+
+      async run({ firestore, assert }) {
+        const doc = await firestore.get('marketing-campaigns/_test-oneoff');
+
+        assert.ok(doc, 'One-off campaign doc should exist');
+        assert.ok(
+          doc.status === 'sent' || doc.status === 'failed',
+          `One-off campaign status should be sent or failed, got: ${doc.status}`,
+        );
+        assert.ok(doc.metadata?.updated, 'Should have updated metadata');
+      },
+    },
+
+    {
+      name: 'recurring-campaign-advanced',
+      auth: 'none',
+
+      async run({ firestore, assert, state }) {
+        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');
+
+        const expectedNext = getNextOccurrence(state.pastSendAt, {
+          pattern: 'weekly',
+          hour: 10,
+          minute: 0,
+          day: 1,
+        });
+        assert.equal(doc.sendAt, expectedNext, 'sendAt should advance to next occurrence');
+      },
+    },
+
+    {
+      name: 'recurring-campaign-has-history',
+      auth: 'none',
+
+      async run({ firestore, assert }) {
+        const snapshot = await firestore.collection('marketing-campaigns')
+          .where('recurringId', '==', '_test-recurring')
+          .limit(1)
+          .get();
+
+        assert.ok(!snapshot.empty, 'Should have a history doc from the recurring campaign');
+
+        const history = snapshot.docs[0].data();
+        assert.ok(
+          history.status === 'sent' || history.status === 'failed',
+          'History doc status should be sent or failed',
+        );
+        assert.equal(history.recurringId, '_test-recurring', 'Should reference the recurring campaign');
+      },
+    },
+
+    {
+      name: 'generator-campaign-not-skipped',
+      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');
+
+        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, {
+            pattern: 'weekly',
+            hour: 17,
+            minute: 30,
+            day: 2,
+          });
+          assert.equal(doc.sendAt, expectedNext, 'Generator campaign sendAt should advance');
+
+          const histSnapshot = await firestore.collection('marketing-campaigns')
+            .where('generatedFrom', '==', '_test-generator')
+            .limit(1)
+            .get();
+          assert.ok(!histSnapshot.empty, 'Should have a history doc from the generator');
+          const histDoc = histSnapshot.docs[0].data();
+          assert.ok(
+            histDoc.status === 'sent' || histDoc.status === 'failed',
+            'History doc status should be sent or failed',
+          );
+          assert.ok(!histDoc.generator, 'History doc should NOT have a generator field');
+        } 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');
+          assert.equal(doc.sendAt, state.pastSendAt, 'sendAt stays unchanged for retry when generator returns null');
+        }
+      },
+    },
+
+    {
+      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');
+
+        // 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();
+        }
+
+        const generatorHist = await firestore.collection('marketing-campaigns')
+          .where('generatedFrom', '==', '_test-generator')
+          .get();
+        for (const doc of generatorHist.docs) {
+          await doc.ref.delete();
+        }
+      },
+    },
+  ],
+};

package/test/email/newsletter-generate.js

@@ -96,8 +96,10 @@ module.exports = {
     const env = process.env;
 
     // --- Apply env overrides into newsletterConfig ---
-    // Newsletter config now lives under marketing.newsletter.content.
-    const newsletterConfig = JSON.parse(JSON.stringify(config.marketing?.newsletter?.content || {}));
+    // Newsletter config lives under marketing.newsletter.content (array or object).
+    const rawContent = config.marketing?.newsletter?.content;
+    const contentEntry = Array.isArray(rawContent) ? rawContent[0] : rawContent;
+    const newsletterConfig = JSON.parse(JSON.stringify(contentEntry || {}));
 
     if (env.NEWSLETTER_PROVIDER_STRUCTURE) {
       newsletterConfig.provider = { ...(newsletterConfig.provider || {}), structure: env.NEWSLETTER_PROVIDER_STRUCTURE };

package/test/routes/test/usage.js

@@ -257,7 +257,7 @@ module.exports = {
 
         // Wait for cron to reset daily counter.
         // bm_cronDaily executes every registered daily job sequentially. In EXTENDED
-        // mode the real-API jobs (marketing-newsletter-generate, expire-paypal-cancellations,
+        // mode the real-API jobs (expire-paypal-cancellations,
         // blog-auto-publisher, etc.) can take 40-50s combined before reset-usage
         // (alphabetical tail) gets its turn. 70s gives that the headroom it needs;
         // the per-test `timeout` below matches.

package/src/manager/events/cron/daily/marketing-newsletter-generate.js

@@ -1,160 +0,0 @@
-/**
- * Newsletter pre-generation cron job
- *
- * Runs daily. Looks for generator campaigns (e.g., _recurring-newsletter)
- * with sendAt within the next 24 hours. For each due campaign it runs the
- * FULL pipeline:
- *
- *   1. Fetch + filter sources from parent server (per brand category set)
- *   2. AI authors structured content (subject, sections/dispatches, signoff, ...)
- *   3. AI authors per-section SVG, rasterized to PNG
- *   4. Upload PNGs to itw-creative-works/newsletter-assets/{brandId}/{newId}/
- *      and render MJML → email-safe HTML embedding those URLs
- *   5. Upload the rendered newsletter.html into the same folder so the issue
- *      has a browseable, downloadable archive (and a paste-into-Beehiiv URL)
- *   6. Create a NEW pending campaign doc with the generated content + asset URLs
- *   7. Advance the recurring template's sendAt to the next occurrence
- *
- * The generated campaign appears on the calendar for review.
- * The frequent cron picks it up and sends it when sendAt is due.
- *
- * Generated doc shape (marketing-campaigns/{newId}):
- *   {
- *     settings:        { ...generated content, subject, contentHtml, ... },
- *     assets:          { folderUrl, htmlUrl, imageUrls, campaignId },
- *     meta:            { telemetry — tokens, cost, durations, source scores },
- *     type, sendAt, status: 'pending', generatedFrom, metadata
- *   }
- *
- * Runs on bm_cronDaily.
- */
-const moment = require('moment');
-const pushid = require('pushid');
-const { getNextOccurrence } = require('../../../libraries/email/constants.js');
-
-// Generator modules — keyed by generator field value
-const generators = {
-  newsletter: require('../../../libraries/email/generators/newsletter.js'),
-};
-
-module.exports = async ({ Manager, assistant, libraries }) => {
-  const { admin } = libraries;
-
-  const now = Math.round(Date.now() / 1000);
-  const oneDayFromNow = now + (24 * 60 * 60);
-
-  // Find generator campaigns with sendAt within the next 24 hours
-  const snapshot = await admin.firestore()
-    .collection('marketing-campaigns')
-    .where('status', '==', 'pending')
-    .where('sendAt', '<=', oneDayFromNow)
-    .get();
-
-  // Filter to only generator campaigns (can't query on field existence in Firestore)
-  const generatorDocs = snapshot.docs.filter(doc => doc.data().generator);
-
-  if (!generatorDocs.length) {
-    assistant.log('No generator campaigns due within 24 hours');
-    return;
-  }
-
-  assistant.log(`Pre-generating ${generatorDocs.length} campaign(s)...`);
-
-  for (const doc of generatorDocs) {
-    const data = doc.data();
-    const { settings, type, generator, recurrence } = data;
-    const campaignId = doc.id;
-
-    if (!generators[generator]) {
-      assistant.log(`Unknown generator "${generator}" on ${campaignId}, skipping`);
-      continue;
-    }
-
-    assistant.log(`Generating content for ${campaignId} (${generator}): ${settings.name}`);
-
-    // Reserve the new doc ID UP FRONT so the generator can use it as the
-    // GitHub folder name. The asset URLs (raw.githubusercontent.com/.../{newId}/...)
-    // get baked into the rendered HTML, and we want those URLs to match the
-    // Firestore doc that hosts the campaign. Stable, predictable, browseable.
-    const newId = pushid();
-
-    // Run the generator with imageHost forced to 'github' (production cron
-    // path always uploads — that's what "production" means here) and the
-    // campaignId pinned so all assets land in marketing-campaigns/{newId}/'s
-    // matching folder. publishArticle: true so the linked blog post (when
-    // config.article.enabled is on) is actually committed to the website repo.
-    const generated = await generators[generator].generate(Manager, assistant, settings, {
-      campaignId: newId,
-      imageHost: 'github',
-      publishArticle: true,
-    });
-
-    if (!generated) {
-      assistant.log(`Generator "${generator}" returned no content for ${campaignId}, skipping`);
-      continue;
-    }
-
-    const nowISO = new Date().toISOString();
-    const nowUNIX = Math.round(Date.now() / 1000);
-
-    // Strip non-serializable / oversized fields out of the generator's return
-    // before writing to Firestore.
-    //   images: Buffer[] — not safe to persist
-    //   mjml:   raw template string — pollutes the doc, available in the GH archive
-    //   structure: full JSON dump (5-10kb) — available via assets.markdownUrl + assets.htmlUrl
-    //   contentMarkdown: large markdown blob — available via assets.markdownUrl
-    const {
-      images: _images,
-      mjml: _mjml,
-      structure: _structure,
-      contentMarkdown: _contentMarkdown,
-      assets,
-      meta,
-      ...campaignSettings
-    } = generated;
-
-    await admin.firestore().doc(`marketing-campaigns/${newId}`).set({
-      settings: campaignSettings,
-      assets: assets || null,   // { folderUrl, htmlUrl, markdownUrl, summaryUrl, imageUrls, beehiivPostId, tags, campaignId }
-      meta:   meta   || null,   // tokens, cost, durations, source scores
-      type,
-      sendAt: data.sendAt,
-      status: 'pending',
-      generatedFrom: campaignId,
-      metadata: {
-        created: { timestamp: nowISO, timestampUNIX: nowUNIX },
-        updated: { timestamp: nowISO, timestampUNIX: nowUNIX },
-      },
-    });
-
-    assistant.log(`Created campaign ${newId} from generator ${campaignId}: "${generated.subject}"`);
-    if (assets?.htmlUrl) {
-      assistant.log(`  HTML:     ${assets.htmlUrl}`);
-      assistant.log(`  Markdown: ${assets.markdownUrl || '(none)'}`);
-      assistant.log(`  Summary:  ${assets.summaryUrl || '(none)'}`);
-      assistant.log(`  Folder:   ${assets.folderUrl}`);
-    }
-    if (assets?.beehiivPostId) {
-      assistant.log(`  Beehiiv:  draft post ${assets.beehiivPostId}`);
-    }
-    if (assets?.tags?.length) {
-      assistant.log(`  Tags:     ${assets.tags.join(', ')}`);
-    }
-
-    // Advance the recurring doc's sendAt to the next occurrence
-    if (recurrence) {
-      const nextSendAt = getNextOccurrence(data.sendAt, recurrence);
-
-      await doc.ref.set({
-        sendAt: nextSendAt,
-        metadata: {
-          updated: { timestamp: nowISO, timestampUNIX: nowUNIX },
-        },
-      }, { merge: true });
-
-      assistant.log(`Advanced ${campaignId} sendAt to ${moment.unix(nextSendAt).toISOString()}`);
-    }
-  }
-
-  assistant.log('Pre-generation complete');
-};