backend-manager 5.0.157 → 5.0.159

package/CHANGELOG.md

@@ -14,6 +14,38 @@ 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.159] - 2026-03-18
+### Added
+- Audience-specific email discount codes: `UPGRADE15`, `COMEBACK20`, `MISSYOU25`, `TRYAGAIN10` with eligibility validation per user
+- `{discount.code}` and `{discount.percent}` campaign template variables
+- `test: true` flag on campaign route — sends real Single Send to `test_admin` segment only
+- `test_admin` segment in SSOT (targets `hello@itwcreativeworks.com`)
+- `trial_claimed` custom field (`user_subscription_trial_claimed`) for marketing sync
+- `subscription_churned_paid` and `subscription_churned_trial` segments (replaces `subscription_churned`)
+- 4 audience-specific recurring sale seed campaigns with tailored messaging + discount codes
+- Full marketing campaign system documentation in CLAUDE.md, README.md, and BEM:patterns skill
+
+### Changed
+- Template variable resolution now recursive — walks all string values in settings (future-proof)
+- UTM values resolved through template vars (`{holiday.name}_sale` → `black_friday_sale`)
+- UTM sanitizer strips apostrophes before underscore conversion
+- Payment intent + discount routes now pass user object for discount eligibility checking
+- Discount code `validate()` accepts optional user param for eligibility checks (backwards compatible)
+
+# [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/CLAUDE.md

@@ -1084,6 +1084,141 @@ BEM syncs user data to marketing providers (SendGrid, Beehiiv) as custom fields.
 | SendGrid provisioning | `omega-manager/src/services/sendgrid/ensure/custom-fields.js` |
 | Beehiiv provisioning | `omega-manager/src/services/beehiiv/ensure/custom-fields.js` |
 
