backend-manager 5.0.154 → 5.0.156

package/CHANGELOG.md

@@ -14,6 +14,33 @@ 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.156] - 2026-03-17
+### Added
+- Marketing campaign system with full CRUD routes (`POST/GET/PUT/DELETE /marketing/campaign`)
+- Calendar-backed scheduling: campaigns stored in `marketing-campaigns` Firestore collection, picked up by `bm_cronFrequent`
+- Multi-provider campaign dispatch: SendGrid (Single Send) + Beehiiv (Post) + Push (FCM)
+- Recurring campaigns with `recurrence` field — cron creates history docs and advances `sendAt`
+- Markdown → HTML conversion at send time for campaign content
+- UTM auto-tagging on brand domain links for both marketing and transactional emails (`libraries/email/utm.js`)
+- Shared notification library (`libraries/notification.js`) extracted from admin route
+- SEGMENTS SSOT dictionary in `constants.js` — 22 segments (subscription, lifecycle, engagement)
+- Runtime segment ID resolution: `resolveSegmentIds()` maps SSOT keys to SendGrid segment IDs
+- Contact pruning cron (`cron/daily/marketing-prune.js`) — monthly re-engagement + deletion of inactive contacts
+- SendGrid `getSegmentContacts()` and `bulkDeleteContacts()` for segment export + batch deletion
+- Seed campaigns via `npx bm setup`: `_recurring-quarterly-sale` (SendGrid) and `_recurring-weekly-newsletter` (Beehiiv) with enforced fields
+- `marketing.prune.enabled` config option (default: true)
+- Provider name extraction from OAuth on signup (Google, Facebook, etc.)
+- Personalized greetings in welcome, checkup, deletion, and data request emails
+
+### Changed
+- `sendCampaign()` refactored for multi-provider dispatch with automatic SSOT segment key → provider ID translation
+- `POST /admin/notification` slimmed down to use shared notification library
+- Setup test data files (`required-indexes.js`, `seed-campaigns.js`) moved to `helpers/` directory
+
+# [5.0.155] - 2026-03-16
+### Added
+- Setup test now ensures consuming project `functions/package.json` has `"private": true` to prevent accidental npm publish
+
 # [5.0.154] - 2026-03-16
 ### Changed
 - Add `display` property to all marketing FIELDS entries so display names are defined in the SSOT

package/CLAUDE.md

@@ -1102,7 +1102,7 @@ BEM syncs user data to marketing providers (SendGrid, Beehiiv) as custom fields.
 
 8. **Increment usage before update** - Call `usage.increment()` then `usage.update()`
 
-9. **Add Firestore composite indexes for new compound queries** - Any new Firestore query using multiple `.where()` clauses or `.where()` + `.orderBy()` requires a composite index. Add it to `src/cli/commands/setup-tests/required-indexes.js` (the SSOT). Consumer projects pick these up via `npx bm setup`, which syncs them into `firestore.indexes.json`. Without the index, the query will crash with `FAILED_PRECONDITION` in production.
+9. **Add Firestore composite indexes for new compound queries** - Any new Firestore query using multiple `.where()` clauses or `.where()` + `.orderBy()` requires a composite index. Add it to `src/cli/commands/setup-tests/helpers/required-indexes.js` (the SSOT). Consumer projects pick these up via `npx bm setup`, which syncs them into `firestore.indexes.json`. Without the index, the query will crash with `FAILED_PRECONDITION` in production.
 
 ## Key Files Reference
 
@@ -1132,7 +1132,7 @@ BEM syncs user data to marketing providers (SendGrid, Beehiiv) as custom fields.
 | Stripe library | `src/manager/libraries/payment/processors/stripe.js` |
 | PayPal library | `src/manager/libraries/payment/processors/paypal.js` |
 | Order ID generator | `src/manager/libraries/payment/order-id.js` |
-| Required Firestore indexes (SSOT) | `src/cli/commands/setup-tests/required-indexes.js` |
+| Required Firestore indexes (SSOT) | `src/cli/commands/setup-tests/helpers/required-indexes.js` |
 | Test accounts | `src/test/test-accounts.js` |
 
 ## Environment Detection

package/package.json

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

package/src/cli/commands/setup-tests/firestore-indexes-required.js

