backend-manager 5.10.0 → 5.10.2

package/docs/marketing-campaigns.md

@@ -231,16 +231,19 @@ AI provider defaults live in code (openai for structure, anthropic for SVG — e
 
 ## Asset hosting (production cron flow)
 
-The frequent 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.
@@ -252,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

package/package.json

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

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,24 @@ 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}`;
+// When true, asset URLs use the parent CDN (cdn.{parentDomain}/newsletters/...)
+// instead of raw.githubusercontent.com. Requires a Cloudflare redirect rule
+// on the CDN domain that maps /newsletters/* to raw.githubusercontent.com.
+// Set to false to revert to direct GitHub URLs.
+const USE_CDN_URLS = true;
+
 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,22 +60,25 @@ 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.
  * @param {string} [args.subject] - Newsletter subject. Embedded in the commit message so
  *                                  `git log` reads as a human-browseable history.
  * @param {string} [args.commitMessage] - Full override of the default commit message
+ * @param {string} [args.cdnBase] - CDN base URL (e.g. 'https://cdn.itwcreativeworks.com/newsletters').
+ *                                  When provided and USE_CDN_URLS is true, asset URLs use this
+ *                                  instead of raw.githubusercontent.com.
  * @param {string} [args.token] - GitHub token (defaults to process.env.GH_TOKEN)
  * @param {object} [args.assistant] - logger
  * @returns {Promise<{ urls: string[], paths: string[], htmlUrl?: string, htmlPath?: string, previewUrl?: string, folderUrl: string, commitSha: string }>}
  */
-async function uploadAssets({ images, html, markdown, summary, brandId, campaignId, subject, commitMessage, token, assistant }) {
+async function uploadAssets({ images, html, markdown, summary, brandId, campaignId, subject, commitMessage, cdnBase, token, assistant }) {
   const hasImages = Array.isArray(images) && images.length > 0;
   const hasHtml = typeof html === 'string' && html.length > 0;
   const hasMarkdown = typeof markdown === 'string' && markdown.length > 0;
@@ -86,13 +99,21 @@ 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 gitRawBase = `https://raw.githubusercontent.com/${REPO_OWNER}/${REPO_NAME}/${branch}`;
+
+  // CDN URLs: cdn.{parentDomain}/newsletters/{brandId}/content/{campaignId}/...
+  // The CDN redirect maps /newsletters/{brandId}/* → raw.githubusercontent.com/{brandId}/*
+  const assetBase = (USE_CDN_URLS && cdnBase) ? `${cdnBase}/${brandId}` : gitRawBase;
+
   // 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 +136,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 +150,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 +164,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 +185,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,34 +238,55 @@ async function uploadAssets({ images, html, markdown, summary, brandId, campaign
     });
   }
 
-  // 4. Build new tree on top of base
-  const { data: newTree } = await octokit.rest.git.createTree({
-    owner: REPO_OWNER,
-    repo: REPO_NAME,
-    base_tree: baseCommit.tree.sha,
-    tree: treeItems,
-  });
-
-  // 5. Commit. Default message format: "[brand] campaignId — Subject" so
-  //    `git log` doubles as a human-readable index of the (opaque) folder names.
+  // 4. Commit + push with retry. The newsletter pipeline calls uploadAssets
+  //    twice sequentially (images then HTML). GitHub's API can return a stale
+  //    ref on the second getRef if the first updateRef hasn't fully propagated.
+  //    Retry with a fresh ref read + jitter handles this.
   const defaultSubject = subject ? subject.trim() : `${files.length} newsletter asset${files.length === 1 ? '' : 's'}`;
   const message = commitMessage || `[${brandId}] ${campaignId} — ${defaultSubject}`;
+  const MAX_RETRIES = 3;
+  let newCommit;
+
+  for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+    const { data: refData } = await octokit.rest.git.getRef({
+      owner: REPO_OWNER, repo: REPO_NAME, ref: `heads/${branch}`,
+    });
+    const tipSha = refData.object.sha;
 