+## Marketing Campaign System
+
+### Campaign CRUD Routes (admin-only)
+
+| Method | Endpoint | Purpose |
+|--------|----------|---------|
+| POST | `/marketing/campaign` | Create campaign (immediate or scheduled) |
+| GET | `/marketing/campaign` | List/filter campaigns by date range, status, type |
+| PUT | `/marketing/campaign` | Update pending campaigns (reschedule, edit) |
+| DELETE | `/marketing/campaign` | Delete pending campaigns |
+
+### Firestore Collection: `marketing-campaigns/{id}`
+
+```javascript
+{
+  settings: { name, subject, preheader, content, template, sender, segments, excludeSegments, ... },
+  sendAt: 1743465600,        // Unix timestamp (any format accepted, normalized on create)
+  status: 'pending',         // pending | sent | failed
+  type: 'email',             // email | push
+  recurrence: { pattern, hour, day },  // Optional — makes it recurring
+  generator: 'newsletter',   // Optional — runs content generator before sending
+  recurringId: '_recurring-sale',      // Present on history docs (links to parent template)
+  generatedFrom: '_recurring-newsletter', // Present on generated docs
+  results: { sendgrid: {...}, beehiiv: {...} },
+  metadata: { created: {...}, updated: {...} },
+}
+```
+
+### Campaign Types
+
+- **Email**: dispatches to SendGrid (Single Send) + Beehiiv (Post) via `mailer.sendCampaign()`
+- **Push**: dispatches to FCM via `notification.send()` (shared library)
+- Content is **markdown** — converted to HTML at send time. Template variables resolved before conversion.
+
+### Recurring Campaigns
+
+Campaigns with a `recurrence` field repeat automatically:
+- Cron fires → creates a **history doc** (same collection, `recurringId` set) → advances `sendAt` to next occurrence
+- Status stays `pending` on the recurring template, history docs are `sent`/`failed`
+- `_` prefix on IDs groups them at top of Firestore console
+
+Recurrence patterns: `daily`, `weekly`, `monthly`, `quarterly`, `yearly`
+
+### Generator Campaigns
+
+Campaigns with a `generator` field don't send directly. A daily cron pre-generates content 24 hours before `sendAt`:
+1. Daily cron finds generator campaigns due within 24 hours
+2. Runs the generator module (e.g., `generators/newsletter.js`)
+3. Creates a NEW standalone `pending` campaign with generated content
+4. Advances the recurring template's `sendAt`
+5. Generated campaign appears on calendar for review, sent by frequent cron when due
+
+### Template Variables
+
+Resolved at send time via `powertools.template()`. Single braces `{var}` for campaign-level, double `{{var}}` for SendGrid template-level.
+
+| Variable | Example Output |
+|----------|---------------|
+| `{brand.name}` | Somiibo |
+| `{brand.id}` | somiibo |
+| `{brand.url}` | https://somiibo.com |
+| `{season.name}` | Winter, Spring, Summer, Fall |
+| `{holiday.name}` | Black Friday, Christmas, Valentine's Day, etc. |
+| `{date.month}` | November |
+| `{date.year}` | 2026 |
+| `{date.full}` | March 17, 2026 |
+
+### UTM Auto-Tagging
+
+`libraries/email/utm.js` scans HTML for `<a href>` matching the brand's domain and appends UTM params. Applied to both marketing campaigns and transactional emails.
+
+Defaults: `utm_source=brand.id`, `utm_medium=email`, `utm_campaign=name`, `utm_content=type`. Override via `settings.utm` object.
+
+### Segments SSOT
+
+`SEGMENTS` dictionary in `constants.js` — 22 segment definitions. OMEGA creates them in SendGrid, BEM resolves keys to provider IDs at runtime via `resolveSegmentIds()` (cached).
+
+| Category | Segments |
+|----------|----------|
+| Subscription (9) | `subscription_free`, `subscription_paid`, `subscription_trialing`, `subscription_cancelling`, `subscription_suspended`, `subscription_cancelled`, `subscription_churned`, `subscription_ever_paid`, `subscription_never_paid` |
+| Lifecycle (5) | `lifecycle_7d`, `lifecycle_30d`, `lifecycle_90d`, `lifecycle_6m`, `lifecycle_1y` |
+| Engagement (5) | `engagement_active_30d`, `engagement_active_90d`, `engagement_inactive_90d`, `engagement_inactive_5m`, `engagement_inactive_6m` |
+
+Campaigns reference segments by SSOT key: `segments: ['subscription_free']`. Auto-translated to provider IDs.
+
+### Contact Pruning
+
+`cron/daily/marketing-prune.js` — runs 1st of each month. Two stages:
+1. **Re-engagement**: send email to `engagement_inactive_5m` (excluding `engagement_inactive_6m`)
+2. **Prune**: export `engagement_inactive_6m` contacts, bulk delete from SendGrid + Beehiiv. Never prunes paying customers.
+
+### Newsletter Generator
+
+`generators/newsletter.js` — pulls content from parent server, AI assembles branded newsletter.
+1. Fetch sources: `GET {parentUrl}/newsletter/sources?category=X&claimFor=brandId` (atomic claim)
+2. AI assembly: GPT-4o-mini generates subject, preheader, and markdown content
+3. Mark used: `PUT {parentUrl}/newsletter/sources` per source
+
+### Seed Campaigns
+
+Created by `npx bm setup` (idempotent, enforced fields checked every run):
+
+| ID | Type | Description |
+|----|------|-------------|
+| `_recurring-sale` | email (sendgrid) | Seasonal sale targeting free + cancelled + churned users |
+| `_recurring-newsletter` | email (beehiiv) | AI-generated newsletter from parent server sources |
+
+### Marketing Config
+
+```javascript
+marketing: {
+  sendgrid: { enabled: true },
+  beehiiv: { enabled: false, publicationId: 'pub_xxxxx' },
+  prune: { enabled: true },
+  newsletter: { enabled: false, categories: ['social-media', 'marketing'] },
+}
+```
+
+### Key Marketing Files
+
+| Purpose | File |
+|---------|------|
+| Marketing library | `src/manager/libraries/email/marketing/index.js` |
+| Field + segment SSOT | `src/manager/libraries/email/constants.js` |
+| UTM tagging | `src/manager/libraries/email/utm.js` |
+| Newsletter generator | `src/manager/libraries/email/generators/newsletter.js` |
+| Notification library | `src/manager/libraries/notification.js` |
+| SendGrid provider | `src/manager/libraries/email/providers/sendgrid.js` |
+| Beehiiv provider | `src/manager/libraries/email/providers/beehiiv.js` |
+| Campaign routes | `src/manager/routes/marketing/campaign/{get,post,put,delete}.js` |
+| Campaign cron | `src/manager/cron/frequent/marketing-campaigns.js` |
+| Newsletter pre-gen cron | `src/manager/cron/daily/marketing-newsletter-generate.js` |
+| Pruning cron | `src/manager/cron/daily/marketing-prune.js` |
+| Seed campaigns | `src/cli/commands/setup-tests/helpers/seed-campaigns.js` |
+
 ## Common Mistakes to Avoid
 
 1. **Don't modify Manager internals directly** - Use factory methods and public APIs

