backend-manager 5.0.154 → 5.0.157

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

@@ -51,6 +51,41 @@ async function resolveFieldIds() {
   }
 }
 
+// Cached segment name → SendGrid segment ID map
+let _segmentIdCache = null;
+
+/**
+ * Fetch segment definitions from SendGrid and build a name → id map.
+ * Segments are created by OMEGA with names matching the SSOT keys in constants.js.
+ * Cached in memory for the lifetime of the process.
+ *
+ * @returns {object} Map of segment name → SendGrid segment ID
+ */
+async function resolveSegmentIds() {
+  if (_segmentIdCache) {
+    return _segmentIdCache;
+  }
+
+  try {
+    const data = await fetch(`${BASE_URL}/marketing/segments/2.0`, {
+      response: 'json',
+      headers: headers(),
+      timeout: 10000,
+    });
+
+    _segmentIdCache = {};
+
+    for (const segment of (data.results || [])) {
+      _segmentIdCache[segment.name] = segment.id;
+    }
+
+    return _segmentIdCache;
+  } catch (e) {
+    console.error('SendGrid resolveSegmentIds error:', e);
+    return {};
+  }
+}
+
 // --- Contact Management ---
 
 /**
@@ -211,7 +246,7 @@ async function getListId() {
  * @param {object} [options.dynamicTemplateData] - Template variables
  * @returns {{ success: boolean, id?: string, error?: string }}
  */
