backend-manager 5.0.203 → 5.1.0

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

@@ -0,0 +1,278 @@
+/**
+ * Newsletter structure generator — AI authors the copy + section layout.
+ *
+ * The schema and AI prompt are NOT fixed here. Each template owns what content
+ * it needs and how the AI should write it (template.schema, template.buildPrompt).
+ * This module merges the template's contract with the universal base contract
+ * (subject, preheader, signoff, citations — things the shell always renders),
+ * dispatches the AI call, and normalizes the result.
+ *
+ * Why template-owned schemas:
+ *   - Different aesthetics demand fundamentally different content. A "Field
+ *     Report" template wants bylines + data callouts + dispatch-style prose; a
+ *     "Postcard" template wants a hand-written note + image caption. Forcing
+ *     them through one universal `{title, body, cta}` shape produces lookalike
+ *     output regardless of layout.
+ *   - The template knows what it's going to render — let it ask for that.
+ *
+ * Trade-off: theme-only iteration (skipping the AI step on re-runs) only works
+ * within the same template. Switching templates means a new AI call, because
+ * the cached structure won't match the new template's schema. That's correct
+ * behavior — different templates produce different content.
+ *
+ * Provider defaults to OpenAI (structured JSON output is more reliable on GPT
+ * via JSON schema). Can be overridden per-brand via
+ * `marketing.beehiiv.content.provider.structure`.
+ */
+const { resolveTemplate } = require('./templates/index.js');
+
+const DEFAULT_MODELS = {
+  openai: 'gpt-5.4-mini',
+  anthropic: 'claude-opus',
+  'claude-code': 'claude-opus-4-7',
+};
+
+/**
+ * BASE_SCHEMA — the universal contract that EVERY newsletter must satisfy
+ * regardless of template. These are the fields the shell uses unconditionally
+ * (subject/preheader for email metadata, signoff for the closing card,
+ * citations for the footnote block).
+ *
+ * Templates extend this with their own `schema` export, which is merged into
+ * `properties` and `required` before the AI call.
+ */
+const BASE_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['subject', 'preheader', 'signoff', 'citations'],
+  properties: {
+    subject:   { type: 'string', maxLength: 80 },
+    preheader: { type: 'string', maxLength: 120 },
+    signoff:   { type: 'string' },
+    // 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).
+    citations: {
+      type: 'array',
+      maxItems: 10,
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['note', 'source'],
+        properties: {
+          note:   { type: 'string' }, // The cited fact, e.g. "70% of social media managers report..."
+          source: { type: 'string' }, // Free-form attribution, e.g. "Reported in industry coverage, May 2026"
+        },
+      },
+    },
+  },
+};
+
+/**
+ * Merge a template's schema fragment into BASE_SCHEMA. The template's
+ * `properties` are merged in, and its `required` is concatenated.
+ *
+ * Templates that don't export a schema get BASE_SCHEMA only — they'll be
+ * limited to subject/preheader/signoff/citations. That's a useful escape
+ * hatch for transactional / receipt-style newsletters that don't need
+ * editorial sections.
+ */
+function mergeSchemas(base, fragment) {
+  if (!fragment) {
+    return base;
+  }
+
+  return {
+    ...base,
+    required: [...(base.required || []), ...(fragment.required || [])],
+    properties: {
+      ...base.properties,
+      ...(fragment.properties || {}),
+    },
+  };
+}
+
+/**
+ * Default prompt builder — used by templates that don't override
+ * buildPrompt. Produces the "classic" newsletter brief (intro + sections
+ * with title/body/cta/image_prompt + signoff).
+ *
+ * Templates that want a different content shape (Field Report, Almanac,
+ * Postcard, etc.) export their own buildPrompt.
+ */
+function defaultBuildPrompt({ brand, newsletterConfig, sources }) {
+  return {
+    system: buildClassicSystemPrompt(brand, newsletterConfig),
+    user:   buildClassicUserPrompt(sources),
+  };
+}
+
+/**
+ * Generate the newsletter structure from a list of sources.
+ *
+ * The active template controls the schema and the AI prompt. This function
+ * is a generic dispatcher: it resolves the template, merges schemas, asks
+ * the template to build the prompt, calls the AI, and normalizes the result.
+ *
+ * @param {object} args
+ * @param {Array<object>} args.sources - Newsletter source records (id, subject, ai: { headline, summary, takeaways })
+ * @param {object} args.brand - { name, url, id, description? }
+ * @param {object} args.newsletterConfig - marketing.beehiiv.content from BEM config
+ * @param {object} args.ai - AI instance from Manager.AI(assistant)
+ * @param {object} args.assistant - BEM assistant
+ * @returns {Promise<object>} Structured newsletter object
+ */
+async function generateStructure({ sources, brand, newsletterConfig, ai, assistant }) {
+  if (!sources?.length) {
+    throw new Error('generateStructure requires at least one source');
+  }
+
+  const templateName = newsletterConfig?.template || 'clean';
+  const template = resolveTemplate(templateName);
+
+  const provider = newsletterConfig?.provider?.structure || 'openai';
+  const model = newsletterConfig?.model?.structure || DEFAULT_MODELS[provider];
+  const startTime = Date.now();
+
+  // Build the schema: BASE + template-specific fields
+  const schema = mergeSchemas(BASE_SCHEMA, template.schema);
+
+  // Build the AI prompt: template owns voice/structure brief, base owns attribution rules
+  const buildPrompt = template.buildPrompt || defaultBuildPrompt;
+  const { system, user } = buildPrompt({ brand, newsletterConfig, sources });
+
+  assistant.log(`Newsletter structure: template=${templateName} provider=${provider} model=${model} sources=${sources.length}`);
+
+  const result = await ai.request({
+    provider,
+    model,
+    messages: [
+      { role: 'system', content: system },
+      { role: 'user',   content: user },
+    ],
+    response: 'json',
+    schema,
+    maxTokens: 3000,
+    temperature: 0.7,
+    moderate: false,
+  });
+
+  const structure = result.content;
+
+  // Validate universals
+  if (!structure?.subject) {
+    throw new Error('AI returned invalid newsletter structure (missing subject)');
+  }
+
+  // Normalize universals
+  structure.subject   = structure.subject   || '';
+  structure.preheader = structure.preheader || '';
+  structure.signoff   = structure.signoff   || `Best,\nThe ${brand?.name || 'Team'} Team`;
+  structure.citations = Array.isArray(structure.citations) ? structure.citations : [];
+
+  // Let the template normalize its own fields (e.g. sections defaults).
+  // Falls back to a sane default if the template doesn't ship one.
+  if (typeof template.normalize === 'function') {
+    template.normalize(structure, { brand, newsletterConfig });
+  }
+
+  // Attach metadata (non-enumerable so it doesn't pollute JSON serialization of the structure itself)
+  Object.defineProperty(structure, '_meta', {
+    enumerable: false,
+    value: {
+      template: templateName,
+      provider,
+      model,
+      durationMs: Date.now() - startTime,
+      sourcesIn: sources.length,
+      tokens: result.tokens || null,
+    },
+  });
+
+  return structure;
+}
+
+// ---------- Default "classic" prompt (clean + editorial use this) ----------
+
+function buildClassicSystemPrompt(brand, config) {
+  const tone = config?.tone || 'professional';
+  const instructions = config?.instructions || '';
+  const taglineLine    = brand?.tagline     ? `\nTagline: ${brand.tagline}`            : '';
+  const descriptionLine = brand?.description ? `\nDescription: ${brand.description}` : '';
+
+  return [
+    `You are a newsletter writer for ${brand?.name || 'a tech company'}.${taglineLine}${descriptionLine}`,
+    instructions ? `\nBrand instructions:\n${instructions}` : '',
+    `\nTone: ${tone}`,
+    '',
+    'You will be given a set of "source articles" — these are background research, NOT publications you are writing for or about.',
+    'Treat them as raw information. Synthesize the IDEAS into original content written as if you are the original author.',
+    '',
+    'CRITICAL ATTRIBUTION RULES:',
+    '- NEVER name the source publication, newsletter, blog, or author in the body of the newsletter.',
+    '  (e.g., do NOT write "according to Daily Carnage", "as reported by Morning Brew", "Forbes says…", etc.)',
+    '- NEVER use phrases like "a recent article said", "according to sources", "industry coverage", or similar dodges that hint at the source.',
+    '- Write the body AS IF the source did not exist — the content should read as original, first-party reporting from the brand.',
+    '- If a source mentions a third-party platform, product, or company by name (e.g., LinkedIn, YouTube, Apple), THAT is fine — those are subjects of the news, not the source. Name them freely.',
+    '',
+    'CITATIONS:',
+    '- If the source contains hard data — specific statistics, percentages, dollar amounts, dates, study results, direct quotes — include them in the body.',
+    '- Then add a corresponding entry to the `citations` array with:',
+    '    - note: the cited fact (e.g. "Crosscheck AI flagged 12,000 impersonation attempts in beta")',
+    '    - source: a neutral attribution that does NOT name the source publication (e.g. "Reported by LinkedIn product team, May 2026", "Per company beta data", "Industry research, Q2 2026")',
+    '- Citations render as small footnotes at the BOTTOM of the newsletter — never inline.',
+    '- If a section has no hard data worth citing, do not invent citations. Empty array is fine.',
+    '',
+    'CONTENT REQUIREMENTS:',
+    '- Subject (≤60 chars, no emojis, attention-grabbing but not clickbait)',
+    '- Preheader (≤100 chars, complements the subject)',
+    '- 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: image_prompt — one-sentence visual description for an illustrator. Be specific about subject/style.',
+    `- 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.',
+    '',
+    'STYLE:',
+    '- Do NOT copy source text verbatim. Synthesize and rewrite in your voice.',
+    '- Do NOT use emojis, hashtags, or "guru" language unless brand instructions say otherwise.',
+    '- Respond with valid JSON only — no markdown fences, no preamble.',
+  ].filter(Boolean).join('\n');
+}
+
+function buildClassicUserPrompt(sources) {
+  // Note: we intentionally do NOT pass through the source publication name (raw.from)
+  // to the AI prompt. Removing it means the AI literally cannot leak it into the body.
+  // The "from" field is metadata about WHERE the research came from, not content to reference.
+  const summaries = sources
+    .map((s, i) => {
+      const raw = s.source || {};
+      const headline = s.ai?.headline || raw.subject || s.subject || `Topic ${i + 1}`;
+      const summary = s.ai?.summary || '';
+      const takeaways = (s.ai?.takeaways || []).join('; ');
+      const rawContent = !summary && raw.content
+        ? raw.content.slice(0, 1500)
+        : '';
+
+      return [
+        `[Research ${i + 1}]`,
+        `Topic: ${headline}`,
+        summary ? `Summary: ${summary}` : '',
+        takeaways ? `Key takeaways: ${takeaways}` : '',
+        rawContent ? `Raw content (excerpt):\n${rawContent}` : '',
+      ].filter(Boolean).join('\n');
+    })
+    .join('\n\n');
+
+  return `Write a newsletter using the following research as background. Do not name or reference these research items — synthesize the ideas into original content.\n\n${summaries}`;
+}
+
+module.exports = {
+  generateStructure,
+  BASE_SCHEMA,
+  defaultBuildPrompt,
+  mergeSchemas,
+  // Re-exported helpers so templates can reuse the classic prompt patterns
+  buildClassicSystemPrompt,
+  buildClassicUserPrompt,
+};

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

@@ -0,0 +1,184 @@
+/**
+ * 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).
+ *
+ * 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.
+ */
+const { Resvg } = require('@resvg/resvg-js');
+
+const DEFAULT_MODELS = {
+  openai: 'gpt-5.4-mini',
+  anthropic: 'claude-opus',
+  'claude-code': 'claude-opus-4-7',
+};
+
+const PNG_WIDTH = 800; // 2x display width of 400px container
+
+/**
+ * Generate one illustration for a section.
+ *
+ * @param {object} args
+ * @param {string} args.imagePrompt - Visual description from the structure
+ * @param {object} args.brand - { name, color: { primary, secondary, ... } }
+ * @param {object} args.newsletterConfig - marketing.beehiiv.content
+ * @param {object} args.ai - AI instance
+ * @param {object} args.assistant - BEM assistant
+ * @returns {Promise<{svg: string, png: Buffer, fallback: boolean}>}
+ */
+async function generateSectionImage({ imagePrompt, brand, newsletterConfig, ai, assistant }) {
+  const provider = newsletterConfig?.provider?.svg || 'anthropic';
+  const model = newsletterConfig?.model?.svg || DEFAULT_MODELS[provider];
+  const startTime = Date.now();
+
+  const palette = resolvePalette(brand, newsletterConfig);
+  const systemPrompt = buildSvgSystemPrompt(palette);
+  const userPrompt = imagePrompt || 'An abstract geometric illustration representing the topic.';
+
+  let svg = '';
+  let fallback = false;
+  let attempts = 0;
+  let lastTokens = null;
+
+  for (let attempt = 0; attempt < 2; attempt++) {
+    attempts++;
+    try {
+      const result = await ai.request({
+        provider,
+        model,
+        messages: [
+          { role: 'system', content: systemPrompt },
+          { role: 'user',   content: userPrompt },
+        ],
+        response: 'text',
+        maxTokens: 2000,
+        temperature: attempt === 0 ? 0.8 : 0.4,
+        moderate: false,
+      });
+
+      lastTokens = result.tokens;
+      svg = extractSvg(result.content);
+
+      if (svg) {
+        break;
+      }
+
+      assistant.log(`SVG generation attempt ${attempt + 1} returned no valid <svg>`);
+    } catch (e) {
+      assistant.error(`SVG generation attempt ${attempt + 1} failed: ${e.message}`);
+    }
+  }
+
+  let png;
+
+  if (svg) {
+    try {
+      png = rasterize(svg);
+    } catch (e) {
+      assistant.error(`SVG rasterization failed, using fallback: ${e.message}`);
+      svg = buildPlaceholderSvg(palette);
+      png = rasterize(svg);
+      fallback = true;
+    }
+  } else {
+    svg = buildPlaceholderSvg(palette);
+    png = rasterize(svg);
+    fallback = true;
+  }
+
+  return {
+    svg,
+    png,
+    fallback,
+    meta: {
+      provider,
+      model,
+      durationMs: Date.now() - startTime,
+      attempts,
+      fallback,
+      tokens: lastTokens,
+    },
+  };
+}
+
+/**
+ * Resolve brand palette from config theme + brand defaults.
+ * Returns { primary, secondary, accent, bg, fg }
+ */
+function resolvePalette(brand, newsletterConfig) {
+  const theme = newsletterConfig?.theme || {};
+
+  return {
+    primary:   theme.primaryColor   || brand?.color?.primary   || '#5B5BFF',
+    secondary: theme.secondaryColor || brand?.color?.secondary || '#1E1E2A',
+    accent:    theme.accentColor    || brand?.color?.accent    || '#F6F7FB',
+    bg:        '#FFFFFF',
+    fg:        '#1E1E2A',
+  };
+}
+
+function buildSvgSystemPrompt(palette) {
+  return [
+    'You are an SVG illustrator. Produce a single self-contained SVG illustration.',
+    '',
+    'STRICT REQUIREMENTS:',
+    '- viewBox="0 0 800 400"',
+    '- No <text>, no <foreignObject>, no <script>, no <image>, no external references',
+    '- Use only: <rect>, <circle>, <ellipse>, <path>, <line>, <polyline>, <polygon>, <g>',
+    '- Maximum 20 shape elements total',
+    '- No filters, no gradients beyond simple <linearGradient>',
+    '- Output ONLY the SVG element. No markdown fences, no preamble, no explanation.',
+    '',
+    'PALETTE (use these colors exclusively):',
+    `- Primary:   ${palette.primary}`,
+    `- Secondary: ${palette.secondary}`,
+    `- Accent:    ${palette.accent}`,
+    `- Background: ${palette.bg}`,
+    '',
+    'STYLE: Flat, geometric, modern, minimal. Think Stripe, Linear, or Vercel marketing illustrations.',
+    'COMPOSITION: Centered subject, balanced negative space, no busy clutter.',
+  ].join('\n');
+}
+
+function extractSvg(text) {
+  if (!text || typeof text !== 'string') {
+    return null;
+  }
+
+  // Strip markdown fences
+  let cleaned = text.trim().replace(/^```(?:svg|xml)?\s*/i, '').replace(/\s*```$/i, '');
+
+  // Find first <svg ... > ... </svg>
+  const match = cleaned.match(/<svg[\s\S]*?<\/svg>/i);
+
+  if (!match) {
+    return null;
+  }
+
+  return match[0];
+}
+
+function buildPlaceholderSvg(palette) {
+  return [
+    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 400">',
+    `  <rect width="800" height="400" fill="${palette.accent}"/>`,
+    `  <circle cx="400" cy="200" r="120" fill="${palette.primary}" opacity="0.85"/>`,
+    `  <circle cx="320" cy="160" r="60"  fill="${palette.secondary}" opacity="0.7"/>`,
+    `  <rect   x="480" y="240" width="120" height="80" fill="${palette.primary}" opacity="0.4"/>`,
+    '</svg>',
+  ].join('\n');
+}
+
+function rasterize(svgString) {
+  const resvg = new Resvg(svgString, {
+    fitTo: { mode: 'width', value: PNG_WIDTH },
+    background: 'rgba(0,0,0,0)',
+  });
+
+  return resvg.render().asPng();
+}
+
+module.exports = { generateSectionImage, rasterize };

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

@@ -0,0 +1,63 @@
+/**
+ * Classic newsletter content schema — used by `clean` and `editorial`.
+ *
+ * Both templates consume the same shape:
+ *   - intro: 1-2 sentence preamble
+ *   - sections: list of {title, body, cta?, 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.
+ */
+const CLASSIC_SCHEMA = {
+  required: ['intro', 'sections'],
+  properties: {
+    intro: { type: 'string' },
+    sections: {
+      type: 'array',
+      minItems: 2,
+      maxItems: 6,
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['title', 'body', 'image_prompt', 'cta'],
+        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' },
+        },
+      },
+    },
+  },
+};
+
+/**
+ * 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.
+ */
+function normalizeClassic(structure) {
+  if (!Array.isArray(structure.sections)) {
+    structure.sections = [];
+  }
+
+  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 || '',
+  }));
+
+  structure.intro = structure.intro || '';
+}
+
+module.exports = { CLASSIC_SCHEMA, normalizeClassic };

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

@@ -0,0 +1,82 @@
+/**
+ * `clean` template — Stripe / Linear marketing aesthetic.
+ *
+ * White cards on a light accent background. Brand wordmark header → intro →
+ * one card per section (image, title, body, optional CTA) → signoff.
+ *
+ * The shell handles cross-cutting concerns (top/end sponsorships, citations,
+ * footer with CAN-SPAM address) automatically. This file only owns the
+ * "clean" identity — header, intro, section cards, signoff.
+ */
+const {
+  shell,
+  resolveTheme,
+  brandHeader,
+  introBlock,
+  sectionCard,
+  signoffBlock,
+  sponsorshipsAt,
+} = require('./shared.js');
+
+const { CLASSIC_SCHEMA, normalizeClassic } = require('./classic-schema.js');
+
+const SPACING_OVERRIDES = {
+  gutter: '32px',
+};
+
+function build({ structure, imagePaths, theme: themeIn, brandName, brandUrl, brandAddress, now, sponsorships }) {
+  const theme = resolveTheme(themeIn, SPACING_OVERRIDES);
+
+  // Section rendering, with middle sponsorships interleaved at the midpoint.
+  // Sections array is optional — a structure with no sections renders just
+  // header + intro + signoff + footer (still a valid newsletter).
+  const safeSections = Array.isArray(structure.sections) ? structure.sections : [];
+  const sectionBlocks = safeSections.map((section, i) =>
+    sectionCard({ section: section || {}, imagePath: imagePaths?.[i], theme })
+  );
+
+  const middleSponsorships = sponsorshipsAt({ sponsorships, position: 'middle', theme });
+  if (middleSponsorships) {
+    const middleIndex = Math.floor(sectionBlocks.length / 2);
+    sectionBlocks.splice(middleIndex, 0, middleSponsorships);
+  }
+
+  // Envelope: shared data for every template
+  const envelope = {
+    structure,
+    theme,
+    brandName,
+    brandUrl,
+    brandAddress,
+    sponsorships,
+    now,
+  };
+
+  // Slots: what 'clean' uniquely contributes
+  const slots = {
+    header: brandHeader({ brandName, brandUrl, theme }),
+    hero: introBlock({ intro: structure.intro, theme }),
+    body: sectionBlocks.join('\n'),
+    signoff: signoffBlock({ signoff: structure.signoff, theme }),
+  };
+
+  // Footer on transparent so it blends with the page background
+  const config = {
+    footerStyle: { background: 'transparent' },
+  };
+
+  return shell(envelope, slots, config);
+}
+
+module.exports = {
+  build,
+  meta: {
+    name: 'clean',
+    description: 'Stripe / Linear marketing aesthetic. Safe, conservative, works everywhere.',
+    requires: ['subject', 'preheader', 'intro', 'sections', 'signoff'],
+    optional: ['citations', 'image_prompt', 'cta'],
+    supports: { sponsorships: ['top', 'middle', 'end'], citations: true, images: true },
+  },
+  schema: CLASSIC_SCHEMA,
+  normalize: normalizeClassic,
+};