backend-manager 5.0.157 → 5.0.158

package/CHANGELOG.md

@@ -14,6 +14,20 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - `Fixed` for any bug fixes.
 - `Security` in case of vulnerabilities.
 
+# [5.0.158] - 2026-03-17
+### Added
+- Newsletter generator system (`libraries/email/generators/newsletter.js`) — fetches sources from parent server, AI assembles branded content with subject/preheader
+- Daily pre-generation cron (`cron/daily/marketing-newsletter-generate.js`) — generates newsletter content 24 hours before sendAt for calendar review
+- `marketing.newsletter.enabled` and `marketing.newsletter.categories` config options
+- `generator` field on campaign docs — tells cron to run content generation instead of sending directly
+
+### Changed
+- Seed campaign IDs are now timing-agnostic: `_recurring-sale`, `_recurring-newsletter`
+- Recurrence timing removed from enforced fields — consuming projects can freely change schedule
+- Newsletter subject/preheader are now AI-generated (empty in seed template)
+- Frequent cron skips generator campaigns (handled by daily pre-generation cron)
+- Admin cron route now passes `libraries` to cron handlers
+
 # [5.0.157] - 2026-03-17
 ### Added
 - Campaign template variables via `powertools.template()` — `{brand.name}`, `{season.name}`, `{holiday.name}`, `{date.month}`, `{date.year}`, `{date.full}`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backend-manager",
