backend-manager 5.1.4 → 5.2.1

package/src/manager/routes/marketing/webhook/processors/beehiiv.js

@@ -0,0 +1,196 @@
+/**
+ * Beehiiv webhook processor
+ *
+ * Beehiiv sends one event per POST (unlike SendGrid's batched array).
+ * Each event includes a `publication_id` so the processor can decide whether
+ * the event belongs to THIS brand or a sibling brand sharing the same parent.
+ *
+ * Supported event types (anything else is silently ignored):
+ *   - 'subscription.unsubscribed' — user clicked unsubscribe in a Beehiiv email
+ *   - 'subscription.deleted'      — admin or API removed the subscriber
+ *   - 'subscription.paused'       — user paused delivery (treat as revoke; we
+ *                                    can't differentiate "pause" semantics)
+ *
+ * Publication routing:
+ *   - If the event's publication_id doesn't match this brand's configured
+ *     publication, silent skip. This is how the shared-devbeans publication
+ *     case works: the parent fans the event to every child, and only the
+ *     brand(s) sharing that publication actually process it.
+ *   - getPublicationId() reads from config.marketing.beehiiv.publicationId
+ *     or fuzzy-matches by brand name against the Beehiiv API.
+ *
+ * Idempotency is enforced by the dispatcher via marketing-webhooks/{eventId} doc.
+ */
+
+const REVOKE_EVENT_TYPES = new Set([
+  'subscription.unsubscribed',
+  'subscription.deleted',
+  'subscription.paused',
+]);
+
+/**
+ * Parse the raw webhook request into a normalized array (single-element).
+ * Beehiiv sends one event per POST. Some HTTP clients serialize objects with
+ * extra keys merged in (e.g. our test client merges query params into the body) —
+ * we tolerate that by pulling fields explicitly.
+ */
+function parseWebhook(req) {
+  const body = req.body;
+
+  if (!body || typeof body !== 'object') {
+    throw new Error('Empty or non-object webhook body');
+  }
+
+  // Beehiiv's event ID lives at `data.id` (per their docs) but their actual
+  // delivery shape can vary across endpoints. Try common locations.
+  const eventId = body.id
+    || body.event_id
+    || body.data?.id
+    || null;
+
+  const eventType = body.event || body.type || null;
+
+  // Email may be at top-level or nested under `data`
+  const rawEmail = body.email || body.data?.email || null;
+  const email = typeof rawEmail === 'string' ? rawEmail.trim().toLowerCase() : null;
+
+  // Publication ID — required to decide whether THIS brand should handle it
+  const publicationId = body.publication_id || body.data?.publication_id || null;
+
+  // Timestamp — Beehiiv uses ISO 8601. Fall back to data.created_at variants.
+  const timestampISO = body.created_at
+    || body.timestamp
+    || body.data?.created_at
+    || null;
+
+  const timestampUNIX = timestampISO
+    ? Math.floor(new Date(timestampISO).getTime() / 1000) || null
+    : null;
+
+  return [{
+    eventId,
+    eventType,
+    email,
+    timestamp: timestampUNIX,
+    publicationId,
+    raw: body,
+  }];
+}
+
+/**
+ * Returns true if this event type represents a revocation we should act on.
+ */
+function isSupported(eventType) {
+  return REVOKE_EVENT_TYPES.has(eventType);
+}
+
+/**
+ * Process a single parsed event. Called by the dispatcher AFTER idempotency check passes.
+ * Returns a result object summarizing what happened.
+ */
+async function handleEvent({ Manager, assistant, parsed }) {
+  const { admin } = Manager.libraries;
+  const { eventId, eventType, email, timestamp, publicationId } = parsed;
+
+  if (!email) {
+    assistant.log(`beehiiv webhook: event ${eventId} (${eventType}) missing email, skipping`);
+    return { handled: false, reason: 'missing-email' };
+  }
+
+  // Publication filter — silent skip if the event isn't for our publication.
+  // This is THE mechanism that routes shared-publication events (e.g. devbeans
+  // across 6 brands) to only the brands that share that publication.
+  // beehiivProvider.getPublicationId() reads Manager.config.marketing.beehiiv.publicationId
+  // first, then falls back to fuzzy-match against the Beehiiv API by brand name.
+  if (publicationId) {
+    let ourPublicationId = null;
+    try {
+      const beehiivProvider = require('../../../../libraries/email/providers/beehiiv.js');
+      if (typeof beehiivProvider.getPublicationId === 'function') {
+        ourPublicationId = await beehiivProvider.getPublicationId();
+      }
+    } catch (e) {
+      assistant.error('beehiiv webhook: failed to resolve our publication ID:', e);
+      return { handled: false, reason: 'publication-resolve-failed' };
+    }
+
+    if (!ourPublicationId) {
+      assistant.log(`beehiiv webhook: no publication configured for this brand, skipping event ${eventId}`);
+      return { handled: false, reason: 'no-local-publication' };
+    }
+
+    if (ourPublicationId !== publicationId) {
+      assistant.log(`beehiiv webhook: publication mismatch (event=${publicationId}, ours=${ourPublicationId}), skipping`);
+      return { handled: false, reason: 'publication-mismatch' };
+    }
+  }
+
+  // Build the canonical revokedAt timestamp from the event (or server time if missing)
+  const startTime = assistant.meta.startTime;
+  const eventUNIX = typeof timestamp === 'number' ? timestamp : startTime.timestampUNIX;
+  const eventISO = new Date(eventUNIX * 1000).toISOString();
+
+  // Look up the user by email
+  const snapshot = await admin.firestore().collection('users')
+    .where('auth.email', '==', email)
+    .limit(1)
+    .get()
+    .catch((e) => {
+      assistant.error(`beehiiv webhook: user lookup failed for ${email}:`, e);
+      return null;
+    });
+
+  if (!snapshot || snapshot.empty) {
+    // Silent skip — this email may not map to a customer of THIS brand even if
+    // the publication matched (legitimate for shared-devbeans where 6 brands
+    // process every event but only one has the user).
+    assistant.log(`beehiiv webhook: no user found for ${email}, skipping doc update`);
+    return { handled: false, reason: 'user-not-found', email };
+  }
+
+  const userDoc = snapshot.docs[0];
+  const uid = userDoc.id;
+
+  // Write consent.marketing.status = 'revoked' (preserve grantedAt — informational audit trail)
+  await admin.firestore().doc(`users/${uid}`).set({
+    consent: {
+      marketing: {
+        status: 'revoked',
+        revokedAt: {
+          timestamp: eventISO,
+          timestampUNIX: eventUNIX,
+          source: 'beehiiv',
+          ip: null,
+          text: null,
+        },
+      },
+    },
+    metadata: Manager.Metadata().set({ tag: 'marketing/webhook:beehiiv' }),
+  }, { merge: true });
+
+  assistant.log(`beehiiv webhook: revoked consent.marketing for ${uid} (${email}) — eventType=${eventType}`);
+
+  // Cross-provider sync: also remove from SendGrid (best-effort, idempotent on 404)
+  const shouldCallExternalAPIs = !assistant.isTesting() || process.env.TEST_EXTENDED_MODE;
+
+  if (shouldCallExternalAPIs) {
+    try {
+      const mailer = Manager.Email(assistant);
+      await mailer.remove(email);
+      assistant.log(`beehiiv webhook: cross-provider sync complete for ${email}`);
+    } catch (e) {
+      // Best-effort — user doc is already updated. Log + continue.
+      assistant.error(`beehiiv webhook: cross-provider sync failed for ${email}:`, e);
+    }
+  } else {
+    assistant.log('beehiiv webhook: skipping cross-provider sync (BEM_TESTING=true)');
+  }
+
+  return { handled: true, uid, email, eventType };
+}
+
+module.exports = {
+  parseWebhook,
+  isSupported,
+  handleEvent,
+};