package/README.md

@@ -404,6 +404,21 @@ Job.prototype.main = function () {
 module.exports = Job;
 ```
 
+## Marketing & Campaigns
+
+Built-in marketing system with multi-provider support (SendGrid + Beehiiv + FCM push).
+
+- **Contact management** — add, sync, remove contacts across providers with custom field syncing
+- **Campaign CRUD** — `POST/GET/PUT/DELETE /marketing/campaign` with calendar-backed scheduling
+- **Recurring campaigns** — seasonal sales, newsletters with automatic sendAt advancement
+- **Newsletter generator** — AI-assembled newsletters from parent server content sources
+- **Segment SSOT** — 22 segment definitions resolved to provider IDs at runtime
+- **UTM auto-tagging** — brand domain links tagged automatically in marketing + transactional emails
+- **Contact pruning** — monthly 2-stage re-engagement + deletion of inactive contacts
+- **Template variables** — `{brand.name}`, `{holiday.name}`, `{season.name}`, `{date.*}` resolved at send time
+
+Configure via `marketing` section in `backend-manager-config.json`. See CLAUDE.md for full documentation.
+
 ## Helper Classes
 
 ### Assistant

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backend-manager",
-  "version": "5.0.157",
+  "version": "5.0.159",
   "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');
   }
@@ -49,34 +51,117 @@ function buildSeedCampaigns() {
   const nowUNIX = now.unix();
 
   return [
+    // --- Seasonal sale campaigns (one per audience segment) ---
     {
-      id: '_recurring-monthly-sale',
+      id: '_recurring-sale-free',
       doc: {
         settings: {
-          name: '{holiday.name} Sale',
-          subject: '{holiday.name} Sale — Upgrade & Save!',
+          name: '{holiday.name} Sale — Free Users',
+          subject: '{holiday.name} Sale — {discount.percent}% Off!',
           preheader: 'Limited time offer from {brand.name}',
+          discountCode: 'UPGRADE15',
           content: [
             '# {holiday.name} Sale',
             '',
-            'For a limited time, upgrade your **{brand.name}** plan and save big.',
+            'You\'ve been using **{brand.name}** on our free plan — and we think you\'ll love what\'s on the other side.',
+            '',
+            'For a limited time, upgrade to Premium and get **{discount.percent}% off** your first month.',
             '',
-            'Don\'t miss out — this offer ends soon!',
+            'Use code **{discount.code}** at checkout.',
           ].join('\n'),
           template: 'default',
           sender: 'marketing',
           providers: ['sendgrid'],
-          segments: ['subscription_free', 'subscription_cancelled', 'subscription_churned'],
+          segments: ['subscription_free'],
           excludeSegments: ['subscription_paid'],
+          utm: { utm_campaign: '{holiday.name}_sale', utm_content: 'free_users' },
         },
         sendAt: nextMonthDay(15, 14),
         status: 'pending',
         type: 'email',
-        recurrence: {
-          pattern: 'monthly',
-          day: 15,
-          hour: 14,
+        recurrence: { pattern: 'monthly', day: 15, hour: 14 },
+        metadata: {
+          created: { timestamp: nowISO, timestampUNIX: nowUNIX },
+          updated: { timestamp: nowISO, timestampUNIX: nowUNIX },
+        },
+      },
+      enforced: {
+        'type': 'email',
+        'settings.providers': ['sendgrid'],
+        'settings.sender': 'marketing',
+        'settings.segments': ['subscription_free'],
+        'settings.excludeSegments': ['subscription_paid'],
+      },
+    },
+    {
+      id: '_recurring-sale-churned-trial',
+      doc: {
+        settings: {
+          name: '{holiday.name} Sale — Churned Trial',
+          subject: 'Your trial ended — come back for {discount.percent}% off!',
+          preheader: 'We saved your spot at {brand.name}',
+          discountCode: 'FLASH20',
+          content: [
+            '# Come Back to {brand.name}',
+            '',
+            'Your free trial may have ended, but we haven\'t forgotten about you.',
+            '',
+            'For our **{holiday.name}** offer, get **{discount.percent}% off** your first month of Premium.',
+            '',
+            'Use code **{discount.code}** at checkout.',
+          ].join('\n'),
+          template: 'default',
+          sender: 'marketing',
+          providers: ['sendgrid'],
+          segments: ['subscription_churned_trial'],
+          excludeSegments: ['subscription_paid'],
+          utm: { utm_campaign: '{holiday.name}_sale', utm_content: 'churned_trial' },
+        },
+        sendAt: nextMonthDay(15, 14),
+        status: 'pending',
+        type: 'email',
+        recurrence: { pattern: 'monthly', day: 15, hour: 14 },
+        metadata: {
+          created: { timestamp: nowISO, timestampUNIX: nowUNIX },
+          updated: { timestamp: nowISO, timestampUNIX: nowUNIX },
+        },
+      },
+      enforced: {
+        'type': 'email',
+        'settings.providers': ['sendgrid'],
+        'settings.sender': 'marketing',
+        'settings.segments': ['subscription_churned_trial'],
+        'settings.excludeSegments': ['subscription_paid'],
+      },
+    },
+    {
+      id: '_recurring-sale-churned-paid',
+      doc: {
+        settings: {
+          name: '{holiday.name} Sale — Churned Paid',
+          subject: 'We miss you — here\'s {discount.percent}% off to come back',
+          preheader: '{holiday.name} offer from {brand.name}',
+          discountCode: 'MISSYOU25',
+          content: [
+            '# We Miss You at {brand.name}',
+            '',
+            'It\'s been a while since you cancelled, and a lot has changed.',
+            '',
+            'For our **{holiday.name}** offer, get **{discount.percent}% off** your next month.',
+            '',
+            'Use code **{discount.code}** at checkout.',
+          ].join('\n'),
+          template: 'default',
+          sender: 'marketing',
+          providers: ['sendgrid'],
+          segments: ['subscription_churned_paid'],
+          excludeSegments: ['subscription_paid'],
+          utm: { utm_campaign: '{holiday.name}_sale', utm_content: 'churned_paid' },
         },
+        sendAt: nextMonthDay(15, 14),
+        status: 'pending',
+        type: 'email',
+        recurrence: { pattern: 'monthly', day: 15, hour: 14 },
         metadata: {
           created: { timestamp: nowISO, timestampUNIX: nowUNIX },
           updated: { timestamp: nowISO, timestampUNIX: nowUNIX },
@@ -84,29 +169,69 @@ 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'],
+        'settings.segments': ['subscription_churned_paid'],
         'settings.excludeSegments': ['subscription_paid'],
       },
     },
     {
-      id: '_recurring-weekly-newsletter',
+      id: '_recurring-sale-cancelled',
+      doc: {
+        settings: {
+          name: '{holiday.name} Sale — Cancelled',
+          subject: 'Ready to give {brand.name} another try?',
+          preheader: '{holiday.name} offer — {discount.percent}% off',
+          discountCode: 'TRYAGAIN10',
+          content: [
+            '# Give {brand.name} Another Try',
+            '',
+            'We know things didn\'t work out before, and that\'s okay.',
+            '',
+            'For our **{holiday.name}** offer, get **{discount.percent}% off** your first month back.',
+            '',
+            'Use code **{discount.code}** at checkout. No pressure — just an open door.',
+          ].join('\n'),
+          template: 'default',
+          sender: 'marketing',
+          providers: ['sendgrid'],
+          segments: ['subscription_cancelled'],
+          excludeSegments: ['subscription_paid', 'subscription_churned_paid', 'subscription_churned_trial'],
+          utm: { utm_campaign: '{holiday.name}_sale', utm_content: 'cancelled' },
+        },
+        sendAt: nextMonthDay(15, 14),
+        status: 'pending',
+        type: 'email',
+        recurrence: { pattern: 'monthly', day: 15, hour: 14 },
+        metadata: {
+          created: { timestamp: nowISO, timestampUNIX: nowUNIX },
+          updated: { timestamp: nowISO, timestampUNIX: nowUNIX },
+        },
+      },
+      enforced: {
+        'type': 'email',
+        'settings.providers': ['sendgrid'],
+        'settings.sender': 'marketing',
+        'settings.segments': ['subscription_cancelled'],
+        'settings.excludeSegments': ['subscription_paid', 'subscription_churned_paid', 'subscription_churned_trial'],
+      },
+    },
+    {
+      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'],
+          utm: { utm_campaign: 'newsletter_{date.month}_{date.year}', utm_content: 'newsletter' },
         },
         sendAt: nextWeekday(1, 10),
         status: 'pending',
         type: 'email',
+        generator: 'newsletter',
         recurrence: {
           pattern: 'weekly',
           hour: 10,
@@ -119,9 +244,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/constants.js

@@ -159,6 +159,7 @@ const FIELDS = {
   user_subscription_plan:                { display: 'Plan', source: 'resolved', path: 'plan', type: 'text' },
   user_subscription_status:              { display: 'Status', source: 'resolved', path: 'status', type: 'text' },
   user_subscription_trialing:            { display: 'Trialing', source: 'resolved', path: 'trialing', type: 'text' },
+  user_subscription_trial_claimed:       { display: 'Trial Claimed', source: 'user', path: 'subscription.trial.claimed', type: 'text' },
   user_subscription_cancelling:          { display: 'Cancelling', source: 'resolved', path: 'cancelling', type: 'text' },
   user_subscription_ever_paid:           { display: 'Ever Paid', source: 'resolved', path: 'everPaid', type: 'text' },
   user_subscription_payment_processor:   { display: 'Payment Processor', source: 'user', path: 'subscription.payment.processor', type: 'text' },
@@ -195,7 +196,8 @@ const SEGMENTS = {
   subscription_cancelling:    { display: 'Cancelling', conditions: [{ field: 'user_subscription_cancelling', op: '==', value: 'true' }] },
   subscription_suspended:     { display: 'Suspended', conditions: [{ field: 'user_subscription_status', op: '==', value: 'suspended' }] },
   subscription_cancelled:     { display: 'Cancelled', conditions: [{ field: 'user_subscription_status', op: '==', value: 'cancelled' }] },
-  subscription_churned:       { display: 'Churned (Paid → Cancelled)', conditions: [{ field: 'user_subscription_ever_paid', op: '==', value: 'true' }, { field: 'user_subscription_status', op: '==', value: 'cancelled' }] },
+  subscription_churned_paid:  { display: 'Churned Paid (Paid → Cancelled)', conditions: [{ field: 'user_subscription_ever_paid', op: '==', value: 'true' }, { field: 'user_subscription_status', op: '==', value: 'cancelled' }] },
+  subscription_churned_trial: { display: 'Churned Trial (Trial → Never Paid)', conditions: [{ field: 'user_subscription_trial_claimed', op: '==', value: 'true' }, { field: 'user_subscription_ever_paid', op: '!=', value: 'true' }] },
   subscription_ever_paid:     { display: 'Ever Paid', conditions: [{ field: 'user_subscription_ever_paid', op: '==', value: 'true' }] },
   subscription_never_paid:    { display: 'Never Paid', conditions: [{ field: 'user_subscription_ever_paid', op: '!=', value: 'true' }] },
 
@@ -212,6 +214,9 @@ const SEGMENTS = {
   engagement_inactive_90d:    { display: 'Inactive 90+ Days', conditions: [{ type: 'engagement', op: 'not_opened', value: '90d' }] },
   engagement_inactive_5m:     { display: 'Inactive 5+ Months', conditions: [{ type: 'engagement', op: 'not_opened', value: '150d' }] },
   engagement_inactive_6m:     { display: 'Inactive 6+ Months', conditions: [{ type: 'engagement', op: 'not_opened', value: '180d' }] },
+
+  // Test
+  test_admin:                 { display: 'Test Admin', conditions: [{ type: 'contact', op: 'email_is', value: 'hello@itwcreativeworks.com' }] },
 };
 
 /**

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/libraries/email/marketing/index.js

@@ -271,19 +271,26 @@ Marketing.prototype.sendCampaign = async function (settings) {
   const results = {};
   const promises = [];
 
-  // Resolve campaign-level variables: {brand.name}, {season}, {year}, etc.
-  // Uses single braces via powertools.template() — distinct from {{template}} vars handled by SendGrid
+  // Resolve campaign-level variables: {brand.name}, {season.name}, {holiday.name}, {date.*}, {discount.*}
+  // Walks all string values in settings and resolves single-brace vars via powertools.template()
+  // Double braces {{var}} are left untouched for SendGrid template-level resolution
   const brand = Manager.config?.brand;
-  const templateContext = buildTemplateContext(brand);
-  const template = require('node-powertools').template;
+  const templateContext = buildTemplateContext(brand, settings);
+  let resolvedSettings = resolveTemplateVars(settings, templateContext);
 
-  const resolvedSettings = {
-    ...settings,
-    name: template(settings.name || '', templateContext),
-    subject: template(settings.subject || '', templateContext),
-    preheader: template(settings.preheader || '', templateContext),
-    content: template(settings.content || '', templateContext),
-  };
+  // Test mode: real Single Send / Beehiiv Post, but targeted only to test_admin segment
+  if (settings.test) {
+    assistant.log('Marketing.sendCampaign(): TEST MODE — targeting test_admin segment only');
+
+    resolvedSettings = {
+      ...resolvedSettings,
+      name: `[TEST] ${resolvedSettings.name}`,
+      segments: ['test_admin'],
+      excludeSegments: [],
+      lists: [],
+      all: false,
+    };
+  }
 
   // Convert markdown content to HTML, then tag links with UTM params
   let contentHtml = resolvedSettings.content ? md.render(resolvedSettings.content) : '';
@@ -292,9 +299,9 @@ Marketing.prototype.sendCampaign = async function (settings) {
     contentHtml = tagLinks(contentHtml, {
       brandUrl: brand?.url,
       brandId: brand?.id,
-      campaign: settings.name,
+      campaign: resolvedSettings.name,
       type: 'marketing',
-      utm: settings.utm,
+      utm: resolvedSettings.utm,
     });
   }
 
@@ -521,10 +528,17 @@ const MONTH_NAMES = [
  *   {date.year}      — 2026
  *   {date.full}      — March 17, 2026
  */
-function buildTemplateContext(brand) {
+function buildTemplateContext(brand, settings) {
   const now = new Date();
   const month = now.getMonth();
 
+  // Resolve discount code if provided in settings
+  const discountCodes = require('../../payment/discount-codes.js');
+  const discountCode = settings?.discountCode;
+  const discount = discountCode
+    ? discountCodes.validate(discountCode)
+    : { code: '', percent: '' };
+
   return {
     brand: brand || {},
     season: {
@@ -538,7 +552,45 @@ function buildTemplateContext(brand) {
       year: String(now.getFullYear()),
       full: now.toLocaleDateString('en-US', { month: 'long', day: 'numeric', year: 'numeric' }),
     },
+    discount: {
+      code: discount.code || '',
+      percent: discount.percent || '',
+    },
   };
 }
 
+/**
+ * Recursively walk an object and resolve {template} variables in all string values.
+ * Arrays and nested objects are walked. Non-string values are passed through.
+ */
+function resolveTemplateVars(obj, context) {
+  const template = require('node-powertools').template;
+
+  if (typeof obj === 'string') {
+    if (!obj.includes('{')) {
+      return obj;
+    }
+
+    // Resolve, then replace any "null" or "undefined" leftovers with empty string
+    const resolved = template(obj, context);
+    return resolved.replace(/\bnull\b|\bundefined\b/g, '').replace(/\s{2,}/g, ' ').trim();
+  }
+
+  if (Array.isArray(obj)) {
+    return obj.map(item => resolveTemplateVars(item, context));
+  }
+
+  if (obj && typeof obj === 'object') {
+    const result = {};
+
+    for (const [key, value] of Object.entries(obj)) {
+      result[key] = resolveTemplateVars(value, context);
+    }
+
+    return result;
+  }
+
+  return obj;
+}
+
 module.exports = Marketing;

package/src/manager/libraries/email/utm.js

@@ -46,12 +46,12 @@ function tagLinks(html, options) {
     ...options.utm,
   };
 
-  // Remove null/undefined values
+  // Remove null/undefined values and sanitize: lowercase, non-alphanumeric → underscore
   const utmParams = {};
 
   for (const [key, value] of Object.entries(utm)) {
     if (value != null && value !== '') {
-      utmParams[key] = String(value);
+      utmParams[key] = String(value).toLowerCase().replace(/[''`]/g, '').replace(/[^a-z0-9]/g, '_').replace(/_+/g, '_').replace(/^_|_$/g, '');
     }
   }
 