@@ -2,7 +2,7 @@ const BaseTest = require('./base-test');
 const jetpack = require('fs-jetpack');
 const _ = require('lodash');
 const chalk = require('chalk');
-const requiredIndexes = require('./required-indexes');
+const requiredIndexes = require('./helpers/required-indexes');
 
 class FirestoreIndexesRequiredTest extends BaseTest {
   getName() {

package/src/cli/commands/setup-tests/functions-package.js

@@ -10,13 +10,15 @@ class FunctionsPackageTest extends BaseTest {
     return !!this.context.package
       && !!this.context.package.dependencies
       && !!this.context.package.devDependencies
-      && !!this.context.package.version;
+      && !!this.context.package.version
+      && this.context.package.private === true;
   }
 
   async fix() {
     this.context.package.dependencies = this.context.package.dependencies || {};
     this.context.package.devDependencies = this.context.package.devDependencies || {};
     this.context.package.version = this.context.package.version || '0.0.1';
+    this.context.package.private = true;
 
     jetpack.write(`${this.self.firebaseProjectPath}/functions/package.json`, JSON.stringify(this.context.package, null, 2));
   }

package/src/cli/commands/setup-tests/{required-indexes.js → helpers/required-indexes.js}

@@ -46,4 +46,26 @@ module.exports = [
       { fieldPath: 'nextReminderAt', order: 'ASCENDING' },
     ],
   },
+
+  // Marketing campaigns cron — find pending campaigns ready to send
+  // Query: .where('status', '==', 'pending').where('sendAt', '<=', now)
+  {
+    collectionGroup: 'marketing-campaigns',
+    queryScope: 'COLLECTION',
+    fields: [
+      { fieldPath: 'status', order: 'ASCENDING' },
+      { fieldPath: 'sendAt', order: 'ASCENDING' },
+    ],
+  },
+
+  // GET /marketing/campaign — list by type + sendAt range
+  // Query: .where('type', '==', type).where('sendAt', '>=', start).where('sendAt', '<=', end)
+  {
+    collectionGroup: 'marketing-campaigns',
+    queryScope: 'COLLECTION',
+    fields: [
+      { fieldPath: 'type', order: 'ASCENDING' },
+      { fieldPath: 'sendAt', order: 'ASCENDING' },
+    ],
+  },
 ];

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