package/src/manager/routes/marketing/webhook/processors/sendgrid.js

@@ -0,0 +1,171 @@
+/**
+ * SendGrid webhook processor
+ *
+ * SendGrid sends an array of events per POST. This module parses the array,
+ * decides which events represent an unsubscribe (revocation of marketing consent),
+ * and exposes a per-event handler that:
+ *   1. Looks up the user by email in this brand's Firestore (silent skip if not found)
+ *   2. Writes consent.marketing.status = 'revoked' to the user doc, source: 'sendgrid'
+ *   3. Calls Beehiiv to remove the contact too (cross-provider sync — idempotent on 404)
+ *
+ * Supported event types (anything else is silently ignored):
+ *   - 'unsubscribe'         — user clicked the unified unsubscribe link
+ *   - 'group_unsubscribe'   — user unsubscribed from a specific ASM group
+ *   - 'spamreport'          — user marked email as spam
+ *   - 'bounce'              — hard bounce (treat as revoke to avoid future sends)
+ *   - 'dropped'             — SendGrid dropped the message (often due to suppression)
+ *
+ * Note: 'group_unsubscribe' is the most common one (matches our ASM-link flow), and since
+ * GROUPS.marketing (25928) is account-global across all brands, an unsub from group 25928
+ * legitimately removes the user from marketing across the entire SendGrid account.
+ *
+ * Idempotency is enforced by the dispatcher via marketing-webhooks/{eventId} doc.
+ */
+
+const REVOKE_EVENT_TYPES = new Set([
+  'unsubscribe',
+  'group_unsubscribe',
+  'spamreport',
+  'bounce',
+  'dropped',
+]);
+
+/**
+ * Parse the raw webhook request into a normalized array of events.
+ * SendGrid sends an array of events as the body. Some HTTP clients (including
+ * BEM's own test client) JSON-encode arrays as objects with numeric keys —
+ * we tolerate both shapes plus the rare single-event object form.
+ */
+function parseWebhook(req) {
+  const body = req.body;
+
+  if (!body) {
+    throw new Error('Empty webhook body');
+  }
+
+  let events;
+  if (Array.isArray(body)) {
+    // Real SendGrid: array body
+    events = body;
+  } else if (body && typeof body === 'object' && typeof body['0'] === 'object' && body['0'] !== null) {
+    // Array serialized as object-with-numeric-keys (test clients, some proxies)
+    events = [];
+    let i = 0;
+    while (body[String(i)]) {
+      events.push(body[String(i)]);
+      i += 1;
+    }
+  } else {
+    // Single event sent as a bare object
+    events = [body];
+  }
+
+  return events.map((event) => {
+    // sg_event_id is SendGrid's per-event unique ID, used for idempotency.
+    // smtp-id is another stable identifier we fall back to.
+    const eventId = event.sg_event_id || event['smtp-id'] || event.smtpId || null;
+    const eventType = event.event;
+    const email = typeof event.email === 'string' ? event.email.trim().toLowerCase() : null;
+    const timestamp = typeof event.timestamp === 'number' ? event.timestamp : null;
+    const asmGroupId = event.asm_group_id || null;
+
+    return {
+      eventId,
+      eventType,
+      email,
+      timestamp,
+      asmGroupId,
+      raw: event,
+    };
+  });
+}
+
+/**
+ * Returns true if this event type represents a revocation we should act on.
+ */
+function isSupported(eventType) {
+  return REVOKE_EVENT_TYPES.has(eventType);
+}
+
+/**
+ * Process a single parsed event. Called by the dispatcher AFTER idempotency check passes.
+ *
+ * Returns a result object summarizing what happened (for logging/response).
+ */
+async function handleEvent({ Manager, assistant, parsed }) {
+  const { admin } = Manager.libraries;
+  const { eventId, eventType, email, timestamp } = parsed;
+
+  if (!email) {
+    assistant.log(`sendgrid webhook: event ${eventId} (${eventType}) missing email, skipping`);
+    return { handled: false, reason: 'missing-email' };
+  }
+
+  // Convert SendGrid's UNIX timestamp to our canonical { timestamp, timestampUNIX } shape.
+  // Fall back to server time if missing.
+  const startTime = assistant.meta.startTime;
+  const eventUNIX = typeof timestamp === 'number' ? timestamp : startTime.timestampUNIX;
+  const eventISO = new Date(eventUNIX * 1000).toISOString();
+
+  // Look up the user by email
+  const snapshot = await admin.firestore().collection('users')
+    .where('auth.email', '==', email)
+    .limit(1)
+    .get()
+    .catch((e) => {
+      assistant.error(`sendgrid webhook: user lookup failed for ${email}:`, e);
+      return null;
+    });
+
+  if (!snapshot || snapshot.empty) {
+    // Silent skip — this email may not map to a customer of THIS brand (shared SendGrid account).
+    assistant.log(`sendgrid webhook: no user found for ${email}, skipping doc update`);
+    return { handled: false, reason: 'user-not-found', email };
+  }
+
+  const userDoc = snapshot.docs[0];
+  const uid = userDoc.id;
+
+  // Write consent.marketing.status = 'revoked' (preserve grantedAt — informational audit trail)
+  await admin.firestore().doc(`users/${uid}`).set({
+    consent: {
+      marketing: {
+        status: 'revoked',
+        revokedAt: {
+          timestamp: eventISO,
+          timestampUNIX: eventUNIX,
+          source: 'sendgrid',
+          ip: null,
+          text: null,
+        },
+      },
+    },
+    metadata: Manager.Metadata().set({ tag: 'marketing/webhook:sendgrid' }),
+  }, { merge: true });
+
+  assistant.log(`sendgrid webhook: revoked consent.marketing for ${uid} (${email}) — eventType=${eventType}`);
+
+  // Cross-provider sync: also remove from Beehiiv (best-effort, idempotent on 404)
+  const shouldCallExternalAPIs = !assistant.isTesting() || process.env.TEST_EXTENDED_MODE;
+
+  if (shouldCallExternalAPIs) {
+    try {
+      const mailer = Manager.Email(assistant);
+      await mailer.remove(email);
+      assistant.log(`sendgrid webhook: cross-provider sync complete for ${email}`);
+    } catch (e) {
+      // Best-effort — user doc is already updated. Log + continue.
+      assistant.error(`sendgrid webhook: cross-provider sync failed for ${email}:`, e);
+    }
+  } else {
+    assistant.log('sendgrid webhook: skipping cross-provider sync (BEM_TESTING=true)');
+  }
+
+  return { handled: true, uid, email, eventType };
+}
+
+module.exports = {
+  parseWebhook,
+  isSupported,
+  handleEvent,
+};

