backend-manager 5.0.147 → 5.0.149

package/src/manager/libraries/{email.js → email/transactional/index.js}

@@ -1,5 +1,5 @@
 /**
- * Shared email library for building and sending emails via SendGrid
+ * Transactional email library — build and send individual emails via SendGrid
  *
  * Usage:
  *   const email = Manager.Email(assistant);
@@ -20,38 +20,17 @@ const md = new MarkdownIt({
   linkify: true,
 });
 
-// SendGrid limit for scheduled emails (72 hours, but use 71 for buffer)
-const SEND_AT_LIMIT = 71;
-
-// 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
-const GROUPS = {
-  'default': 24077,
-  'marketing': 25927,
-  'account': 25928,
-};
-
-function Email(assistant) {
+const {
+  TEMPLATES,
+  GROUPS,
+  SENDERS,
+  SEND_AT_LIMIT,
+  sanitizeImagesForEmail,
+  encode,
+  errorWithCode,
+} = require('../constants.js');
+
+function Transactional(assistant) {
   const self = this;
 
   self.assistant = assistant;
@@ -68,7 +47,7 @@ function Email(assistant) {
  * @returns {object} SendGrid-ready email object
  * @throws {Error} On validation failure
  */
-Email.prototype.build = async function (settings) {
+Transactional.prototype.build = async function (settings) {
   const self = this;
   const Manager = self.Manager;
   const admin = self.admin;
@@ -80,15 +59,29 @@ Email.prototype.build = async function (settings) {
   let cc = normalizeRecipients(settings.cc);
   let bcc = normalizeRecipients(settings.bcc);
 
-  // Resolve any uid: prefixed recipients from Firestore
+  // Resolve any UID recipients from Firestore
   [to, cc, bcc] = await Promise.all([
     resolveRecipients(to, admin, assistant),
     resolveRecipients(cc, admin, assistant),
     resolveRecipients(bcc, admin, assistant),
   ]);
 
-  // Build user template data from settings.user (for legacy callers that pass user object)
-  const userProperties = Manager.User(settings.user || {}).properties;
+  // Resolve user template data from the primary recipient's user doc (if available)
+  const rawUserDoc = to[0]?._userDoc || {};
+  const userProperties = Manager.User(rawUserDoc).properties;
+  delete userProperties.api;
+  delete userProperties.oauth2;
+  delete userProperties.activity;
+  delete userProperties.affiliate;
+  delete userProperties.attribution;
+  delete userProperties.flags;
+
+  // Clean internal markers from recipients
+  for (const list of [to, cc, bcc]) {
+    for (const entry of list) {
+      delete entry._userDoc;
+    }
+  }
 
   // Get brand config
   const brand = Manager.config?.brand;
@@ -148,7 +141,23 @@ Email.prototype.build = async function (settings) {
   }
 
   const templateId = TEMPLATES[settings.template] || settings.template || TEMPLATES['default'];
-  const groupId = GROUPS[settings.group] || settings.group || GROUPS['default'];
+
+  // Resolve sender category
+  const sender = SENDERS[settings.sender] || null;
+  const brandDomain = brandData.contact.email.split('@')[1];
+
+  // From: explicit from > sender-derived > brand default
+  const from = settings.from
+    || (sender && {
+      email: `${sender.localPart}@${brandDomain}`,
+      name: sender.displayName.replace('{brand}', brandData.name),
+    })
+    || { email: brandData.contact.email, name: brandData.name };
+
+  // ASM group: explicit group > sender-derived > default
+  const groupId = settings.group != null
+    ? (GROUPS[settings.group] || settings.group)
+    : (sender ? sender.group : GROUPS['account']);
 
   // Build categories
   const categories = _.uniq([
@@ -161,10 +170,8 @@ Email.prototype.build = async function (settings) {
   const sendAt = normalizeSendAt(settings.sendAt);
 
   // Build unsubscribe URL
-  // Generate HMAC signature for unsubscribe link verification
   const crypto = require('crypto');
   const unsubSig = crypto.createHmac('sha256', process.env.UNSUBSCRIBE_HMAC_KEY).update(to[0].email.toLowerCase()).digest('hex');
-
   const unsubscribeUrl = `${Manager.project.websiteUrl}/portal/email-preferences?email=${encode(to[0].email)}&asmId=${encode(groupId)}&templateId=${encode(templateId)}&sig=${unsubSig}`;
 
   // Build signoff
@@ -217,19 +224,19 @@ Email.prototype.build = async function (settings) {
     to,
     cc,
     bcc,
-    from: settings.from || { email: brandData.contact.email, name: brandData.name },
-    replyTo: settings.replyTo || brandData.contact.email,
+    from,
+    replyTo: settings.replyTo || from.email,
     subject,
     templateId,
-    asm: { groupId },
     categories,
     dynamicTemplateData,
     substitutionWrappers: ['{{', '}}'],
-    headers: {
-      'List-Unsubscribe': `<${unsubscribeUrl}>`,
-    },
   };
 
+  // ASM group + unsubscribe header (always present on every email)
+  email.asm = { groupId };
+  email.headers = { 'List-Unsubscribe': `<${unsubscribeUrl}>` };
+
   // Set sendAt
   if (sendAt) {
     email.sendAt = sendAt;
@@ -257,7 +264,7 @@ Email.prototype.build = async function (settings) {
  * @returns {{ status: string, options?: object, response?: object }}
  * @throws {Error} With code 400 for validation errors, code 500 for send failures
  */
-Email.prototype.send = async function (settings) {
+Transactional.prototype.send = async function (settings) {
   const self = this;
   const Manager = self.Manager;
   const admin = self.admin;
@@ -272,9 +279,9 @@ Email.prototype.send = async function (settings) {
   const sendgrid = Manager.require('@sendgrid/mail');
   sendgrid.setApiKey(process.env.SENDGRID_API_KEY);
 
-  // If scheduled beyond the limit, queue it
+  // If scheduled beyond the limit, queue it for later
   if (email.sendAt && email.sendAt >= moment().add(SEND_AT_LIMIT, 'hours').unix()) {
-    await saveToEmailQueue(email, admin, assistant);
+    await saveToEmailQueue(settings, email.sendAt, admin, assistant);
 
     return {
       status: 'queued',
@@ -315,8 +322,13 @@ Email.prototype.send = async function (settings) {
 // --- Private helpers ---
 
 /**
- * Normalize recipient input into a consistent array of { email, name? } objects.
- * Entries with a `uid:` prefix are marked with `_uid` for later Firestore resolution.
+ * Normalize recipient input into a consistent array of { email, name?, _userDoc? } objects.
+ *
+ * Accepts:
+ *   - Email string: 'user@example.com'
+ *   - UID string (no @): 'abc123' — fetched from Firestore in resolveRecipients
+ *   - Email object: { email: 'user@example.com', name: 'John' }
+ *   - User doc object: { auth: { email: '...' }, personal: { name: { first: '...' } }, ... }
  */
 function normalizeRecipients(input) {
   if (!input) {
@@ -332,11 +344,18 @@ function normalizeRecipients(input) {
     }
 
     if (typeof item === 'string') {
-      if (item.startsWith('uid:')) {
-        result.push({ _uid: item.slice(4) });
-      } else {
+      if (item.includes('@')) {
         result.push({ email: item });
+      } else {
+        result.push({ _uid: item });
       }
+    } else if (typeof item === 'object' && item.auth?.email) {
+      // Full user doc — extract email/name and stash doc for template data
+      result.push({
+        email: item.auth.email,
+        ...(item.personal?.name?.first && { name: item.personal.name.first }),
+        _userDoc: item,
+      });
     } else if (typeof item === 'object' && item.email) {
       result.push({ email: item.email, ...(item.name && { name: item.name }) });
     }
@@ -346,7 +365,8 @@ function normalizeRecipients(input) {
 }
 
 /**
- * Resolve any uid-prefixed recipients by fetching user docs from Firestore.
+ * Resolve any UID recipients by fetching user docs from Firestore.
+ * Stashes the full user doc as `_userDoc` for template data resolution in build().
  */
 async function resolveRecipients(recipients, admin, assistant) {
   const uidEntries = recipients.filter(r => r._uid);
@@ -388,6 +408,7 @@ async function resolveRecipients(recipients, admin, assistant) {
     resolved.push({
       email,
       ...(data?.personal?.name?.first && { name: data.personal.name.first }),
+      _userDoc: data,
     });
   }
 
@@ -456,23 +477,28 @@ function normalizeSendAt(sendAt) {
 }
 
 /**
- * Save email to queue for deferred sending (beyond 71h limit)
+ * Save original settings to queue for deferred sending (beyond 71h limit).
+ * Stores the raw settings so the email can be re-sent through the full
+ * build pipeline when the cron picks it up.
  */
-async function saveToEmailQueue(email, admin, assistant) {
-  const emailId = email.dynamicTemplateData.email.id;
+async function saveToEmailQueue(settings, sendAt, admin, assistant) {
+  const powertools = require('node-powertools');
+  const emailId = powertools.random(32, { type: 'alphanumeric' });
 
-  // Clone and clean before storage
-  const emailCloned = _.cloneDeepWith(email, (value) => {
+  // Clone and clean undefined values for Firestore
+  const settingsCloned = _.cloneDeepWith(settings, (value) => {
     if (typeof value === 'undefined') {
       return null;
     }
   });
-  delete emailCloned.dynamicTemplateData._stringified;
 
-  assistant.log(`saveToEmailQueue(): Saving email ${emailId}`);
+  assistant.log(`saveToEmailQueue(): Saving ${emailId}, sendAt=${sendAt}`);
 
-  await admin.firestore().doc(`email-queue/${emailId}`)
-    .set(emailCloned)
+  await admin.firestore().doc(`emails-queue/${emailId}`)
+    .set({
+      settings: settingsCloned,
+      sendAt,
+    })
     .then(() => assistant.log(`saveToEmailQueue(): Success ${emailId}`))
     .catch(e => assistant.error(`saveToEmailQueue(): Failed ${emailId}`, e));
 }
@@ -500,38 +526,4 @@ function saveAuditTrail(email, messageId, admin, assistant) {
     .catch(e => assistant.error(`Audit trail failed: ${messageId}`, e));
 }
 
-/**
- * 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;
-}
-
-/**
- * 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'));
-}
-
-module.exports = Email;
+module.exports = Transactional;

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

@@ -0,0 +1,168 @@
+/**
+ * Email validation — single entry point for all email quality checks
+ *
+ * Available checks (run in this order):
+ * - format     — basic email regex
+ * - disposable — checks against known disposable domain list
+ * - localPart  — blocks spam/junk local parts (test, noreply, all-numeric, etc.)
+ * - mailbox  — verifies mailbox exists via API (costs money, requires ZEROBOUNCE_API_KEY)
+ *
+ * Usage:
+ *   validate(email)                                          // All free checks (format + disposable + localPart)
+ *   validate(email, { checks: ['format', 'disposable'] })    // Only format + disposable
+ *   validate(email, { checks: ALL_CHECKS })                  // Everything including mailbox
+ *
+ * Used by:
+ * - routes/marketing/contact/post.js
+ * - functions/core/actions/api/general/add-marketing-contact.js
+ * - routes/user/signup/post.js (disposable check only)
+ */
+const fetch = require('wonderful-fetch');
+const path = require('path');
+
+// Load disposable domains list once at module level
+const DISPOSABLE_DOMAINS = require(path.join(__dirname, '..', 'disposable-domains.json'));
+const DISPOSABLE_SET = new Set(DISPOSABLE_DOMAINS.map(d => d.toLowerCase()));
+
+// Spam/junk local parts — exact matches (checked after stripping +suffix)
+const BLOCKED_LOCAL_PARTS = new Set([
+  // Generic/test
+  'test', 'testing', 'tester', 'test1', 'test123',
+  'example', 'sample', 'demo', 'dummy', 'fake', 'temp',
+  // System/role addresses
+  'noreply', 'no-reply', 'donotreply', 'do-not-reply',
+  'mailer-daemon', 'postmaster', 'webmaster', 'hostmaster',
+  'abuse', 'spam', 'root',
+  // Keyboard walks / junk
+  'asdf', 'qwerty', 'zxcv', 'asd', 'qwe',
+  'aaa', 'bbb', 'xxx', 'zzz',
+  'abc', 'abc123', 'abcdef',
+  // Placeholder
+  'user', 'email', 'mail', 'hello', 'info',
+  'admin', 'administrator', 'support',
+  'contact', 'name', 'firstname', 'lastname',
+  'foo', 'bar', 'baz', 'foobar',
+  'null', 'undefined', 'none', 'anonymous',
+]);
+
+// Patterns that indicate junk local parts (checked after stripping +suffix)
+const BLOCKED_LOCAL_PATTERNS = [
+  /^\d+$/,           // All numeric: 123456
+  /^(.)\1{2,}$/,     // Repeating single char: aaaa, xxxx
+  /^[a-z]{1,2}\d+$/, // Single letter + numbers: a123, x999
+  /^test[._-]/,      // Starts with test separator: test.user, test_123
+];
+
+// Format regex
+const EMAIL_FORMAT = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+// Default checks (all free checks — mailbox excluded because it costs money)
+const DEFAULT_CHECKS = ['format', 'disposable', 'localPart'];
+
+// All available checks
+const ALL_CHECKS = ['format', 'disposable', 'localPart', 'mailbox'];
+
+/**
+ * Validate an email address through selected checks.
+ *
+ * Returns valid: true on mailbox API errors so emails are never silently dropped.
+ *
+ * @param {string} email
+ * @param {object} [options]
+ * @param {Array<string>} [options.checks] - Which checks to run (default: DEFAULT_CHECKS)
+ * @returns {{ valid: boolean, checks: { format?: object, disposable?: object, localPart?: object, mailbox?: object } }}
+ */
+async function validate(email, options = {}) {
+  const checks = new Set(options.checks || DEFAULT_CHECKS);
+  const result = { valid: true, checks: {} };
+
+  // 1. Format
+  if (checks.has('format')) {
+    if (!email || !EMAIL_FORMAT.test(email)) {
+      result.valid = false;
+      result.checks.format = { valid: false, reason: 'Invalid email format' };
+      return result;
+    }
+
+    result.checks.format = { valid: true };
+  }
+
+  const [rawLocalPart, domain] = (email || '').toLowerCase().split('@');
+
+  // 2. Disposable domain
+  if (checks.has('disposable') && domain) {
+    if (DISPOSABLE_SET.has(domain)) {
+      result.valid = false;
+      result.checks.disposable = { valid: false, blocked: true, domain };
+      return result;
+    }
+
+    result.checks.disposable = { valid: true, blocked: false };
+  }
+
+  // 3. Local part — strip +suffix before checking
+  if (checks.has('localPart') && rawLocalPart) {
+    const localPart = rawLocalPart.split('+')[0];
+
+    if (BLOCKED_LOCAL_PARTS.has(localPart)) {
+      result.valid = false;
+      result.checks.localPart = { valid: false, blocked: true, localPart, reason: 'Blocked local part' };
+      return result;
+    }
+
+    const blockedPattern = BLOCKED_LOCAL_PATTERNS.find((p) => p.test(localPart));
+
+    if (blockedPattern) {
+      result.valid = false;
+      result.checks.localPart = { valid: false, blocked: true, localPart, reason: 'Matches junk pattern' };
+      return result;
+    }
+
+    result.checks.localPart = { valid: true };
+  }
+
+  // 4. Mailbox verification (ZeroBounce)
+  if (checks.has('mailbox')) {
+    if (!process.env.ZEROBOUNCE_API_KEY) {
+      result.checks.mailbox = { valid: true, skipped: true, reason: 'No API key' };
+      return result;
+    }
+
+    try {
+      const data = await fetch(
+        `https://api.zerobounce.net/v2/validate?api_key=${process.env.ZEROBOUNCE_API_KEY}&email=${encodeURIComponent(email)}`,
+        { response: 'json', timeout: 10000 }
+      );
+
+      if (data.error) {
+        console.error('ZeroBounce API error:', data.error);
+        result.checks.mailbox = { valid: true, error: data.error };
+        return result;
+      }
+
+      if (!data.status) {
+        console.error('ZeroBounce unexpected response:', data);
+        result.checks.mailbox = { valid: true, error: 'Unexpected response format' };
+        return result;
+      }
+
+      const zbValid = data.status === 'valid';
+      result.checks.mailbox = {
+        valid: zbValid,
+        status: data.status,
+        subStatus: data.sub_status || null,
+      };
+
+      if (!zbValid) {
+        result.valid = false;
+      }
+    } catch (e) {
+      console.error('ZeroBounce validation error:', e);
+      result.checks.mailbox = { valid: true, error: e.message };
+    }
+  }
+
+  return result;
+}
+
+module.exports = { validate, DEFAULT_CHECKS, ALL_CHECKS };

package/src/manager/libraries/infer-contact.js

@@ -29,7 +29,7 @@ const GENERIC_DOMAINS = new Set([
  * @returns {{ firstName: string, lastName: string, company: string, confidence: number, method: string }}
  */
 async function inferContact(email, assistant) {
-  if (process.env.OPENAI_API_KEY) {
+  if (process.env.BACKEND_MANAGER_OPENAI_API_KEY) {
     const aiResult = await inferContactWithAI(email, assistant);
     if (aiResult && (aiResult.firstName || aiResult.lastName)) {
       return aiResult;

package/src/manager/routes/admin/cron/post.js

@@ -22,9 +22,9 @@ module.exports = async ({ assistant, Manager, user, settings, analytics }) => {
   assistant.log('Running cron job:', settings.id);
 
   // Run the cron job
-  const result = await Manager._process(
-    (new (require(`../../functions/core/cron/${settings.id}.js`))()).init(Manager, { context: {} })
-  ).catch(e => e);
+  const cronPath = require('path').resolve(__dirname, `../../../cron/${settings.id}.js`);
+  const cronHandler = require(cronPath);
+  const result = await cronHandler({ Manager, assistant, context: {} }).catch(e => e);
 
   if (result instanceof Error) {
     return assistant.respond(result.message, { code: 500 });

package/src/manager/routes/admin/email/post.js

@@ -4,7 +4,7 @@
  * Admin-only endpoint to send transactional emails.
  * Supports flexible recipient formats (string, object, UID, or arrays of mixed).
  *
- * See: src/manager/libraries/email.js for the shared email builder and sender.
+ * See: src/manager/libraries/email/ for the shared email builder and sender.
  */
 module.exports = async ({ assistant, user, settings }) => {
   // Require authentication

package/src/manager/routes/admin/stats/get.js

@@ -32,7 +32,7 @@ module.exports = async ({ assistant, Manager, user, settings, libraries }) => {
   if (!doc.exists) {
     await stats.set({
       users: { total: 0 },
-      app: Manager.config?.app?.id || null,
+      brand: Manager.config?.brand?.id || null,
     });
     data = { users: { total: 0 } };
   }
@@ -63,7 +63,7 @@ async function updateStats(assistant, existingData, update) {
   const { admin } = Manager.libraries;
   const stats = admin.firestore().doc('meta/stats');
   const newData = {
-    app: Manager.config?.app?.id || null,
+    brand: Manager.config?.brand?.id || null,
   };
 
   assistant.log('updateStats(): Starting...');

package/src/manager/routes/{app → brand}/get.js

@@ -1,5 +1,5 @@
 /**
- * GET /app - Public app configuration
+ * GET /brand - Public brand configuration
  * Returns a safe subset of the project's config (no secrets)
  */
 module.exports = async ({ assistant, Manager }) => {

package/src/manager/routes/general/email/templates/download-app-link.js

@@ -14,10 +14,10 @@ module.exports = function (payload, config) {
         email: payload.email,
         name: payload.name,
       },
+      sender: 'marketing',
       categories: ['download'],
       subject: `Free ${config.brand.name} download link for ${payload.name || 'you'}!`,
       template: 'main/misc/app-download-link',
-      group: 'marketing',
       copy: false,
       data: {},
     }