@@ -0,0 +1,136 @@
+const moment = require('moment');
+
+/**
+ * Seed marketing campaigns — recurring templates created/enforced on setup.
+ *
+ * Each seed defines:
+ *   - id: Stable Firestore doc ID (prefixed with _ for grouping)
+ *   - doc: Full document for initial creation
+ *   - 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).
+ */
+
+/**
+ * Get the next occurrence of a quarterly date from now.
+ * Quarters: Jan 1, Apr 1, Jul 1, Oct 1.
+ */
+function nextQuarter(hour) {
+  const now = moment.utc();
+  const quarters = [
+    moment.utc({ month: 0, day: 1, hour }),
+    moment.utc({ month: 3, day: 1, hour }),
+    moment.utc({ month: 6, day: 1, hour }),
+    moment.utc({ month: 9, day: 1, hour }),
+  ];
+
+  for (const q of quarters) {
+    if (q.year(now.year()).isAfter(now)) {
+      return q.year(now.year()).unix();
+    }
+  }
+
+  return quarters[0].year(now.year() + 1).unix();
+}
+
+/**
+ * Get the next occurrence of a specific weekday.
+ * @param {number} dayOfWeek - 0=Sunday, 1=Monday, ..., 6=Saturday
+ * @param {number} hour - Hour (UTC)
+ */
+function nextWeekday(dayOfWeek, hour) {
+  const next = moment.utc().startOf('day').hour(hour);
+
+  while (next.day() !== dayOfWeek || next.isBefore(moment.utc())) {
+    next.add(1, 'day');
+  }
+
+  return next.unix();
+}
+
+function buildSeedCampaigns() {
+  const now = moment.utc();
+  const nowISO = now.toISOString();
+  const nowUNIX = now.unix();
+
+  return [
+    {
+      id: '_recurring-quarterly-sale',
+      doc: {
+        settings: {
+          name: 'Quarterly Sale',
+          subject: 'Limited Time — Upgrade & Save!',
+          preheader: 'Our biggest discount this quarter',
+          content: [
+            '# Quarterly Sale',
+            '',
+            'For a limited time, upgrade your plan and save big.',
+            '',
+            'Don\'t miss out — this offer ends soon!',
+          ].join('\n'),
+          template: 'default',
+          sender: 'marketing',
+          providers: ['sendgrid'],
+          segments: ['subscription_free'],
+          excludeSegments: [],
+        },
+        sendAt: nextQuarter(14),
+        status: 'pending',
+        type: 'email',
+        recurrence: {
+          pattern: 'quarterly',
+          hour: 14,
+        },
+        metadata: {
+          created: { timestamp: nowISO, timestampUNIX: nowUNIX },
+          updated: { timestamp: nowISO, timestampUNIX: nowUNIX },
+        },
+      },
+      // Fields enforced on every setup run (deep path → value)
+      enforced: {
+        'type': 'email',
+        'recurrence.pattern': 'quarterly',
+        'recurrence.hour': 14,
+        'settings.providers': ['sendgrid'],
+        'settings.sender': 'marketing',
+        'settings.segments': ['subscription_free'],
+      },
+    },
+    {
+      id: '_recurring-weekly-newsletter',
+      doc: {
+        settings: {
+          name: 'Weekly Newsletter',
+          subject: 'This Week\'s Update',
+          preheader: 'News, tips, and updates',
+          content: '',
+          sender: 'newsletter',
+          providers: ['beehiiv'],
+        },
+        sendAt: nextWeekday(1, 10),
+        status: 'pending',
+        type: 'email',
+        recurrence: {
+          pattern: 'weekly',
+          hour: 10,
+          day: 1,
+        },
+        metadata: {
+          created: { timestamp: nowISO, timestampUNIX: nowUNIX },
+          updated: { timestamp: nowISO, timestampUNIX: nowUNIX },
+        },
+      },
+      enforced: {
+        'type': 'email',
+        'recurrence.pattern': 'weekly',
+        'recurrence.hour': 10,
+        'recurrence.day': 1,
+        'settings.providers': ['beehiiv'],
+        'settings.sender': 'newsletter',
+      },
+    },
+  ];
+}
+
+module.exports = { buildSeedCampaigns };

package/src/cli/commands/setup-tests/index.js

@@ -37,6 +37,7 @@ const HostingFolderTest = require('./hosting-folder');
 const PublicHtmlFilesTest = require('./public-html-files');
 const FirestoreIndexesRequiredTest = require('./firestore-indexes-required');
 const LegacyTestsCleanupTest = require('./legacy-tests-cleanup');
