backend-manager 5.1.2 → 5.2.0

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

@@ -0,0 +1,168 @@
+/**
+ * POST /marketing/webhook/forward?provider=sendgrid|beehiiv&key=<BACKEND_MANAGER_WEBHOOK_KEY>
+ *
+ * Parent-only forwarder. SendGrid and Beehiiv send webhooks to this single URL
+ * on the parent BEM. The parent reads its `brands` collection and re-POSTs the
+ * raw body to every child's /marketing/webhook?provider=X. Each child then
+ * processes the event against its own Firestore and providers.
+ *
+ * Gating:
+ *   - Only enabled when Manager.config.parent === 'self'. Any other value (a URL
+ *     pointing TO the parent, the typical setup for child BEMs) returns 404.
+ *   - Same BACKEND_MANAGER_WEBHOOK_KEY is shared across all brands, so the
+ *     parent forwards the key it received (already validated) when calling
+ *     each child.
+ *
+ * Brand URL derivation:
+ *   - Each brand doc in the `brands` collection has `brand.url` (e.g. 'https://somiibo.com').
+ *   - API URL is derived by inserting 'api.' subdomain: 'https://api.somiibo.com'.
+ *   - Child receivers live at `/backend-manager/marketing/webhook` on that host.
+ *
+ * Self-inclusion:
+ *   - The parent's own brand IS included in the fan-out. The parent BEM has
+ *     its own user base (e.g. itwcreativeworks.com users) and needs the same
+ *     consent updates as any other brand. Self-fan-out goes via HTTP like
+ *     every other child — no special inline path.
+ *
+ * Failure isolation:
+ *   - Each child POST is awaited via Promise.allSettled so one slow/down child
+ *     doesn't block the others. Failures are logged but the overall request
+ *     still returns 200 so the provider doesn't retry the parent indefinitely.
+ *     Children themselves track idempotency, so provider retries are safe.
+ */
+const fetch = require('wonderful-fetch');
+
+const CHILD_TIMEOUT_MS = 10000;
+
+module.exports = async ({ assistant, Manager, libraries }) => {
+  const { admin } = libraries;
+  const query = assistant.request.query;
+
+  // Gate: only the parent BEM exposes this route. Any brand whose config.parent
+  // points to a URL (the normal case) returns 404 — pretend the route doesn't exist.
+  if (!Manager.isParent()) {
+    return assistant.respond('Not found', { code: 404 });
+  }
+
+  const provider = query.provider;
+  const key = query.key;
+
+  if (!provider) {
+    return assistant.respond('Missing provider parameter', { code: 400 });
+  }
+
+  // Same key used for the receiver — parent validates incoming, then re-uses
+  // it for outbound calls to children (all brands share this env value).
+  if (!key || key !== process.env.BACKEND_MANAGER_WEBHOOK_KEY) {
+    return assistant.respond('Invalid key', { code: 401 });
+  }
+
+  // Read the brands collection. This lives in the PARENT's Firestore.
+  const snapshot = await admin.firestore().collection('brands').get()
+    .catch((e) => {
+      assistant.error('marketing webhook forward: failed to read brands collection:', e);
+      return null;
+    });
+
+  if (!snapshot) {
+    return assistant.respond('Failed to load brands', { code: 500 });
+  }
+
+  // Collect brand URLs from the docs
+  const brands = [];
+  snapshot.forEach((doc) => {
+    const data = doc.data() || {};
+    const brandUrl = data.brand?.url || null;
+    const brandId = data.brand?.id || doc.id;
+
+    if (!brandUrl) {
+      assistant.log(`marketing webhook forward: brand ${brandId} has no brand.url, skipping`);
+      return;
+    }
+
+    brands.push({ brandId, brandUrl });
+  });
+
+  if (brands.length === 0) {
+    assistant.log('marketing webhook forward: no brands to forward to');
+    return assistant.respond({ received: true, forwarded: 0 });
+  }
+
+  assistant.log(`marketing webhook forward: fanning out ${provider} event to ${brands.length} brand(s)`);
+
+  // Forward the raw body to every child. assistant.ref.req.body holds the body
+  // as we received it from the provider. We re-POST it without modification.
+  const rawBody = assistant.ref.req?.body;
+
+  const results = await Promise.allSettled(
+    brands.map(({ brandId, brandUrl }) => forwardToChild({
+      assistant,
+      brandId,
+      brandUrl,
+      provider,
+      key,
+      body: rawBody,
+    }))
+  );
+
+  let succeeded = 0;
+  let failed = 0;
+  const failures = [];
+  for (let i = 0; i < results.length; i += 1) {
+    const r = results[i];
+    const brand = brands[i];
+    if (r.status === 'fulfilled' && r.value?.ok) {
+      succeeded += 1;
+    } else {
+      failed += 1;
+      const reason = r.status === 'rejected' ? r.reason?.message : (r.value?.error || 'unknown');
+      failures.push({ brandId: brand.brandId, reason });
+      assistant.error(`marketing webhook forward: ${brand.brandId} failed:`, reason);
+    }
+  }
+
+  assistant.log(`marketing webhook forward: ${provider} complete — succeeded=${succeeded}, failed=${failed}`);
+
+  // Always return 200 — child failures shouldn't make the provider retry the
+  // parent. Each child tracks its own idempotency so safe to re-fan on retry.
+  return assistant.respond({
+    received: true,
+    forwarded: brands.length,
+    succeeded,
+    failed,
+    failures: failures.length > 0 ? failures : undefined,
+  });
+};
+
+/**
+ * POST the raw body to one child BEM's /marketing/webhook receiver.
+ * Returns { ok: true } on success, { ok: false, error } on failure.
+ */
+async function forwardToChild({ assistant, brandId, brandUrl, provider, key, body }) {
+  // Derive API URL: brandUrl 'https://somiibo.com' → 'https://api.somiibo.com'.
+  // Use URL parsing so we tolerate trailing slashes and unusual hosts.
+  let apiUrl;
+  try {
+    const url = new URL(brandUrl);
+    url.hostname = `api.${url.hostname}`;
+    url.pathname = '/backend-manager/marketing/webhook';
+    url.search = `?provider=${encodeURIComponent(provider)}&key=${encodeURIComponent(key)}`;
+    apiUrl = url.toString();
+  } catch (e) {
+    return { ok: false, error: `Invalid brand URL "${brandUrl}": ${e.message}` };
+  }
+
+  try {
+    const result = await fetch(apiUrl, {
+      method: 'POST',
+      response: 'json',
+      timeout: CHILD_TIMEOUT_MS,
+      headers: { 'Content-Type': 'application/json' },
+      body,
+    });
+    assistant.log(`marketing webhook forward: ${brandId} OK — ${JSON.stringify(result)}`);
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, error: e?.message || String(e) };
+  }
+}

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

