backend-manager 5.1.2 → 5.2.0

package/src/manager/libraries/email/generators/lib/markdown-renderer.js

@@ -0,0 +1,285 @@
+/**
+ * Markdown renderer — deterministic, no AI cost. Walks the `structure` object
+ * produced by structure.js and emits a markdown document suitable for pasting
+ * into Beehiiv's block editor (one section per `## heading` block, so you can
+ * drop ad blocks between dispatches).
+ *
+ * Why this exists:
+ *   - The MJML-rendered HTML is one giant styled block. Pasting it into Beehiiv
+ *     defeats the block editor — ads can't be inserted between sections.
+ *   - Markdown gives Beehiiv (and any future provider) a clean per-section
+ *     structure that maps to native blocks.
+ *
+ * Why programmatic, not AI:
+ *   - Cost: zero. Layout never changes between issues for a given template.
+ *   - Determinism: same `structure` → same markdown. Easy to test.
+ *   - SSOT: the AI-authored `structure` is the source of truth; markdown and
+ *     HTML are two views of the same data.
+ *
+ * Template-awareness:
+ *   - `clean`/`editorial` use the classic shape (intro + sections[]).
+ *   - `field-report` uses dispatches[] with kickers, bylines, dataPoints.
+ *   - The renderer reads `structure._meta.template` (set by structure.js) to
+ *     pick the body strategy; falls back to "classic sections" if absent.
+ *
+ * Sections render as standalone blocks so each can be pasted independently:
+ *   - heading (## ...)
+ *   - image (markdown ![alt](url) — only if image URL is present)
+ *   - body
+ *   - CTA as a markdown link on its own line
+ *   - horizontal rule between sections (---)
+ */
+
+/**
+ * Render a newsletter structure as markdown.
+ *
+ * @param {object} args
+ * @param {object} args.structure - The output of generateStructure()
+ * @param {object} [args.brand] - { name, url, id }
+ * @param {string[]} [args.imagePaths] - Per-section image URLs (same order as sections/dispatches)
+ * @param {Array<{position, html, image_url, link_url}>} [args.sponsorships] - Optional sponsorships
+ * @returns {string} Markdown document
+ */
+function renderMarkdown({ structure, brand, imagePaths, sponsorships }) {
+  if (!structure) {
+    throw new Error('markdown-renderer: structure is required');
+  }
+
+  const template = structure._meta?.template || 'clean';
+  const parts = [];
+
+  // ----- Header -----
+  if (structure.subject) {
+    parts.push(`# ${structure.subject}`);
+  }
+
+  if (structure.preheader) {
+    parts.push(`_${structure.preheader}_`);
+  }
+
+  // Field-report-only opener: TLDR strip + dateline
+  if (template === 'field-report') {
+    if (structure.dateline) {
+      parts.push(`**${structure.dateline.toUpperCase()} —** _Filed today_`);
+    }
+
+    if (structure.tldr) {
+      parts.push(`> **TL;DR** — ${structure.tldr}`);
+    }
+  }
+
+  // Classic intro
+  if (structure.intro) {
+    parts.push(structure.intro);
+  }
+
+  // Top sponsorship (above sections)
+  const topSponsorship = pickSponsorship(sponsorships, 'top');
+  if (topSponsorship) {
+    parts.push('---');
+    parts.push(renderSponsorshipMarkdown(topSponsorship));
+  }
+
+  parts.push('---');
+
+  // ----- Body -----
+  const sections = getBodySections(structure, template);
+
+  for (let i = 0; i < sections.length; i++) {
+    const block = renderSection(sections[i], i, imagePaths, template);
+
+    if (!block) {
+      continue;
+    }
+
+    parts.push(block);
+    parts.push('---');
+
+    // Mid-section sponsorship (after the middle dispatch)
+    const middleIdx = Math.floor(sections.length / 2);
+
+    if (i === middleIdx - 1) {
+      const midSponsorship = pickSponsorship(sponsorships, 'middle');
+
+      if (midSponsorship) {
+        parts.push(renderSponsorshipMarkdown(midSponsorship));
+        parts.push('---');
+      }
+    }
+  }
+
+  // End sponsorship (above signoff)
+  const endSponsorship = pickSponsorship(sponsorships, 'end');
+  if (endSponsorship) {
+    parts.push(renderSponsorshipMarkdown(endSponsorship));
+    parts.push('---');
+  }
+
+  // ----- Footer -----
+  if (structure.signoff) {
+    // Signoffs are stored with literal "\n" — convert to a markdown line break.
+    parts.push(structure.signoff.replace(/\n/g, '  \n'));
+  }
+
+  if (Array.isArray(structure.citations) && structure.citations.length) {
+    parts.push('---');
+    parts.push('## Notes');
+
+    for (let i = 0; i < structure.citations.length; i++) {
+      const c = structure.citations[i];
+
+      if (!c?.note) {
+        continue;
+      }
+
+      const src = c.source ? ` — _${c.source}_` : '';
+      parts.push(`${i + 1}. ${c.note}${src}`);
+    }
+  }
+
+  if (Array.isArray(structure.tags) && structure.tags.length) {
+    parts.push(`_Tags: ${structure.tags.map((t) => `#${t}`).join(' ')}_`);
+  }
+
+  if (brand?.name && brand?.url) {
+    parts.push(`---\n_You're receiving this because you subscribed to [${brand.name}](${brand.url})._`);
+  }
+
+  // Join with blank-line separators; collapse any accidental triple-newlines.
+  return parts.join('\n\n').replace(/\n{3,}/g, '\n\n').trim() + '\n';
+}
+
+/**
+ * Extract the "body sections" — what we'll loop over to render as ## headings.
+ * The shape depends on the template.
+ */
+function getBodySections(structure, template) {
+  if (template === 'field-report' && Array.isArray(structure.dispatches)) {
+    return structure.dispatches.map((d) => ({
+      kind: 'dispatch',
+      title: d.headline,
+      kicker: d.kicker,
+      byline: d.byline,
+      location: d.location,
+      lede: d.lede,
+      body: d.dispatch,
+      dataPoints: d.dataPoints,
+      image_prompt: d.image_prompt,
+    }));
+  }
+
+  // Classic shape (clean, editorial)
+  if (Array.isArray(structure.sections)) {
+    return structure.sections.map((s) => ({
+      kind: 'section',
+      title: s.title,
+      body: s.body,
+      image_prompt: s.image_prompt,
+    }));
+  }
+
+  return [];
+}
+
+/**
+ * Render a single section/dispatch as a self-contained markdown block.
+ * Empty sections (no title and no body) return null so the caller can skip
+ * them entirely — avoids "## undefined" stubs and dangling `---` dividers.
+ */
+function renderSection(section, idx, imagePaths, template) {
+  if (!section?.title && !section?.body) {
+    return null;
+  }
+
+  const lines = [];
+
+  // Kicker prefix (field-report only)
+  if (section.kicker) {
+    lines.push(`**${section.kicker.toUpperCase()}**`);
+  }
+
+  if (section.title) {
+    lines.push(`## ${section.title}`);
+  }
+
+  // Byline / location bar (field-report only)
+  if (section.byline || section.location) {
+    const parts = [];
+    if (section.location) parts.push(`**${section.location.toUpperCase()}**`);
+    if (section.byline) parts.push(`_${section.byline}_`);
+    lines.push(parts.join(' — '));
+  }
+
+  // Image (if hosted)
+  const imageUrl = imagePaths && imagePaths[idx];
+
+  if (imageUrl && !imageUrl.startsWith('about:')) {
+    const alt = section.image_prompt || section.title || `Section ${idx + 1}`;
+    lines.push(`![${alt.replace(/[\[\]]/g, '')}](${imageUrl})`);
+  }
+
+  // Lede (field-report)
+  if (section.lede) {
+    lines.push(`_${section.lede}_`);
+  }
+
+  // Data points (field-report)
+  if (Array.isArray(section.dataPoints) && section.dataPoints.length) {
+    const rows = section.dataPoints
+      .map((dp) => `| **${dp.label || ''}** | ${dp.value || ''} |`)
+      .join('\n');
+    lines.push(`| Metric | Value |\n|---|---|\n${rows}`);
+  }
+
+  // Body
+  if (section.body) {
+    lines.push(section.body);
+  }
+
+  return lines.join('\n\n');
+}
+
+/**
+ * Pick the first sponsorship matching the requested position. Position is
+ * one of 'top' | 'middle' | 'end'. Returns null if no match.
+ */
+function pickSponsorship(sponsorships, position) {
+  if (!Array.isArray(sponsorships) || !sponsorships.length) {
+    return null;
+  }
+
+  return sponsorships.find((s) => (s?.position || 'top') === position) || null;
+}
+
+/**
+ * Render a sponsorship as markdown. Sponsorships in the HTML template are
+ * styled blocks; in markdown they're a simple "Sponsored by" callout with
+ * optional image and link.
+ */
+function renderSponsorshipMarkdown(sp) {
+  const lines = ['**Sponsored**'];
+
+  if (sp.image_url && sp.link_url) {
+    lines.push(`[![Sponsor](${sp.image_url})](${sp.link_url})`);
+  } else if (sp.image_url) {
+    lines.push(`![Sponsor](${sp.image_url})`);
+  }
+
+  if (sp.html) {
+    // Strip HTML tags for the markdown view; keep the text.
+    const text = String(sp.html).replace(/<[^>]+>/g, '').trim();
+    if (text) {
+      lines.push(text);
+    }
+  }
+
+  if (sp.link_url) {
+    lines.push(`**[Learn more →](${sp.link_url})**`);
+  }
+
+  return lines.join('\n\n');
+}
+
+module.exports = {
+  renderMarkdown,
+};

package/src/manager/libraries/email/generators/lib/structure.js

@@ -44,11 +44,23 @@ const DEFAULT_MODELS = {
 const BASE_SCHEMA = {
   type: 'object',
   additionalProperties: false,
-  required: ['subject', 'preheader', 'signoff', 'citations'],
+  required: ['subject', 'preheader', 'signoff', 'citations', 'tags', 'summary'],
   properties: {
     subject:   { type: 'string', maxLength: 80 },
     preheader: { type: 'string', maxLength: 120 },
     signoff:   { type: 'string' },
+    // Two-to-three-sentence editorial summary of the issue. Used as the body of
+    // `summary.md` alongside the newsletter, and as a preview snippet when the
+    // issue is shared. Distinct from preheader (which is an inbox-preview hook).
+    summary:   { type: 'string', maxLength: 600 },
+    // Topical tags for the issue. Flow into Beehiiv's `content_tags` field on
+    // the post draft (array of strings, lowercase, kebab-case preferred).
+    // Empty array is valid.
+    tags: {
+      type: 'array',
+      maxItems: 5,
+      items: { type: 'string', maxLength: 40 },
+    },
     // Citations for hard data (statistics, numbers, direct quotes) pulled from sources.
     // Rendered as a small footnote section at the bottom of the newsletter — never inline.
     // Empty array is valid (most newsletters won't need citations).
@@ -169,6 +181,8 @@ async function generateStructure({ sources, brand, newsletterConfig, ai, assista
   structure.preheader = structure.preheader || '';
   structure.signoff   = structure.signoff   || `Best,\nThe ${brand?.name || 'Team'} Team`;
   structure.citations = Array.isArray(structure.citations) ? structure.citations : [];
+  structure.tags      = Array.isArray(structure.tags) ? structure.tags : [];
+  structure.summary   = typeof structure.summary === 'string' ? structure.summary : '';
 
   // Let the template normalize its own fields (e.g. sections defaults).
   // Falls back to a sane default if the template doesn't ship one.
@@ -226,10 +240,13 @@ function buildClassicSystemPrompt(brand, config) {
     'CONTENT REQUIREMENTS:',
     '- Subject (≤60 chars, no emojis, attention-grabbing but not clickbait)',
     '- Preheader (≤100 chars, complements the subject)',
+    '- Summary (2-3 sentences, plain text, no markdown) — an editorial recap of the issue, written like a TL;DR. Distinct from preheader (which is an inbox hook). This is what someone reads if they only have 10 seconds.',
+    '- Tags (3-5 short topical tags, lowercase, kebab-case, no spaces) — e.g. "linkedin", "creator-economy", "platform-policy". Empty array is fine if nothing fits.',
     '- Intro (1-2 sentences, markdown allowed) — frame the issue as if you are setting up your own reporting',
     '- 3-5 sections — each is ONE topic, rewritten in your voice as original content',
-    '- Each section: title (compelling, scannable), body (80-150 words, markdown OK), optional cta { label, url }',
+    '- Each section: title (compelling, scannable), body (80-150 words, markdown OK)',
     '- Each section: image_prompt — one-sentence visual description for an illustrator. Be specific about subject/style.',
+    '- Do NOT include CTAs, "read more" links, or any URLs in section bodies. The newsletter is a self-contained read — never invent links or send readers off-property.',
     `- Signoff: a SHORT human sign-off, formatted as two lines with \\n between them. First line is a closing phrase like "Best,", "Cheers,", "Until next week,", or "Stay sharp,". Second line is the team name like "The ${brand?.name || 'Team'} Team". Example: "Best,\\nThe ${brand?.name || 'Team'} Team". Do NOT write a summary, tagline, motto, or thematic conclusion sentence — this is the literal way you sign off the email, like the end of a letter.`,
     '- citations: array of { note, source } for any hard data referenced. Empty array if none.',
     '',

package/src/manager/libraries/email/generators/lib/svg-illustrator.js

@@ -2,16 +2,25 @@
  * SVG illustrator — AI authors per-section SVG illustrations, rasterized to PNG.
  *
  * Each section in a newsletter gets one illustration. Default provider is
- * Anthropic (Claude generates cleaner geometric SVG than GPT in practice).
+ * OpenAI Codex (gpt-5.3-codex) — markup/code-specialized GPT-5 variant tuned
+ * for structured output. SVG is just structured markup, so Codex is the right
+ * fit. Anthropic is supported as a fallback provider.
  *
  * Output is both the raw SVG string (for debugging) and a rasterized PNG buffer
  * (for embedding). Local file persistence is the caller's responsibility — this
  * module returns buffers only.
+ *
+ * Provider-specific default models:
+ *   openai → gpt-5.3-codex  (Codex family is markup/code-specialized; SVG is
+ *                            structured markup. ~$0.005-0.015/image.)
+ *   anthropic → claude-opus (Claude is good at artistic SVG.)
  */
 const { Resvg } = require('@resvg/resvg-js');
 
+const DEFAULT_PROVIDER = 'openai';
+
 const DEFAULT_MODELS = {
-  openai: 'gpt-5.4-mini',
+  openai: 'gpt-5.3-codex',
   anthropic: 'claude-opus',
   'claude-code': 'claude-opus-4-7',
 };
@@ -30,7 +39,7 @@ const PNG_WIDTH = 800; // 2x display width of 400px container
  * @returns {Promise<{svg: string, png: Buffer, fallback: boolean}>}
  */
 async function generateSectionImage({ imagePrompt, brand, newsletterConfig, ai, assistant }) {
-  const provider = newsletterConfig?.provider?.svg || 'anthropic';
+  const provider = newsletterConfig?.provider?.svg || DEFAULT_PROVIDER;
   const model = newsletterConfig?.model?.svg || DEFAULT_MODELS[provider];
   const startTime = Date.now();
 

package/src/manager/libraries/email/generators/lib/templates/classic-schema.js

@@ -3,12 +3,18 @@
  *
  * Both templates consume the same shape:
  *   - intro: 1-2 sentence preamble
- *   - sections: list of {title, body, cta?, image_prompt}
+ *   - sections: list of {title, body, image_prompt}
  *
  * Defined here so adding a new field (e.g. an eyebrow per section) updates
  * every classic-style template at once. Templates with fundamentally
  * different content shapes (Field Report, Postcard, Almanac) declare their
  * own schema instead.
+ *
+ * NOTE: CTAs / outbound links are intentionally NOT part of the schema. The
+ * AI cannot reliably author URLs without inventing them (it can't browse the
+ * brand's site and has no real source URLs), so we forbid the field entirely.
+ * Newsletters are self-contained — link out from the rendered HTML manually
+ * (sponsorship blocks, footer) rather than from generated section bodies.
  */
 const CLASSIC_SCHEMA = {
   required: ['intro', 'sections'],
@@ -21,19 +27,10 @@ const CLASSIC_SCHEMA = {
       items: {
         type: 'object',
         additionalProperties: false,
-        required: ['title', 'body', 'image_prompt', 'cta'],
+        required: ['title', 'body', 'image_prompt'],
         properties: {
           title: { type: 'string' },
           body:  { type: 'string' },
-          cta: {
-            type: ['object', 'null'],
-            additionalProperties: false,
-            required: ['label', 'url'],
-            properties: {
-              label: { type: 'string' },
-              url:   { type: 'string' },
-            },
-          },
           image_prompt: { type: 'string' },
         },
       },
@@ -43,7 +40,7 @@ const CLASSIC_SCHEMA = {
 
 /**
  * Normalize a classic structure post-AI-call. Ensures every section has the
- * fields the templates expect, even when the AI omits an optional like cta.
+ * fields the templates expect, even when the AI omits an optional.
  */
 function normalizeClassic(structure) {
   if (!Array.isArray(structure.sections)) {
@@ -53,7 +50,6 @@ function normalizeClassic(structure) {
   structure.sections = structure.sections.map((s, i) => ({
     title:        s.title || `Section ${i + 1}`,
     body:         s.body || '',
-    cta:          s.cta || null,
     image_prompt: s.image_prompt || '',
   }));
 

package/src/manager/libraries/email/generators/lib/templates/clean.js

@@ -74,7 +74,7 @@ module.exports = {
     name: 'clean',
     description: 'Stripe / Linear marketing aesthetic. Safe, conservative, works everywhere.',
     requires: ['subject', 'preheader', 'intro', 'sections', 'signoff'],
-    optional: ['citations', 'image_prompt', 'cta'],
+    optional: ['citations', 'image_prompt'],
     supports: { sponsorships: ['top', 'middle', 'end'], citations: true, images: true },
   },
   schema: CLASSIC_SCHEMA,

package/src/manager/libraries/email/generators/lib/templates/editorial.js

@@ -309,7 +309,7 @@ module.exports = {
     name: 'editorial',
     description: 'Magazine-style: masthead, drop-cap intro, numbered sections, pull-quotes, italic signoff.',
     requires: ['subject', 'preheader', 'intro', 'sections', 'signoff'],
-    optional: ['citations', 'image_prompt', 'cta'],
+    optional: ['citations', 'image_prompt'],
     supports: { sponsorships: ['top', 'middle', 'end'], citations: true, images: true },
   },
   schema: CLASSIC_SCHEMA,

package/src/manager/libraries/email/generators/lib/templates/field-report.js

@@ -16,7 +16,7 @@
  *
  * Content schema (template-owned — different from the classic schema):
  *   { tldr, dateline, dispatches: [{ kicker, headline, byline, location,
- *     lede, dispatch, dataPoints?, cta?, image_prompt }] }
+ *     lede, dispatch, dataPoints?, image_prompt }] }
  */
 const {
   shell,
@@ -337,7 +337,7 @@ const FIELD_REPORT_SCHEMA = {
       items: {
         type: 'object',
         additionalProperties: false,
-        required: ['kicker', 'headline', 'byline', 'location', 'lede', 'dispatch', 'image_prompt', 'cta', 'dataPoints'],
+        required: ['kicker', 'headline', 'byline', 'location', 'lede', 'dispatch', 'image_prompt', 'dataPoints'],
         properties: {
           kicker:   { type: 'string', maxLength: 30 },  // "DISPATCH" / "FIELD NOTES" / "WATCH" / "BRIEF"
           headline: { type: 'string', maxLength: 90 },  // Tight, declarative
@@ -358,15 +358,10 @@ const FIELD_REPORT_SCHEMA = {
               },
             },
           },
-          cta: {
-            type: ['object', 'null'],
-            additionalProperties: false,
-            required: ['label', 'url'],
-            properties: {
-              label: { type: 'string' },
-              url:   { type: 'string' },
-            },
-          },
+          // CTAs intentionally not part of the contract — the AI cannot author URLs
+          // reliably (no source URLs available, no brand-site knowledge). Newsletters
+          // are self-contained; outbound links come from sponsorship blocks rendered
+          // by the template shell, not from generated dispatch bodies.
           image_prompt: { type: 'string' },
         },
       },
@@ -390,7 +385,6 @@ function normalizeFieldReport(structure, { brand } = {}) {
     lede:         d.lede        || '',
     dispatch:     d.dispatch    || '',
     dataPoints:   Array.isArray(d.dataPoints) ? d.dataPoints.slice(0, 4) : [],
-    cta:          d.cta         || null,
     image_prompt: d.image_prompt || '',
   }));
 
@@ -439,6 +433,8 @@ function buildPrompt({ brand, newsletterConfig, sources }) {
     'CONTENT REQUIREMENTS:',
     '- subject: ≤60 chars, declarative, no clickbait. Reads like a wire-service headline.',
     '- preheader: ≤100 chars, complements subject.',
+    '- summary: 2-3 sentences, plain text, no markdown. An editorial recap of the whole issue (distinct from the in-template `tldr` strip — the summary is consumed by external surfaces like the share preview / summary.md file).',
+    '- tags: 3-5 topical tags. Lowercase, kebab-case, no spaces. Examples: "linkedin", "creator-economy", "platform-policy". Empty array OK if nothing fits cleanly.',
     '- tldr: 2 short sentences max, ~200 chars total. Present tense. Reads like a terminal briefing — what changed, why it matters.',
     '- dateline: one city or "REMOTE" — sets where the issue is filed from. UPPERCASE. Example: "LOS ANGELES" / "REMOTE" / "NEW YORK".',
     '- dispatches: 3-5 items, each is a discrete filed story.',
@@ -449,8 +445,8 @@ function buildPrompt({ brand, newsletterConfig, sources }) {
     '  - lede: one paragraph (1-2 sentences), italic-serif quality, sets the scene in present tense. Reads like the opening of a New Yorker article.',
     '  - dispatch: the body. 90-160 words. Markdown allowed. Present tense. Specific. End with the practical implication for the reader.',
     '  - dataPoints: 2-4 short label/value pairs IF there are meaningful numbers in the topic. Example: [{label:"USERS REACHED",value:"12.4K"},{label:"WoW GROWTH",value:"+38%"}]. SKIP this (empty array) if the topic has no quantifiable data.',
-    '  - cta: { label, url } OR null. Label is mono, uppercase, short (≤24 chars). Examples: "READ THE BRIEF", "SEE THE NUMBERS".',
     '  - image_prompt: one-sentence visual brief for an illustrator. Specific. Think editorial illustration, not stock photo.',
+    '  - DO NOT invent CTAs, "read more" links, or any URLs anywhere in the dispatch. The dispatch must stand on its own without sending the reader off-property.',
     `- signoff: render as TWO LINES with a literal \\n between them. Format: a short closing phrase + the desk name. Examples:\n    "— Stay sharp,\\nThe ${brandName} Desk"\n    "— Until next dispatch,\\nThe ${brandName} Editorial Desk"\n  Do NOT write a summary, motto, or thematic sentence. This is a literal sign-off.`,
     '',
     'OUTPUT:',
@@ -488,7 +484,7 @@ module.exports = {
     name: 'field-report',
     description: 'Wire-service correspondent × Bloomberg terminal. Dispatch kickers, datelines, mono data callouts, end-of-dispatch terminators.',
     requires: ['subject', 'preheader', 'tldr', 'dateline', 'dispatches', 'signoff'],
-    optional: ['citations', 'dataPoints', 'cta', 'image_prompt'],
+    optional: ['citations', 'dataPoints', 'image_prompt'],
     supports: { sponsorships: ['top', 'middle', 'end'], citations: true, images: true },
   },
   schema: FIELD_REPORT_SCHEMA,