backend-manager 5.0.148 → 5.0.150

package/src/manager/libraries/email/marketing/index.js

@@ -0,0 +1,370 @@
+/**
+ * Marketing email library — contact syncing + campaign management
+ *
+ * Usage:
+ *   const email = Manager.Email(assistant);
+ *
+ *   // Add a new contact (newsletter subscribe, lightweight)
+ *   await email.add({ email, firstName, lastName, source });
+ *
+ *   // Sync a user's full data to SendGrid/Beehiiv (all custom fields)
+ *   await email.sync(userDoc);
+ *
+ *   // Remove a contact from all providers
+ *   await email.remove('user@example.com');
+ *
+ *   // Send a marketing campaign (Single Send)
+ *   await email.send({ type: 'marketing', name, subject, segments, ... });
+ *
+ * Used by:
+ * - routes/marketing/contact (add)
+ * - Auth on-create handler (sync on signup)
+ * - Payment transition handlers (sync on subscription change)
+ * - Auth on-delete handler (remove contact)
+ * - Campaign cron jobs (send campaigns)
+ */
+const _ = require('lodash');
+
+const { TEMPLATES, GROUPS, SENDERS } = require('../constants.js');
+const sendgridProvider = require('../providers/sendgrid.js');
+const beehiivProvider = require('../providers/beehiiv.js');
+
+function Marketing(assistant) {
+  const self = this;
+
+  self.assistant = assistant;
+  self.Manager = assistant.Manager;
+  self.admin = self.Manager.libraries.admin;
+
+  // Resolve provider availability from config + env
+  const marketing = self.Manager.config?.marketing || {};
+
+  self.providers = {
+    sendgrid: marketing.sendgrid?.enabled !== false && !!process.env.SENDGRID_API_KEY,
+    beehiiv: marketing.beehiiv?.enabled !== false && !!process.env.BEEHIIV_API_KEY,
+  };
+
+  return self;
+}
+
+/**
+ * Add a new contact to enabled providers (lightweight — no full user doc needed).
+ * Used by newsletter subscribe and admin bulk import.
+ *
+ * @param {object} options
+ * @param {string} options.email
+ * @param {string} [options.firstName]
+ * @param {string} [options.lastName]
+ * @param {string} [options.source] - UTM source
+ * @param {object} [options.customFields] - Extra SendGrid custom fields (keyed by field ID)
+ * @returns {{ sendgrid?: object, beehiiv?: object }}
+ */
+Marketing.prototype.add = async function (options) {
+  const self = this;
+  const assistant = self.assistant;
+  const { email, firstName, lastName, source, customFields } = options;
+
+  if (!email) {
+    assistant.warn('Marketing.add(): No email provided, skipping');
+    return {};
+  }
+
+  if (assistant.isTesting() && !process.env.TEST_EXTENDED_MODE) {
+    assistant.log('Marketing.add(): Skipping providers (testing mode)');
+    return {};
+  }
+
+  assistant.log('Marketing.add():', { email });
+
+  const results = {};
+  const promises = [];
+
+  if (self.providers.sendgrid) {
+    promises.push(
+      sendgridProvider.addContact({
+        email,
+        firstName,
+        lastName,
+        customFields,
+      }).then((r) => { results.sendgrid = r; })
+    );
+  }
+
+  if (self.providers.beehiiv) {
+    promises.push(
+      beehiivProvider.addContact({
+        email,
+        firstName,
+        lastName,
+        source,
+      }).then((r) => { results.beehiiv = r; })
+    );
+  }
+
+  await Promise.all(promises);
+
+  assistant.log('Marketing.add() result:', results);
+
+  return results;
+};
+
+/**
+ * Sync a user's data to SendGrid and Beehiiv.
+ * Upserts the contact with all custom fields derived from the user doc.
+ *
+ * @param {string|object} userDocOrUid - UID string (fetches from Firestore) or full user document object
+ * @returns {{ sendgrid?: object, beehiiv?: object }}
+ */
+Marketing.prototype.sync = async function (userDocOrUid) {
+  const self = this;
+  const assistant = self.assistant;
+
+  // Resolve UID to user doc if string
+  let userDoc;
+
+  if (typeof userDocOrUid === 'string') {
+    const snap = await self.admin.firestore().doc(`users/${userDocOrUid}`).get()
+      .catch((e) => {
+        assistant.error('Marketing.sync(): Failed to fetch user doc:', e);
+        return null;
+      });
+
+    if (!snap || !snap.exists) {
+      assistant.warn(`Marketing.sync(): User ${userDocOrUid} not found, skipping`);
+      return {};
+    }
+
+    userDoc = snap.data();
+  } else {
+    userDoc = userDocOrUid;
+  }
+
+  const email = _.get(userDoc, 'auth.email');
+
+  if (!email) {
+    assistant.warn('Marketing.sync(): No email found in user doc, skipping');
+    return {};
+  }
+
+  if (assistant.isTesting() && !process.env.TEST_EXTENDED_MODE) {
+    assistant.log('Marketing.sync(): Skipping providers (testing mode)');
+    return {};
+  }
+
+  assistant.log('Marketing.sync():', { email });
+
+  const firstName = _.get(userDoc, 'personal.name.first');
+  const lastName = _.get(userDoc, 'personal.name.last');
+  const source = _.get(userDoc, 'attribution.utm.tags.utm_source');
+  const results = {};
+  const promises = [];
+
+  if (self.providers.sendgrid) {
+    promises.push(
+      sendgridProvider.buildFields(userDoc).then((customFields) =>
+        sendgridProvider.addContact({
+          email,
+          firstName,
+          lastName,
+          customFields,
+        })
+      ).then((r) => { results.sendgrid = r; })
+    );
+  }
+
+  if (self.providers.beehiiv) {
+    promises.push(
+      beehiivProvider.addContact({
+        email,
+        firstName,
+        lastName,
+        source,
+        customFields: beehiivProvider.buildFields(userDoc),
+      }).then((r) => { results.beehiiv = r; })
+    );
+  }
+
+  await Promise.all(promises);
+
+  assistant.log('Marketing.sync() result:', results);
+
+  return results;
+};
+
+/**
+ * Remove a contact from all enabled providers.
+ *
+ * @param {string} email - Email address to remove
+ * @returns {{ sendgrid?: object, beehiiv?: object }}
+ */
+Marketing.prototype.remove = async function (email) {
+  const self = this;
+  const assistant = self.assistant;
+
+  if (!email) {
+    assistant.warn('Marketing.remove(): No email provided, skipping');
+    return {};
+  }
+
+  assistant.log('Marketing.remove():', { email });
+
+  const results = {};
+  const promises = [];
+
+  if (self.providers.sendgrid) {
+    promises.push(
+      sendgridProvider.removeContact(email)
+        .then((r) => { results.sendgrid = r; })
+    );
+  }
+
+  if (self.providers.beehiiv) {
+    promises.push(
+      beehiivProvider.removeContact(email)
+        .then((r) => { results.beehiiv = r; })
+    );
+  }
+
+  await Promise.all(promises);
+
+  assistant.log('Marketing.remove() result:', results);
+
+  return results;
+};
+
+/**
+ * Create and optionally schedule a marketing campaign (SendGrid Single Send).
+ *
+ * @param {object} settings
+ * @param {string} settings.name - Campaign name
+ * @param {string} settings.subject - Email subject
+ * @param {string} [settings.template] - Template shortcut or SendGrid template ID
+ * @param {string} [settings.sender] - Sender category ('marketing', 'newsletter', etc.)
+ * @param {Array<string>} [settings.segments] - Segment IDs to target
+ * @param {Array<string>} [settings.lists] - List IDs to target
+ * @param {boolean} [settings.all] - Target all contacts
+ * @param {string|number} [settings.sendAt] - ISO datetime or 'now' to schedule immediately
+ * @param {Array<string>} [settings.categories] - Email categories
+ * @returns {{ success: boolean, id?: string, scheduled?: boolean, error?: string }}
+ */
+Marketing.prototype.sendCampaign = async function (settings) {
+  const self = this;
+  const Manager = self.Manager;
+  const assistant = self.assistant;
+
+  if (!self.providers.sendgrid) {
+    return { success: false, error: 'SendGrid not enabled' };
+  }
+
+  const templateId = TEMPLATES[settings.template] || settings.template || TEMPLATES['default'];
+
+  // Resolve sender
+  const sender = SENDERS[settings.sender] || SENDERS['marketing'];
+  const brand = Manager.config?.brand;
+  const brandDomain = brand?.contact?.email?.split('@')[1];
+
+  const from = settings.from || {
+    email: `${sender.localPart}@${brandDomain}`,
+    name: sender.displayName.replace('{brand}', brand?.name || ''),
+  };
+
+  // Build send_to targeting
+  const sendTo = {};
+
+  if (settings.all) {
+    sendTo.all = true;
+  }
+  if (settings.lists && settings.lists.length) {
+    sendTo.list_ids = settings.lists;
+  }
+  if (settings.segments && settings.segments.length) {
+    sendTo.segment_ids = settings.segments;
+  }
+
+  // ASM group
+  const asmGroupId = settings.group != null
+    ? (GROUPS[settings.group] || settings.group)
+    : sender.group;
+
+  // Categories
+  const categories = _.uniq([
+    'marketing',
+    brand?.id,
+    ...require('node-powertools').arrayify(settings.categories),
+  ].filter(Boolean));
+
+  assistant.log('Marketing.sendCampaign():', { name: settings.name, sendTo, templateId });
+
+  // Create the Single Send
+  const createResult = await sendgridProvider.createSingleSend({
+    name: settings.name,
+    subject: settings.subject,
+    templateId,
+    from,
+    sendTo,
+    asmGroupId,
+    categories,
+  });
+
+  if (!createResult.success) {
+    assistant.error('Marketing.sendCampaign() create failed:', createResult.error);
+    return createResult;
+  }
+
+  // Schedule if sendAt is provided
+  if (settings.sendAt) {
+    const sendAt = settings.sendAt === 'now' ? 'now' : new Date(settings.sendAt).toISOString();
+
+    const scheduleResult = await sendgridProvider.scheduleSingleSend(createResult.id, sendAt);
+
+    if (!scheduleResult.success) {
+      assistant.error('Marketing.sendCampaign() schedule failed:', scheduleResult.error);
+      return { success: false, id: createResult.id, error: scheduleResult.error };
+    }
+
+    assistant.log('Marketing.sendCampaign() scheduled:', createResult.id);
+
+    return { success: true, id: createResult.id, scheduled: true };
+  }
+
+  // Created but not scheduled (draft)
+  return { success: true, id: createResult.id, scheduled: false };
+};
+
+/**
+ * Cancel a scheduled campaign.
+ *
+ * @param {string} campaignId - Single Send ID
+ * @returns {{ success: boolean, error?: string }}
+ */
+Marketing.prototype.cancelCampaign = async function (campaignId) {
+  const self = this;
+  const assistant = self.assistant;
+
+  assistant.log('Marketing.cancelCampaign():', campaignId);
+
+  return sendgridProvider.cancelSingleSend(campaignId);
+};
+
+/**
+ * Get a campaign by ID.
+ *
+ * @param {string} campaignId - Single Send ID
+ * @returns {object|null}
+ */
+Marketing.prototype.getCampaign = async function (campaignId) {
+  return sendgridProvider.getSingleSend(campaignId);
+};
+
+/**
+ * List campaigns with optional status filter.
+ *
+ * @param {object} [options]
+ * @param {string} [options.status] - Filter: draft, scheduled, triggered
+ * @returns {Array<object>}
+ */
+Marketing.prototype.listCampaigns = async function (options) {
+  return sendgridProvider.listSingleSends(options);
+};
+
+module.exports = Marketing;