-  const { data: newCommit } = await octokit.rest.git.createCommit({
-    owner: REPO_OWNER,
-    repo: REPO_NAME,
-    message,
-    tree: newTree.sha,
-    parents: [baseCommitSha],
-  });
-
-  // 6. Update branch ref
-  await octokit.rest.git.updateRef({
-    owner: REPO_OWNER,
-    repo: REPO_NAME,
-    ref: `heads/${REPO_BRANCH}`,
-    sha: newCommit.sha,
-  });
+    const { data: baseCommit } = await octokit.rest.git.getCommit({
+      owner: REPO_OWNER, repo: REPO_NAME, commit_sha: tipSha,
+    });
+
+    const { data: newTree } = await octokit.rest.git.createTree({
+      owner: REPO_OWNER, repo: REPO_NAME,
+      base_tree: baseCommit.tree.sha,
+      tree: treeItems,
+    });
+
+    newCommit = (await octokit.rest.git.createCommit({
+      owner: REPO_OWNER, repo: REPO_NAME,
+      message,
+      tree: newTree.sha,
+      parents: [tipSha],
+    })).data;
+
+    try {
+      await octokit.rest.git.updateRef({
+        owner: REPO_OWNER, repo: REPO_NAME,
+        ref: `heads/${branch}`,
+        sha: newCommit.sha,
+      });
+      break;
+    } catch (e) {
+      if (attempt < MAX_RETRIES && /fast.forward/i.test(e.message)) {
+        const jitter = 500 + Math.floor(Math.random() * 1500);
+        log(`updateRef race (attempt ${attempt}/${MAX_RETRIES}), retrying in ${jitter}ms...`);
+        await new Promise(r => setTimeout(r, jitter));
+        continue;
+      }
+      throw e;
+    }
+  }
 
   // 7. Split the URL list by kind so callers can grab each independently.
   const imageFiles = files.filter((f) => f.kind === 'image');
@@ -238,29 +295,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) => `${assetBase}/${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 = `${assetBase}/${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 = `${assetBase}/${markdownFile.path}`;
     result.markdownPath = markdownFile.path;
   }
 
   if (summaryFile) {
-    result.summaryUrl = `${RAW_BASE}/${summaryFile.path}`;
+    result.summaryUrl = `${assetBase}/${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;
 }
@@ -279,9 +336,9 @@ function validateCampaignId(campaignId) {
 
 module.exports = {
   uploadAssets,
+  USE_CDN_URLS,
   REPO_OWNER,
   REPO_NAME,
-  REPO_BRANCH,
   RAW_BASE,
   PAGES_BASE,
 };

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

@@ -39,7 +39,7 @@ function resolveSectionImageFn(newsletterConfig) {
   return method === 'svg' ? generateSvgSection : generateImageSection;
 }
 const { renderMarkdown } = require('./lib/markdown-renderer.js');
-const { uploadAssets, RAW_BASE } = require('./lib/image-host.js');
+const { uploadAssets, USE_CDN_URLS, REPO_OWNER, REPO_NAME, RAW_BASE } = require('./lib/image-host.js');
 const { buildPublicConfig } = require('../../../routes/brand/get.js');
 const { writeArticle, publishArticle } = require('../../../libraries/content/ghostii.js');
 const { trackContentSource, contentSourceHash, resolveNewsletterSources } = require('../../../libraries/content/source-resolver.js');
@@ -162,6 +162,23 @@ async function generate(Manager, assistant, settings, opts = {}) {
   // Defaults to 'github' so production cron path "just works" without flag fiddling.
   const host = opts.imageHost || 'github';
 
+  // CDN base URL — resolves from the parent config.
+  // parent: 'https://itwcreativeworks.com' → cdn.itwcreativeworks.com
+  // parent: 'self' / '' / null             → falls back to brand.url
+  let cdnBase = null;
+  if (USE_CDN_URLS && host === 'github') {
+    const parentUrl = Manager.config?.parent;
+    let cdnDomain;
+    if (parentUrl && parentUrl !== 'self' && parentUrl !== '$self' && parentUrl.startsWith('http')) {
+      cdnDomain = new URL(parentUrl).hostname;
+    } else {
+      cdnDomain = brand?.url ? new URL(brand.url).hostname : null;
+    }
+    if (cdnDomain) {
+      cdnBase = `https://cdn.${cdnDomain}/newsletters`;
+    }
+  }
+
   // campaignId — used as the GitHub folder name (and as the doc ID in production).
   // Resolution priority (most-specific first):
   //   1. opts.campaignId            — explicit override (test runs, cron paths)
