backend-manager 5.0.158 → 5.0.160

package/CHANGELOG.md

@@ -14,6 +14,32 @@ 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.160] - 2026-03-18
+### Added
+- Beehiiv `resolveSegmentIds()` — fetches segments from API, builds name→ID cache (same pattern as SendGrid)
+- Beehiiv segment resolution in `sendCampaign()` — SSOT keys auto-translate to Beehiiv segment IDs
+
+### Changed
+- Beehiiv `createPost()` now receives resolved segment IDs instead of raw SSOT keys
+
+# [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

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.158",
+  "version": "5.0.160",
   "description": "Quick tools for developing Firebase functions",
   "main": "src/manager/index.js",
   "bin": {

package/src/cli/commands/serve.js

@@ -11,6 +11,12 @@ class ServeCommand extends BaseCommand {
     const port = self.argv.port || self.argv?._?.[1] || '5000';
     const projectDir = self.firebaseProjectPath;
 
+    // Check for port conflicts before starting server
+    const canProceed = await this.checkAndKillBlockingProcesses({ serving: parseInt(port, 10) });
+    if (!canProceed) {
+      throw new Error('Port conflicts could not be resolved');
+    }
+
     // Start BEM watcher in background
     const watcher = new WatchCommand(self);
     watcher.startBackground();

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

@@ -51,34 +51,76 @@ function buildSeedCampaigns() {
   const nowUNIX = now.unix();
 
   return [
+    // --- Seasonal sale campaigns (one per audience segment) ---
     {
-      id: '_recurring-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.',
             '',
-            'Don\'t miss out — this offer ends soon!',
+            'For a limited time, upgrade to Premium and get **{discount.percent}% off** your first month.',
+            '',
+            '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 },
@@ -88,10 +130,92 @@ function buildSeedCampaigns() {
         'type': 'email',
         'settings.providers': ['sendgrid'],
         'settings.sender': 'marketing',
-        'settings.segments': ['subscription_free', 'subscription_cancelled', 'subscription_churned'],
+        '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 },
+        },
+      },
+      enforced: {
+        'type': 'email',
+        'settings.providers': ['sendgrid'],
+        'settings.sender': 'marketing',
+        'settings.segments': ['subscription_churned_paid'],
+        'settings.excludeSegments': ['subscription_paid'],
+      },
+    },
+    {
+      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: {
@@ -102,6 +226,7 @@ function buildSeedCampaigns() {
           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',

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/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,
     });
   }
 
@@ -310,7 +317,14 @@ Marketing.prototype.sendCampaign = async function (settings) {
     };
   }
 
-  // Beehiiv: segment resolution will go here when Beehiiv segments are supported
+  if (useProviders.includes('beehiiv') && self.providers.beehiiv) {
+    const segmentIdMap = await beehiivProvider.resolveSegmentIds();
+
+    resolvedSegments.beehiiv = {
+      segments: (resolvedSettings.segments || []).map(key => segmentIdMap[key] || key).filter(Boolean),
+      excludeSegments: (resolvedSettings.excludeSegments || []).map(key => segmentIdMap[key] || key).filter(Boolean),
+    };
+  }
 
   assistant.log('Marketing.sendCampaign():', {
     name: resolvedSettings.name,
@@ -342,8 +356,8 @@ Marketing.prototype.sendCampaign = async function (settings) {
         preheader: resolvedSettings.preheader,
         content: contentHtml,
         sendAt: settings.sendAt,
-        segments: settings.segments,
-        excludeSegments: settings.excludeSegments,
+        segments: resolvedSegments.beehiiv?.segments || [],
+        excludeSegments: resolvedSegments.beehiiv?.excludeSegments || [],
       })
         .then((r) => { results.beehiiv = r; })
         .catch((e) => { results.beehiiv = { success: false, error: e.message }; })
@@ -521,10 +535,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 +559,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/providers/beehiiv.js

@@ -274,6 +274,47 @@ function buildFields(userDoc) {
   return fields;
 }
 
+// Cached segment name → Beehiiv segment ID map
+let _segmentIdCache = null;
+
+/**
+ * Fetch segment definitions from Beehiiv and build a name → id map.
+ * Segments are created by OMEGA with names matching the SSOT keys in constants.js.
+ * Cached in memory for the lifetime of the process.
+ *
+ * @returns {object} Map of segment name → Beehiiv segment ID
+ */
+async function resolveSegmentIds() {
+  if (_segmentIdCache) {
+    return _segmentIdCache;
+  }
+
+  const publicationId = await getPublicationId();
+
+  if (!publicationId) {
+    return {};
+  }
+
+  try {
+    const data = await fetch(`${BASE_URL}/publications/${publicationId}/segments?limit=100`, {
+      response: 'json',
+      headers: headers(),
+      timeout: 10000,
+    });
+
+    _segmentIdCache = {};
+
+    for (const segment of (data.data || [])) {
+      _segmentIdCache[segment.name] = segment.id;
+    }
+
+    return _segmentIdCache;
+  } catch (e) {
+    console.error('Beehiiv resolveSegmentIds error:', e);
+    return {};
+  }
+}
+
 // --- Campaigns (Posts) ---
 
 /**
@@ -362,6 +403,9 @@ async function createPost(options) {
 }
 
 module.exports = {
+  // Resolution
+  resolveSegmentIds,
+
   // Contacts
   addContact,
   removeContact,

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/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: '' },