backend-manager 5.0.91 → 5.0.93

package/src/manager/libraries/email.js

@@ -0,0 +1,523 @@
+/**
+ * Shared email library for building and sending emails via SendGrid
+ *
+ * Usage:
+ *   const email = Manager.Email(assistant);
+ *   const result = await email.send(settings);
+ *
+ * Used by:
+ * - POST /admin/email route
+ * - POST /general/email route
+ * - Payment transition handlers (send-email.js)
+ * - Auth on-create handler (welcome/checkup/feedback emails)
+ */
+const _ = require('lodash');
+const moment = require('moment');
+
+// 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 = {
+  // v1 templates
+  'main/basic/card': 'd-b7f8da3c98ad49a2ad1e187f3a67b546',
+  'main/engagement/feedback': 'd-c1522214c67b47058669acc5a81ed663',
+  'main/misc/app-download-link': 'd-1d730ac8cc544b7cbccc8fa4a4b3f9ce',
+
+  // v2 templates
+  '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',
+};
+
+// "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 self = this;
+
+  self.assistant = assistant;
+  self.Manager = assistant.Manager;
+  self.admin = self.Manager.libraries.admin;
+
+  return self;
+}
+
+/**
+ * Build a complete SendGrid email object from settings.
+ *
+ * @param {object} settings - Email settings (to, cc, bcc, subject, template, etc.)
+ * @returns {object} SendGrid-ready email object
+ * @throws {Error} On validation failure
+ */
+Email.prototype.build = async function (settings) {
+  const self = this;
+  const Manager = self.Manager;
+  const admin = self.admin;
+  const assistant = self.assistant;
+  const powertools = require('node-powertools');
+
+  // Normalize recipients
+  let to = normalizeRecipients(settings.to);
+  let cc = normalizeRecipients(settings.cc);
+  let bcc = normalizeRecipients(settings.bcc);
+
+  // Resolve any uid: prefixed 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;
+
+  // Get brand config
+  const brand = Manager.config?.brand;
+
+  if (!brand) {
+    throw errorWithCode('Missing brand configuration in backend-manager-config.json', 400);
+  }
+
+  const app = {
+    id: brand.id,
+    name: brand.name,
+    url: brand.url,
+    email: brand.contact?.email,
+    images: sanitizeImagesForEmail(brand.images || {}),
+  };
+
+  if (!app.email) {
+    throw errorWithCode('Missing brand.contact.email in backend-manager-config.json', 400);
+  }
+
+  // Add carbon copy recipients
+  if (copy) {
+    cc.push({
+      email: app.email,
+      name: app.name,
+    });
+    bcc.push(
+      {
+        email: 'support@itwcreativeworks.com',
+        name: 'ITW Creative Works',
+      },
+      {
+        email: 'parser+carboncopy@sendgrid-parser.itwcreativeworks.com',
+        name: 'ITW Creative Works (Carbon Copy)',
+      }
+    );
+  }
+
+  // Deduplicate all lists
+  ({ to, cc, bcc } = deduplicateRecipients(to, cc, bcc));
+
+  // Delete empty names
+  for (const list of [to, cc, bcc]) {
+    for (const entry of list) {
+      if (!entry.name) {
+        delete entry.name;
+      }
+    }
+  }
+
+  // Validate
+  if (!to.length || !to[0].email) {
+    throw errorWithCode('Parameter to is required with at least one email', 400);
+  }
+
+  const subject = settings.subject || settings?.data?.email?.subject || null;
+
+  if (!subject) {
+    throw errorWithCode('Parameter subject is required', 400);
+  }
+
+  const templateId = TEMPLATES[settings.template] || settings.template || TEMPLATES['default'];
+  const groupId = GROUPS[settings.group] || settings.group || GROUPS['default'];
+  const copy = settings.copy ?? true;
+
+  // Build categories
+  const categories = _.uniq([
+    'transactional',
+    app.id,
+    ...powertools.arrayify(settings.categories),
+  ]);
+
+  // Normalize sendAt
+  const sendAt = normalizeSendAt(settings.sendAt);
+
+  // Build unsubscribe URL
+  const unsubscribeUrl = `${Manager.project.websiteUrl}/portal/account/email-preferences?email=${encode(to[0].email)}&asmId=${encode(groupId)}&templateId=${encode(templateId)}&appName=${app.name}&appUrl=${app.url}`;
+
+  // Build signoff
+  const signoff = settings?.data?.signoff || {};
+  signoff.type = signoff.type || 'team';
+
+  if (signoff.type === 'personal') {
+    signoff.image = signoff.image
+      || 'https://cdn.itwcreativeworks.com/assets/ian-wiedenman/images/website/ian-wiedenman-headshot-2021-color-1024x1024.jpg';
+    signoff.name = signoff.name || 'Ian Wiedenman, CEO';
+    signoff.url = signoff.url || 'https://ianwiedenman.com';
+    signoff.urlText = signoff.urlText || '@ianwieds';
+  }
+
+  // Build dynamic template data
+  const dynamicTemplateData = {
+    email: {
+      id: Manager.require('uuid').v4(),
+      subject: settings?.data?.email?.subject || subject,
+      preview: settings?.data?.email?.preview || null,
+      body: settings?.data?.email?.body || null,
+      unsubscribeUrl,
+      categories,
+      footer: {
+        text: settings?.data?.email?.footer?.text || null,
+      },
+      carbonCopy: copy,
+    },
+    personalization: {
+      email: to[0].email,
+      name: to[0].name,
+      ...settings?.data?.personalization,
+    },
+    signoff,
+    app,
+    user: userProperties,
+    data: settings.data || {},
+  };
+
+  // Build the email object
+  const email = {
+    to,
+    cc,
+    bcc,
+    from: settings.from || { email: app.email, name: app.name },
+    replyTo: settings.replyTo || app.email,
+    subject,
+    templateId,
+    asm: { groupId },
+    categories,
+    dynamicTemplateData,
+    substitutionWrappers: ['{{', '}}'],
+    headers: {
+      'List-Unsubscribe': `<${unsubscribeUrl}>`,
+    },
+  };
+
+  // Set sendAt
+  if (sendAt) {
+    email.sendAt = sendAt;
+  }
+
+  // Handle raw HTML override
+  if (settings.html) {
+    email.content = [{ type: 'text/html', value: settings.html }];
+    delete email.templateId;
+  }
+
+  // Build stringified version for template rendering
+  const clonedData = _.cloneDeep(dynamicTemplateData);
+  clonedData.app.sponsorships = {};
+  email.dynamicTemplateData._stringified = JSON.stringify(clonedData, null, 2);
+
+  return email;
+};
+
+/**
+ * Build and send an email via SendGrid, or queue it if scheduled beyond the limit.
+ * Calls .build() internally — callers only need to pass raw settings.
+ *
+ * @param {object} settings - Email settings (to, cc, bcc, subject, template, etc.)
+ * @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) {
+  const self = this;
+  const Manager = self.Manager;
+  const admin = self.admin;
+  const assistant = self.assistant;
+
+  assistant.log(`Email.send(): to=${JSON.stringify(settings.to)}, subject=${settings.subject}, template=${settings.template}`);
+
+  // Build email from settings (throws with code: 400 on validation failure)
+  const email = await self.build(settings);
+
+  // Initialize SendGrid
+  const sendgrid = Manager.require('@sendgrid/mail');
+  sendgrid.setApiKey(process.env.SENDGRID_API_KEY);
+
+  // If scheduled beyond the limit, queue it
+  if (email.sendAt && email.sendAt >= moment().add(SEND_AT_LIMIT, 'hours').unix()) {
+    await saveToEmailQueue(email, admin, assistant);
+
+    return {
+      status: 'queued',
+      options: email,
+      response: null,
+    };
+  }
+
+  // Send via SendGrid
+  const send = await sendgrid.send(email).catch(e => e);
+
+  if (send instanceof Error) {
+    const details = send?.response?.body?.errors || send;
+    assistant.error('Email send failed:', details);
+    throw errorWithCode(`Failed to send email: ${JSON.stringify(details)}`, 500);
+  }
+
+  // Extract message ID
+  const messageId = send[0].headers['x-message-id'];
+
+  assistant.log('Email send succeeded:', messageId, send);
+
+  // Save audit trail (non-blocking)
+  saveAuditTrail(email, messageId, admin, assistant);
+
+  // Track analytics
+  if (assistant.analytics) {
+    assistant.analytics.event('admin/email', { status: 'sent' });
+  }
+
+  return {
+    status: 'sent',
+    options: email,
+    response: send,
+  };
+};
+
+// --- 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.
+ */
+function normalizeRecipients(input) {
+  if (!input) {
+    return [];
+  }
+
+  const items = Array.isArray(input) ? input : [input];
+  const result = [];
+
+  for (const item of items) {
+    if (!item) {
+      continue;
+    }
+
+    if (typeof item === 'string') {
+      if (item.startsWith('uid:')) {
+        result.push({ _uid: item.slice(4) });
+      } else {
+        result.push({ email: item });
+      }
+    } else if (typeof item === 'object' && item.email) {
+      result.push({ email: item.email, ...(item.name && { name: item.name }) });
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Resolve any uid-prefixed recipients by fetching user docs from Firestore.
+ */
+async function resolveRecipients(recipients, admin, assistant) {
+  const uidEntries = recipients.filter(r => r._uid);
+  const nonUidEntries = recipients.filter(r => !r._uid);
+
+  if (uidEntries.length === 0) {
+    return nonUidEntries;
+  }
+
+  // Fetch all UIDs in parallel
+  const snapshots = await Promise.all(
+    uidEntries.map(entry =>
+      admin.firestore().doc(`users/${entry._uid}`).get()
+        .catch(e => {
+          assistant.error(`resolveRecipients(): Failed to fetch user ${entry._uid}`, e);
+          return null;
+        })
+    )
+  );
+
+  const resolved = [];
+
+  for (let i = 0; i < uidEntries.length; i++) {
+    const snap = snapshots[i];
+
+    if (!snap || !snap.exists) {
+      assistant.warn(`resolveRecipients(): User ${uidEntries[i]._uid} not found, skipping`);
+      continue;
+    }
+
+    const data = snap.data();
+    const email = data?.auth?.email;
+
+    if (!email) {
+      assistant.warn(`resolveRecipients(): User ${uidEntries[i]._uid} has no email, skipping`);
+      continue;
+    }
+
+    resolved.push({
+      email,
+      ...(data?.personal?.name?.first && { name: data.personal.name.first }),
+    });
+  }
+
+  return [...nonUidEntries, ...resolved];
+}
+
+/**
+ * Deduplicate recipients within each list and cross-dedup cc/bcc against to.
+ */
+function deduplicateRecipients(to, cc, bcc) {
+  const dedup = (arr) => {
+    const seen = new Set();
+
+    return arr.filter(r => {
+      if (!r.email || typeof r.email !== 'string') {
+        return false;
+      }
+
+      const key = r.email.toLowerCase();
+
+      if (seen.has(key)) {
+        return false;
+      }
+
+      seen.add(key);
+      return true;
+    });
+  };
+
+  to = dedup(to);
+
+  const toEmails = new Set(to.map(r => r.email.toLowerCase()));
+  cc = dedup(cc).filter(r => !toEmails.has(r.email.toLowerCase()));
+
+  const toCcEmails = new Set([...toEmails, ...cc.map(r => r.email.toLowerCase())]);
+  bcc = dedup(bcc).filter(r => !toCcEmails.has(r.email.toLowerCase()));
+
+  return { to, cc, bcc };
+}
+
+/**
+ * Normalize sendAt to a unix timestamp (seconds).
+ */
+function normalizeSendAt(sendAt) {
+  if (!sendAt && sendAt !== 0) {
+    return null;
+  }
+
+  if (typeof sendAt === 'number') {
+    // If it looks like milliseconds (> year 2100 in seconds), convert
+    if (sendAt > 4102444800) {
+      return Math.floor(sendAt / 1000);
+    }
+    return sendAt;
+  }
+
+  if (typeof sendAt === 'string') {
+    const parsed = moment(sendAt);
+
+    if (parsed.isValid()) {
+      return parsed.unix();
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Save email to queue for deferred sending (beyond 71h limit)
+ */
+async function saveToEmailQueue(email, admin, assistant) {
+  const emailId = email.dynamicTemplateData.email.id;
+
+  // Clone and clean before storage
+  const emailCloned = _.cloneDeepWith(email, (value) => {
+    if (typeof value === 'undefined') {
+      return null;
+    }
+  });
+  delete emailCloned.dynamicTemplateData._stringified;
+
+  assistant.log(`saveToEmailQueue(): Saving email ${emailId}`);
+
+  await admin.firestore().doc(`email-queue/${emailId}`)
+    .set(emailCloned)
+    .then(() => assistant.log(`saveToEmailQueue(): Success ${emailId}`))
+    .catch(e => assistant.error(`saveToEmailQueue(): Failed ${emailId}`, e));
+}
+
+/**
+ * Save sent email to Firestore for audit trail (non-blocking)
+ */
+function saveAuditTrail(email, messageId, admin, assistant) {
+  // Clone and clean before storage
+  const emailCloned = _.cloneDeepWith(email, (value) => {
+    if (typeof value === 'undefined') {
+      return null;
+    }
+  });
+  delete emailCloned.dynamicTemplateData._stringified;
+
+  admin.firestore().doc(`emails/${messageId}`)
+    .set({
+      id: messageId,
+      request: emailCloned,
+      body: { html: '', text: '' },
+      created: assistant.meta.startTime,
+    })
+    .then(() => assistant.log(`Audit trail saved: ${messageId}`))
+    .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;

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

@@ -0,0 +1,140 @@
+/**
+ * Shared contact inference library
+ *
+ * Infers first/last name and company from an email address.
+ * Tries AI first (if OPENAI_API_KEY is set), falls back to regex parsing.
+ *
+ * Usage:
+ *   const { inferContact } = require('./libraries/infer-contact.js');
+ *   const result = await inferContact(email, assistant);
+ *   // { firstName, lastName, company, confidence, method }
+ */
+const path = require('path');
+
+const PROMPT_PATH = path.join(__dirname, 'prompts', 'infer-contact.md');
+
+// Common email providers (don't infer company from these domains)
+const GENERIC_DOMAINS = new Set([
+  'gmail.com', 'yahoo.com', 'hotmail.com', 'outlook.com', 'aol.com',
+  'icloud.com', 'mail.com', 'protonmail.com', 'proton.me', 'zoho.com',
+  'yandex.com', 'gmx.com', 'live.com', 'msn.com', 'me.com',
+]);
+
+/**
+ * Infer contact info from email address
+ * Tries AI first (if OPENAI_API_KEY is set), falls back to regex
+ *
+ * @param {string} email - Email address
+ * @param {object} assistant - Assistant instance (for AI access)
+ * @returns {{ firstName: string, lastName: string, company: string, confidence: number, method: string }}
+ */
+async function inferContact(email, assistant) {
+  if (process.env.OPENAI_API_KEY) {
+    const aiResult = await inferContactWithAI(email, assistant);
+    if (aiResult && (aiResult.firstName || aiResult.lastName)) {
+      return aiResult;
+    }
+  }
+
+  return inferContactFromEmail(email);
+}
+
+/**
+ * Use AI to infer contact info from email
+ *
+ * @param {string} email - Email address
+ * @param {object} assistant - Assistant instance
+ * @returns {object|null} Inferred contact or null on failure
+ */
+async function inferContactWithAI(email, assistant) {
+  try {
+    const ai = assistant.Manager.AI(assistant);
+    const result = await ai.request({
+      model: 'gpt-5-mini',
+      timeout: 30000,
+      maxTokens: 1024,
+      moderate: false,
+      response: 'json',
+      prompt: {
+        path: PROMPT_PATH,
+      },
+      message: {
+        content: `Email: ${email}`,
+      },
+    });
+
+    if (result?.firstName !== undefined) {
+      return {
+        firstName: capitalize(result.firstName || ''),
+        lastName: capitalize(result.lastName || ''),
+        company: capitalize(result.company || ''),
+        confidence: typeof result.confidence === 'number' ? result.confidence : 0.5,
+        method: 'ai',
+      };
+    }
+  } catch (e) {
+    if (assistant) {
+      assistant.error('inferContactWithAI: Failed:', e);
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Regex-based contact inference from email
+ * Extracts name from local part and company from domain
+ *
+ * @param {string} email - Email address
+ * @returns {{ firstName: string, lastName: string, company: string, confidence: number, method: string }}
+ */
+function inferContactFromEmail(email) {
+  const [local, domain] = email.split('@');
+
+  // Infer company from domain (skip generic providers)
+  let company = '';
+  if (domain && !GENERIC_DOMAINS.has(domain.toLowerCase())) {
+    const domainName = domain.split('.')[0];
+    company = capitalize(domainName.replace(/[-_]/g, ' '));
+  }
+
+  // Infer name from local part
+  const cleaned = local.replace(/[0-9]+$/, '');
+  const parts = cleaned.split(/[._-]/);
+
+  if (parts.length >= 2) {
+    return {
+      firstName: capitalize(parts[0]),
+      lastName: capitalize(parts.slice(1).join(' ')),
+      company,
+      confidence: 0.5,
+      method: 'regex',
+    };
+  }
+
+  return {
+    firstName: capitalize(cleaned),
+    lastName: '',
+    company,
+    confidence: 0.25,
+    method: 'regex',
+  };
+}
+
+/**
+ * Capitalize first letter of each word
+ *
+ * @param {string} str - String to capitalize
+ * @returns {string} Capitalized string
+ */
+function capitalize(str) {
+  if (!str) {
+    return '';
+  }
+  return str
+    .split(' ')
+    .map(word => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+    .join(' ');
+}
+
+module.exports = { inferContact, inferContactFromEmail, capitalize };

package/src/manager/libraries/prompts/infer-contact.md

@@ -0,0 +1,43 @@
+<identity>
+You extract names and company from email addresses.
+</identity>
+
+<format>
+Return ONLY valid JSON like so:
+{
+  "firstName": "...",
+  "lastName": "...",
+  "company": "...",
+  "confidence": "..."
+}
+
+- firstName: First name (string), capitalized
+- lastName: Last name (string), capitalized
+- company: Company name (string), capitalized
+- confidence: Confidence level (number), 0-1 scale
+
+If you cannot determine a name, use empty strings.
+</format>
+
+<examples>
+<example>
+<input>john.smith@acme.com</input>
+<output>{"firstName": "John", "lastName": "Smith", "company": "Acme", "confidence": 0.9}</output>
+</example>
+<example>
+<input>jsmith123@gmail.com</input>
+<output>{"firstName": "J", "lastName": "Smith", "company": "", "confidence": 0.4}</output>
+</example>
+<example>
+<input>support@bigcorp.io</input>
+<output>{"firstName": "", "lastName": "", "company": "Bigcorp", "confidence": 0.7}</output>
+</example>
+<example>
+<input>mary_jane_watson@stark-industries.com</input>
+<output>{"firstName": "Mary", "lastName": "Watson", "company": "Stark Industries", "confidence": 0.85}</output>
+</example>
+<example>
+<input>info@company.org</input>
+<output>{"firstName": "", "lastName": "", "company": "Company", "confidence": 0.6}</output>
+</example>
+</examples>