-  "version": "5.0.157",
+  "version": "5.0.158",
   "description": "Quick tools for developing Firebase functions",
   "main": "src/manager/index.js",
   "bin": {

package/src/cli/commands/setup-tests/helpers/seed-campaigns.js

@@ -9,7 +9,10 @@ const moment = require('moment');
  *   - enforced: Fields that MUST match on every setup run (overwritten if changed)
  *
  * Fields NOT in `enforced` are only set on creation and never touched again,
- * allowing runtime changes (sendAt advances, status changes, content edits).
+ * allowing runtime changes (sendAt advances, recurrence timing, content edits).
+ *
+ * IDs and names are timing-agnostic so consuming projects can change
+ * the recurrence pattern without breaking the ID.
  */
 
 /**
@@ -20,7 +23,6 @@ const moment = require('moment');
 function nextMonthDay(dayOfMonth, hour) {
   const next = moment.utc().startOf('month').date(dayOfMonth).hour(hour);
 
-  // If this month's date has passed, go to next month
   if (next.isBefore(moment.utc())) {
     next.add(1, 'month');
   }
@@ -50,7 +52,7 @@ function buildSeedCampaigns() {
 
   return [
     {
-      id: '_recurring-monthly-sale',
+      id: '_recurring-sale',
       doc: {
         settings: {
           name: '{holiday.name} Sale',
@@ -84,9 +86,6 @@ function buildSeedCampaigns() {
       },
       enforced: {
         'type': 'email',
-        'recurrence.pattern': 'monthly',
-        'recurrence.day': 15,
-        'recurrence.hour': 14,
         'settings.providers': ['sendgrid'],
         'settings.sender': 'marketing',
         'settings.segments': ['subscription_free', 'subscription_cancelled', 'subscription_churned'],
@@ -94,19 +93,20 @@ function buildSeedCampaigns() {
       },
     },
     {
-      id: '_recurring-weekly-newsletter',
+      id: '_recurring-newsletter',
       doc: {
         settings: {
-          name: 'Weekly Newsletter',
-          subject: 'This Week\'s Update',
-          preheader: 'News, tips, and updates',
-          content: '',
+          name: '{brand.name} Newsletter — {date.month} {date.year}',
+          subject: '',   // Generated by AI
+          preheader: '', // Generated by AI
+          content: '',  // Generated at send time by newsletter generator
           sender: 'newsletter',
           providers: ['beehiiv'],
         },
         sendAt: nextWeekday(1, 10),
         status: 'pending',
         type: 'email',
+        generator: 'newsletter',
         recurrence: {
           pattern: 'weekly',
           hour: 10,
@@ -119,9 +119,7 @@ function buildSeedCampaigns() {
       },
       enforced: {
         'type': 'email',
-        'recurrence.pattern': 'weekly',
-        'recurrence.hour': 10,
-        'recurrence.day': 1,
+        'generator': 'newsletter',
         'settings.providers': ['beehiiv'],
         'settings.sender': 'newsletter',
       },

package/src/manager/cron/daily/marketing-newsletter-generate.js

@@ -0,0 +1,118 @@
+/**
+ * Newsletter pre-generation cron job
+ *
+ * Runs daily. Looks for generator campaigns (e.g., _recurring-newsletter)
+ * with sendAt within the next 24 hours. Generates content via AI and creates
+ * a NEW standalone pending campaign with the real content.
+ *
+ * The generated campaign appears on the calendar for review.
+ * The frequent cron picks it up and sends it when sendAt is due.
+ *
+ * After generating, advances the recurring doc's sendAt to the next occurrence.
+ *
+ * Runs on bm_cronDaily.
+ */
+const moment = require('moment');
+const pushid = require('pushid');
+
+// Generator modules — keyed by generator field value
+const generators = {
+  newsletter: require('../../libraries/email/generators/newsletter.js'),
+};
+
+module.exports = async ({ Manager, assistant, libraries }) => {
+  const { admin } = libraries;
+
+  const now = Math.round(Date.now() / 1000);
+  const oneDayFromNow = now + (24 * 60 * 60);
+
+  // Find generator campaigns with sendAt within the next 24 hours
+  const snapshot = await admin.firestore()
+    .collection('marketing-campaigns')
+    .where('status', '==', 'pending')
+    .where('sendAt', '<=', oneDayFromNow)
+    .get();
+
+  // Filter to only generator campaigns (can't query on field existence in Firestore)
+  const generatorDocs = snapshot.docs.filter(doc => doc.data().generator);
+
+  if (!generatorDocs.length) {
+    assistant.log('No generator campaigns due within 24 hours');
+    return;
+  }
+
+  assistant.log(`Pre-generating ${generatorDocs.length} campaign(s)...`);
+
+  for (const doc of generatorDocs) {
+    const data = doc.data();
+    const { settings, type, generator, recurrence } = data;
+    const campaignId = doc.id;
+
+    if (!generators[generator]) {
+      assistant.log(`Unknown generator "${generator}" on ${campaignId}, skipping`);
+      continue;
+    }
+
+    assistant.log(`Generating content for ${campaignId} (${generator}): ${settings.name}`);
+
+    // Run the generator
+    const generated = await generators[generator].generate(Manager, assistant, settings);
+
+    if (!generated) {
+      assistant.log(`Generator "${generator}" returned no content for ${campaignId}, skipping`);
+      continue;
+    }
+
+    // Create a new standalone campaign with the generated content
+    const newId = pushid();
+    const nowISO = new Date().toISOString();
+    const nowUNIX = Math.round(Date.now() / 1000);
+
+    await admin.firestore().doc(`marketing-campaigns/${newId}`).set({
+      settings: generated,
+      type,
+      sendAt: data.sendAt,
+      status: 'pending',
+      generatedFrom: campaignId,
+      metadata: {
+        created: { timestamp: nowISO, timestampUNIX: nowUNIX },
+        updated: { timestamp: nowISO, timestampUNIX: nowUNIX },
+      },
+    });
+
+    assistant.log(`Created campaign ${newId} from generator ${campaignId}: "${generated.subject}"`);
+
+    // Advance the recurring doc's sendAt to the next occurrence
+    if (recurrence) {
+      const nextSendAt = getNextOccurrence(data.sendAt, recurrence);
+
+      await doc.ref.set({
+        sendAt: nextSendAt,
+        metadata: {
+          updated: { timestamp: nowISO, timestampUNIX: nowUNIX },
+        },
+      }, { merge: true });
+
+      assistant.log(`Advanced ${campaignId} sendAt to ${moment.unix(nextSendAt).toISOString()}`);
+    }
+  }
+
+  assistant.log('Pre-generation complete');
+};
+
+/**
+ * Calculate the next occurrence unix timestamp.
+ */
+function getNextOccurrence(currentSendAt, recurrence) {
+  const current = moment.unix(currentSendAt);
+  const { pattern } = recurrence;
+
+  switch (pattern) {
+    case 'daily':     return current.add(1, 'day').unix();
+    case 'weekly':    return current.add(1, 'week').unix();
+    case 'monthly':   return current.add(1, 'month').unix();
+    case 'quarterly': return current.add(3, 'months').unix();
+    case 'yearly':    return current.add(1, 'year').unix();
+    default:          return current.add(1, 'month').unix();
+  }
+}

package/src/manager/cron/frequent/marketing-campaigns.js

@@ -40,11 +40,17 @@ module.exports = async ({ Manager, assistant, libraries }) => {
 
   const results = await Promise.allSettled(snapshot.docs.map(async (doc) => {
     const data = doc.data();
-    const { settings, type, recurrence } = data;
+    let { settings, type, recurrence, generator } = data;
     const campaignId = doc.id;
 
     assistant.log(`Processing campaign ${campaignId} (${type}): ${settings.name}`);
 
+    // --- Generator campaigns are handled by the daily pre-generation cron, not here ---
+    if (generator) {
+      assistant.log(`Skipping generator campaign ${campaignId} — handled by daily pre-generation cron`);
+      return;
+    }
+
     // --- Dispatch by type ---
     let campaignResults;
 

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

@@ -0,0 +1,184 @@
+/**
+ * Newsletter generator — pulls content from parent server and assembles a branded newsletter.
+ *
+ * Called by the marketing-campaigns cron when a campaign has `generator: 'newsletter'`.
+ * Instead of sending the campaign directly, this generates the content first,
+ * then returns the assembled settings for the cron to send.
+ *
+ * Flow:
+ *   1. Read newsletter categories from Manager.config.marketing.newsletter.categories
+ *   2. Fetch ready sources from parent server (GET /newsletter/sources)
+ *   3. AI assembles sources into branded markdown newsletter
+ *   4. Mark sources as used on parent server (PUT /newsletter/sources)
+ *   5. Return assembled settings with content filled in
+ */
+const fetch = require('wonderful-fetch');
+
+/**
+ * Generate newsletter content from parent server sources.
+ *
+ * @param {object} Manager - BEM Manager instance
+ * @param {object} assistant - BEM assistant instance
+ * @param {object} settings - Campaign settings from the recurring template
+ * @returns {object} Updated settings with content filled in, or null if no content available
+ */
+async function generate(Manager, assistant, settings) {
+  const config = Manager.config?.marketing?.newsletter;
+
+  if (!config?.enabled) {
+    assistant.log('Newsletter generator: disabled in config');
+    return null;
+  }
+
+  const categories = config.categories || [];
+
+  if (!categories.length) {
+    assistant.log('Newsletter generator: no categories configured');
+    return null;
+  }
+
+  const parentUrl = Manager.config?.parent?.apiUrl;
+
+  if (!parentUrl) {
+    assistant.log('Newsletter generator: no parent API URL configured');
+    return null;
+  }
+
+  // Fetch and atomically claim sources from parent server
+  const brandId = Manager.config?.brand?.id;
+  const sources = await fetchSources(parentUrl, categories, brandId, assistant);
+
+  if (!sources.length) {
+    assistant.log('Newsletter generator: no sources available');
+    return null;
+  }
+
+  assistant.log(`Newsletter generator: ${sources.length} sources found, assembling...`);
+
+  const brand = Manager.config?.brand;
+
+  // AI assembles sources into newsletter with subject + preheader + content
+  const assembled = await assembleNewsletter(Manager, assistant, sources, brand);
+
+  if (!assembled) {
+    assistant.log('Newsletter generator: AI assembly failed');
+    return null;
+  }
+
+  // Mark sources as used on parent server
+  await claimSources(parentUrl, sources, brand?.id, assistant);
+
+  // Return updated settings — AI-generated fields override template placeholders
+  return {
+    ...settings,
+    subject: assembled.subject,
+    preheader: assembled.preheader,
+    content: assembled.content,
+  };
+}
+
+/**
+ * Fetch ready newsletter sources from the parent server.
+ */
+async function fetchSources(parentUrl, categories, brandId, assistant) {
+  const allSources = [];
+
+  for (const category of categories) {
+    try {
+      const data = await fetch(`${parentUrl}/backend-manager/newsletter/sources`, {
+        method: 'get',
+        response: 'json',
+        timeout: 15000,
+        query: {
+          category,
+          limit: 3,
+          claimFor: brandId,
+          backendManagerKey: process.env.BACKEND_MANAGER_KEY,
+        },
+      });
+
+      if (data.sources?.length) {
+        allSources.push(...data.sources);
+      }
+    } catch (e) {
+      assistant.error(`Newsletter generator: Failed to fetch ${category} sources:`, e.message);
+    }
+  }
+
+  return allSources;
+}
+
+/**
+ * Assemble newsletter sources into a branded newsletter via AI.
+ * Returns { subject, preheader, content } or null on failure.
+ */
+async function assembleNewsletter(Manager, assistant, sources, brand) {
+  const ai = require('../../openai.js');
+
+  const sourceSummaries = sources.map((s, i) =>
+    `[${i + 1}] ${s.ai?.headline || s.subject}\n${s.ai?.summary || ''}\nTakeaways: ${(s.ai?.takeaways || []).join('; ')}`
+  ).join('\n\n');
+
+  try {
+    const result = await ai.request({
+      model: 'gpt-4o-mini',
+      messages: [
+        {
+          role: 'system',
+          content: `You are a newsletter writer for ${brand?.name || 'a tech company'}. ${brand?.description || ''}
+
+Given source articles, write a branded newsletter in markdown. Be concise, engaging, and professional.
+
+Respond in JSON:
+{
+  "subject": "Catchy email subject line (max 60 chars, no emojis)",
+  "preheader": "Preview text that complements the subject (max 100 chars)",
+  "content": "Full newsletter body in markdown with ## section headers"
+}
+
+Guidelines:
+- Start with a brief intro (1-2 sentences)
+- Each source becomes a section with ## header
+- Rewrite in your own voice — don't copy verbatim
+- End with a short sign-off
+- Keep it scannable — use bold, bullets, short paragraphs`,
+        },
+        {
+          role: 'user',
+          content: `Write a newsletter from these ${sources.length} sources:\n\n${sourceSummaries}`,
+        },
+      ],
+      response_format: { type: 'json_object' },
+      apiKey: process.env.BACKEND_MANAGER_OPENAI_API_KEY,
+    });
+
+    return result.content;
+  } catch (e) {
+    assistant.error('Newsletter AI assembly failed:', e.message);
+    return null;
+  }
+}
+
+/**
+ * Mark sources as used on the parent server.
+ */
+async function claimSources(parentUrl, sources, brandId, assistant) {
+  for (const source of sources) {
+    try {
+      await fetch(`${parentUrl}/backend-manager/newsletter/sources`, {
+        method: 'put',
+        response: 'json',
+        timeout: 10000,
+        body: {
+          id: source.id,
+          usedBy: brandId || 'unknown',
+          backendManagerKey: process.env.BACKEND_MANAGER_KEY,
+        },
+      });
+    } catch (e) {
+      assistant.error(`Newsletter generator: Failed to claim source ${source.id}:`, e.message);
+    }
+  }
+}
+
+module.exports = { generate };

package/src/manager/routes/admin/cron/post.js

@@ -24,7 +24,7 @@ module.exports = async ({ assistant, Manager, user, settings, analytics }) => {
   // Run the cron job
   const cronPath = require('path').resolve(__dirname, `../../../cron/${settings.id}.js`);
   const cronHandler = require(cronPath);
-  const result = await cronHandler({ Manager, assistant, context: {} }).catch(e => e);
+  const result = await cronHandler({ Manager, assistant, context: {}, libraries: Manager.libraries }).catch(e => e);
 
   if (result instanceof Error) {
     return assistant.respond(result.message, { code: 500 });

package/templates/backend-manager-config.json

@@ -133,6 +133,10 @@
     prune: {
       enabled: true,
     },
+    newsletter: {
+      enabled: false,
+      categories: [],  // e.g., ['social-media', 'marketing'] — content categories to pull from parent server
+    },
   },
   firebaseConfig: {
     apiKey: '123-456',