package/src/manager/libraries/payment/discount-codes.js

@@ -1,22 +1,64 @@
 /**
- * Discount codes — hardcoded for now, move to Firestore/config later
+ * Discount codes — SSOT for all promo codes
  *
  * Each code maps to a discount definition:
  *   - percent: Percentage off (1-100)
  *   - duration: 'once' (first payment only)
+ *   - eligible: Optional function (user) => boolean. If present, the code is only
+ *     valid for users who pass this check. Receives the raw user doc or User instance.
+ *     If omitted, the code is valid for everyone.
  */
+const User = require('../../helpers/user.js');
+
 const DISCOUNT_CODES = {
-  'FLASH20': { percent: 20, duration: 'once' },
-  'SAVE10': { percent: 10, duration: 'once' },
+  // Website (displayed on pricing page, landing pages — no eligibility restrictions)
   'WELCOME15': { percent: 15, duration: 'once' },
+  'SAVE10': { percent: 10, duration: 'once' },
+  'FLASH20': { percent: 20, duration: 'once' },
+
+  // Email campaigns (used by recurring sale seeds — restricted by audience)
+  'UPGRADE15': {
+    percent: 15,
+    duration: 'once',
+    eligible: (user) => {
+      const sub = User.resolveSubscription(user);
+      return sub.plan === 'basic';
+    },
+  },
+  'COMEBACK20': {
+    percent: 20,
+    duration: 'once',
+    eligible: (user) => {
+      const sub = User.resolveSubscription(user);
+      return sub.plan === 'basic' && user.subscription?.trial?.claimed === true;
+    },
+  },
+  'MISSYOU25': {
+    percent: 25,
+    duration: 'once',
+    eligible: (user) => {
+      const sub = User.resolveSubscription(user);
+      return sub.everPaid && user.subscription?.status === 'cancelled';
+    },
+  },
+  'TRYAGAIN10': {
+    percent: 10,
+    duration: 'once',
+    eligible: (user) => {
+      return user.subscription?.status === 'cancelled';
+    },
+  },
 };
 
 /**
- * Validate a discount code
+ * Validate a discount code, optionally checking user eligibility.
+ *
  * @param {string} code - The discount code (case-insensitive)
- * @returns {{ valid: boolean, code: string, percent: number, duration: string } | { valid: boolean, code: string }}
+ * @param {object} [user] - User doc or User instance. If provided and the code has
+ *   an eligible() function, eligibility is checked. If not provided, eligibility is skipped.
+ * @returns {{ valid: boolean, code: string, percent?: number, duration?: string, reason?: string }}
  */