@@ -0,0 +1,180 @@
+/**
+ * POST /marketing/webhook?provider=sendgrid|beehiiv&key=<BACKEND_MANAGER_WEBHOOK_KEY>
+ *
+ * Receives cross-provider unsubscribe webhooks (SendGrid + Beehiiv) and:
+ *   1. Authenticates via ?key= query param (BACKEND_MANAGER_WEBHOOK_KEY env)
+ *   2. Optionally rejects mismatched brand via ?brand= filter
+ *   3. Loads the matching processor module from ./processors/{provider}.js
+ *   4. Parses the webhook payload into one or more normalized events
+ *   5. For each event: idempotency check via marketing-webhooks/{eventId}, then dispatch
+ *   6. Returns 200 immediately so the provider doesn't retry
+ *
+ * Each processor module defines:
+ *   - parseWebhook(req)   — returns Array<{ eventId, eventType, email, timestamp, raw, ... }>
+ *   - isSupported(type)   — returns true if this event should be processed
+ *   - handleEvent(ctx)    — does the work for one event (user doc + cross-provider sync)
+ *
+ * Mirrors the existing payments-webhook pattern. Processes events inline rather than
+ * via a Firestore trigger — marketing webhooks are lower volume and lighter work than
+ * payments, so the extra async layer isn't justified.
+ */
+const path = require('path');
+const powertools = require('node-powertools');
+
+module.exports = async ({ assistant, Manager, libraries }) => {
+  const { admin } = libraries;
+  const query = assistant.request.query;
+
+  const provider = query.provider;
+  const key = query.key;
+
+  // Validate provider
+  if (!provider) {
+    return assistant.respond('Missing provider parameter', { code: 400 });
+  }
+
+  // Validate key against BACKEND_MANAGER_WEBHOOK_KEY (separate from BACKEND_MANAGER_KEY
+  // so it can be rotated independently and scoped narrowly)
+  if (!key || key !== process.env.BACKEND_MANAGER_WEBHOOK_KEY) {
+    return assistant.respond('Invalid key', { code: 401 });
+  }
+
+  // Brand filter (defensive — mirror payments webhook pattern). If a brand is
+  // specified and doesn't match ours, silently ignore. This lets one webhook
+  // URL be shared across brands while each brand only processes its own events.
+  const brand = query.brand;
+  const ourBrand = Manager.config.brand?.id;
+  if (brand && ourBrand && brand !== ourBrand) {
+    assistant.log(`marketing webhook: brand mismatch (received=${brand}, expected=${ourBrand}), ignoring`);
+    return assistant.respond({ received: true, ignored: true });
+  }
+
+  // Load the processor module
+  let processorModule;
+  try {
+    processorModule = require(path.resolve(__dirname, `processors/${provider}.js`));
+  } catch (e) {
+    assistant.error(`marketing webhook: failed to load processor "${provider}":`, e);
+    return assistant.respond(`Unknown provider: ${provider}`, { code: 400 });
+  }
+
+  // Parse the webhook body into events
+  let events;
+  try {
+    events = processorModule.parseWebhook(assistant.ref.req);
+  } catch (e) {
+    assistant.error(`marketing webhook: parse failed for ${provider}:`, e);
+    return assistant.respond(`Failed to parse webhook: ${e.message}`, { code: 400 });
+  }
+
+  if (!Array.isArray(events) || events.length === 0) {
+    assistant.log(`marketing webhook: ${provider} returned no events`);
+    return assistant.respond({ received: true, processed: 0 });
+  }
+
+  assistant.log(`marketing webhook: ${provider} delivered ${events.length} event(s)`);
+
+  // Process each event independently — one failure shouldn't block the others.
+  // Use Promise.allSettled so we return success only after all events have been
+  // attempted.
+  const results = await Promise.allSettled(
+    events.map((event) => processOneEvent({ Manager, assistant, admin, provider, event, processorModule }))
+  );
+
+  let processed = 0;
+  let skipped = 0;
+  let failed = 0;
+  for (const r of results) {
+    if (r.status === 'fulfilled') {
+      if (r.value?.processed) processed++;
+      else skipped++;
+    } else {
+      failed++;
+      assistant.error('marketing webhook: event processing rejected:', r.reason);
+    }
+  }
+
+  assistant.log(`marketing webhook: ${provider} complete — processed=${processed}, skipped=${skipped}, failed=${failed}`);
+
+  return assistant.respond({ received: true, processed, skipped, failed });
+};
+
+/**
+ * Process a single event end-to-end: idempotency check, support check, dispatch to handler.
+ * Returns { processed: bool, skipped?: string, error?: any }.
+ */
+async function processOneEvent({ Manager, assistant, admin, provider, event, processorModule }) {
+  const { eventId, eventType } = event;
+
+  // No eventId means we can't dedupe — skip rather than risk double-processing
+  if (!eventId) {
+    assistant.log(`marketing webhook: ${provider} event missing eventId (type=${eventType}), skipping`);
+    return { processed: false, skipped: 'missing-event-id' };
+  }
+
+  // Filter by supported event types
+  if (processorModule.isSupported && !processorModule.isSupported(eventType)) {
+    return { processed: false, skipped: 'unsupported-event-type' };
+  }
+
+  // Idempotency: skip if we've already processed this event
+  const idempotencyRef = admin.firestore().doc(`marketing-webhooks/${eventId}`);
+  const existingDoc = await idempotencyRef.get();
+
+  if (existingDoc.exists) {
+    const existingStatus = existingDoc.data()?.status;
+    if (existingStatus !== 'failed') {
+      assistant.log(`marketing webhook: ${provider} duplicate event ${eventId} (status=${existingStatus}), skipping`);
+      return { processed: false, skipped: 'duplicate' };
+    }
+    assistant.log(`marketing webhook: ${provider} retrying previously failed event ${eventId}`);
+  }
+
+  // Build the audit doc
+  const now = powertools.timestamp(new Date(), { output: 'string' });
+  const nowUNIX = powertools.timestamp(now, { output: 'unix' });
+
+  // Write 'pending' state before dispatching so concurrent deliveries see the lock
+  await idempotencyRef.set({
+    id: eventId,
+    provider,
+    status: 'pending',
+    raw: event.raw || null,
+    event: {
+      type: eventType,
+      email: event.email || null,
+      timestamp: event.timestamp || null,
+    },
+    error: null,
+    metadata: {
+      created: { timestamp: now, timestampUNIX: nowUNIX },
+      completed: { timestamp: null, timestampUNIX: null },
+    },
+  });
+
+  // Dispatch to the processor's event handler
+  let handlerResult;
+  try {
+    handlerResult = await processorModule.handleEvent({ Manager, assistant, parsed: event });
+
+    // Mark completed
+    await idempotencyRef.set({
+      status: 'completed',
+      result: handlerResult || null,
+      metadata: {
+        completed: { timestamp: powertools.timestamp(new Date(), { output: 'string' }), timestampUNIX: powertools.timestamp(new Date(), { output: 'unix' }) },
+      },
+    }, { merge: true });
+
+    return { processed: true };
+  } catch (e) {
+    assistant.error(`marketing webhook: handler failed for ${provider} event ${eventId}:`, e);
+
+    await idempotencyRef.set({
+      status: 'failed',
+      error: { message: e.message || String(e), stack: e.stack || null },
+    }, { merge: true }).catch(() => {});
+
+    return { processed: false, error: e };
+  }
+}

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,
+};