@@ -181,6 +198,7 @@ async function generate(Manager, assistant, settings, opts = {}) {
   //    the article build expands the lead section into a full blog post and
   //    returns its public URL, which we inject as a "Read more" CTA before render.
   let imagePaths = [];
+  let generatedImages = null;
 
   const buildImages = async () => {
     if (opts.skipImages) {
@@ -188,7 +206,7 @@ async function generate(Manager, assistant, settings, opts = {}) {
     }
 
     const generateSectionImage = resolveSectionImageFn(config);
-    const images = await Promise.all(
+    generatedImages = await Promise.all(
       structure.sections.map((s) => generateSectionImage({
         imagePrompt: s.image_prompt,
         brand,
@@ -198,35 +216,23 @@ async function generate(Manager, assistant, settings, opts = {}) {
       }))
     );
 
-    // Run persistImage side-effects first (writes to disk, etc.). The local
-    // paths it returns are used as a fallback if no host produces URLs.
+    // Run persistImage side-effects (writes to disk for iteration test).
     const persistedPaths = typeof opts.persistImage === 'function'
-      ? await Promise.all(images.map((img, i) => opts.persistImage(img, i)))
+      ? await Promise.all(generatedImages.map((img, i) => opts.persistImage(img, i)))
       : null;
 
     if (host === 'github') {
-      try {
-        const { urls } = await uploadAssets({
-          images,
-          brandId: brand?.id,
-          campaignId,
-          subject: structure.subject,
-          assistant,
-        });
-        imagePaths = urls;
-      } catch (e) {
-        assistant.error(`Newsletter generator: image upload failed — ${e.message}`);
-        imagePaths = persistedPaths || images.map((_, i) => `about:blank#section-${i + 1}`);
-      }
+      // Compute image URLs from the deterministic path — no upload needed yet.
+      // The URLs are based on branch + path, not commit SHA, so they're valid
+      // before the commit exists. Everything uploads in one atomic commit later.
+      const imgBase = cdnBase ? `${cdnBase}/${brand?.id}` : `https://raw.githubusercontent.com/${REPO_OWNER}/${REPO_NAME}/${brand?.id}`;
+      imagePaths = generatedImages.map((_, i) => `${imgBase}/content/${campaignId}/section-${i + 1}.png`);
     } else {
-      // 'local' — use persisted paths if available, else placeholder
-      imagePaths = persistedPaths || images.map((_, i) => `about:blank#section-${i + 1}`);
+      imagePaths = persistedPaths || generatedImages.map((_, i) => `about:blank#section-${i + 1}`);
     }
 
-    assistant.log(`Newsletter generator: ${images.length} images rendered`);
-
-    // Stash images on the return for callers that want to access raw buffers
-    opts._lastImages = images;
+    assistant.log(`Newsletter generator: ${generatedImages.length} images rendered`);
+    opts._lastImages = generatedImages;
   };
 
   // The linked-article build is gated by config.article.enabled and needs a lead
@@ -307,9 +313,9 @@ async function generate(Manager, assistant, settings, opts = {}) {
 
   const summaryText = (structure.summary || '').trim();
 
-  // 3b. Upload the rendered HTML + markdown + summary to GitHub alongside the
-  //     images. All four kinds live in the same {brandId}/{campaignId}/ folder.
-  //     The folder URL becomes the canonical archive of the issue.
+  // 3b. Upload EVERYTHING to GitHub in one atomic commit — images + HTML +
+  //     markdown + summary. Image URLs were pre-computed from the deterministic
+  //     path, so the HTML already embeds the correct URLs before the commit exists.
   let assetsFolderUrl = null;
   let htmlUrl = null;
   let previewUrl = null;
@@ -319,12 +325,14 @@ async function generate(Manager, assistant, settings, opts = {}) {
   if (host === 'github') {
     try {
       const upload = await uploadAssets({
+        images: generatedImages,
         html,
         markdown,
         summary: summaryText || undefined,
         brandId: brand?.id,
         campaignId,
         subject: structure.subject,
+        cdnBase,
         assistant,
       });
       assetsFolderUrl = upload.folderUrl;
@@ -333,7 +341,7 @@ async function generate(Manager, assistant, settings, opts = {}) {
       markdownUrl = upload.markdownUrl || null;
       summaryUrl = upload.summaryUrl || null;
     } catch (e) {
-      assistant.error(`Newsletter generator: HTML upload failed — ${e.message}`);
+      assistant.error(`Newsletter generator: asset upload failed — ${e.message}`);
     }
   }
 
@@ -377,7 +385,7 @@ async function generate(Manager, assistant, settings, opts = {}) {
   //     paste), markdown URL (per-section blocks for ad insertion), summary
   //     URL, and the tags to set. Failure of THIS email is logged but never
   //     blocks the cron — the campaign doc is still written either way.
-  if (beehiivFailureReason && htmlUrl) {
+  if (beehiivFailureReason) {
     await sendBeehiivFallbackEmail(Manager, assistant, {
       brand,
       subject: structure.subject,
@@ -389,6 +397,7 @@ async function generate(Manager, assistant, settings, opts = {}) {
       summaryUrl,
       folderUrl: assetsFolderUrl,
       reason: beehiivFailureReason,
+      articles: (articleResult?.published) ? [{ title: articleResult.article?.title || structure.sections?.[0]?.title, url: articleResult.url }] : [],
     });
   }
 
@@ -545,15 +554,25 @@ async function buildLinkedArticle({ Manager, assistant, brand, config, structure
     return { url, slug, path: null, published: false, article };
   }
 
-  const result = await publishArticle(assistant, {
-    brand: publicConfig,
-    article,
-    id: Math.round(Date.now() / 1000),
-    author: config?.article?.author,
-    postPath: 'newsletter',
-  });
+  try {
+    const result = await publishArticle(assistant, {
+      brand: publicConfig,
+      article,
+      id: Math.round(Date.now() / 1000),
+      author: config?.article?.author,
+      postPath: 'newsletter',
+    });
+
+    if (result?.path) {
+      return { url: result.url || url, slug: result.slug || slug, path: result.path, published: true, article };
+    }
 
-  return { url: result.url || url, slug: result.slug || slug, path: result.path, published: true, article };
+    assistant.log(`Newsletter generator: publishArticle returned no path — treating as unpublished`);
+    return { url, slug, path: null, published: false, article };
+  } catch (e) {
+    assistant.error(`Newsletter generator: publishArticle failed — ${e.message}`);
+    return { url, slug, path: null, published: false, article };
+  }
 }
 
 /**
@@ -599,39 +618,73 @@ async function sendBeehiivFallbackEmail(Manager, assistant, args) {
     const email = Manager.Email(assistant);
     const messageLines = [];
 
-    messageLines.push(`<strong>Beehiiv draft creation failed</strong> — the newsletter is generated and archived, but needs to be manually uploaded to Beehiiv.`);
+    messageLines.push(`The newsletter is generated and archived, but Beehiiv draft creation failed. It needs to be manually uploaded.`);
     messageLines.push('');
-    messageLines.push(`<strong>Failure reason:</strong> ${args.reason}`);
+
+    // --- Failure ---
+    messageLines.push('<strong>Failure reason</strong>');
+    messageLines.push('<ul>');
+    messageLines.push(`<li>${args.reason}</li>`);
+    messageLines.push('</ul>');
     messageLines.push('');
-    messageLines.push('<strong>Newsletter details:</strong>');
+
+    // --- Details ---
+    messageLines.push('<strong>Newsletter details</strong>');
     messageLines.push('<ul>');
-    messageLines.push(`<li><strong>Subject:</strong> ${args.subject}</li>`);
-    messageLines.push(`<li><strong>Preheader:</strong> ${args.preheader || '(none)'}</li>`);
+    messageLines.push(`<li>Subject: ${args.subject}</li>`);
+    messageLines.push(`<li>Preheader: ${args.preheader || '(none)'}</li>`);
     if (args.tags?.length) {
-      messageLines.push(`<li><strong>Tags:</strong> ${args.tags.join(', ')}</li>`);
+      messageLines.push(`<li>Tags: ${args.tags.join(', ')}</li>`);
     }
     messageLines.push('</ul>');
     messageLines.push('');
-    messageLines.push('<strong>Assets:</strong>');
-    messageLines.push('<ul>');
-    messageLines.push('<li><strong>Full HTML</strong> (one-shot paste into Beehiiv)');
+
+    // --- Full HTML ---
+    messageLines.push('<strong>Full HTML</strong> — one-shot paste into Beehiiv');
     messageLines.push('<ul>');
     if (args.previewUrl) {
       messageLines.push(`<li><a href="${args.previewUrl}">Preview in browser</a></li>`);
     }
     messageLines.push(`<li><a href="${args.htmlUrl}">View raw HTML</a></li>`);
     messageLines.push('</ul>');
-    messageLines.push('</li>');
+    messageLines.push('');
+
+    // --- Markdown ---
     if (args.markdownUrl) {
-      messageLines.push(`<li><a href="${args.markdownUrl}"><strong>Per-section markdown</strong></a> — paste as separate blocks, ads between</li>`);
+      messageLines.push('<strong>Per-section markdown</strong> — paste as separate blocks, ads between');
+      messageLines.push('<ul>');
+      messageLines.push(`<li><a href="${args.markdownUrl}">View markdown</a></li>`);
+      messageLines.push('</ul>');
+      messageLines.push('');
     }
+
+    // --- Summary ---
     if (args.summaryUrl) {
-      messageLines.push(`<li><a href="${args.summaryUrl}"><strong>Summary</strong></a> — 2-3 sentence recap</li>`);
+      messageLines.push('<strong>Summary</strong> — 2-3 sentence recap');
+      messageLines.push('<ul>');
+      messageLines.push(`<li><a href="${args.summaryUrl}">View summary</a></li>`);
+      messageLines.push('</ul>');
+      messageLines.push('');
     }
+
+    // --- Linked articles (only published ones) ---
+    if (args.articles?.length) {
+      messageLines.push('');
+      messageLines.push('<strong>Linked articles</strong>');
+      messageLines.push('<ul>');
+      for (const article of args.articles) {
+        messageLines.push(`<li><a href="${article.url}">${article.title || 'Article'}</a></li>`);
+      }
+      messageLines.push('</ul>');
+    }
+
+    // --- All assets ---
     if (args.folderUrl) {
-      messageLines.push(`<li><a href="${args.folderUrl}"><strong>All assets</strong></a> — GitHub folder</li>`);
+      messageLines.push('<strong>All assets</strong> — full GitHub archive');
+      messageLines.push('<ul>');
+      messageLines.push(`<li><a href="${args.folderUrl}">Browse folder</a></li>`);
+      messageLines.push('</ul>');
     }
-    messageLines.push('</ul>');
 
     await email.send({
       sender: 'internal',  // resolves to alerts@{brandDomain}

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 };