package/src/manager/routes/payments/cancel/post.js

@@ -32,9 +32,9 @@ module.exports = async ({ assistant, user, settings }) => {
     return assistant.respond('No active paid subscription found', { code: 400 });
   }
 
-  // Guard: subscription younger than 24 hours
+  // Guard: subscription younger than 24 hours (callers may bypass via skipGuards)
   const startDateUNIX = subscription.payment?.startDate?.timestampUNIX;
-  if (startDateUNIX) {
+  if (!settings.skipGuards && startDateUNIX) {
     const ageMs = Date.now() - (startDateUNIX * 1000);
     const twentyFourHoursMs = 24 * 60 * 60 * 1000;
     if (ageMs < twentyFourHoursMs) {

package/src/manager/routes/payments/cancel/processors/test.js

@@ -23,7 +23,8 @@ module.exports = {
     const now = Math.floor(timestamp / 1000);
     const periodEnd = now + (30 * 86400);
 
-    // Look up the Stripe product ID from the existing order so resolveProduct() can match
+    // Look up the Stripe product ID from the existing order so resolveProduct() can match.
+    // Falls back to the "_test_<id>" sentinel when no real Stripe product is configured.
     const orderId = subscription?.payment?.orderId;
     let stripeProductId = null;
 
@@ -34,7 +35,9 @@ module.exports = {
         const productId = orderData.unified?.product?.id;
         const products = assistant.Manager.config.payment?.products || [];
         const product = products.find(p => p.id === productId);
-        stripeProductId = product?.stripe?.productId || null;
+        if (product) {
+          stripeProductId = product.stripe?.productId || `_test_${product.id}`;
+        }
       }
     }
 

package/src/manager/routes/payments/intent/processors/test.js

@@ -57,14 +57,18 @@ async function createSubscriptionIntent({ uid, orderId, product, frequency, tria
   const now = Math.floor(timestamp / 1000);
   const periodEnd = now + (FREQUENCY_TO_PERIOD[frequency] || 30 * 86400);
 
-  // Build Stripe-shaped subscription object
-  // Uses product's Stripe product ID so resolveProduct() can match it
+  // Build Stripe-shaped subscription object.
+  // Prefer the real Stripe product ID if configured; otherwise use a sentinel of the
+  // form "_test_<id>" that the Stripe resolver recognizes and maps back to product.id.
+  // This lets the test processor work in brands that haven't wired up Stripe yet.
+  const planProductId = product.stripe?.productId || `_test_${product.id}`;
+
   const subscription = {
     id: subscriptionId,
     object: 'subscription',
     status: trial && product.trial?.days ? 'trialing' : 'active',
     metadata: { uid, orderId },
-    plan: { product: product.stripe?.productId || null, interval },
+    plan: { product: planProductId, interval },
     current_period_end: periodEnd,
     current_period_start: now,
     start_date: now,

package/src/manager/routes/payments/refund/processors/test.js

@@ -22,6 +22,7 @@ module.exports = {
 
     // Look up the Stripe product ID from the existing order so resolveProduct() can match
     const orderId = subscription?.payment?.orderId;
+    // Falls back to the "_test_<id>" sentinel when no real Stripe product is configured.
     let stripeProductId = null;
 
     if (orderId) {
@@ -31,7 +32,9 @@ module.exports = {
         const productId = orderData.unified?.product?.id;
         const products = assistant.Manager.config.payment?.products || [];
         const product = products.find(p => p.id === productId);
-        stripeProductId = product?.stripe?.productId || null;
+        if (product) {
+          stripeProductId = product.stripe?.productId || `_test_${product.id}`;
+        }
       }
     }
 

package/src/manager/routes/user/signup/post.js

@@ -76,7 +76,12 @@ module.exports = async ({ assistant, user, settings, libraries }) => {
   await processAffiliate(assistant, uid, email, settings);
 
   // 6. Send emails + marketing (non-blocking, fire-and-forget)
-  syncMarketingContact(assistant, uid, email);
+  // Gate marketing sync on explicit consent — never add a user to marketing lists without it
+  if (userRecord.consent?.marketing?.status === 'granted') {
+    syncMarketingContact(assistant, uid, email);
+  } else {
+    assistant.log(`signup(): Skipping marketing sync — consent.marketing.status is "${userRecord.consent?.marketing?.status}"`);
+  }
   sendWelcomeEmails(assistant, uid, inferred?.firstName);
 
   return assistant.respond({ signedUp: true });
@@ -137,6 +142,7 @@ function buildUserRecord(assistant, settings, inferred) {
       },
     },
     attribution: attribution || {},
+    consent: buildConsentRecord(assistant, settings.consent),
     metadata: Manager.Metadata().set({ tag: 'user/signup' }),
   };
 
@@ -156,6 +162,64 @@ function buildUserRecord(assistant, settings, inferred) {
   return record;
 }
 
+/**
+ * Translate the client's lightweight consent payload into the canonical user-doc shape.
+ *
+ * Client sends: { legal: { granted, text }, marketing: { granted, text } }
+ * Server writes: { legal: { status, grantedAt: {...} }, marketing: { status, grantedAt: {...}, revokedAt: {...} } }
+ *
+ * Server time (not client-supplied) is authoritative — defends against clock manipulation.
+ * IP is captured from request geolocation.
+ *
+ * Legal is REQUIRED — the client must send legal.granted=true. If missing/false we still
+ * record what the client sent, but the route will not have reached this point in practice
+ * (the signup-form HTML5-requires the legal checkbox).
+ */
+function buildConsentRecord(assistant, clientConsent) {
+  const consent = clientConsent || {};
+  const ip = assistant.request.geolocation?.ip || null;
+  const timestamp = assistant.meta.startTime.timestamp;
+  const timestampUNIX = assistant.meta.startTime.timestampUNIX;
+
+  // Build empty leaf shape — used wherever grantedAt or revokedAt is "not set"
+  const emptyMeta = { timestamp: null, timestampUNIX: null, source: null, ip: null, text: null };
+
+  // --- Legal ---
+  const legalGranted = consent.legal?.granted === true;
+  const legalText = typeof consent.legal?.text === 'string' ? consent.legal.text : null;
+
+  const legal = legalGranted
+    ? {
+      status: 'granted',
+      grantedAt: { timestamp, timestampUNIX, source: 'signup', ip, text: legalText },
+    }
+    : {
+      status: 'revoked',
+      grantedAt: { ...emptyMeta },
+    };
+
+  // --- Marketing ---
+  const marketingGranted = consent.marketing?.granted === true;
+  const marketingText = typeof consent.marketing?.text === 'string' ? consent.marketing.text : null;
+
+  const marketing = marketingGranted
+    ? {
+      status: 'granted',
+      grantedAt: { timestamp, timestampUNIX, source: 'signup', ip, text: marketingText },
+      revokedAt: { ...emptyMeta },
+    }
+    : {
+      status: 'revoked',
+      grantedAt: { ...emptyMeta },
+      // Record the decline with source=signup-form-declined. text=null (no message shown).
+      revokedAt: { timestamp, timestampUNIX, source: 'signup', ip, text: null },
+    };
+
+  assistant.log(`buildConsentRecord: legal=${legal.status}, marketing=${marketing.status} (raw input legal.granted=${consent.legal?.granted}, marketing.granted=${consent.marketing?.granted})`);
+
+  return { legal, marketing };
+}
+
 /**
  * Infer name/company from email using AI (or regex fallback)
  * Returns the inferred contact info, or null on failure

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

@@ -1,9 +1,13 @@
 /**
  * Schema for POST /marketing/email-preferences
+ *
+ * Two supported modes (route decides based on user.authenticated):
+ * - Authenticated (account page toggle): action ('subscribe' | 'unsubscribe'). Other fields ignored.
+ * - Anonymous (HMAC link from email footer): email + asmId + sig + action ('subscribe' | 'unsubscribe').
  */
 module.exports = () => ({
-  email: { types: ['string'], default: undefined, required: true },
-  asmId: { types: ['string', 'number'], default: undefined, required: true },
-  action: { types: ['string'], default: 'unsubscribe' },
-  sig: { types: ['string'], default: undefined, required: true },
+  email: { types: ['string'], default: undefined, required: false },
+  asmId: { types: ['string', 'number'], default: undefined, required: false },
+  action: { types: ['string'], default: 'unsubscribe', required: true },
+  sig: { types: ['string'], default: undefined, required: false },
 });

package/src/manager/schemas/marketing/webhook/forward/post.js

@@ -0,0 +1,8 @@
+/**
+ * Schema: POST /marketing/webhook/forward
+ *
+ * Empty by design — the body is the raw provider webhook payload that gets
+ * forwarded to every child BEM unchanged. Validation happens in the dispatcher
+ * (provider + key query params) and at each child's receiver.
+ */
+module.exports = () => ({});

package/src/manager/schemas/marketing/webhook/post.js

@@ -0,0 +1,7 @@
+/**
+ * Schema: POST /marketing/webhook
+ *
+ * Empty by design — webhook payloads are provider-defined and validated inside
+ * each processor module. Auth + provider come from query params, not the body.
+ */
+module.exports = () => ({});

package/src/manager/schemas/payments/cancel/post.js

@@ -15,4 +15,9 @@ module.exports = () => ({
     types: ['boolean'],
     required: true,
   },
+  // Bypass route-level guards (e.g. 24-hour subscription age). Used by tests and internal callers.
+  skipGuards: {
+    types: ['boolean'],
+    default: false,
+  },
 });

package/src/manager/schemas/user/signup/post.js

@@ -19,4 +19,9 @@ module.exports = ({ user }) => ({
     default: {},
     required: false,
   },
+  consent: {
+    types: ['object'],
+    default: {},
+    required: false,
+  },
 });