@omega.js/backend 0.1.0

package/dist/manager/libraries/email/generators/lib/image-illustrator.js

@@ -0,0 +1,154 @@
+/**
+ * Image illustrator — AI generates a flat-vector PNG illustration per section
+ * directly via OpenAI's image model (gpt-image-2), no SVG-author-then-rasterize step.
+ *
+ * This is the DEFAULT newsletter illustration method. It replaces the older
+ * svg-illustrator.js approach (AI writes an <svg>, resvg rasterizes it) which is
+ * still available as a fallback via newsletterConfig.method.image = 'svg'.
+ *
+ * Output matches svg-illustrator's contract: { png: Buffer, fallback, meta }.
+ * The newsletter pipeline (image-host.js) only requires `img.png` to be a PNG Buffer.
+ *
+ * Style: clean flat 2D vector illustration (Stripe / Linear / undraw.co aesthetic),
+ * built from the brand palette, on a white background, no text. The prompt mirrors
+ * the validated spike in scripts/.temp/ai-image-test/.
+ */
+const DEFAULT_MODEL = 'gpt-image-2';
+const DEFAULT_SIZE = '1024x1024';     // square reads best for flat section art
+const DEFAULT_QUALITY = 'medium';     // medium is plenty for flat vector; ~40-50s/image
+
+/**
+ * Generate one illustration for a section.
+ *
+ * @param {object} args
+ * @param {string} args.imagePrompt - Visual description from the structure
+ * @param {object} args.brand - { name, tagline, color: { primary, secondary, ... } }
+ * @param {object} args.newsletterConfig - marketing.newsletter.content
+ * @param {object} args.ai - Manager.AI() instance
+ * @param {object} args.ctx - @omega.js/backend ctx
+ * @returns {Promise<{png: Buffer, fallback: boolean, meta: object}>}
+ */
+async function generateSectionImage({ imagePrompt, brand, newsletterConfig, ai, ctx }) {
+  const startTime = Date.now();
+  const model = newsletterConfig?.model?.image || DEFAULT_MODEL;
+  const size = newsletterConfig?.image?.size || DEFAULT_SIZE;
+  const quality = newsletterConfig?.image?.quality || DEFAULT_QUALITY;
+
+  const palette = resolvePalette(brand, newsletterConfig);
+  const subject = imagePrompt || 'An abstract geometric shape representing the topic.';
+  const prompt = buildImagePrompt({ brand, palette, subject });
+
+  let png = null;
+  let fallback = false;
+  let revisedPrompt = null;
+  let attempts = 0;
+
+  for (let attempt = 0; attempt < 2; attempt++) {
+    attempts++;
+    try {
+      const result = await ai.image({
+        provider: 'openai',
+        model,
+        prompt,
+        size,
+        quality,
+        background: 'opaque',
+      });
+
+      if (result?.png || result?.buffer) {
+        png = result.png || result.buffer;
+        revisedPrompt = result.revisedPrompt || null;
+        break;
+      }
+
+      ctx.log(`Image generation attempt ${attempt + 1} returned no buffer`);
+    } catch (e) {
+      ctx.error(`Image generation attempt ${attempt + 1} failed: ${e.message}`);
+    }
+  }
+
+  // No transparent-PNG placeholder fallback that's valid as an image — if both
+  // attempts fail, return a 1x1 transparent PNG so the pipeline doesn't crash on
+  // a non-Buffer. The caller logs and proceeds.
+  if (!png) {
+    png = TRANSPARENT_PNG;
+    fallback = true;
+  }
+
+  return {
+    png,
+    fallback,
+    meta: {
+      method: 'image',
+      provider: 'openai',
+      model,
+      size,
+      quality,
+      durationMs: Date.now() - startTime,
+      attempts,
+      fallback,
+      revisedPrompt,
+    },
+  };
+}
+
+/**
+ * Resolve brand palette — same precedence as svg-illustrator.js#resolvePalette:
+ * newsletter theme colors → brand.color.* → sensible defaults.
+ */
+function resolvePalette(brand, newsletterConfig) {
+  const theme = newsletterConfig?.theme || {};
+
+  return {
+    primary:   theme.primaryColor   || brand?.color?.primary   || '#4B5BFF',
+    secondary: theme.secondaryColor || brand?.color?.secondary || '#1E1E2A',
+    accent:    theme.accentColor    || brand?.color?.accent    || '#F4F6FA',
+  };
+}
+
+/**
+ * Build the flat-vector art-direction prompt with brand identity + palette baked in.
+ * Mirrors the validated prompt from scripts/.temp/ai-image-test/generate.js.
+ */
+function buildImagePrompt({ brand, palette, subject }) {
+  const { primary, secondary, accent } = palette;
+  const name = brand?.name || 'the brand';
+  const tagline = brand?.tagline ? ` — ${brand.tagline}` : '';
+
+  return [
+    `Minimal flat vector illustration for the newsletter of "${name}"${tagline}.`,
+    '',
+    'STYLE: modern flat 2D vector illustration, like the marketing graphics on',
+    'Stripe, Linear, Vercel, Notion, or undraw.co. Clean geometric shapes with',
+    'flat solid color fills and crisp edges. Simple, friendly, and minimal.',
+    '',
+    'ABSOLUTELY NOT: no photorealism, no 3D renders, no realistic textures, no',
+    'photography, no depth of field, no dramatic lighting, no film grain, no',
+    'shading or gradients beyond a single subtle flat tone shift, no glossy',
+    'reflections, no metallic surfaces. This must look hand-designed in a vector',
+    'tool (Figma/Illustrator), NOT rendered or photographed.',
+    '',
+    'PALETTE (use ONLY these flat colors, plus white):',
+    `- Primary:   ${primary}`,
+    `- Secondary: ${secondary}`,
+    `- Accent:    ${accent}`,
+    'Flat solid fills only. A clean white or very-light background.',
+    '',
+    'COMPOSITION: single clear simple subject, lots of clean negative space,',
+    'centered or rule-of-thirds, uncluttered, plenty of breathing room.',
+    '',
+    'HARD CONSTRAINTS: absolutely NO text, NO words, NO letters, NO numbers,',
+    'NO logos, NO watermarks, NO UI mockups, NO borders or frames.',
+    '',
+    `SUBJECT (the focal scene to illustrate): ${subject}`,
+  ].join('\n');
+}
+
+// 1x1 transparent PNG — last-resort fallback so a failed generation still yields a
+// valid PNG Buffer instead of crashing image-host.js's Buffer check.
+const TRANSPARENT_PNG = Buffer.from(
+  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==',
+  'base64'
+);
+
+module.exports = { generateSectionImage };

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