-async function createSingleSend({ name, subject, templateId, from, sendTo, asmGroupId, categories, dynamicTemplateData }) {
+async function createSingleSend({ name, subject, preheader, templateId, from, sendTo, excludeSegments, asmGroupId, categories, dynamicTemplateData }) {
   try {
     const body = {
       name,
@@ -224,6 +259,10 @@ async function createSingleSend({ name, subject, templateId, from, sendTo, asmGr
       },
     };
 
+    if (preheader) {
+      body.email_config.html_content = `<span style="display:none">${preheader}</span>`;
+    }
+
     // Use design_editor with template
     if (templateId) {
       body.email_config.editor = 'design';
@@ -245,6 +284,17 @@ async function createSingleSend({ name, subject, templateId, from, sendTo, asmGr
       body.email_config.categories = categories;
     }
 
+    // Exclude segments from targeting
+    if (excludeSegments && excludeSegments.length) {
+      body.send_to = body.send_to || {};
+      body.send_to.exclude_segment_ids = excludeSegments;
+    }
+
+    // Dynamic template variables
+    if (dynamicTemplateData && Object.keys(dynamicTemplateData).length) {
+      body.email_config.dynamic_template_data = dynamicTemplateData;
+    }
+
     const data = await fetch(`${BASE_URL}/marketing/singlesends`, {
       method: 'post',
       response: 'json',
@@ -423,10 +473,138 @@ async function buildFields(userDoc) {
   return fields;
 }
 
+/**
+ * Get all contact emails in a segment (handles async export + download).
+ *
+ * @param {string} segmentId - SendGrid segment ID
+ * @param {number} [maxWaitMs=60000] - Max time to wait for export
+ * @returns {{ success: boolean, contacts?: Array<{email: string, id: string}>, error?: string }}
+ */
+async function getSegmentContacts(segmentId, maxWaitMs = 60000) {
+  try {
+    // Start export job
+    const exportData = await fetch(`${BASE_URL}/marketing/contacts/exports`, {
+      method: 'post',
+      response: 'json',
+      headers: headers(),
+      timeout: 15000,
+      body: { segment_ids: [segmentId] },
+    });
+
+    if (!exportData.id) {
+      return { success: false, error: 'Failed to start export' };
+    }
+
+    console.log(`SendGrid getSegmentContacts: Export started (job: ${exportData.id})`);
+
+    // Poll for completion
+    const startTime = Date.now();
+    let pollCount = 0;
+
+    while (Date.now() - startTime < maxWaitMs) {
+      await new Promise(r => setTimeout(r, 3000));
+      pollCount++;
+
+      const statusData = await fetch(`${BASE_URL}/marketing/contacts/exports/${exportData.id}`, {
+        response: 'json',
+        headers: headers(),
+        timeout: 10000,
+      });
+
+      console.log(`SendGrid getSegmentContacts: Poll #${pollCount} — ${statusData.status} (${Date.now() - startTime}ms)`);
+
+      if (statusData.status === 'ready' && statusData.urls?.length) {
+        // Download CSV — disable cacheBreaker to preserve presigned S3 URL signature
+        const csvText = await fetch(statusData.urls[0], {
+          response: 'text',
+          timeout: 30000,
+          cacheBreaker: false,
+        });
+
+        // Parse CSV — first line is headers, find email and id columns
+        const lines = csvText.trim().split('\n');
+
+        if (lines.length < 2) {
+          return { success: true, contacts: [] };
+        }
+
+        const headerCols = lines[0].split(',').map(h => h.replace(/"/g, '').trim().toLowerCase());
+        const emailIdx = headerCols.indexOf('email');
+        const idIdx = headerCols.indexOf('contact_id');
+
+        const contacts = [];
+
+        for (let i = 1; i < lines.length; i++) {
+          const cols = lines[i].split(',');
+          const email = cols[emailIdx]?.replace(/"/g, '').trim();
+          const id = cols[idIdx]?.replace(/"/g, '').trim();
+
+          if (email) {
+            contacts.push({ email, id });
+          }
+        }
+
+        console.log(`SendGrid getSegmentContacts: Downloaded ${contacts.length} contacts (${Date.now() - startTime}ms)`);
+
+        return { success: true, contacts };
+      }
+
+      if (statusData.status === 'failure') {
+        console.error('SendGrid getSegmentContacts: Export failed');
+        return { success: false, error: 'Export failed' };
+      }
+    }
+
+    console.error(`SendGrid getSegmentContacts: Timed out after ${maxWaitMs}ms (${pollCount} polls)`);
+    return { success: false, error: 'Export timed out' };
+  } catch (e) {
+    console.error('SendGrid getSegmentContacts error:', e);
+    return { success: false, error: e.message };
+  }
+}
+
+/**
+ * Bulk delete contacts by ID.
+ *
+ * @param {Array<string>} contactIds - SendGrid contact IDs
+ * @returns {{ success: boolean, jobId?: string, error?: string }}
+ */
+async function bulkDeleteContacts(contactIds) {
+  if (!contactIds.length) {
+    return { success: true, jobId: null };
+  }
+
+  try {
+    // SendGrid accepts up to 100 IDs per request
+    const ids = contactIds.slice(0, 100).join(',');
+    const data = await fetch(`${BASE_URL}/marketing/contacts?ids=${ids}`, {
+      method: 'delete',
+      response: 'json',
+      headers: headers(),
+      timeout: 15000,
+    });
+
+    if (data.job_id) {
+      return { success: true, jobId: data.job_id };
+    }
+
+    return { success: false, error: data.errors?.[0]?.message || 'Delete failed' };
+  } catch (e) {
+    console.error('SendGrid bulkDeleteContacts error:', e);
+    return { success: false, error: e.message };
+  }
+}
+
 module.exports = {
+  // Resolution
+  resolveFieldIds,
+  resolveSegmentIds,
+
   // Contacts
   addContact,
   removeContact,
+  getSegmentContacts,
+  bulkDeleteContacts,
   buildFields,
 
   // Campaigns (Single Sends)

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

@@ -30,6 +30,7 @@ const {
   encode,
   errorWithCode,
 } = require('../constants.js');
+const { tagLinks } = require('../utm.js');
 
 function Transactional(assistant) {
   const self = this;
@@ -195,6 +196,22 @@ Transactional.prototype.build = async function (settings) {
     settings.data.email.body = md.render(settings.data.email.body);
   }
 
+  // Tag links with UTM params for attribution
+  const utmOptions = {
+    brandUrl: brand?.url,
+    brandId: brand?.id,
+    campaign: settings.sender || templateId,
+    type: 'transactional',
+    utm: settings.utm,
+  };
+
+  if (settings?.data?.body?.message) {
+    settings.data.body.message = tagLinks(settings.data.body.message, utmOptions);
+  }
+  if (settings?.data?.email?.body) {
+    settings.data.email.body = tagLinks(settings.data.email.body, utmOptions);
+  }
+
   // Build dynamic template data
   const dynamicTemplateData = {
     email: {

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

@@ -0,0 +1,116 @@
+/**
+ * UTM link tagging for email HTML content
+ *
+ * Scans HTML for <a href> tags pointing to the brand's domain
+ * and appends UTM parameters for attribution tracking.
+ *
+ * Used by: marketing/index.js (campaigns), transactional/index.js (emails)
+ */
+
+const DEFAULT_UTM = {
+  utm_source: null,    // Defaults to brand.id at runtime
+  utm_medium: 'email',
+  utm_campaign: null,  // Defaults to campaign name or email template
+};
+
+/**
+ * Append UTM parameters to all links matching the brand's domain(s).
+ *
+ * @param {string} html - HTML content with <a href="..."> links
+ * @param {object} options
+ * @param {string} options.brandUrl - Brand URL (e.g., 'https://somiibo.com')
+ * @param {string} options.brandId - Brand ID (e.g., 'somiibo') — used as default utm_source
+ * @param {string} [options.campaign] - Campaign/template name — used as default utm_campaign
+ * @param {string} [options.type] - 'marketing' or 'transactional' — used as utm_content
+ * @param {object} [options.utm] - Override/additional UTM params (e.g., { utm_term: 'spring' })
+ * @returns {string} HTML with UTM params appended to matching links
+ */
+function tagLinks(html, options) {
+  if (!html || !options.brandUrl) {
+    return html;
+  }
+
+  // Extract brand hostname(s) to match against
+  const brandHostnames = extractHostnames(options.brandUrl);
+
+  if (!brandHostnames.length) {
+    return html;
+  }
+
+  // Build UTM params
+  const utm = {
+    ...DEFAULT_UTM,
+    utm_source: options.brandId || DEFAULT_UTM.utm_source,
+    utm_campaign: options.campaign || DEFAULT_UTM.utm_campaign,
+    utm_content: options.type || undefined,
+    ...options.utm,
+  };
+
+  // Remove null/undefined values
+  const utmParams = {};
+
+  for (const [key, value] of Object.entries(utm)) {
+    if (value != null && value !== '') {
+      utmParams[key] = String(value);
+    }
+  }
+
+  if (!Object.keys(utmParams).length) {
+    return html;
+  }
+
+  // Replace href values in <a> tags
+  return html.replace(/<a\s([^>]*?)href=["']([^"']+)["']/gi, (match, before, href) => {
+    try {
+      const url = new URL(href);
+
+      // Only tag links to the brand's domain
+      if (!brandHostnames.includes(url.hostname.toLowerCase())) {
+        return match;
+      }
+
+      // Append UTM params (don't override existing ones)
+      for (const [key, value] of Object.entries(utmParams)) {
+        if (!url.searchParams.has(key)) {
+          url.searchParams.set(key, value);
+        }
+      }
+
+      return `<a ${before}href="${url.toString()}"`;
+    } catch (e) {
+      // Not a valid URL (relative path, mailto:, etc.) — skip
+      return match;
+    }
+  });
+}
+
+/**
+ * Extract hostnames from a brand URL.
+ * Returns the base domain + www variant.
+ *
+ * @param {string} brandUrl
+ * @returns {string[]}
+ */
+function extractHostnames(brandUrl) {
+  try {
+    const url = new URL(brandUrl);
+    const hostname = url.hostname.toLowerCase();
+    const hostnames = [hostname];
+
+    // Add www variant
+    if (hostname.startsWith('www.')) {
+      hostnames.push(hostname.slice(4));
+    } else {
+      hostnames.push(`www.${hostname}`);
+    }
+
+    return hostnames;
+  } catch (e) {
+    return [];
+  }
+}
+
+module.exports = {
+  tagLinks,
+  DEFAULT_UTM,
+};

package/src/manager/libraries/notification.js

@@ -0,0 +1,223 @@
+/**
+ * Push notification library — send FCM notifications to subscribers
+ *
+ * Usage:
+ *   const notification = require('./libraries/notification.js');
+ *   await notification.send(assistant, { title, body, icon, clickAction, filters });
+ *
+ * Used by:
+ * - POST /admin/notification route
+ * - marketing-campaigns cron job (type: 'push')
+ */
+const PATH_NOTIFICATIONS = 'notifications';
+const BAD_TOKEN_REASONS = [
+  'messaging/invalid-registration-token',
+  'messaging/registration-token-not-registered',
+];
+const BATCH_SIZE = 500;
+
+/**
+ * Send push notification to FCM subscribers.
+ *
+ * @param {object} assistant - BEM assistant instance
+ * @param {object} options
+ * @param {string} options.title - Notification title
+ * @param {string} options.body - Notification body
+ * @param {string} [options.icon] - Notification icon URL
+ * @param {string} [options.clickAction] - URL to open on click
+ * @param {object} [options.filters] - Targeting filters
+ * @param {Array<string>} [options.filters.tags] - Filter by tags
+ * @param {string} [options.filters.owner] - Filter by owner UID
+ * @param {string} [options.filters.token] - Send to specific token
+ * @param {number} [options.filters.limit] - Max tokens to send to
+ * @returns {{ subscribers: number, batches: number, sent: number, deleted: number }}
+ */
+async function send(assistant, options) {
+  const { title, body, icon, clickAction, filters } = options;
+
+  if (!title || !body) {
+    throw new Error('Notification title and body are required');
+  }
+
+  // Build notification payload
+  const notification = {
+    title,
+    body,
+    imageUrl: icon
+      || 'https://cdn.itwcreativeworks.com/assets/itw-creative-works/images/socials/itw-creative-works-brandmark-square-black-1024x1024.png',
+    click_action: clickAction || 'https://itwcreativeworks.com',
+  };
+
+  // Add cache buster to click_action URL
+  try {
+    const url = new URL(notification.click_action);
+    url.searchParams.set('cb', new Date().getTime());
+    notification.click_action = url.toString();
+  } catch (e) {
+    throw new Error(`Invalid click_action URL: ${e.message}`);
+  }
+
+  assistant.log('notification.send():', notification);
+
+  const response = { subscribers: 0, batches: 0, sent: 0, deleted: 0 };
+  const filterOptions = {
+    tags: filters?.tags || false,
+    owner: filters?.owner || null,
+    token: filters?.token || null,
+    limit: filters?.limit || null,
+  };
+
+  await processTokens(assistant, notification, filterOptions, response);
+
+  return response;
+}
+
+async function processTokens(assistant, notification, options, response) {
+  const Manager = assistant.Manager;
+
+  // Specific token — send directly
+  if (options.token) {
+    assistant.log(`Sending to specific token: ${options.token}`);
+
+    try {
+      await sendBatch(assistant, [options.token], 0, notification, response);
+    } catch (e) {
+      assistant.error('Error sending to specific token', e);
+    }
+
+    return;
+  }
+
+  // Build query conditions
+  const queryConditions = [];
+
+  if (options.tags) {
+    queryConditions.push({ field: 'tags', operator: 'array-contains-any', value: options.tags });
+  }
+  if (options.owner) {
+    queryConditions.push({ field: 'owner', operator: '==', value: options.owner });
+  }
+
+  const maxBatches = options.limit
+    ? Math.ceil(options.limit / BATCH_SIZE)
+    : Infinity;
+
+  assistant.log('Processing tokens with filters:', {
+    tags: options.tags,
+    owner: options.owner,
+    limit: options.limit,
+    maxBatches,
+  });
+
+  let tokensProcessed = 0;
+
+  await Manager.Utilities().iterateCollection(
+    async (batch, index) => {
+      let batchTokens = [];
+
+      for (const doc of batch.docs) {
+        if (options.limit && tokensProcessed >= options.limit) {
+          break;
+        }
+
+        const data = doc.data();
+        batchTokens.push(data.token);
+        tokensProcessed++;
+      }
+
+      if (batchTokens.length === 0) {
+        return;
+      }
+
+      try {
+        assistant.log(`Sending batch ${index} with ${batchTokens.length} tokens.`);
+        await sendBatch(assistant, batchTokens, index, notification, response);
+      } catch (e) {
+        assistant.error(`Error sending batch ${index}`, e);
+      }
+    },
+    {
+      collection: PATH_NOTIFICATIONS,
+      where: queryConditions,
+      batchSize: BATCH_SIZE,
+      maxBatches,
+      log: true,
+    }
+  ).catch(e => {
+    assistant.error(`Error during token processing: ${e}`);
+  });
+}
+
+async function sendBatch(assistant, batch, id, notification, response) {
+  const { admin } = assistant.Manager.libraries;
+
+  assistant.log(`Sending batch #${id}: tokens=${batch.length}...`);
+
+  const messages = batch.map(token => ({
+    token,
+    notification: {
+      title: notification.title,
+      body: notification.body,
+      imageUrl: notification.imageUrl,
+    },
+    webpush: {
+      notification: {
+        title: notification.title,
+        body: notification.body,
+        icon: notification.imageUrl,
+        click_action: notification.click_action,
+      },
+      data: {
+        click_action: notification.click_action,
+      },
+      fcm_options: {
+        link: notification.click_action,
+      },
+    },
+    data: {
+      click_action: notification.click_action,
+    },
+  }));
+
+  const result = await admin.messaging().sendEach(messages);
+
+  assistant.log(`Sent batch #${id}: success=${result.successCount}, failures=${result.failureCount}`);
+
+  result.responses = result.responses.map((item, index) => {
+    item.token = batch[index];
+    return item;
+  });
+
+  // Clean bad tokens
+  if (result.failureCount > 0) {
+    await cleanTokens(assistant, batch, result.responses, id, response);
+  }
+
+  response.sent += (batch.length - result.failureCount);
+  response.batches++;
+}
+
+async function cleanTokens(assistant, batch, results, id, response) {
+  const { admin } = assistant.Manager.libraries;
+
+  const cleanPromises = results
+    .map((item) => {
+      if (!item.error || !BAD_TOKEN_REASONS.includes(item?.error?.code)) {
+        return null;
+      }
+
+      return admin.firestore().doc(`${PATH_NOTIFICATIONS}/${item.token}`).delete()
+        .then(() => {
+          assistant.log(`Deleted bad token: ${item.token} (${item.error.code})`);
+          response.deleted++;
+        })
+        .catch((e) => {
+          assistant.error(`Failed to delete bad token: ${item.token}`, e);
+        });
+    })
+    .filter(Boolean);
+
+  await Promise.all(cleanPromises);
+}
+
+module.exports = { send };