+const MarketingCampaignsSeededTest = require('./marketing-campaigns-seeded');
 
 /**
  * Get all tests in the order they should run
@@ -78,6 +79,7 @@ function getTests(context) {
     new HostingFolderTest(context),
     new PublicHtmlFilesTest(context),
     new LegacyTestsCleanupTest(context),
+    new MarketingCampaignsSeededTest(context),
   ];
 }
 

package/src/cli/commands/setup-tests/marketing-campaigns-seeded.js

@@ -0,0 +1,109 @@
+const BaseTest = require('./base-test');
+const chalk = require('chalk');
+const _ = require('lodash');
+const { buildSeedCampaigns } = require('./helpers/seed-campaigns');
+
+class MarketingCampaignsSeededTest extends BaseTest {
+  getName() {
+    return 'marketing campaigns seeded in Firestore';
+  }
+
+  async run() {
+    const admin = this._getAdmin();
+
+    if (!admin) {
+      return true; // Can't connect — skip gracefully
+    }
+
+    const seeds = buildSeedCampaigns();
+
+    for (const seed of seeds) {
+      const doc = await admin.firestore().doc(`marketing-campaigns/${seed.id}`).get();
+
+      // Doc doesn't exist → fail
+      if (!doc.exists) {
+        return false;
+      }
+
+      // Check enforced fields
+      const data = doc.data();
+
+      for (const [path, expected] of Object.entries(seed.enforced)) {
+        const actual = _.get(data, path);
+
+        if (!_.isEqual(actual, expected)) {
+          return false;
+        }
+      }
+    }
+
+    return true;
+  }
+
+  async fix() {
+    const admin = this._getAdmin();
+
+    if (!admin) {
+      console.log(chalk.yellow('  ⚠ No Firebase connection — skipping campaign seeding'));
+      console.log(chalk.yellow('    Run from a project with service-account.json to seed'));
+      return;
+    }
+
+    const seeds = buildSeedCampaigns();
+
+    for (const seed of seeds) {
+      const docRef = admin.firestore().doc(`marketing-campaigns/${seed.id}`);
+      const doc = await docRef.get();
+
+      // Doc doesn't exist → create it
+      if (!doc.exists) {
+        await docRef.set(seed.doc);
+        console.log(chalk.green(`  + Created ${chalk.cyan(seed.id)}: ${seed.doc.settings.name}`));
+        continue;
+      }
+
+      // Doc exists → check and fix enforced fields
+      const data = doc.data();
+      const updates = {};
+
+      for (const [path, expected] of Object.entries(seed.enforced)) {
+        const actual = _.get(data, path);
+
+        if (!_.isEqual(actual, expected)) {
+          _.set(updates, path, expected);
+          console.log(chalk.yellow(`  ↻ ${seed.id}: ${chalk.cyan(path)} ${chalk.dim(JSON.stringify(actual))} → ${chalk.bold(JSON.stringify(expected))}`));
+        }
+      }
+
+      if (Object.keys(updates).length) {
+        updates.metadata = {
+          updated: {
+            timestamp: new Date().toISOString(),
+            timestampUNIX: Math.round(Date.now() / 1000),
+          },
+        };
+
+        await docRef.set(updates, { merge: true });
+      } else {
+        console.log(chalk.dim(`  ✓ ${seed.id} — all enforced fields correct`));
+      }
+    }
+  }
+
+  _getAdmin() {
+    try {
+      const { initFirebase } = require('../firebase-init');
+      const { admin } = initFirebase({
+        firebaseProjectPath: this.self.firebaseProjectPath,
+        emulator: false,
+      });
+
+      return admin;
+    } catch (e) {
+      console.log(chalk.dim(`  (firebase-init failed: ${e.message})`));
+      return null;
+    }
+  }
+}
+
+module.exports = MarketingCampaignsSeededTest;

package/src/manager/cron/daily/marketing-prune.js

@@ -0,0 +1,140 @@
+/**
+ * Marketing contact pruning cron job
+ *
+ * Runs daily but only acts on the 1st of each month.
+ * Two-stage process using SSOT segment keys from constants.js:
+ *
+ *   Stage 1 (engagement_inactive_5m):
+ *     → Send re-engagement email via sendCampaign
+ *     → Excludes engagement_inactive_6m (those get pruned instead)
+ *
+ *   Stage 2 (engagement_inactive_6m):
+ *     → Export contacts from segment, bulk delete
+ *     → Excludes subscription_paid (never prune paying customers)
+ *
+ * Segment keys are resolved to provider-specific IDs at runtime.
+ * Requires marketing.prune.enabled = true in backend-manager-config.json.
+ *
+ * Runs on bm_cronDaily.
+ */
+const sendgridProvider = require('../../libraries/email/providers/sendgrid.js');
+
+module.exports = async ({ Manager, assistant }) => {
+  // Only run on the 1st of the month
+  if (new Date().getDate() !== 1) {
+    return;
+  }
+
+  if (Manager.config?.marketing?.prune?.enabled === false) {
+    assistant.log('Marketing prune: disabled');
+    return;
+  }
+
+  assistant.log('Marketing prune: Starting monthly prune cycle');
+
+  // --- Stage 1: Re-engagement email ---
+  await stageReengage(Manager, assistant);
+
+  // --- Stage 2: Delete inactive contacts ---
+  await stagePrune(Manager, assistant);
+
+  assistant.log('Marketing prune: Completed');
+};
+
+/**
+ * Stage 1: Send re-engagement email to contacts inactive 5+ months
+ * (excluding 6+ months — those get pruned in stage 2)
+ */
+async function stageReengage(Manager, assistant) {
+  assistant.log('Marketing prune: Stage 1 — Re-engagement');
+
+  const mailer = Manager.Email(assistant);
+  const brand = Manager.config?.brand;
+
+  const result = await mailer.sendCampaign({
+    name: 'Re-engagement: Are you still with us?',
+    subject: `We miss you at ${brand?.name || 'our service'}!`,
+    preheader: 'Update your preferences or say goodbye',
+    content: [
+      '# We miss you!',
+      '',
+      'It\'s been a while since you\'ve opened one of our emails. We want to make sure we\'re sending you content you actually want.',
+      '',
+      '**If you\'d like to keep hearing from us**, simply open this email — no action needed!',
+      '',
+      'If we don\'t hear from you, we\'ll remove you from our mailing list next month to keep your inbox clean.',
+      '',
+      `Thanks for being part of the ${brand?.name || ''} community.`,
+    ].join('\n'),
+    sender: 'hello',
+    segments: ['engagement_inactive_5m'],
+    excludeSegments: ['engagement_inactive_6m'],
+    sendAt: 'now',
+  });
+
+  assistant.log('Marketing prune: Re-engagement result:', result);
+}
+
+/**
+ * Stage 2: Delete contacts inactive 6+ months.
+ * Resolves segment IDs from SSOT keys at runtime.
+ * Excludes paying customers.
+ */
+async function stagePrune(Manager, assistant) {
+  assistant.log('Marketing prune: Stage 2 — Prune');
+
+  const marketing = Manager.config?.marketing || {};
+
+  // --- SendGrid ---
+  if (marketing.sendgrid?.enabled !== false && process.env.SENDGRID_API_KEY) {
+    const segmentIdMap = await sendgridProvider.resolveSegmentIds();
+    const pruneSegmentId = segmentIdMap['engagement_inactive_6m'];
+
+    if (!pruneSegmentId) {
+      assistant.error('Marketing prune: engagement_inactive_6m segment not found in SendGrid');
+      return;
+    }
+
+    const exportResult = await sendgridProvider.getSegmentContacts(pruneSegmentId);
+
+    if (!exportResult.success) {
+      assistant.error('Marketing prune: Failed to export segment:', exportResult.error);
+      return;
+    }
+
+    if (exportResult.contacts.length === 0) {
+      assistant.log('Marketing prune: No contacts to prune');
+      return;
+    }
+
+    assistant.log(`Marketing prune: Deleting ${exportResult.contacts.length} contacts`);
+
+    const ids = exportResult.contacts.map(c => c.id).filter(Boolean);
+    let totalDeleted = 0;
+
+    for (let i = 0; i < ids.length; i += 100) {
+      const batch = ids.slice(i, i + 100);
+      const deleteResult = await sendgridProvider.bulkDeleteContacts(batch);
+
+      if (deleteResult.success) {
+        totalDeleted += batch.length;
+      } else {
+        assistant.error('Marketing prune: Batch delete failed:', deleteResult.error);
+      }
+    }
+
+    assistant.log(`Marketing prune: Deleted ${totalDeleted} SendGrid contacts`);
+
+    // Also remove from Beehiiv (same emails)
+    if (marketing.beehiiv?.enabled !== false && process.env.BEEHIIV_API_KEY) {
+      const beehiivProvider = require('../../libraries/email/providers/beehiiv.js');
+      const emails = exportResult.contacts.map(c => c.email).filter(Boolean);
+
+      assistant.log(`Marketing prune: Removing ${emails.length} contacts from Beehiiv`);
+
+      await Promise.allSettled(
+        emails.map(email => beehiivProvider.removeContact(email))
+      );
+    }
+  }
+}

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

