@omega.js/backend 0.1.0

package/dist/manager/libraries/email/generators/lib/templates/base.js

@@ -0,0 +1,229 @@
+/**
+ * Base building blocks for campaign/transactional email templates.
+ *
+ * skeleton() — the required wrapper. Every template uses this. Provides:
+ *   <mjml>, <mj-head> (title, preview, font-family, styles), hidden ASM tags, close tags.
+ *   The second arg is the body content — templates compose whatever they want inside.
+ *
+ * Everything else is an opt-in block — a function that returns an MJML string.
+ * Templates import what they need and ignore the rest.
+ */
+const { escape, safeUrl } = require('./shared-campaign.js');
+
+const DEFAULT_STYLES = `
+  body { background-color: #F7FAFC; }
+  h1, h2, h3 { color: #1A202C; margin: 0 0 12px; font-weight: 500; }
+  h2 { font-size: 32px; line-height: 1.2; }
+  a { color: #0d6efd; }
+  p { margin: 0 0 12px; color: #4A5568; }
+`;
+
+// Hidden ASM tags — suppress SendGrid's auto-inserted unsubscribe text.
+// _raw_url variants output just the URL, not a full <a> tag.
+const HIDDEN_ASM = `<div style="display:none;max-height:0;overflow:hidden;mso-hide:all;">
+    <a href="<%asm_group_unsubscribe_raw_url%>">unsubscribe</a>
+    <a href="<%asm_preferences_raw_url%>">preferences</a>
+  </div>`;
+
+/**
+ * The required skeleton — every template wraps its content in this.
+ *
+ * @param {object} options
+ * @param {string} [options.subject] - Email subject (for <mj-title>)
+ * @param {string} [options.preview] - Preheader text
+ * @param {string} [options.styles] - Additional CSS (appended to defaults)
+ * @param {string} [options.width] - Body width (default '600px')
+ * @param {string[]} [options.categories] - Email categories for hidden tagging
+ * @param {string} content - MJML body content
+ * @returns {string} Complete MJML document
+ */
+function skeleton({ subject, preview, styles, width, categories }, content) {
+  const categoryTags = (categories || [])
+    .map(c => `category=${escape(c)}`)
+    .join('\n                  ,\n                  ');
+  const hiddenMeta = `<div style="display:none;max-height:0;overflow:hidden;mso-hide:all;">
+    ${HIDDEN_ASM}
+    ${categoryTags ? `<span>${categoryTags}</span>` : ''}
+  </div>`;
+
+  return `<mjml>
+  <mj-head>
+    <mj-title>${escape(subject || '')}</mj-title>
+    <mj-preview>${escape(preview || '')}</mj-preview>
+    <mj-attributes>
+      <mj-all font-family="Helvetica, Arial, sans-serif" />
+      <mj-text font-size="16px" line-height="1.5" color="#1A202C" />
+      <mj-section padding="0" />
+    </mj-attributes>
+    <mj-style>${DEFAULT_STYLES}${styles || ''}</mj-style>
+  </mj-head>
+  <mj-body background-color="#F7FAFC" width="${width || '600px'}">
+${content}
+    <mj-section padding="0"><mj-column><mj-text padding="0">${hiddenMeta}</mj-text></mj-column></mj-section>
+  </mj-body>
+</mjml>`;
+}
+
+/**
+ * Brandmark logo centered above the card.
+ * Falls back to brand name text if no image.
+ */
+function logo(brand, theme) {
+  const brandName = brand?.name || '';
+  const brandUrl = brand?.url || '#';
+  const logoUrl = brand?.images?.brandmark || '';
+  const primaryColor = theme?.primaryColor || '#5B5BFF';
+
+  const inner = logoUrl
+    ? `<img src="${escape(logoUrl)}" alt="${escape(brandName)}" width="96" style="width: 96px; height: auto; display: inline-block;" />`
+    : `<span style="font-size: 20px; font-weight: 700; color: ${primaryColor};">${escape(brandName)}</span>`;
+
+  return `
+    <mj-section padding="40px 0 0 0">
+      <mj-column>
+        <mj-text align="center" padding="0">
+          <a href="${brandUrl}" style="text-decoration: none;">${inner}</a>
+        </mj-text>
+      </mj-column>
+    </mj-section>
+    <mj-section><mj-column><mj-spacer height="16px" /></mj-column></mj-section>`;
+}
+
+/**
+ * White card with border + rounded corners. Wraps content.
+ */
+function cardWrapper(content) {
+  return `
+    <mj-section padding="0 16px">
+      <mj-column padding="40px" background-color="#ffffff" border="1px solid #E2E8F0" border-radius="16px">
+        ${content}
+      </mj-column>
+    </mj-section>
+    <mj-section><mj-column><mj-spacer height="24px" /></mj-column></mj-section>`;
+}
+
+/**
+ * Signoff block — handles team vs personal (with headshot + link).
+ */
+function signoff(data, theme) {
+  const s = data?.signoff || {};
+  const brandName = data?.brand?.name || '';
+  const primaryColor = theme?.primaryColor || '#5B5BFF';
+  const isPersonal = s.type === 'personal' && s.name;
+
+  if (isPersonal) {
+    const img = s.image
+      ? `<img src="${escape(s.image)}" alt="${escape(s.name)}" width="60" style="width: 60px; height: 60px; border-radius: 50%; display: block;" />`
+      : '';
+    const link = s.url
+      ? `<br/><a href="${safeUrl(s.url)}" style="color: ${primaryColor}; font-size: 14px; text-decoration: none;">${escape(s.urlText || s.url)}</a>`
+      : '';
+
+    const inner = img
+      ? `<table cellpadding="0" cellspacing="0" border="0"><tr>
+          <td style="vertical-align: middle; padding-right: 16px;">${img}</td>
+          <td style="vertical-align: middle; color: #4A5568;">Warm regards,<br/><strong>${escape(s.name)}</strong>${link}</td>
+        </tr></table>`
+      : `<div style="color: #4A5568;">Warm regards,<br/><strong>${escape(s.name)}</strong>${link}</div>`;
+
+    return `
+        <mj-divider border-color="#E2E8F0" border-width="1px" padding="32px 0 24px 0" />
+        <mj-text padding="0">${inner}</mj-text>`;
+  }
+
+  return `
+        <mj-divider border-color="#E2E8F0" border-width="1px" padding="32px 0 24px 0" />
+        <mj-text padding="0"><div style="color: #4A5568;">Sincerely,<br/>The ${escape(brandName)} Team</div></mj-text>`;
+}
+
+/**
+ * CTA button (dark style).
+ */
+function button(btn) {
+  if (!btn?.url || !btn?.text) {
+    return '';
+  }
+
+  return `<mj-button href="${safeUrl(btn.url)}" background-color="#1A202C" color="#ffffff" border-radius="4px" font-size="16px" font-weight="normal" inner-padding="10px 20px" padding="24px 0 0 0">${escape(btn.text)}</mj-button>`;
+}
+
+/**
+ * Full footer — company wordmark, footer text, divider, links, copyright, address.
+ *
+ * The parent/legal entity comes from config: `brand.company` (falling back to
+ * `brand.name`, the documented schema chain) and `brand.images.companyWordmark`.
+ * An unset wordmark renders NO wordmark — never another company's logo.
+ */
+function footer(brand, email) {
+  const brandUrl = brand?.url || '#';
+  const addr = brand?.address || {};
+  const address = [addr.line1, addr.line2, addr.city, addr.region, addr.postalCode].filter(Boolean).join(' · ');
+  const footerText = email?.footer?.text || 'You are receiving this email because you recently interacted with our website.';
+  const unsubscribeUrl = email?.unsubscribeUrl || `${brandUrl}/portal/email-preferences`;
+  const year = new Date().getFullYear();
+  const companyName = brand?.company || brand?.name || '';
+  const companyWordmark = brand?.images?.companyWordmark || '';
+
+  const wordmarkSection = companyWordmark
+    ? `
+    <mj-section padding="0 32px">
+      <mj-column>
+        <mj-image src="${escape(companyWordmark)}" alt="${escape(companyName)}" width="160px" padding="0" />
+      </mj-column>
+    </mj-section>`
+    : '';
+
+  return `${wordmarkSection}
+
+    <mj-section padding="8px 32px 0 32px">
+      <mj-column>
+        <mj-text align="center" font-size="14px" color="#718096" padding="0">
+          ${escape(footerText)}
+        </mj-text>
+      </mj-column>
+    </mj-section>
+
+    <mj-section padding="16px 32px">
+      <mj-column>
+        <mj-divider border-color="#E2E8F0" border-width="1px" padding="0" />
+      </mj-column>
+    </mj-section>
+
+    <mj-section padding="0 32px">
+      <mj-column>
+        <mj-text align="center" font-size="13px" color="#718096" padding="0">
+          <a href="${brandUrl}/dashboard/account" style="color: #718096; text-decoration: underline;">Manage account</a> &middot;
+          <a href="${brandUrl}/terms" style="color: #718096; text-decoration: underline;">Terms</a> &middot;
+          <a href="${brandUrl}/privacy" style="color: #718096; text-decoration: underline;">Privacy</a> &middot;
+          <a href="${unsubscribeUrl}" style="color: #718096; text-decoration: underline;">Unsubscribe</a>
+        </mj-text>
+      </mj-column>
+    </mj-section>
+
+    <mj-section padding="4px 32px 0 32px">
+      <mj-column>
+        <mj-text align="center" font-size="13px" color="#A0AEC0" padding="0">
+          &copy; ${year} ${escape(companyName)}
+        </mj-text>
+      </mj-column>
+    </mj-section>
+
+    <mj-section padding="2px 32px 32px 32px">
+      <mj-column>
+        <mj-text align="center" font-size="13px" color="#A0AEC0" padding="0">
+          ${escape(address)}
+        </mj-text>
+      </mj-column>
+    </mj-section>`;
+}
+
+module.exports = {
+  skeleton,
+  logo,
+  cardWrapper,
+  signoff,
+  button,
+  footer,
+  escape,
+  HIDDEN_ASM,
+};

