backend-manager 5.1.2 → 5.2.0

package/src/manager/libraries/email/generators/newsletter.js

@@ -24,6 +24,7 @@ const { filterSources } = require('./lib/filter.js');
 const { generateStructure } = require('./lib/structure.js');
 const { generateSectionImage } = require('./lib/svg-illustrator.js');
 const { renderNewsletter } = require('./lib/mjml-template.js');
+const { renderMarkdown } = require('./lib/markdown-renderer.js');
 const { uploadAssets, RAW_BASE } = require('./lib/image-host.js');
 
 /**
@@ -76,7 +77,7 @@ async function generate(Manager, assistant, settings, opts = {}) {
       return null;
     }
 
-    const parentUrl = Manager.config?.parent;
+    const parentUrl = Manager.getParentApiUrl();
 
     if (!parentUrl) {
       assistant.log('Newsletter generator: no parent URL configured');
@@ -208,16 +209,34 @@ async function generate(Manager, assistant, settings, opts = {}) {
     sponsorships,
   });
 
-  // 3b. Upload the rendered HTML to GitHub alongside the images. Lives in the
-  //     same {brandId}/{campaignId}/ folder as newsletter.html. The folder URL
-  //     becomes the canonical archive of the issue, browseable + downloadable.
+  // 3a. Programmatic markdown view — same `structure`, walked by code (no AI).
+  //     The markdown is split into ## blocks per section so it can be pasted
+  //     into Beehiiv's block editor with ad blocks inserted between dispatches.
+  //     `summary` is a separate short editorial recap, written by the AI
+  //     during the structure step.
+  const markdown = renderMarkdown({
+    structure,
+    brand,
+    imagePaths,
+    sponsorships,
+  });
+
+  const summaryText = (structure.summary || '').trim();
+
+  // 3b. Upload the rendered HTML + markdown + summary to GitHub alongside the
+  //     images. All four kinds live in the same {brandId}/{campaignId}/ folder.
+  //     The folder URL becomes the canonical archive of the issue.
   let assetsFolderUrl = null;
   let htmlUrl = null;
+  let markdownUrl = null;
+  let summaryUrl = null;
 
   if (host === 'github') {
     try {
       const upload = await uploadAssets({
         html,
+        markdown,
+        summary: summaryText || undefined,
         brandId: brand?.id,
         campaignId,
         subject: structure.subject,
@@ -225,6 +244,8 @@ async function generate(Manager, assistant, settings, opts = {}) {
       });
       assetsFolderUrl = upload.folderUrl;
       htmlUrl = upload.htmlUrl;
+      markdownUrl = upload.markdownUrl || null;
+      summaryUrl = upload.summaryUrl || null;
     } catch (e) {
       assistant.error(`Newsletter generator: HTML upload failed — ${e.message}`);
     }
@@ -238,6 +259,7 @@ async function generate(Manager, assistant, settings, opts = {}) {
   //     succeeds regardless. beehiivConfig was already resolved at the top
   //     of the function for the initial enabled-check.
   let beehiivPostId = null;
+  let beehiivFailureReason = null;
 
   if (host === 'github' && beehiivConfig?.enabled) {
     try {
@@ -248,6 +270,7 @@ async function generate(Manager, assistant, settings, opts = {}) {
         subject:       structure.subject,
         preheader:     structure.preheader,
         content:       html,
+        contentTags:   Array.isArray(structure.tags) ? structure.tags : [],
         status:        'draft',
       });
 
@@ -256,16 +279,39 @@ async function generate(Manager, assistant, settings, opts = {}) {
         assistant.log(`Newsletter generator: Beehiiv draft created — ${beehiivPostId}`);
       } else {
         // Expected today until Enterprise plan — log, do not throw.
-        assistant.log(`Newsletter generator: Beehiiv draft upload skipped/failed — ${result?.error || 'unknown'}`);
+        beehiivFailureReason = result?.error || 'unknown error';
+        assistant.log(`Newsletter generator: Beehiiv draft upload skipped/failed — ${beehiivFailureReason}`);
       }
     } catch (e) {
+      beehiivFailureReason = e.message;
       assistant.error(`Newsletter generator: Beehiiv draft upload threw — ${e.message}`);
     }
   }
 
+  // 3d. Fallback alert email — sent to the brand's internal alerts inbox when
+  //     Beehiiv draft creation fails. The newsletter is fully generated and
+  //     archived to GitHub at this point, so the email contains everything
+  //     needed for a human to manually upload to Beehiiv: HTML URL (one-shot
+  //     paste), markdown URL (per-section blocks for ad insertion), summary
+  //     URL, and the tags to set. Failure of THIS email is logged but never
+  //     blocks the cron — the campaign doc is still written either way.
+  if (beehiivFailureReason && htmlUrl) {
+    await sendBeehiivFallbackEmail(Manager, assistant, {
+      brand,
+      subject: structure.subject,
+      preheader: structure.preheader,
+      tags: Array.isArray(structure.tags) ? structure.tags : [],
+      htmlUrl,
+      markdownUrl,
+      summaryUrl,
+      folderUrl: assetsFolderUrl,
+      reason: beehiivFailureReason,
+    });
+  }
+
   // 4. Mark sources as used on parent server (unless caller opted out)
   if (!opts.skipClaim) {
-    const parentUrl = Manager.config?.parent;
+    const parentUrl = Manager.getParentApiUrl();
 
     if (parentUrl) {
       await claimSources(parentUrl, sources, brand?.id, assistant);
@@ -308,8 +354,11 @@ async function generate(Manager, assistant, settings, opts = {}) {
     campaignId,
     folderUrl: assetsFolderUrl,
     htmlUrl,
+    markdownUrl,
+    summaryUrl,
     imageUrls: imagePaths,
     beehiivPostId,
+    tags: Array.isArray(structure.tags) ? structure.tags : [],
   } : null;
 
   return {
@@ -318,14 +367,112 @@ async function generate(Manager, assistant, settings, opts = {}) {
     preheader: structure.preheader,
     content: '',          // legacy markdown field, unused when contentHtml is set
     contentHtml: html,    // pre-rendered email-safe HTML
+    contentMarkdown: markdown,  // programmatic markdown view (per-section blocks for Beehiiv paste)
+    summary: summaryText, // editorial recap (separate from preheader)
+    tags: Array.isArray(structure.tags) ? structure.tags : [],
     structure,            // structured copy for debugging / migration
     mjml,                 // raw MJML for debugging
     images: opts._lastImages || [],  // image buffers for the iteration test to persist locally
-    assets,               // GitHub asset URLs (folder, html, images) — null in local mode
+    assets,               // GitHub asset URLs (folder, html, md, summary, images) — null in local mode
     meta,                 // per-step provider/model/cost/timing telemetry
   };
 }
 
+/**
+ * Send an internal alert email when Beehiiv draft creation fails so the
+ * brand team knows there's a ready newsletter waiting for manual upload.
+ *
+ * Uses `sender: 'internal'` which auto-resolves to `alerts@{brandDomain}` via
+ * the SENDERS table in email/constants.js. Recipient is the same alerts@
+ * address — a self-addressed operational alert, no human inbox involved.
+ *
+ * Errors here are logged but never thrown — the alert is best-effort. If
+ * brand.url is unset, the email is skipped entirely.
+ *
+ * @param {object} Manager
+ * @param {object} assistant
+ * @param {object} args
+ * @param {object} args.brand
+ * @param {string} args.subject - The newsletter's subject (used in the alert subject)
+ * @param {string} args.preheader
+ * @param {string[]} args.tags
+ * @param {string} args.htmlUrl - GitHub raw URL to the fully-rendered HTML
+ * @param {string} [args.markdownUrl] - GitHub raw URL to the per-section markdown
+ * @param {string} [args.summaryUrl] - GitHub raw URL to the 2-3 sentence summary
+ * @param {string} [args.folderUrl] - GitHub folder URL (browseable archive)
+ * @param {string} args.reason - Why Beehiiv upload failed (API error message)
+ */
+async function sendBeehiivFallbackEmail(Manager, assistant, args) {
+  // Send TO and FROM the same internal alerts inbox — alerts@{brandDomain}.
+  // The `sender: 'internal'` SENDERS entry already resolves the FROM address
+  // to this; we mirror the same domain for the TO so it's a self-addressed
+  // operational alert (no human inbox involved).
+  const brandDomain = (Manager.config?.brand?.url || '').replace(/^https?:\/\//, '').replace(/\/$/, '');
+
+  if (!brandDomain) {
+    assistant.log('Newsletter generator: Beehiiv fallback email skipped — no brand.url');
+    return;
+  }
+
+  const alertsEmail = `alerts@${brandDomain}`;
+
+  try {
+    const email = Manager.Email(assistant);
+    const messageLines = [];
+
+    messageLines.push(`<strong>Beehiiv draft creation failed</strong> — the newsletter is generated and archived, but needs to be manually uploaded to Beehiiv.`);
+    messageLines.push('');
+    messageLines.push(`<strong>Failure reason:</strong> ${args.reason}`);
+    messageLines.push('');
+    messageLines.push('<strong>Newsletter details:</strong>');
+    messageLines.push('<ul>');
+    messageLines.push(`<li><strong>Subject:</strong> ${args.subject}</li>`);
+    messageLines.push(`<li><strong>Preheader:</strong> ${args.preheader || '(none)'}</li>`);
+    if (args.tags?.length) {
+      messageLines.push(`<li><strong>Tags:</strong> ${args.tags.join(', ')}</li>`);
+    }
+    messageLines.push('</ul>');
+    messageLines.push('');
+    messageLines.push('<strong>Assets (manual upload links):</strong>');
+    messageLines.push('<ul>');
+    messageLines.push(`<li><strong>Full HTML</strong> (one-shot paste): <a href="${args.htmlUrl}">${args.htmlUrl}</a></li>`);
+    if (args.markdownUrl) {
+      messageLines.push(`<li><strong>Per-section markdown</strong> (paste as separate blocks, ads between): <a href="${args.markdownUrl}">${args.markdownUrl}</a></li>`);
+    }
+    if (args.summaryUrl) {
+      messageLines.push(`<li><strong>Summary</strong> (2-3 sentence recap): <a href="${args.summaryUrl}">${args.summaryUrl}</a></li>`);
+    }
+    if (args.folderUrl) {
+      messageLines.push(`<li><strong>All assets</strong>: <a href="${args.folderUrl}">${args.folderUrl}</a></li>`);
+    }
+    messageLines.push('</ul>');
+
+    await email.send({
+      sender: 'internal',  // resolves to alerts@{brandDomain}
+      to: alertsEmail,
+      copy: false,  // self-addressed operational alert — no CC/BCC clutter
+      subject: `Newsletter ready for manual Beehiiv upload: "${args.subject}"`,
+      template: 'core/card',
+      categories: ['marketing/newsletter-manual-upload'],
+      data: {
+        email: {
+          preview: `Beehiiv upload failed — newsletter awaiting manual upload from ${args.folderUrl || 'GitHub archive'}`,
+        },
+        body: {
+          title: 'Newsletter Ready for Manual Upload',
+          message: messageLines.join('\n'),
+        },
+      },
+    });
+
+    assistant.log(`Newsletter generator: Beehiiv fallback alert sent to ${alertsEmail}`);
+  } catch (e) {
+    // Best-effort — log and move on. We don't want a misconfigured email
+    // setup to break the cron's Firestore write.
+    assistant.error(`Newsletter generator: Beehiiv fallback email failed — ${e.message}`);
+  }
+}
+
 /**
  * Sum tokens + cost across all steps (filter, structure, all SVGs).
  */

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

@@ -329,6 +329,7 @@ async function resolveSegmentIds() {
  * @param {string} [options.subject] - Email subject line (defaults to title)
  * @param {string} [options.preheader] - Email preview text
  * @param {string} [options.content] - HTML content body
+ * @param {Array<string>} [options.contentTags] - Topical tags attached to the post (Beehiiv `content_tags`)
  * @param {string} [options.status] - 'draft' or 'confirmed' (default: confirmed = send)
  * @param {string} [options.sendAt] - ISO datetime to schedule, or null for immediate
  * @param {Array<string>} [options.segments] - Segment IDs to include
@@ -342,7 +343,7 @@ async function createPost(options) {
     return { success: false, error: 'Publication not found' };
   }
 
-  const { title, subject, preheader, content, status, sendAt, segments, excludeSegments } = options;
+  const { title, subject, preheader, content, contentTags, status, sendAt, segments, excludeSegments } = options;
 
   try {
     const body = {
@@ -355,6 +356,11 @@ async function createPost(options) {
       body.body_content = content;
     }
 
+    // Tags (Beehiiv field is `content_tags`, array of strings)
+    if (Array.isArray(contentTags) && contentTags.length) {
+      body.content_tags = contentTags;
+    }
+
     // Scheduling
     if (sendAt && sendAt !== 'now') {
       body.scheduled_at = new Date(sendAt).toISOString();
@@ -409,6 +415,7 @@ async function createPost(options) {
 module.exports = {
   // Resolution
   resolveSegmentIds,
+  getPublicationId,
 
   // Contacts
   addContact,

package/src/manager/libraries/payment/processors/stripe.js

@@ -452,6 +452,18 @@ function resolveProduct(raw, config) {
     return { id: 'basic', name: 'Basic' };
   }
 
+  // Test-mode sentinel: the test processor synthesizes "_test_<id>" when no real
+  // Stripe product is configured. Map it back to the matching BEM product so the
+  // pipeline can be exercised end-to-end without real Stripe credentials.
+  if (typeof stripeProductId === 'string' && stripeProductId.startsWith('_test_')) {
+    const bemId = stripeProductId.slice('_test_'.length);
+    const product = config.payment.products.find((p) => p.id === bemId);
+    if (product) {
+      return { id: product.id, name: product.name || product.id };
+    }
+    return { id: 'basic', name: 'Basic' };
+  }
+
   for (const product of config.payment.products) {
     // Match current product ID
     if (product.stripe?.productId === stripeProductId) {

package/src/manager/libraries/payment/processors/test.js

@@ -174,5 +174,12 @@ function resolveStripeProductId(productId, config) {
 
   const product = config.payment.products.find(p => p.id === productId);
 
-  return product?.stripe?.productId || null;
+  if (!product) {
+    return null;
+  }
+
+  // Real Stripe product ID if configured, otherwise the "_test_<id>" sentinel that the
+  // Stripe resolver recognizes and maps back to the BEM product. Lets reconstruction
+  // work in brands without real Stripe (Somiibo uses PayPal, Chargebee, etc.).
+  return product.stripe?.productId || `_test_${product.id}`;
 }

package/src/manager/routes/admin/infer-contact/post.js

@@ -16,8 +16,9 @@ module.exports = async ({ assistant, user, settings }) => {
     return assistant.respond('Admin required.', { code: 403 });
   }
 
-  // Accept single email or array of emails
-  const emails = Array.isArray(settings.emails)
+  // Accept single email or array of emails. Schema defaults `emails` to [], so check length:
+  // an empty default should NOT shadow a provided single `email`.
+  const emails = Array.isArray(settings.emails) && settings.emails.length > 0
     ? settings.emails
     : [settings.email];
 

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

@@ -82,7 +82,7 @@ module.exports = async ({ assistant, Manager, user, settings, analytics }) => {
   settings.layout = settings.layout;
   settings.date = moment(settings.date || now).subtract(1, 'days').format('YYYY-MM-DD');
   settings.id = settings.id || Math.round(new Date(now).getTime() / 1000);
-  settings.path = `src/_posts/${moment(now).format('YYYY')}/${settings.postPath}`;
+  settings.directory = `src/_posts/${moment(now).format('YYYY')}/${settings.postPath}`;
   settings.githubUser = settings.githubUser || bemRepo.user;
   settings.githubRepo = settings.githubRepo || bemRepo.name;
 
@@ -108,7 +108,7 @@ module.exports = async ({ assistant, Manager, user, settings, analytics }) => {
   );
 
   // Build post file entry
-  const postFilename = `${settings.path}/${settings.date}-${settings.url}.md`;
+  settings.path = `${settings.directory}/${settings.date}-${settings.url}.md`;
   const allFiles = [
     ...imageFiles.map(img => ({
       path: img.githubPath,
@@ -116,7 +116,7 @@ module.exports = async ({ assistant, Manager, user, settings, analytics }) => {
       encoding: 'base64',
     })),
     {
-      path: postFilename,
+      path: settings.path,
       content: Buffer.from(formattedContent).toString('base64'),
       encoding: 'base64',
     },

package/src/manager/routes/marketing/email-preferences/post.js

@@ -1,24 +1,118 @@
 /**
- * POST /marketing/email-preferences - Update email preferences
- * Public endpoint — no authentication required
+ * POST /marketing/email-preferences - Update marketing email consent
  *
- * Supports two actions:
- * - "unsubscribe": Adds email to SendGrid ASM suppression group
- * - "resubscribe": Removes email from SendGrid ASM suppression group
+ * Two supported modes:
+ *
+ * 1) Authenticated (account-page toggle):
+ *    - User must be logged in.
+ *    - settings.action = 'opt-in' | 'opt-out'.
+ *    - Writes canonical consent.marketing to user doc.
+ *    - Hits BOTH SendGrid + Beehiiv via the email library (one source of truth).
+ *
+ * 2) Anonymous (HMAC unsubscribe link from email footer):
+ *    - No login. settings.email + settings.asmId + settings.sig + settings.action.
+ *    - HMAC validates the link was generated by us.
+ *    - Hits SendGrid ASM directly (legacy behavior — preserves existing one-click unsub).
+ *    - Also writes canonical consent.marketing to user doc when email maps to a user.
  */
 const fetch = require('wonderful-fetch');
 const crypto = require('crypto');
 
 const RATE_LIMIT = 5;
 
-module.exports = async ({ assistant, Manager, settings, analytics }) => {
+module.exports = async ({ assistant, Manager, user, settings, analytics }) => {
+
+  // --- AUTHENTICATED MODE ---
+  if (user.authenticated) {
+    return handleAuthenticated({ assistant, Manager, user, settings, analytics });
+  }
+
+  // --- ANONYMOUS HMAC MODE ---
+  return handleAnonymous({ assistant, Manager, settings, analytics });
+};
+
+/**
+ * Authenticated user toggling marketing on/off from the account page.
+ */
+async function handleAuthenticated({ assistant, Manager, user, settings, analytics }) {
+  const { admin } = Manager.libraries;
+  const action = settings.action;
+
+  if (action !== 'subscribe' && action !== 'unsubscribe') {
+    return assistant.respond('Invalid action — must be "subscribe" or "unsubscribe"', { code: 400 });
+  }
+
+  // Rate-limit per-user (defense against accidental toggling spam)
+  const usage = await Manager.Usage().init(assistant);
+  const currentUsage = usage.getUsage('email-preferences');
+  if (currentUsage >= RATE_LIMIT) {
+    return assistant.respond('Rate limit exceeded', { code: 429 });
+  }
+  usage.increment('email-preferences');
+  await usage.update();
+
+  const uid = user.auth.uid;
+  const email = user.auth.email;
+  const ip = assistant.request.geolocation?.ip || null;
+  const timestamp = assistant.meta.startTime.timestamp;
+  const timestampUNIX = assistant.meta.startTime.timestampUNIX;
+
+  // Build the consent.marketing mutation
+  const marketingPatch = action === 'subscribe'
+    ? {
+      status: 'granted',
+      grantedAt: { timestamp, timestampUNIX, source: 'account', ip, text: null },
+      // Leave revokedAt untouched — informational record of most recent revoke
+    }
+    : {
+      status: 'revoked',
+      revokedAt: { timestamp, timestampUNIX, source: 'account', ip, text: null },
+      // Leave grantedAt untouched — informational record of original grant
+    };
+
+  await admin.firestore().doc(`users/${uid}`).set({
+    consent: { marketing: marketingPatch },
+    metadata: Manager.Metadata().set({ tag: 'marketing/email-preferences' }),
+  }, { merge: true });
+
+  assistant.log(`email-preferences (auth): ${uid} → ${action}`);
+
+  // Skip provider calls in test mode unless extended mode is on
+  const shouldCallExternalAPIs = !assistant.isTesting() || process.env.TEST_EXTENDED_MODE;
+
+  if (shouldCallExternalAPIs) {
+    const mailer = Manager.Email(assistant);
+
+    try {
+      if (action === 'unsubscribe') {
+        await mailer.remove(email);
+      } else {
+        await mailer.sync(uid);
+      }
+    } catch (e) {
+      assistant.error(`email-preferences (auth) provider sync failed:`, e);
+      // Doc is already updated — provider sync is best-effort. Don't fail the request.
+    }
+  } else {
+    assistant.log('email-preferences (auth): Skipping provider calls (BEM_TESTING=true)');
+  }
+
+  analytics.event('marketing/email-preferences', { action, mode: 'authenticated' });
+
+  return assistant.respond({ success: true, action });
+}
+
+/**
+ * Anonymous HMAC unsubscribe link (preserves existing email-footer one-click flow).
+ */
+async function handleAnonymous({ assistant, Manager, settings, analytics }) {
+  const { admin } = Manager.libraries;
 
-  // Extract parameters
   const email = (settings.email || '').trim().toLowerCase();
   const asmId = parseInt(settings.asmId, 10);
   const action = settings.action || 'unsubscribe';
 
-  // Validate email
+  // Validate inputs
   if (!email) {
     return assistant.respond('Email is required', { code: 400 });
   }
@@ -28,29 +122,25 @@ module.exports = async ({ assistant, Manager, settings, analytics }) => {
     return assistant.respond('Invalid email format', { code: 400 });
   }
 
-  // Validate ASM group ID
   if (!asmId || isNaN(asmId)) {
     return assistant.respond('ASM group ID is required', { code: 400 });
   }
 
-  // Validate action
-  if (action !== 'unsubscribe' && action !== 'resubscribe') {
+  if (action !== 'subscribe' && action !== 'unsubscribe') {
     return assistant.respond('Invalid action', { code: 400 });
   }
 
-  // Verify HMAC signature (proves the link was generated by our server)
+  // HMAC validation (proves we generated this link)
   const expectedSig = crypto.createHmac('sha256', process.env.UNSUBSCRIBE_HMAC_KEY).update(email).digest('hex');
   if (settings.sig !== expectedSig) {
     return assistant.respond('Invalid signature', { code: 403 });
   }
 
-  // Initialize Usage for rate limiting (key: IP forces unauthenticated storage always)
+  // IP rate limiting (anonymous flow — unauthenticated firestore storage)
   const usage = await Manager.Usage().init(assistant, {
     unauthenticatedMode: 'firestore',
     key: assistant.request.geolocation.ip,
   });
-
-  // Rate limiting (manual check since email-preferences isn't in product limits)
   const currentUsage = usage.getUsage('email-preferences');
   if (currentUsage >= RATE_LIMIT) {
     return assistant.respond('Rate limit exceeded', { code: 429 });
@@ -58,37 +148,34 @@ module.exports = async ({ assistant, Manager, settings, analytics }) => {
   usage.increment('email-preferences');
   await usage.update();
 
-  // Skip external API calls in test mode unless TEST_EXTENDED_MODE is set
+  // Mirror to the user doc if this email maps to a user (best-effort, silent on miss)
+  await mirrorAnonymousToUserDoc({ assistant, Manager, email, action });
+
+  // Call SendGrid ASM (legacy behavior)
   const shouldCallExternalAPIs = !assistant.isTesting() || process.env.TEST_EXTENDED_MODE;
 
   if (!shouldCallExternalAPIs) {
-    assistant.log('marketing/email-preferences: Skipping SendGrid (BEM_TESTING=true, TEST_EXTENDED_MODE not set)');
+    assistant.log('email-preferences (anon): Skipping SendGrid (BEM_TESTING=true)');
     return assistant.respond({ success: true });
   }
 
-  // Call SendGrid ASM API
   try {
     if (action === 'unsubscribe') {
-      // Add email to suppression group
+      // POST returns JSON ({recipient_emails: [...]}) on success
       await fetch(`https://api.sendgrid.com/v3/asm/groups/${asmId}/suppressions`, {
         method: 'POST',
         response: 'json',
-        headers: {
-          'Authorization': `Bearer ${process.env.SENDGRID_API_KEY}`,
-        },
+        headers: { 'Authorization': `Bearer ${process.env.SENDGRID_API_KEY}` },
         timeout: 10000,
-        body: {
-          recipient_emails: [email],
-        },
+        body: { recipient_emails: [email] },
       });
     } else {
-      // Remove email from suppression group
+      // DELETE returns 204 with empty body — must NOT request response: 'json'
+      // or wonderful-fetch throws SyntaxError on the empty body.
       await fetch(`https://api.sendgrid.com/v3/asm/groups/${asmId}/suppressions/${encodeURIComponent(email)}`, {
         method: 'DELETE',
-        response: 'json',
-        headers: {
-          'Authorization': `Bearer ${process.env.SENDGRID_API_KEY}`,
-        },
+        response: 'text',
+        headers: { 'Authorization': `Bearer ${process.env.SENDGRID_API_KEY}` },
         timeout: 10000,
       });
     }
@@ -97,12 +184,53 @@ module.exports = async ({ assistant, Manager, settings, analytics }) => {
     return assistant.respond('Failed to process your request', { code: 500 });
   }
 
-  // Log result
-  assistant.log('marketing/email-preferences result:', { email, asmId, action });
-
-  // Track analytics
-  analytics.event('marketing/email-preferences', { action });
+  assistant.log('email-preferences (anon) result:', { email, asmId, action });
+  analytics.event('marketing/email-preferences', { action, mode: 'anonymous' });
 
-  // Generic success (no sensitive info leakage)
   return assistant.respond({ success: true });
-};
+}
+
+/**
+ * Anonymous HMAC unsub also writes to the user doc (if found) so consent stays in sync.
+ * Silent if the email doesn't map to a user. Source is recorded as 'sendgrid' since the
+ * HMAC link only fires from SendGrid email footers.
+ */
+async function mirrorAnonymousToUserDoc({ assistant, Manager, email, action }) {
+  const { admin } = Manager.libraries;
+
+  const snapshot = await admin.firestore().collection('users')
+    .where('auth.email', '==', email)
+    .limit(1)
+    .get()
+    .catch((e) => {
+      assistant.error('email-preferences (anon): Failed to look up user by email:', e);
+      return null;
+    });
+
+  if (!snapshot || snapshot.empty) {
+    return; // Silent — email may not map to a current user
+  }
+
+  const userDoc = snapshot.docs[0];
+  const uid = userDoc.id;
+  const timestamp = assistant.meta.startTime.timestamp;
+  const timestampUNIX = assistant.meta.startTime.timestampUNIX;
+
+  const marketingPatch = action === 'unsubscribe'
+    ? {
+      status: 'revoked',
+      revokedAt: { timestamp, timestampUNIX, source: 'sendgrid', ip: null, text: null },
+    }
+    : {
+      status: 'granted',
+      grantedAt: { timestamp, timestampUNIX, source: 'sendgrid', ip: null, text: null },
+    };
+
+  await admin.firestore().doc(`users/${uid}`).set({
+    consent: { marketing: marketingPatch },
+    metadata: Manager.Metadata().set({ tag: 'marketing/email-preferences' }),
+  }, { merge: true })
+    .catch((e) => {
+      assistant.error(`email-preferences (anon): Failed to mirror to user doc ${uid}:`, e);
+    });
+}