@@ -0,0 +1,158 @@
+/**
+ * Marketing campaigns cron job
+ *
+ * Picks up campaigns from the `marketing-campaigns` collection that are
+ * past their sendAt time and still pending. Dispatches based on type:
+ *   - email: fires through mailer.sendCampaign()
+ *   - push: fires through notification.send()
+ *
+ * Recurring campaigns (has `recurrence` field):
+ *   - Creates a history doc in the same collection with results
+ *   - Advances the recurring doc's sendAt to the next occurrence
+ *   - Status stays 'pending' on the recurring doc
+ *
+ * Runs on bm_cronFrequent (every 10 minutes).
+ */
+const moment = require('moment');
+const pushid = require('pushid');
+const notification = require('../../libraries/notification.js');
+
+module.exports = async ({ Manager, assistant, libraries }) => {
+  const { admin } = libraries;
+  const now = Math.round(Date.now() / 1000);
+
+  // Query campaigns that are ready to send
+  const snapshot = await admin.firestore()
+    .collection('marketing-campaigns')
+    .where('status', '==', 'pending')
+    .where('sendAt', '<=', now)
+    .limit(20)
+    .get();
+
+  if (snapshot.empty) {
+    assistant.log('No pending campaigns ready to send');
+    return;
+  }
+
+  assistant.log(`Processing ${snapshot.size} campaign(s)...`);
+
+  const email = Manager.Email(assistant);
+
+  const results = await Promise.allSettled(snapshot.docs.map(async (doc) => {
+    const data = doc.data();
+    const { settings, type, recurrence } = data;
+    const campaignId = doc.id;
+
+    assistant.log(`Processing campaign ${campaignId} (${type}): ${settings.name}`);
+
+    // --- Dispatch by type ---
+    let campaignResults;
+
+    if (type === 'email') {
+      campaignResults = await email.sendCampaign({ ...settings, sendAt: 'now' });
+    } else if (type === 'push') {
+      campaignResults = {
+        push: await notification.send(assistant, {
+          title: settings.name,
+          body: settings.subject || settings.body,
+          icon: settings.icon,
+          clickAction: settings.clickAction,
+          filters: settings.filters,
+        }),
+      };
+    } else {
+      assistant.log(`Unknown campaign type "${type}", skipping ${campaignId}`);
+      return;
+    }
+
+    const success = Object.values(campaignResults).some(r => r.success || r.sent > 0);
+    const nowISO = new Date().toISOString();
+    const nowUNIX = Math.round(Date.now() / 1000);
+
+    // --- Handle recurring vs one-off ---
+    if (recurrence) {
+      // Create history record
+      const historyId = pushid();
+
+      await admin.firestore().doc(`marketing-campaigns/${historyId}`).set({
+        settings,
+        type,
+        sendAt: data.sendAt,
+        status: success ? 'sent' : 'failed',
+        results: campaignResults,
+        recurringId: campaignId,
+        metadata: {
+          created: { timestamp: nowISO, timestampUNIX: nowUNIX },
+          updated: { timestamp: nowISO, timestampUNIX: nowUNIX },
+        },
+      });
+
+      // Advance sendAt to next occurrence
+      const nextSendAt = getNextOccurrence(data.sendAt, recurrence);
+
+      await doc.ref.set({
+        sendAt: nextSendAt,
+        metadata: {
+          updated: { timestamp: nowISO, timestampUNIX: nowUNIX },
+        },
+      }, { merge: true });
+
+      assistant.log(`Recurring campaign ${campaignId} ${success ? 'sent' : 'failed'}, next: ${moment.unix(nextSendAt).toISOString()}`);
+    } else {
+      // One-off: update status directly
+      await doc.ref.set({
+        status: success ? 'sent' : 'failed',
+        results: campaignResults,
+        metadata: {
+          updated: { timestamp: nowISO, timestampUNIX: nowUNIX },
+        },
+      }, { merge: true });
+
+      assistant.log(`Campaign ${campaignId} ${success ? 'sent' : 'failed'}`);
+    }
+  }));
+
+  const sent = results.filter(r => r.status === 'fulfilled').length;
+  const failed = results.filter(r => r.status === 'rejected').length;
+
+  for (const r of results) {
+    if (r.status === 'rejected') {
+      assistant.error(`Failed to process campaign: ${r.reason?.message}`, r.reason);
+    }
+  }
+
+  assistant.log(`Completed! (${sent} processed, ${failed} failed)`);
+};
+
+/**
+ * Calculate the next occurrence unix timestamp from the current sendAt.
+ *
+ * @param {number} currentSendAt - Current fire time (unix)
+ * @param {object} recurrence - { pattern, hour, day, month }
+ * @returns {number} Next fire time (unix)
+ */
+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:
+      // Fallback: 1 month
+      return current.add(1, 'month').unix();
+  }
+}