-function validate(code) {
+function validate(code, user) {
   const normalized = (code || '').trim().toUpperCase();
 
   if (!normalized) {
@@ -29,6 +71,16 @@ function validate(code) {
     return { valid: false, code: normalized };
   }
 
+  // Check eligibility if user is provided and code has a restriction
+  if (user && entry.eligible) {
+    // Support both raw user doc and User instance (check .properties for User instance)
+    const userDoc = user.properties || user;
+
+    if (!entry.eligible(userDoc)) {
+      return { valid: false, code: normalized, reason: 'not eligible' };
+    }
+  }
+
   return {
     valid: true,
     code: normalized,

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/src/manager/routes/payments/discount/get.js

@@ -4,8 +4,8 @@
  */
 const discountCodes = require('../../../libraries/payment/discount-codes.js');
 
-module.exports = async ({ assistant, settings }) => {
-  const result = discountCodes.validate(settings.code);
+module.exports = async ({ assistant, user, settings }) => {
+  const result = discountCodes.validate(settings.code, user.authenticated ? user : undefined);
 
   assistant.log(`Discount validation: code=${result.code}, valid=${result.valid}`);
 

package/src/manager/routes/payments/intent/post.js

@@ -83,7 +83,7 @@ module.exports = async ({ assistant, Manager, user, settings, libraries }) => {
   // Validate discount code (if provided)
   let resolvedDiscount = null;
   if (discount) {
-    const discountResult = discountCodes.validate(discount);
+    const discountResult = discountCodes.validate(discount, user);
     if (!discountResult.valid) {
       return assistant.respond(`Invalid discount code: ${discount}`, { code: 400 });
     }

package/src/manager/schemas/marketing/campaign/post.js

@@ -28,6 +28,8 @@ module.exports = () => ({
   utm: { types: ['object'], default: {} },
 
   // Config
+  test: { types: ['boolean'], default: false },
+  discountCode: { types: ['string'], default: '' },
   sender: { types: ['string'], default: 'marketing' },
   providers: { types: ['array'], default: [] },
   group: { types: ['string'], default: '' },

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',