backend-manager 5.0.148 → 5.0.149

package/src/manager/index.js

@@ -138,6 +138,11 @@ Manager.prototype.init = function (exporter, options) {
     (_objValue, srcValue) => isArray(srcValue) ? srcValue : undefined,
   );
 
+  // Expose config on the constructor for static access by internal libraries.
+  // Since Node.js caches require(), any `require('./index.js')` returns this same
+  // Manager function with .config already set — no need for setConfig() patterns.
+  Manager.config = self.config;
+
   // Set PAYPAL_CLIENT_ID from config (clientId is public, not a secret — lives in config, not .env)
   process.env.PAYPAL_CLIENT_ID = process.env.PAYPAL_CLIENT_ID || self.config?.payment?.processors?.paypal?.clientId || '';
 
@@ -145,12 +150,12 @@ Manager.prototype.init = function (exporter, options) {
   process.env.CHARGEBEE_SITE = process.env.CHARGEBEE_SITE || self.config?.payment?.processors?.chargebee?.site || '';
 
   // Resolve legacy paths
-  // TODO: Remove this in future versions (after we migrate to removing app.id from config)
+  // TODO: Remove this in future versions (after all consumers migrate to brand.id)
   self.config.app = self.config.app || {};
-  self.config.app.id = self.config.brand.id || self.config.app.id || null;
+  self.config.brand.id = self.config.brand.id || self.config.app.id || null;
 
-  // Get app ID
-  const appId = self.config?.app?.id;
+  // Get brand ID
+  const brandId = self.config?.brand?.id;
 
   // Set log
   if (options.logSavePath) {
@@ -267,13 +272,13 @@ Manager.prototype.init = function (exporter, options) {
     self.assistant.log('Resolved backendManagerConfigPath', self.project.backendManagerConfigPath);
   }
 
-  if (!appId) {
-    self.assistant.warn('⚠️ Missing config.app.id');
+  if (!brandId) {
+    self.assistant.warn('⚠️ Missing config.brand.id');
   }
 
   // Setup sentry
   if (self.options.sentry) {
-    const sentryRelease = `${appId || self.project.projectId}@${self.package.version}`;
+    const sentryRelease = `${brandId || self.project.projectId}@${self.package.version}`;
     const sentryDSN = self.config?.sentry?.dsn || '';
     // self.assistant.log('Sentry', sentryRelease, sentryDSN);
 
@@ -310,8 +315,8 @@ Manager.prototype.init = function (exporter, options) {
       // self.app = self.libraries.initializedAdmin;
 
       const loadedProjectId = serviceAccount.project_id;
-      if (!loadedProjectId || !loadedProjectId.includes(appId)) {
-        self.assistant.error(`Loaded app may have wrong service account: ${loadedProjectId} =/= ${appId}`);
+      if (!loadedProjectId || !loadedProjectId.includes(brandId)) {
+        self.assistant.error(`Loaded app may have wrong service account: ${loadedProjectId} =/= ${brandId}`);
       }
     }
   }
@@ -534,7 +539,7 @@ Manager.prototype.Metadata = function () {
 
 Manager.prototype.Email = function (assistant) {
   const self = this;
-  self.libraries.Email = self.libraries.Email || require('./libraries/email.js');
+  self.libraries.Email = self.libraries.Email || require('./libraries/email/index.js');
   return new self.libraries.Email(assistant);
 };
 

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

@@ -0,0 +1,243 @@
+/**
+ * Shared constants for email libraries (transactional + marketing)
+ *
+ * SSOT for templates, ASM groups, and semantic senders.
+ * Used by: transactional/index.js, marketing/index.js, providers/*
+ */
+
+// Template shortcut map — callers use readable paths instead of SendGrid IDs
+// Paths mirror the email website structure: {category}/{subcategory}/{name}
+const TEMPLATES = {
+  // v2 templates
+  'main/basic/card': 'd-1cd2eee44b6340268c964cd7971d49b9',
+  'main/engagement/feedback': 'd-319ab5c9d5074b21926a93562d6f41f6',
+  'main/misc/app-download-link': 'd-fc8b4834d7e1472896fe7e46152029f4',
+  'main/order/confirmation': 'd-5371ac2b4e3b490bbce51bfc2922ece8',
+  'main/order/payment-failed': 'd-e56af0ac62364bfb9e50af02854e2cd3',
+  'main/order/payment-recovered': 'd-d6dbd17a260a4755b34a852ba09c2454',
+  'main/order/cancellation-requested': 'd-78074f3e8c844146bf263b86fc8d5ecf',
+  'main/order/cancelled': 'd-39041132e6b24e5ebf0e95bce2d94dba',
+  'main/order/plan-changed': 'd-399086311bbb48b4b77bc90b20fb9d0a',
+  'main/order/trial-ending': 'd-af8ab499cbfb4d56918b4118f44343b0',
+  'main/order/refunded': 'd-aa47fdbffa2b4ca9b73b6256e963e49f',
+  'main/order/abandoned-cart': 'd-d8b3fa67e2b44b398dc280d0576bf1b7',
+};
+
+// "default" resolves to the basic card template
+TEMPLATES['default'] = TEMPLATES['main/basic/card'];
+
+// Group shortcut map — SendGrid ASM group IDs
+// Rename these in SendGrid dashboard to match the comments
+const GROUPS = {
+  'orders': 16223,         // BEM - Order Updates
+  'hello': 35092,          // BEM - Onboarding
+  'account': 25927,        // BEM - Account
+  'marketing': 25928,      // BEM - Marketing & Promotions
+  'newsletter': 28096,     // BEM - Newsletter
+  'security': 35093,       // BEM - Security
+  'internal': 35094,       // BEM - Internal Alerts
+};
+
+// Semantic sender categories — pass `sender: 'orders'` to auto-resolve from address, display name, and ASM group
+const SENDERS = {
+  // Payment receipts, failed/recovered, cancellation, plan changes, refunds, trial ending
+  orders: {
+    localPart: 'orders',
+    displayName: '{brand} Orders',
+    group: GROUPS['orders'],
+  },
+  // Warm onboarding: welcome, 7-day checkup, feedback request
+  hello: {
+    localPart: 'hello',
+    displayName: '{brand}',
+    group: GROUPS['hello'],
+  },
+  // Transactional account actions: deletion, data requests
+  account: {
+    localPart: 'account',
+    displayName: '{brand} Account',
+    group: GROUPS['account'],
+  },
+  // Promotions, discounts, win-back, abandoned cart, app download link
+  marketing: {
+    localPart: 'offers',
+    displayName: '{brand}',
+    group: GROUPS['marketing'],
+  },
+  // Forgot password, 2FA, password reset
+  security: {
+    localPart: 'security',
+    displayName: '{brand} Security',
+    group: GROUPS['security'],
+  },
+  // Monthly newsletters, feature announcements, industry news
+  newsletter: {
+    localPart: 'newsletter',
+    displayName: '{brand}',
+    group: GROUPS['newsletter'],
+  },
+  // Dispute alerts, system notifications sent to brand contact
+  internal: {
+    localPart: 'alerts',
+    displayName: '{brand} Alerts',
+    group: GROUPS['internal'],
+  },
+};
+
+// Default marketing providers — SSOT for all provider loops
+const DEFAULT_PROVIDERS = ['sendgrid', 'beehiiv'];
+
+// SendGrid limit for scheduled emails (72 hours, but use 71 for buffer)
+const SEND_AT_LIMIT = 71;
+
+/**
+ * Convert SVG image URLs to PNG equivalents — email clients don't render SVGs.
+ * CDN naming convention: `-x.svg` -> `-1024.png`
+ */
+function sanitizeImagesForEmail(images) {
+  const result = {};
+
+  for (const [key, value] of Object.entries(images)) {
+    if (typeof value === 'string' && value.endsWith('.svg')) {
+      result[key] = value.replace(/-x\.svg$/, '-1024.png');
+    } else {
+      result[key] = value;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * URL-encode a value as base64
+ */
+function encode(s) {
+  return encodeURIComponent(Buffer.from(String(s)).toString('base64'));
+}
+
+/**
+ * Create an Error with a code property for distinguishing build (400) vs send (500) failures.
+ */
+function errorWithCode(message, code) {
+  const err = new Error(message);
+  err.code = code;
+  return err;
+}
+
+// Master field dictionary — the key IS the field name used in both providers.
+//
+// SendGrid: key is matched against custom field names at runtime (fetched + cached).
+// Beehiiv: key is used directly as the custom field name.
+//
+// Source types:
+//   'user'     — read from user doc via _.get(userDoc, path)
+//   'resolved' — read from User.resolveSubscription() output via path
+//   'config'   — read from Manager.config via _.get(config, path)
+//
+// To add a new tracked marketing field:
+//   1. Add an entry here — the key becomes the field name in both providers
+//   2. Add matching entry in OMEGA's src/lib/bem-fields.js (name, display, type)
+//   3. Run OMEGA: npm start -- --service=sendgrid,beehiiv --brand=X
+//   4. BEM resolves field IDs at runtime — no provider code changes needed
+//   5. If 'resolved' source, ensure resolveFieldValues() computes it
+const FIELDS = {
+  // Brand
+  brand_id:                              { source: 'config', path: 'brand.id', type: 'text' },
+
+  // User identity
+  user_auth_uid:                         { source: 'user', path: 'auth.uid', type: 'text' },
+  user_personal_country:                 { source: 'user', path: 'personal.location.country', type: 'text' },
+  user_metadata_signup_date:             { source: 'user', path: 'metadata.created.timestamp', type: 'date' },
+  user_metadata_last_activity:           { source: 'user', path: 'metadata.updated.timestamp', type: 'date' },
+
+  // Subscription
+  user_subscription_plan:                { source: 'resolved', path: 'plan', type: 'text' },
+  user_subscription_status:              { source: 'resolved', path: 'status', type: 'text' },
+  user_subscription_trialing:            { source: 'resolved', path: 'trialing', type: 'text' },
+  user_subscription_cancelling:          { source: 'resolved', path: 'cancelling', type: 'text' },
+  user_subscription_ever_paid:           { source: 'resolved', path: 'everPaid', type: 'text' },
+  user_subscription_payment_processor:   { source: 'user', path: 'subscription.payment.processor', type: 'text' },
+  user_subscription_payment_frequency:   { source: 'user', path: 'subscription.payment.frequency', type: 'text' },
+  user_subscription_payment_price:       { source: 'user', path: 'subscription.payment.price', type: 'number' },
+  user_subscription_payment_last_date:   { source: 'user', path: 'subscription.payment.updatedBy.date.timestamp', type: 'date' },
+
+  // Attribution
+  user_attribution_utm_source:           { source: 'user', path: 'attribution.utm.tags.utm_source', type: 'text' },
+};
+
+
+/**
+ * Resolve all field values from a user doc + config.
+ * Returns a map of semantic field names → resolved values (type-coerced).
+ * Providers use this internally to build their native field format.
+ *
+ * @param {object} userDoc - User document from Firestore
+ * @param {object} config - Manager.config
+ * @returns {object} Map of semantic name → value (e.g., { plan: 'basic', status: 'active', ... })
+ */
+const _ = require('lodash');
+const User = require('../../helpers/user.js');
+
+function resolveFieldValues(userDoc, config) {
+  const resolved = User.resolveSubscription(userDoc);
+  const subscription = userDoc.subscription || {};
+
+  // Computed values from resolveSubscription() + raw status
+  const resolvedValues = {
+    plan: resolved.plan,
+    status: subscription.status || 'active',
+    everPaid: String(resolved.everPaid),
+    trialing: String(resolved.trialing),
+    cancelling: String(resolved.cancelling),
+  };
+
+  const result = {};
+
+  for (const [name, fieldConfig] of Object.entries(FIELDS)) {
+    let value;
+
+    if (fieldConfig.source === 'config') {
+      value = _.get(config, fieldConfig.path);
+    } else if (fieldConfig.source === 'resolved') {
+      value = resolvedValues[fieldConfig.path];
+    } else {
+      value = _.get(userDoc, fieldConfig.path);
+    }
+
+    if (value == null) {
+      continue;
+    }
+
+    // Coerce booleans to strings for text fields
+    if (fieldConfig.type === 'text' && typeof value === 'boolean') {
+      value = String(value);
+    }
+
+    // Coerce to number for number fields
+    if (fieldConfig.type === 'number' && typeof value !== 'number') {
+      value = Number(value) || 0;
+    }
+
+    // Skip epoch default dates (1970-01-01)
+    if (fieldConfig.type === 'date' && (!value || value === '1970-01-01T00:00:00.000Z')) {
+      continue;
+    }
+
+    result[name] = value;
+  }
+
+  return result;
+}
+
+module.exports = {
+  TEMPLATES,
+  GROUPS,
+  SENDERS,
+  FIELDS,
+  DEFAULT_PROVIDERS,
+  SEND_AT_LIMIT,
+  sanitizeImagesForEmail,
+  encode,
+  errorWithCode,
+  resolveFieldValues,
+};

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

@@ -0,0 +1,145 @@
+/**
+ * Unified email library — transactional + marketing
+ *
+ * Usage:
+ *   const email = Manager.Email(assistant);
+ *
+ *   // Transactional (default)
+ *   await email.send({ to, subject, template, ... });
+ *   await email.build({ ... });
+ *
+ *   // Marketing campaign
+ *   await email.send({ type: 'marketing', name, subject, segments, ... });
+ *
+ *   // Add a new contact (newsletter subscribe)
+ *   await email.add({ email, firstName, lastName, source });
+ *
+ *   // Sync full user data to SendGrid/Beehiiv (all custom fields)
+ *   await email.sync(userDoc);
+ *
+ *   // Remove contact from all providers
+ *   await email.remove('user@example.com');
+ *
+ *   // Campaign management
+ *   await email.cancelCampaign(id);
+ *   await email.getCampaign(id);
+ *   await email.listCampaigns({ status: 'scheduled' });
+ */
+const Transactional = require('./transactional/index.js');
+const Marketing = require('./marketing/index.js');
+
+function Email(assistant) {
+  const self = this;
+
+  self.assistant = assistant;
+  self.Manager = assistant.Manager;
+
+  // Compose internal modules
+  self._transactional = new Transactional(assistant);
+  self._marketing = new Marketing(assistant);
+
+  return self;
+}
+
+/**
+ * Send an email.
+ *
+ * @param {object} settings
+ * @param {string} [settings.type] - 'transactional' (default) or 'marketing'
+ *
+ * Transactional settings: { to, subject, template, sender, sendAt, data, ... }
+ * Marketing settings: { name, subject, template, sender, segments, lists, sendAt, ... }
+ *
+ * @returns {object} Result from the appropriate sender
+ */
+Email.prototype.send = function (settings) {
+  const self = this;
+  const type = settings.type || 'transactional';
+
+  if (type === 'marketing') {
+    return self._marketing.sendCampaign(settings);
+  }
+
+  return self._transactional.send(settings);
+};
+
+/**
+ * Build a transactional email without sending it.
+ *
+ * @param {object} settings - Same as send() transactional settings
+ * @returns {object} SendGrid-ready email object
+ */
+Email.prototype.build = function (settings) {
+  return this._transactional.build(settings);
+};
+
+/**
+ * Sync a user's data to marketing providers (SendGrid + Beehiiv).
+ *
+ * @param {object} userDoc - Full user document from Firestore
+ * @param {object} [options] - { providers: array of provider names (default: DEFAULT_PROVIDERS) }
+ * @returns {{ sendgrid?: object, beehiiv?: object }}
+ */
+/**
+ * Add a new contact to marketing providers (lightweight, no full user doc needed).
+ *
+ * @param {object} options - { email, firstName, lastName, source, customFields, providers }
+ * @returns {{ sendgrid?: object, beehiiv?: object }}
+ */
+Email.prototype.add = function (options) {
+  return this._marketing.add(options);
+};
+
+/**
+ * Sync a user's full data to marketing providers (SendGrid + Beehiiv).
+ *
+ * @param {object} userDoc - Full user document from Firestore
+ * @param {object} [options] - { providers: array of provider names (default: DEFAULT_PROVIDERS) }
+ * @returns {{ sendgrid?: object, beehiiv?: object }}
+ */
+Email.prototype.sync = function (userDoc, options) {
+  return this._marketing.sync(userDoc, options);
+};
+
+/**
+ * Remove a contact from all marketing providers.
+ *
+ * @param {string} email - Email address to remove
+ * @param {object} [options] - { providers: array of provider names (default: DEFAULT_PROVIDERS) }
+ * @returns {{ sendgrid?: object, beehiiv?: object }}
+ */
+Email.prototype.remove = function (email, options) {
+  return this._marketing.remove(email, options);
+};
+
+/**
+ * Cancel a scheduled marketing campaign.
+ *
+ * @param {string} campaignId - Single Send ID
+ * @returns {{ success: boolean, error?: string }}
+ */
+Email.prototype.cancelCampaign = function (campaignId) {
+  return this._marketing.cancelCampaign(campaignId);
+};
+
+/**
+ * Get a marketing campaign by ID.
+ *
+ * @param {string} campaignId - Single Send ID
+ * @returns {object|null}
+ */
+Email.prototype.getCampaign = function (campaignId) {
+  return this._marketing.getCampaign(campaignId);
+};
+
+/**
+ * List marketing campaigns.
+ *
+ * @param {object} [options] - { status: 'draft' | 'scheduled' | 'triggered' }
+ * @returns {Array<object>}
+ */
+Email.prototype.listCampaigns = function (options) {
+  return this._marketing.listCampaigns(options);
+};
+
+module.exports = Email;