package/src/manager/libraries/email/providers/beehiiv.js

@@ -0,0 +1,274 @@
+/**
+ * Beehiiv provider — shared API helpers for subscriber management
+ *
+ * Used by: marketing/index.js (sync, remove)
+ */
+const fetch = require('wonderful-fetch');
+const Manager = require('../../../index.js');
+const { resolveFieldValues } = require('../constants.js');
+
+const BASE_URL = 'https://api.beehiiv.com/v2';
+
+// --- Internal helpers ---
+
+function headers() {
+  return {
+    'Authorization': `Bearer ${process.env.BEEHIIV_API_KEY}`,
+  };
+}
+
+// --- Subscriber Management ---
+
+/**
+ * Add or reactivate a subscriber to a Beehiiv publication.
+ *
+ * @param {object} options
+ * @param {string} options.email
+ * @param {string} [options.firstName]
+ * @param {string} [options.lastName]
+ * @param {string} [options.source] - UTM source
+ * @param {string} options.publicationId
+ * @param {Array<{name: string, value: string}>} [options.customFields] - Additional custom fields
+ * @returns {{ success: boolean, id?: string, error?: string }}
+ */
+async function addSubscriber({ email, firstName, lastName, source, publicationId, customFields }) {
+  try {
+    const body = {
+      email,
+      reactivate_existing: true,
+      send_welcome_email: true,
+    };
+
+    if (source) {
+      body.utm_source = source;
+    }
+
+    // Build custom fields array
+    const fields = [
+      ...(customFields || []),
+    ];
+
+    if (firstName) {
+      fields.push({ name: 'first_name', value: firstName });
+    }
+    if (lastName) {
+      fields.push({ name: 'last_name', value: lastName });
+    }
+
+    if (fields.length) {
+      body.custom_fields = fields;
+    }
+
+    const data = await fetch(`${BASE_URL}/publications/${publicationId}/subscriptions`, {
+      method: 'post',
+      response: 'json',
+      headers: headers(),
+      timeout: 15000,
+      body,
+    });
+
+    if (data.data?.id) {
+      return { success: true, id: data.data.id };
+    }
+
+    return { success: false, error: data.message || 'Unknown error' };
+  } catch (e) {
+    console.error('Beehiiv addSubscriber error:', e);
+    return { success: false, error: e.message };
+  }
+}
+
+/**
+ * Remove a subscriber from a Beehiiv publication by email.
+ *
+ * @param {string} email
+ * @param {string} publicationId
+ * @returns {{ success: boolean, deleted?: boolean, skipped?: boolean, error?: string }}
+ */
+async function removeSubscriber(email, publicationId) {
+  try {
+    const encodedEmail = encodeURIComponent(email);
+
+    // Step 1: Get subscription by email
+    let searchData;
+    try {
+      searchData = await fetch(
+        `${BASE_URL}/publications/${publicationId}/subscriptions/by_email/${encodedEmail}`,
+        {
+          response: 'json',
+          headers: headers(),
+          timeout: 10000,
+        }
+      );
+    } catch (e) {
+      if (e.status === 404) {
+        return { success: true, skipped: true, reason: 'Subscriber not found' };
+      }
+      throw e;
+    }
+
+    if (!searchData.data?.id) {
+      return { success: true, skipped: true, reason: 'Subscription not found' };
+    }
+
+    const subscriptionId = searchData.data.id;
+
+    // Step 2: Permanently delete the subscription
+    await fetch(
+      `${BASE_URL}/publications/${publicationId}/subscriptions/${subscriptionId}`,
+      {
+        method: 'delete',
+        headers: headers(),
+        timeout: 10000,
+      }
+    );
+
+    return { success: true, deleted: true, subscriptionId };
+  } catch (e) {
+    console.error('Beehiiv removeSubscriber error:', e);
+    return { success: false, error: e.message };
+  }
+}
+
+/**
+ * Get a Beehiiv publication ID by brand name (fuzzy match).
+ *
+ * @param {string} brandName
+ * @returns {string|null} Publication ID or null
+ */
+let _publicationIdCache = null;
+
+async function getPublicationId() {
+  if (_publicationIdCache) {
+    return _publicationIdCache;
+  }
+
+  // Use publicationId from config if set (skips API call)
+  const configPubId = Manager.config?.marketing?.beehiiv?.publicationId;
+
+  if (configPubId) {
+    _publicationIdCache = configPubId;
+    return configPubId;
+  }
+
+  // Fuzzy-match by brand name
+  const brandName = Manager.config.brand?.name;
+
+  if (!brandName) {
+    console.error('Beehiiv: Brand name is required to find publication');
+    return null;
+  }
+
+  const brandNameLower = brandName.toLowerCase();
+  const allPublications = [];
+  let page = 1;
+  const limit = 100;
+
+  try {
+    while (true) {
+      const data = await fetch(`${BASE_URL}/publications?limit=${limit}&page=${page}`, {
+        response: 'json',
+        headers: headers(),
+        timeout: 10000,
+      });
+
+      if (!data.data || data.data.length === 0) {
+        break;
+      }
+
+      const matchedPub = data.data.find(pub =>
+        pub.name.toLowerCase() === brandNameLower
+        || pub.name.toLowerCase().includes(brandNameLower)
+        || brandNameLower.includes(pub.name.toLowerCase())
+      );
+
+      if (matchedPub) {
+        _publicationIdCache = matchedPub.id;
+        return matchedPub.id;
+      }
+
+      allPublications.push(...data.data);
+
+      if (data.data.length < limit) {
+        break;
+      }
+
+      page++;
+    }
+
+    console.error(`Beehiiv: No publication matched brand "${brandName}". Available: ${allPublications.map(p => p.name).join(', ')}`);
+  } catch (e) {
+    console.error('Beehiiv publication lookup error:', e);
+  }
+
+  return null;
+}
+
+/**
+ * Add a contact to Beehiiv — resolves publication, adds subscriber with optional custom fields.
+ *
+ * @param {object} options
+ * @param {string} options.email
+ * @param {string} [options.firstName]
+ * @param {string} [options.lastName]
+ * @param {string} [options.source] - UTM source
+ * @param {Array<{name: string, value: string}>} [options.customFields] - Pre-built custom fields
+ * @returns {{ success: boolean, id?: string, error?: string }}
+ */
+async function addContact({ email, firstName, lastName, source, customFields }) {
+  const publicationId = await getPublicationId();
+
+  if (!publicationId) {
+    return { success: false, error: 'Publication not found' };
+  }
+
+  return addSubscriber({
+    email,
+    firstName,
+    lastName,
+    source,
+    publicationId,
+    customFields: customFields || [],
+  });
+}
+
+/**
+ * Remove a contact from Beehiiv — resolves publication from config.
+ *
+ * @param {string} email
+ * @returns {{ success: boolean, deleted?: boolean, skipped?: boolean, error?: string }}
+ */
+async function removeContact(email) {
+  const publicationId = await getPublicationId();
+
+  if (!publicationId) {
+    return { success: false, error: 'Publication not found' };
+  }
+
+  return removeSubscriber(email, publicationId);
+}
+
+/**
+ * Build Beehiiv custom_fields array from a user doc.
+ * Resolves all field values — the key IS the field name in Beehiiv.
+ *
+ * @param {object} userDoc - User document from Firestore
+ * @returns {Array<{name: string, value: string}>} Custom fields in Beehiiv format
+ */
+function buildFields(userDoc) {
+  const values = resolveFieldValues(userDoc, Manager.config);
+  const fields = [];
+
+  for (const [name, value] of Object.entries(values)) {
+    fields.push({ name, value: String(value) });
+  }
+
+  return fields;
+}
+
+module.exports = {
+  // Contacts
+  addContact,
+  removeContact,
+  buildFields,
+};