package/dist/manager/libraries/email/generators/lib/templates/card.js

@@ -0,0 +1,33 @@
+/**
+ * Card template — the default. Brandmark → white card (title + message + CTA) → signoff → footer.
+ */
+const { skeleton, logo, cardWrapper, signoff, button, footer, escape } = require('./base.js');
+
+function build({ data, theme }) {
+  const brand = data?.brand || {};
+  const email = data?.email || {};
+  const content = data?.content || {};
+  const title = content.title || '';
+  const message = content.message || '';
+
+  const titleMjml = title
+    ? `<h2 style="font-size: 32px; line-height: 1.2; font-weight: 500; margin: 0 0 8px;">${escape(title)}</h2>`
+    : '';
+
+  return skeleton({ subject: email.subject, preview: email.preview, categories: email.categories }, `
+    ${logo(brand, theme)}
+    ${cardWrapper(`
+        <mj-text padding="0">${titleMjml}${message}</mj-text>
+        ${button(content.button)}
+        ${signoff(data, theme)}
+    `)}
+    ${footer(brand, email)}
+  `);
+}
+
+const meta = {
+  name: 'card',
+  description: 'Branded card layout — the default email template',
+};
+
+module.exports = { build, meta };

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

@@ -0,0 +1,59 @@
+/**
+ * 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, 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'],
+  properties: {
+    intro: { type: 'string' },
+    sections: {
+      type: 'array',
+      minItems: 2,
+      maxItems: 6,
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['title', 'body', 'image_prompt'],
+        properties: {
+          title: { type: 'string' },
+          body:  { 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.
+ */
+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 || '',
+    image_prompt: s.image_prompt || '',
+  }));
+
+  structure.intro = structure.intro || '';
+}
+
+module.exports = { CLASSIC_SCHEMA, normalizeClassic };