@@ -0,0 +1,294 @@
+/**
+ * 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,
+      cta: d.cta,  // injected post-generation (e.g. linked-article "Read more")
+    }));
+  }
+
+  // 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,
+      cta: s.cta,  // injected post-generation (e.g. linked-article "Read more")
+    }));
+  }
+
+  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);
+  }
+
+  // CTA (e.g. "Read the full article →") — injected by code post-generation,
+  // never authored by the AI. The MJML template renders section.cta via
+  // sectionCard; this is the markdown equivalent for the Beehiiv-paste view.
+  if (section.cta?.url && section.cta?.label) {
+    lines.push(`[${section.cta.label} →](${section.cta.url})`);
+  }
+
+  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/dist/manager/libraries/email/generators/lib/mjml-template.js

@@ -0,0 +1,120 @@
+/**
+ * MJML newsletter template — turns a structured newsletter into email-safe HTML.
+ *
+ * Dispatches by `newsletterConfig.template` into one of the layouts in
+ * `./templates/` and compiles the resulting MJML to HTML.
+ *
+ * Templates are pure builders — they take the structured data + theme tokens
+ * and return MJML. This file owns the compilation, UTM tagging, and brand
+ * resolution that's identical across templates.
+ */
+const mjml = require('mjml');
+
+const { resolveNewsletterTemplate, resolveEmailTemplate } = require('./templates/index.js');
+const { formatAddress } = require('./templates/newsletter-shared.js');
+const { tagLinks } = require('../../utm');
+
+const DEFAULT_THEME = {
+  primaryColor:   '#5B5BFF',
+  secondaryColor: '#1E1E2A',
+  accentColor:    '#F6F7FB',
+  font:           'Inter, system-ui, sans-serif',
+};
+
+const DEFAULT_TEMPLATE = 'clean';
+
+/**
+ * Render the newsletter to email-safe HTML.
+ *
+ * @param {object} args
+ * @param {object} args.brand - { name, id, url }
+ * @param {object} args.newsletterConfig - marketing.newsletter.content (theme, template, ...)
+ * @param {object} args.structure - Output from structure.js
+ * @param {string[]} args.imagePaths - One entry per section (URL or local path)
+ * @param {string} [args.campaign] - Used for UTM utm_campaign
+ * @param {string} [args.template] - Template override (otherwise newsletterConfig.template)
+ * @param {Array<object>} [args.sponsorships] - Brand-owned sponsorship promos to inject (merged with config)
+ * @returns {Promise<{mjml: string, html: string, template: string, errors: object[]}>}
+ */
+async function renderNewsletter({ brand, newsletterConfig, structure, imagePaths, campaign, template, sponsorships }) {
+  const theme = { ...DEFAULT_THEME, ...(newsletterConfig?.theme || {}) };
+  const brandName = brand?.name || 'Newsletter';
+  const brandUrl = brand?.url || '#';
+  const brandId = brand?.id || '';
+  const brandAddress = formatAddress(brand?.address);
+
+  const templateName = template || newsletterConfig?.template || DEFAULT_TEMPLATE;
+  const builder = resolveNewsletterTemplate(templateName);
+
+  // Resolve sponsorships: per-call override beats per-campaign beats config defaults
+  const resolvedSponsorships = Array.isArray(sponsorships) && sponsorships.length
+    ? sponsorships
+    : (newsletterConfig?.sponsorships || []);
+
+  const mjmlString = builder.build({
+    structure,
+    imagePaths,
+    theme,
+    brandName,
+    brandUrl,
+    brandAddress,
+    sponsorships: resolvedSponsorships,
+    now: new Date(),
+  });
+
+  const compiled = await mjml(mjmlString, { validationLevel: 'soft' });
+
+  if (compiled.errors?.length) {
+    // Soft — log but don't throw. MJML often emits warnings that don't affect output.
+    // eslint-disable-next-line no-console
+    console.warn('MJML compilation warnings:', compiled.errors.map((e) => e.message));
+  }
+
+  const html = tagLinks(compiled.html, {
+    brandUrl,
+    brandId,
+    campaign: campaign || 'newsletter',
+    type: 'marketing',
+  });
+
+  return { mjml: mjmlString, html, template: templateName, errors: compiled.errors || [] };
+}
+
+/**
+ * Render a campaign/transactional email to email-safe HTML.
+ * Uses the campaign template registry (card, plain, order, feedback).
+ *
+ * @param {object} args
+ * @param {object} args.brand - { name, id, url, address, theme }
+ * @param {string} args.template - Template name ('card', 'plain', 'order', 'feedback')
+ * @param {object} args.data - Full data object (brand, user, content, signoff, email, etc.)
+ * @param {object} [args.utm] - UTM overrides for link tagging ({ campaign, type })
+ * @returns {Promise<{mjml: string, html: string, template: string, errors: object[]}>}
+ */
+async function renderEmail({ brand, template, data, utm }) {
+  const theme = { ...DEFAULT_THEME, ...(brand?.theme || {}) };
+  const templateName = template || 'card';
+  const builder = resolveEmailTemplate(templateName);
+
+  const mjmlString = builder.build({ data, theme, templateName });
+
+  const compiled = await mjml(mjmlString, { validationLevel: 'soft' });
+
+  if (compiled.errors?.length) {
+    console.warn('MJML compilation warnings:', compiled.errors.map((e) => e.message));
+  }
+
+  const brandUrl = brand?.url || '';
+  const brandId = brand?.id || '';
+
+  let html = brandUrl
+    ? tagLinks(compiled.html, { brandUrl, brandId, campaign: utm?.campaign || templateName, type: utm?.type || 'transactional' })
+    : compiled.html;
+
+  // Wrap the body content with id="email-content" (matches legacy SendGrid template convention)
+  html = html.replace(/(<body[^>]*>)/, '$1<div id="email-content">').replace(/<\/body>/, '</div></body>');
+
+  return { mjml: mjmlString, html, template: templateName, errors: compiled.errors || [] };
+}
+
+module.exports = { renderNewsletter, renderEmail };