@omega.js/backend 0.1.0

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

@@ -0,0 +1,845 @@
+/**
+ * SendGrid provider — shared API helpers for contacts and Single Sends
+ *
+ * Used by: marketing/index.js (sync, remove, campaigns)
+ */
+const fetch = require('wonderful-fetch');
+const Manager = require('../../../index.js');
+const { resolveFieldValues, fieldsForProvider } = require('../constants.js');
+const env = require('../../env.js');
+
+const BASE_URL = 'https://api.sendgrid.com/v3';
+
+// SendGrid's API is normally fast (<2s) but spikes past 10s during their
+// hiccups, dropping signups silently. 60s is generous but harmless — the
+// metadata calls (resolveFieldIds, getListId) are cached for the process
+// lifetime so a slow first call costs nothing in steady state.
+const SENDGRID_TIMEOUT_MS = 60000;
+
+// --- Internal helpers ---
+
+function headers() {
+  return {
+    'Authorization': `Bearer ${env.get('SENDGRID_API_KEY')}`,
+  };
+}
+
+// Cached field name → SendGrid ID map (e.g., { brand_id: 'e1_T', user_auth_uid: 'e2_T' })
+let _fieldIdCache = null;
+
+/**
+ * Fetch custom field definitions from SendGrid and build a name → id map.
+ * Cached in memory for the lifetime of the process.
+ *
+ * @returns {object} Map of field name → SendGrid field ID
+ */
+async function resolveFieldIds() {
+  if (_fieldIdCache) {
+    return _fieldIdCache;
+  }
+
+  try {
+    const data = await fetch(`${BASE_URL}/marketing/field_definitions`, {
+      response: 'json',
+      headers: headers(),
+      timeout: SENDGRID_TIMEOUT_MS,
+    });
+
+    _fieldIdCache = {};
+
+    for (const field of (data.custom_fields || [])) {
+      _fieldIdCache[field.name] = field.id;
+    }
+
+    console.log(`SendGrid resolveFieldIds: ${Object.keys(_fieldIdCache).length} fields loaded:`, _fieldIdCache);
+
+    return _fieldIdCache;
+  } catch (e) {
+    console.error('SendGrid resolveFieldIds error:', e);
+    return {};
+  }
+}
+
+// Cached sender from_email → sender_id map
+let _senderIdCache = null;
+
+/**
+ * Fetch sender identities from SendGrid and build a from_email → id map.
+ * Sender identities are created by OMEGA's sendgrid/ensure/sender-identity handler.
+ * Cached in memory for the lifetime of the process.
+ *
+ * @returns {object} Map of from_email → sender ID (integer)
+ */
+async function resolveSenderIds() {
+  if (_senderIdCache) {
+    return _senderIdCache;
+  }
+
+  try {
+    const data = await fetch(`${BASE_URL}/verified_senders`, {
+      response: 'json',
+      headers: headers(),
+      timeout: SENDGRID_TIMEOUT_MS,
+    });
+
+    _senderIdCache = {};
+
+    for (const sender of (data?.results || [])) {
+      if (sender.from_email) {
+        _senderIdCache[sender.from_email] = sender.id;
+      }
+    }
+
+    console.log(`SendGrid resolveSenderIds: ${Object.keys(_senderIdCache).length} senders loaded:`, _senderIdCache);
+
+    return _senderIdCache;
+  } catch (e) {
+    console.error('SendGrid resolveSenderIds error:', e);
+    return {};
+  }
+}
+
+// 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: SENDGRID_TIMEOUT_MS,
+    });
+
+    _segmentIdCache = {};
+
+    for (const segment of (data.results || [])) {
+      _segmentIdCache[segment.name] = segment.id;
+    }
+
+    console.log(`SendGrid resolveSegmentIds: ${Object.keys(_segmentIdCache).length} segments loaded:`, _segmentIdCache);
+
+    return _segmentIdCache;
+  } catch (e) {
+    console.error('SendGrid resolveSegmentIds error:', e);
+    return {};
+  }
+}
+
+// --- Dynamic Segments (brand-scoped temp segments) ---
+
+/**
+ * Fetch a segment's query_dsl by ID.
+ */
+async function getSegmentQuery(segmentId) {
+  const data = await fetch(`${BASE_URL}/marketing/segments/2.0/${segmentId}`, {
+    response: 'json',
+    headers: headers(),
+    timeout: SENDGRID_TIMEOUT_MS,
+  });
+  return data.query_dsl;
+}
+
+/**
+ * Create a temporary brand-scoped segment by combining existing segment queries
+ * with a brand_id filter.
+ *
+ * SendGrid's send_to.segment_ids is a UNION (OR), not an intersection. To achieve
+ * AND behavior (e.g. "cancelled users ON THIS BRAND"), we create a single temp
+ * segment whose query_dsl ANDs the original conditions with brand_id = '<brand>'.
+ *
+ * The temp segment is immediately usable in send_to.segment_ids — SendGrid evaluates
+ * the query at send dispatch time, not at segment creation time.
+ *
+ * Ideal solution is per-brand SendGrid subusers (full isolation), but that requires
+ * a Pro plan. This is the workaround for shared-account multi-brand setups.
+ *
+ * @param {string[]} segmentIds - Original segment IDs to combine (ANDed together)
+ * @param {string} brandId - Brand ID to scope to (injected as AND brand_id = '<brandId>')
+ * @param {object} [options]
+ * @param {boolean} [options.skipBrandFilter] - If true, don't add brand_id condition (used for test mode)
+ * @returns {{ segmentId: string, cleanup: () => Promise<void> }}
+ */
+async function createBrandScopedSegment(segmentIds, brandId, options = {}) {
+  console.log('SendGrid createBrandScopedSegment: starting', { segmentIds, brandId, options });
+
+  const whereParts = [];
+
+  if (!options.skipBrandFilter && brandId) {
+    whereParts.push(`"brand_id" = '${brandId}'`);
+    console.log(`SendGrid createBrandScopedSegment: added brand filter — "brand_id" = '${brandId}'`);
+  }
+
+  for (const id of segmentIds) {
+    console.log(`SendGrid createBrandScopedSegment: fetching query for segment ${id}...`);
+    const query = await getSegmentQuery(id);
+    console.log(`SendGrid createBrandScopedSegment: segment ${id} query_dsl:`, query || '(empty)');
+
+    if (!query) {
+      console.warn(`SendGrid createBrandScopedSegment: segment ${id} has no query_dsl, skipping`);
+      continue;
+    }
+
+    const whereMatch = query.match(/WHERE\s+(.+)$/i);
+    if (whereMatch) {
+      whereParts.push(`(${whereMatch[1]})`);
+      console.log(`SendGrid createBrandScopedSegment: extracted WHERE clause from ${id}:`, whereMatch[1]);
+    } else {
+      console.warn(`SendGrid createBrandScopedSegment: segment ${id} query has no WHERE clause, skipping`);
+    }
+  }
+
+  if (whereParts.length === 0) {
+    console.warn('SendGrid createBrandScopedSegment: no conditions resolved, returning null');
+    return null;
+  }
+
+  const combinedQuery = `SELECT contact_id, updated_at FROM contact_data WHERE ${whereParts.join(' AND ')}`;
+  const name = `__temp_${brandId || 'global'}_${Date.now()}`;
+
+  console.log('SendGrid createBrandScopedSegment: creating temp segment', { name, combinedQuery });
+
+  const start = Date.now();
+  const data = await fetch(`${BASE_URL}/marketing/segments/2.0`, {
+    method: 'post',
+    response: 'json',
+    headers: headers(),
+    timeout: SENDGRID_TIMEOUT_MS,
+    body: { name, query_dsl: combinedQuery },
+  });
+
+  console.log(`SendGrid createBrandScopedSegment: created in ${Date.now() - start}ms`, { id: data.id, contacts_count: data.contacts_count });
+
+  return {
+    segmentId: data.id,
+    cleanup: async () => {
+      try {
+        await fetch(`${BASE_URL}/marketing/segments/2.0/${data.id}`, {
+          method: 'delete',
+          headers: headers(),
+          timeout: SENDGRID_TIMEOUT_MS,
+        });
+        console.log(`SendGrid cleanup: deleted temp segment ${data.id} (${name})`);
+      } catch (e) {
+        console.error(`SendGrid cleanup: failed to delete temp segment ${data.id}:`, e.message);
+      }
+    },
+  };
+}
+
+// --- Contact Management ---
+
+/**
+ * Upsert contacts to SendGrid Marketing Contacts.
+ * Creates if new, merges/overwrites fields if existing.
+ *
+ * @param {object} options
+ * @param {Array<object>} options.contacts - Array of contact objects ({ email, first_name, last_name, custom_fields })
+ * @param {Array<string>} [options.listIds] - List IDs to add contacts to
+ * @returns {{ success: boolean, jobId?: string, error?: string }}
+ */
+async function upsertContacts({ contacts, listIds }) {
+  try {
+    const body = { contacts };
+
+    if (listIds && listIds.length) {
+      body.list_ids = listIds;
+    }
+
+    const data = await fetch(`${BASE_URL}/marketing/contacts`, {
+      method: 'put',
+      response: 'json',
+      headers: headers(),
+      timeout: SENDGRID_TIMEOUT_MS,
+      body,
+    });
+
+    if (data.job_id) {
+      return { success: true, jobId: data.job_id };
+    }
+
+    return { success: false, error: data.errors?.[0]?.message || 'Unknown error' };
+  } catch (e) {
+    console.error('SendGrid upsertContacts error:', e);
+    return { success: false, error: e.message };
+  }
+}
+
+/**
+ * Look up a SendGrid contact by email. Returns the contact object (id, email,
+ * list_ids, custom_fields, ...) or null if not found.
+ *
+ * Useful for tests that need to verify whether a contact landed in the list
+ * after a marketing sync.
+ *
+ * @param {string} email
+ * @returns {Promise<object|null>}
+ */
+async function findContact(email) {
+  try {
+    const searchData = await fetch(`${BASE_URL}/marketing/contacts/search/emails`, {
+      method: 'post',
+      response: 'json',
+      headers: headers(),
+      timeout: SENDGRID_TIMEOUT_MS,
+      body: { emails: [email] },
+    });
+
+    return searchData.result?.[email]?.contact || null;
+  } catch (e) {
+    // 404 is the normal "not in contacts" response — return null silently.
+    if (e.status === 404) {
+      return null;
+    }
+    console.error('SendGrid findContact error:', e);
+    return null;
+  }
+}
+
+/**
+ * Remove a contact from SendGrid by email address.
+ *
+ * @param {string} email
+ * @returns {{ success: boolean, jobId?: string, skipped?: boolean, error?: string }}
+ */
+async function removeContact(email) {
+  try {
+    // Step 1: Get contact ID by email
+    const contact = await findContact(email);
+
+    if (!contact?.id) {
+      return { success: true, skipped: true, reason: 'Contact not found' };
+    }
+
+    const contactId = contact.id;
+
+    // Step 2: Delete contact by ID
+    const deleteData = await fetch(`${BASE_URL}/marketing/contacts?ids=${contactId}`, {
+      method: 'delete',
+      response: 'json',
+      headers: headers(),
+      timeout: SENDGRID_TIMEOUT_MS,
+    });
+
+    if (deleteData.job_id) {
+      return { success: true, jobId: deleteData.job_id };
+    }
+
+    return { success: false, error: deleteData.errors?.[0]?.message || 'Delete failed' };
+  } catch (e) {
+    console.error('SendGrid removeContact error:', e);
+    return { success: false, error: e.message };
+  }
+}
+
+/**
+ * Get this brand's SendGrid Marketing list ID.
+ *
+ * Reads `Manager.config.marketing.campaigns.providers.sendgrid.listId` (#425) —
+ * populated by OMEGA's `campaigns/ensure/list.js` at brand-onboarding time, same
+ * as how Beehiiv's `publicationId` works. No runtime API call, no fuzzy-match
+ * fragility.
+ *
+ * If the brand hasn't been onboarded yet (listId missing/empty), logs a
+ * warning and returns null — the marketing sync will still succeed, but the
+ * contact lands in SendGrid's global pool instead of the brand's list. Fix:
+ * run OMEGA's sendgrid service to populate the config.
+ *
+ * @returns {string|null} List ID or null if not configured
+ */
+function getListId() {
+  const listId = Manager.config.marketing?.campaigns?.providers?.sendgrid?.listId;
+
+  if (!listId) {
+    console.warn(
+      'SendGrid: marketing.campaigns.providers.sendgrid.listId is not set in config. '
+      + 'Contact will be added to All Contacts only, not the brand list. '
+      + 'Run OMEGA to populate.',
+    );
+    return null;
+  }
+
+  return listId;
+}
+
+// LEGACY: Fuzzy-match-by-brand-name fallback. Kept commented out as a backstop
+// in case the config-based approach has an edge case we haven't seen yet.
+// Delete once we've verified the config-based approach works across all brands.
+//
+// async function getListIdByFuzzyMatch() {
+//   const brandName = Manager.config.brand?.name;
+//   const brandNameLower = (brandName || '').toLowerCase();
+//   const allLists = [];
+//   let pageToken = '';
+//   const pageSize = 1000;
+//
+//   try {
+//     while (true) {
+//       const url = `${BASE_URL}/marketing/lists?page_size=${pageSize}${pageToken ? `&page_token=${pageToken}` : ''}`;
+//       const data = await fetch(url, {
+//         response: 'json',
+//         headers: headers(),
+//         timeout: SENDGRID_TIMEOUT_MS,
+//       });
+//
+//       if (!data.result || data.result.length === 0) {
+//         break;
+//       }
+//
+//       const matchedList = data.result.find(list =>
+//         list.name.toLowerCase() === brandNameLower
+//         || list.name.toLowerCase().includes(brandNameLower)
+//         || brandNameLower.includes(list.name.toLowerCase())
+//       );
+//
+//       if (matchedList) {
+//         return matchedList.id;
+//       }
+//
+//       allLists.push(...data.result);
+//
+//       if (!data._metadata?.next) {
+//         break;
+//       }
+//
+//       const nextUrl = new URL(data._metadata.next);
+//       pageToken = nextUrl.searchParams.get('page_token');
+//
+//       if (!pageToken) {
+//         break;
+//       }
+//     }
+//
+//     if (allLists.length === 1) {
+//       return allLists[0].id;
+//     }
+//
+//     if (allLists.length > 0) {
+//       console.error(`SendGrid: No list matched brand "${brandName}". Available: ${allLists.map(l => l.name).join(', ')}`);
+//     }
+//   } catch (e) {
+//     console.error('SendGrid list lookup error:', e);
+//   }
+//
+//   return null;
+// }
+
+// --- Single Sends (Campaigns) ---
+
+/**
+ * Create a Single Send (marketing campaign).
+ * Accepts pre-rendered HTML (from MJML pipeline) as htmlContent.
+ *
+ * @param {object} options
+ * @param {string} options.name - Campaign name
+ * @param {string} options.subject - Email subject
+ * @param {string} options.htmlContent - Complete rendered HTML email
+ * @param {object} options.from - { email, name }
+ * @param {object} options.sendTo - { list_ids?, segment_ids?, all? }
+ * @param {number} [options.asmGroupId] - Unsubscribe group ID
+ * @param {Array<string>} [options.categories] - Email categories
+ * @returns {{ success: boolean, id?: string, error?: string }}
+ */
+async function createSingleSend({ name, subject, htmlContent, from, sendTo, excludeSegments, asmGroupId, categories }) {
+  try {
+    const body = {
+      name,
+      send_to: sendTo,
+      email_config: {
+        subject,
+        editor: 'code',
+        html_content: htmlContent,
+        generate_plain_content: true,
+      },
+    };
+
+    // Resolve sender_id from registered Sender Identities (created by OMEGA)
+    if (from) {
+      const senderIdMap = await resolveSenderIds();
+      const senderId = senderIdMap[from.email];
+
+      if (senderId) {
+        body.email_config.sender_id = senderId;
+      } else {
+        return {
+          success: false,
+          error: `No SendGrid Sender Identity found for "${from.email}". Run OMEGA sendgrid service to create one.`,
+        };
+      }
+    }
+
+    if (asmGroupId) {
+      body.email_config.suppression_group_id = asmGroupId;
+    }
+
+    if (categories && categories.length) {
+      body.email_config.categories = categories;
+    }
+
+    if (excludeSegments && excludeSegments.length) {
+      body.send_to = body.send_to || {};
+      body.send_to.exclude_segment_ids = excludeSegments;
+    }
+
+    console.log('SendGrid createSingleSend body:', JSON.stringify(body, null, 2));
+
+    const data = await fetch(`${BASE_URL}/marketing/singlesends`, {
+      method: 'post',
+      response: 'json',
+      headers: headers(),
+      timeout: SENDGRID_TIMEOUT_MS,
+      body,
+    });
+
+    if (data.id) {
+      return { success: true, id: data.id };
+    }
+
+    return { success: false, error: data.errors?.[0]?.message || 'Unknown error' };
+  } catch (e) {
+    console.error('SendGrid createSingleSend error:', e);
+    return { success: false, error: e.message };
+  }
+}
+
+/**
+ * Schedule a Single Send for delivery.
+ *
+ * @param {string} singleSendId - The Single Send ID
+ * @param {string} sendAt - ISO 8601 datetime string (e.g., '2026-04-01T14:00:00Z'), or 'now'
+ * @returns {{ success: boolean, error?: string }}
+ */
+async function scheduleSingleSend(singleSendId, sendAt) {
+  try {
+    const data = await fetch(`${BASE_URL}/marketing/singlesends/${singleSendId}/schedule`, {
+      method: 'put',
+      response: 'json',
+      headers: headers(),
+      timeout: SENDGRID_TIMEOUT_MS,
+      body: { send_at: sendAt },
+    });
+
+    console.log('SendGrid scheduleSingleSend response:', JSON.stringify(data, null, 2));
+
+    if (data.send_at || data.status === 'scheduled') {
+      return { success: true };
+    }
+
+    return { success: false, error: data.errors?.[0]?.message || 'Schedule failed' };
+  } catch (e) {
+    console.error('SendGrid scheduleSingleSend error:', e);
+    return { success: false, error: e.message };
+  }
+}
+
+/**
+ * Cancel a scheduled Single Send.
+ *
+ * @param {string} singleSendId
+ * @returns {{ success: boolean, error?: string }}
+ */
+async function cancelSingleSend(singleSendId) {
+  try {
+    const data = await fetch(`${BASE_URL}/marketing/singlesends/${singleSendId}`, {
+      method: 'delete',
+      response: 'json',
+      headers: headers(),
+      timeout: SENDGRID_TIMEOUT_MS,
+    });
+
+    return { success: true };
+  } catch (e) {
+    console.error('SendGrid cancelSingleSend error:', e);
+    return { success: false, error: e.message };
+  }
+}
+
+/**
+ * Get a Single Send by ID.
+ *
+ * @param {string} singleSendId
+ * @returns {object|null}
+ */
+async function getSingleSend(singleSendId) {
+  try {
+    const data = await fetch(`${BASE_URL}/marketing/singlesends/${singleSendId}`, {
+      response: 'json',
+      headers: headers(),
+      timeout: SENDGRID_TIMEOUT_MS,
+    });
+
+    return data.id ? data : null;
+  } catch (e) {
+    console.error('SendGrid getSingleSend error:', e);
+    return null;
+  }
+}
+
+/**
+ * List Single Sends with optional status filter.
+ *
+ * @param {object} [options]
+ * @param {string} [options.status] - Filter by status: draft, scheduled, triggered
+ * @returns {Array<object>}
+ */
+async function listSingleSends(options) {
+  const { status } = options || {};
+
+  try {
+    const url = `${BASE_URL}/marketing/singlesends${status ? `?status=${status}` : ''}`;
+    const data = await fetch(url, {
+      response: 'json',
+      headers: headers(),
+      timeout: SENDGRID_TIMEOUT_MS,
+    });
+
+    return data.result || [];
+  } catch (e) {
+    console.error('SendGrid listSingleSends error:', e);
+    return [];
+  }
+}
+
+/**
+ * Add a contact to SendGrid — resolves list, upserts with optional custom fields.
+ *
+ * @param {object} options
+ * @param {string} options.email
+ * @param {string} [options.firstName]
+ * @param {string} [options.lastName]
+ * @param {object} [options.customFields] - Pre-built custom_fields object (keyed by SendGrid field IDs)
+ * @returns {{ success: boolean, jobId?: string, listId?: string, error?: string }}
+ */
+async function addContact({ email, firstName, lastName, company, customFields }) {
+  const contact = {
+    email: email.toLowerCase(),
+    first_name: firstName || undefined,
+    last_name: lastName || undefined,
+    custom_fields: customFields || {},
+  };
+
+  // Add company to custom fields if provided (requires field provisioned via OMEGA)
+  if (company) {
+    const idMap = await resolveFieldIds();
+    const companyFieldId = idMap['user_personal_company'];
+    if (companyFieldId) {
+      contact.custom_fields[companyFieldId] = company;
+    }
+  }
+
+  const listId = getListId();
+
+  console.log(`SendGrid addContact: ${email} → list=${listId || '(none)'}, customFields=${Object.keys(contact.custom_fields).length}`);
+
+  const result = await upsertContacts({
+    contacts: [contact],
+    listIds: listId ? [listId] : [],
+  });
+
+  if (result.success && listId) {
+    result.listId = listId;
+  }
+
+  return result;
+}
+
+/**
+ * Build SendGrid custom_fields object from a user doc.
+ * Resolves all field values, maps to display names, then resolves SendGrid IDs.
+ *
+ * The catalog decides which fields SendGrid owns (#695): a field the catalog
+ * skips for SendGrid is never written here, so the only fields that can come
+ * back unmapped are ones OMEGA has yet to provision — a real, actionable warn.
+ *
+ * @param {object} userDoc - User document from Firestore
+ * @returns {object} Custom fields keyed by SendGrid field ID (e.g., { e1_T: 'basic' })
+ */
+async function buildFields(userDoc) {
+  const values = resolveFieldValues(userDoc, Manager.config);
+  const owned = new Set(fieldsForProvider('sendgrid'));
+  const idMap = await resolveFieldIds();
+  const fields = {};
+
+  const unmapped = [];
+
+  for (const [name, value] of Object.entries(values)) {
+    if (!owned.has(name)) {
+      continue;
+    }
+
+    const sgId = idMap[name];
+
+    if (sgId) {
+      fields[sgId] = value;
+    } else {
+      unmapped.push(name);
+    }
+  }
+
+  if (unmapped.length) {
+    console.warn(`SendGrid buildFields: ${unmapped.length} field(s) have no SendGrid ID (skipped):`, unmapped);
+  }
+
+  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: SENDGRID_TIMEOUT_MS,
+      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: SENDGRID_TIMEOUT_MS,
+      });
+
+      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: 60000,
+          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: SENDGRID_TIMEOUT_MS,
+    });
+
+    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,
+  resolveSenderIds,
+
+  // Contacts
+  addContact,
+  findContact,
+  removeContact,
+  getSegmentContacts,
+  bulkDeleteContacts,
+  buildFields,
+
+  // Lists
+  getListId,
+
+  // Dynamic segments (brand-scoped temp segments)
+  getSegmentQuery,
+  createBrandScopedSegment,
+
+  // Campaigns (Single Sends)
+  createSingleSend,
+  scheduleSingleSend,
+  cancelSingleSend,
+  getSingleSend,
+  listSingleSends,
+};