package/dist/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('./newsletter-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'],
+    supports: { sponsorships: ['top', 'middle', 'end'], citations: true, images: true },
+  },
+  schema: CLASSIC_SCHEMA,
+  normalize: normalizeClassic,
+};

package/dist/manager/libraries/email/generators/lib/templates/editorial/helpers.js

@@ -0,0 +1,100 @@
+/**
+ * Helpers used by editorial / magazine-style templates.
+ *
+ * Lives separately from shared.js because these are NOT general-purpose
+ * primitives — they encode editorial-specific conventions (pull-quotes,
+ * issue numbering, serif eyebrow labels). Templates that want this aesthetic
+ * import from here; other templates (clean, future minimal/digest variants)
+ * don't touch this file.
+ */
+const { escape } = require('../newsletter-shared.js');
+
+const SERIF_FONT = 'Georgia, \'Times New Roman\', serif';
+
+const EYEBROW_STYLE = 'font-size: 11px; letter-spacing: 4px; text-transform: uppercase; font-weight: 700;';
+
+/**
+ * Render an "eyebrow" — a small uppercase tracked label used above headlines
+ * and over closing cards. Pass a `color` to tint it; defaults to 'inherit'.
+ */
+function eyebrow({ text, color, marginBottom }) {
+  const extra = marginBottom ? ` margin-bottom: ${marginBottom};` : '';
+  return `<div style="${EYEBROW_STYLE} color: ${color || 'inherit'};${extra}">${escape(text)}</div>`;
+}
+
+/**
+ * Pick a quotable sentence from a body of text. Returns the longest sentence
+ * between 60 and 180 characters, biased toward sentences containing hook
+ * words like "means", "matters", "practical", "risk", etc.
+ */
+function pullQuoteFrom(body) {
+  if (!body) {
+    return null;
+  }
+
+  const sentences = body
+    .replace(/\n+/g, ' ')
+    .split(/(?<=[.!?])\s+/)
+    .map((s) => s.trim())
+    .filter((s) => s.length >= 60 && s.length <= 180);
+
+  if (!sentences.length) {
+    return null;
+  }
+
+  const hooks = /\b(means|matters|will|should|need|important|key|critical|practical|takeaway|risk|trust)\b/i;
+  const hooked = sentences.find((s) => hooks.test(s));
+
+  return hooked || sentences.sort((a, b) => b.length - a.length)[0];
+}
+
+/**
+ * Remove a sentence from a body. Used to avoid duplicating the pull-quote
+ * in the running body text.
+ */
+function stripSentence(body, sentence) {
+  if (!body || !sentence) {
+    return body || '';
+  }
+
+  const escaped = sentence.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const pattern = new RegExp(`\\s*${escaped}\\s*`, '');
+
+  return body.replace(pattern, ' ').trim();
+}
+
+/**
+ * "Issue 0863 · May 12, 2026"-style line. The number is monotonically
+ * increasing since 2024-01-01, so a daily newsletter gets a stable
+ * issue number per day.
+ */
+function issueLine({ now, prefix }) {
+  const d = now || new Date();
+  return {
+    number: computeIssueNumber(d),
+    date: formatIssueDate(d),
+    line: `${prefix || 'Issue'} ${computeIssueNumber(d)} · ${formatIssueDate(d)}`,
+  };
+}
+
+function formatIssueDate(date) {
+  return date.toLocaleDateString('en-US', { month: 'long', day: 'numeric', year: 'numeric' });
+}
+
+function computeIssueNumber(date) {
+  const epoch = new Date('2024-01-01T00:00:00Z');
+  const days = Math.floor((date.getTime() - epoch.getTime()) / (1000 * 60 * 60 * 24));
+
+  return String(days).padStart(4, '0');
+}
+
+module.exports = {
+  SERIF_FONT,
+  EYEBROW_STYLE,
+  eyebrow,
+  pullQuoteFrom,
+  stripSentence,
+  issueLine,
+  formatIssueDate,
+  computeIssueNumber,
+};