@omega.js/backend 0.1.0

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

@@ -0,0 +1,275 @@
+/**
+ * POST /marketing/email-preferences - Update marketing email consent
+ *
+ * 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.
+ *    - Then cross-syncs via the email library (best-effort): unsubscribe removes the
+ *      contact from ALL providers (Beehiiv too — compliance); subscribe re-adds the
+ *      contact (sync when the email maps to a user, add when it doesn't).
+ */
+const fetch = require('wonderful-fetch');
+const crypto = require('crypto');
+const env = require('../../../libraries/env.js');
+const { MARKETING_RATE_LIMIT } = require('../../../libraries/rate-limits.js');
+
+module.exports = async ({ ctx, Manager, user, settings, analytics }) => {
+
+  // --- AUTHENTICATED MODE ---
+  if (user.authenticated) {
+    return handleAuthenticated({ ctx, Manager, user, settings, analytics });
+  }
+
+  // --- ANONYMOUS HMAC MODE ---
+  return handleAnonymous({ ctx, Manager, settings, analytics });
+};
+
+/**
+ * Authenticated user toggling marketing on/off from the account page.
+ */
+async function handleAuthenticated({ ctx, Manager, user, settings, analytics }) {
+  const { admin } = Manager.libraries;
+  const action = settings.action;
+
+  if (action !== 'subscribe' && action !== 'unsubscribe') {
+    return ctx.respond('Invalid action — must be "subscribe" or "unsubscribe"', { code: 400 });
+  }
+
+  // Rate-limit per-user (defense against accidental toggling spam). consume()
+  // is check, count and write in ONE call and throws the 429 itself
+  // ([#647](https://github.com/Omega-JS-Stack/omega/issues/647)); the limit is
+  // EXPLICIT because this is a framework anti-abuse gate, not a plan feature.
+  try {
+    await ctx.usage.consume('email-preferences', 1, { limit: MARKETING_RATE_LIMIT });
+  } catch (e) {
+    // Only a rate limit is a rate limit — a 500 from consume() must not come
+    // back as one
+    if (e.code !== 429) {
+      throw e;
+    }
+
+    return ctx.respond('Rate limit exceeded', { code: 429 });
+  }
+
+  const uid = user.auth.uid;
+  const email = user.auth.email;
+  const ip = ctx.request.geolocation?.ip || null;
+  const timestamp = ctx.meta.startTime.timestamp;
+  const timestampUNIX = ctx.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 });
+
+  ctx.log(`email-preferences (auth): ${uid} → ${action}`);
+
+  // Skip provider calls in test mode unless extended mode is on
+  const shouldCallExternalAPIs = !ctx.isTesting() || process.env.TEST_EXTENDED_MODE;
+
+  if (shouldCallExternalAPIs) {
+    const mailer = Manager.Email(ctx);
+
+    try {
+      if (action === 'unsubscribe') {
+        await mailer.remove(email);
+      } else {
+        await mailer.sync(uid);
+      }
+    } catch (e) {
+      ctx.error(`email-preferences (auth) provider sync failed:`, e);
+      // Doc is already updated — provider sync is best-effort. Don't fail the request.
+    }
+  } else {
+    ctx.log('email-preferences (auth): Skipping provider calls (OMEGA_TEST_MODE=true)');
+  }
+
+  analytics.event('marketing/email-preferences', { action, mode: 'authenticated' });
+
+  return ctx.respond({ success: true, action });
+}
+
+/**
+ * Anonymous HMAC unsubscribe link (preserves existing email-footer one-click flow).
+ */
+async function handleAnonymous({ ctx, Manager, settings, analytics }) {
+  const { admin } = Manager.libraries;
+
+  const email = (settings.email || '').trim().toLowerCase();
+  const asmId = parseInt(settings.asmId, 10);
+  const action = settings.action || 'unsubscribe';
+
+  // Validate inputs
+  if (!email) {
+    return ctx.respond('Email is required', { code: 400 });
+  }
+
+  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+  if (!emailRegex.test(email)) {
+    return ctx.respond('Invalid email format', { code: 400 });
+  }
+
+  if (!asmId || isNaN(asmId)) {
+    return ctx.respond('ASM group ID is required', { code: 400 });
+  }
+
+  if (action !== 'subscribe' && action !== 'unsubscribe') {
+    return ctx.respond('Invalid action', { code: 400 });
+  }
+
+  // HMAC validation (proves we generated this link)
+  const expectedSig = crypto.createHmac('sha256', env.require('UNSUBSCRIBE_HMAC_KEY')).update(email).digest('hex');
+  if (settings.sig !== expectedSig) {
+    return ctx.respond('Invalid signature', { code: 403 });
+  }
+
+  // IP rate limiting (anonymous flow) — an EXPLICIT keyed counter, which is
+  // the only way an anonymous caller is counted now
+  // ([#647](https://github.com/Omega-JS-Stack/omega/issues/647))
+  try {
+    await ctx.usage.forKey(ctx.request.geolocation.ip).consume('email-preferences', 1, { limit: MARKETING_RATE_LIMIT });
+  } catch (e) {
+    // Only a rate limit is a rate limit — a 500 from consume() must not come
+    // back as one
+    if (e.code !== 429) {
+      throw e;
+    }
+
+    return ctx.respond('Rate limit exceeded', { code: 429 });
+  }
+
+  // Mirror to the user doc if this email maps to a user (best-effort, silent on miss).
+  // Runs BEFORE the provider calls below — on subscribe it writes consent granted first,
+  // so the email library's consent gate passes when we re-sync.
+  const uid = await mirrorAnonymousToUserDoc({ ctx, Manager, email, action });
+
+  // Call SendGrid ASM (legacy behavior)
+  const shouldCallExternalAPIs = !ctx.isTesting() || process.env.TEST_EXTENDED_MODE;
+
+  if (!shouldCallExternalAPIs) {
+    ctx.log('email-preferences (anon): Skipping SendGrid (OMEGA_TEST_MODE=true)');
+    return ctx.respond({ success: true });
+  }
+
+  try {
+    if (action === 'unsubscribe') {
+      // 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 ${env.get('SENDGRID_API_KEY')}` },
+        timeout: 60000,
+        body: { recipient_emails: [email] },
+      });
+    } else {
+      // 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: 'text',
+        headers: { 'Authorization': `Bearer ${env.get('SENDGRID_API_KEY')}` },
+        timeout: 60000,
+      });
+    }
+  } catch (e) {
+    ctx.log(`SendGrid ASM ${action} error:`, e);
+    return ctx.respond('Failed to process your request', { code: 500 });
+  }
+
+  // Cross-provider sync via the email library (best-effort — ASM suppression above
+  // already succeeded). Unsubscribe must remove the contact from Beehiiv too
+  // (compliance); subscribe must actually re-add the contact: sync the matched user
+  // (the mirror above already wrote consent granted, so the library consent gate
+  // passes) or add a bare newsletter contact when no user matched.
+  const mailer = Manager.Email(ctx);
+
+  try {
+    if (action === 'unsubscribe') {
+      await mailer.remove(email);
+    } else if (uid) {
+      await mailer.sync(uid);
+    } else {
+      await mailer.add({ email, source: 'resubscribe' });
+    }
+  } catch (e) {
+    ctx.error(`email-preferences (anon) provider sync failed:`, e);
+    // Doc + ASM are already updated — provider sync is best-effort. Don't fail the request.
+  }
+
+  ctx.log('email-preferences (anon) result:', { email, asmId, action });
+  analytics.event('marketing/email-preferences', { action, mode: 'anonymous' });
+
+  return ctx.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.
+ *
+ * @returns {Promise<string|null>} The matched user's uid, or null when no user matches.
+ */
+async function mirrorAnonymousToUserDoc({ ctx, Manager, email, action }) {
+  const { admin } = Manager.libraries;
+
+  const snapshot = await admin.firestore().collection('users')
+    .where('auth.email', '==', email)
+    .limit(1)
+    .get()
+    .catch((e) => {
+      ctx.error('email-preferences (anon): Failed to look up user by email:', e);
+      return null;
+    });
+
+  if (!snapshot || snapshot.empty) {
+    return null; // Silent — email may not map to a current user
+  }
+
+  const userDoc = snapshot.docs[0];
+  const uid = userDoc.id;
+  const timestamp = ctx.meta.startTime.timestamp;
+  const timestampUNIX = ctx.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) => {
+      ctx.error(`email-preferences (anon): Failed to mirror to user doc ${uid}:`, e);
+    });
+
+  return uid;
+}

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

@@ -0,0 +1,170 @@
+/**
+ * POST /marketing/webhook/forward?provider=sendgrid|beehiiv&key=<OMEGA_WEBHOOK_KEY>
+ *
+ * Parent-only forwarder. SendGrid and Beehiiv send webhooks to this single URL
+ * on the parent @omega.js/backend. 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 OMEGA_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 `/omega/marketing/webhook` on that host.
+ *
+ * Self-inclusion:
+ *   - The parent's own brand IS included in the fan-out. The parent @omega.js/backend 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 safeCompare = require('../../../../helpers/safe-compare.js');
+const env = require('../../../../libraries/env.js');
+
+const CHILD_TIMEOUT_MS = 10000;
+
+module.exports = async ({ ctx, Manager, libraries }) => {
+  const { admin } = libraries;
+  const query = ctx.request.query;
+
+  // Gate: only the parent @omega.js/backend 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 ctx.respond('Not found', { code: 404 });
+  }
+
+  const provider = query.provider;
+  const key = query.key;
+
+  if (!provider) {
+    return ctx.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 (!safeCompare(key, env.get('OMEGA_WEBHOOK_KEY'))) {
+    return ctx.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) => {
+      ctx.error('marketing webhook forward: failed to read brands collection:', e);
+      return null;
+    });
+
+  if (!snapshot) {
+    return ctx.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) {
+      ctx.log(`marketing webhook forward: brand ${brandId} has no brand.url, skipping`);
+      return;
+    }
+
+    brands.push({ brandId, brandUrl });
+  });
+
+  if (brands.length === 0) {
+    ctx.log('marketing webhook forward: no brands to forward to');
+    return ctx.respond({ received: true, forwarded: 0 });
+  }
+
+  ctx.log(`marketing webhook forward: fanning out ${provider} event to ${brands.length} brand(s)`);
+
+  // Forward the raw body to every child. ctx.ref.req.body holds the body
+  // as we received it from the provider. We re-POST it without modification.
+  const rawBody = ctx.ref.req?.body;
+
+  const results = await Promise.allSettled(
+    brands.map(({ brandId, brandUrl }) => forwardToChild({
+      ctx,
+      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 });
+      ctx.error(`marketing webhook forward: ${brand.brandId} failed:`, reason);
+    }
+  }
+
+  ctx.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 ctx.respond({
+    received: true,
+    forwarded: brands.length,
+    succeeded,
+    failed,
+    failures: failures.length > 0 ? failures : undefined,
+  });
+};
+
+/**
+ * POST the raw body to one child @omega.js/backend's /marketing/webhook receiver.
+ * Returns { ok: true } on success, { ok: false, error } on failure.
+ */
+async function forwardToChild({ ctx, 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 = '/omega/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,
+    });
+    ctx.log(`marketing webhook forward: ${brandId} OK — ${JSON.stringify(result)}`);
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, error: e?.message || String(e) };
+  }
+}

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

@@ -0,0 +1,123 @@
+/**
+ * POST /marketing/webhook?provider=sendgrid|beehiiv&key=<OMEGA_WEBHOOK_KEY>
+ *
+ * Receives cross-provider unsubscribe webhooks (SendGrid + Beehiiv) and:
+ *   1. Authenticates via ?key= query param (OMEGA_WEBHOOK_KEY env)
+ *   2. Optionally rejects mismatched brand via ?brand= filter
+ *   3. Loads the matching provider module from ./providers/{provider}.js
+ *   4. Parses the webhook payload into one or more normalized events
+ *   5. For each supported event: dispatch to the provider's handler
+ *   6. Returns 200 immediately so the provider doesn't retry
+ *
+ * Each provider module defines:
+ *   - parseWebhook(req)   — returns Array<{ eventId, eventType, email, timestamp, raw, ... }>
+ *   - isSupported(parsed) — returns true if this parsed event should be processed
+ *   - handleEvent(ctx)    — does the work for one event (user doc + cross-provider sync)
+ *
+ * No idempotency ledger: every supported handler (revoke consent + cross-provider
+ * remove) is naturally idempotent — re-processing a provider retry produces the same
+ * end state with no extra side effects, so duplicate suppression buys nothing.
+ */
+const path = require('path');
+const loadProvider = require('../../../libraries/load-provider.js');
+const safeCompare = require('../../../helpers/safe-compare.js');
+const env = require('../../../libraries/env.js');
+
+module.exports = async ({ ctx, Manager }) => {
+  const query = ctx.request.query;
+
+  const provider = query.provider;
+  const key = query.key;
+
+  // Validate provider
+  if (!provider) {
+    return ctx.respond('Missing provider parameter', { code: 400 });
+  }
+
+  // Validate key against OMEGA_WEBHOOK_KEY (separate from OMEGA_ADMIN_KEY
+  // so it can be rotated independently and scoped narrowly)
+  if (!safeCompare(key, env.get('OMEGA_WEBHOOK_KEY'))) {
+    return ctx.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) {
+    ctx.log(`marketing webhook: brand mismatch (received=${brand}, expected=${ourBrand}), ignoring`);
+    return ctx.respond({ received: true, ignored: true });
+  }
+
+  // Load the provider module
+  let providerModule;
+  try {
+    providerModule = loadProvider(path.join(__dirname, 'providers'), provider);
+  } catch (e) {
+    ctx.error(`marketing webhook: failed to load provider "${provider}":`, e);
+    return ctx.respond(`Unknown provider: ${provider}`, { code: 400 });
+  }
+
+  // Parse the webhook body into events
+  let events;
+  try {
+    events = providerModule.parseWebhook(ctx.ref.req);
+  } catch (e) {
+    ctx.error(`marketing webhook: parse failed for ${provider}:`, e);
+    return ctx.respond(`Failed to parse webhook: ${e.message}`, { code: 400 });
+  }
+
+  if (!Array.isArray(events) || events.length === 0) {
+    ctx.log(`marketing webhook: ${provider} returned no events`);
+    return ctx.respond({ received: true, processed: 0 });
+  }
+
+  ctx.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, ctx, provider, event, providerModule }))
+  );
+
+  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++;
+      ctx.error('marketing webhook: event processing rejected:', r.reason);
+    }
+  }
+
+  ctx.log(`marketing webhook: ${provider} complete — processed=${processed}, skipped=${skipped}, failed=${failed}`);
+
+  return ctx.respond({ received: true, processed, skipped, failed });
+};
+
+/**
+ * Process a single event: support check, then dispatch to the provider's handler.
+ * Handlers are idempotent, so provider retries re-run safely with no dedup ledger.
+ * Returns { processed: bool, skipped?: string, error?: any }.
+ */
+async function processOneEvent({ Manager, ctx, provider, event, providerModule }) {
+  const { eventType } = event;
+
+  // Filter by supported event types
+  if (providerModule.isSupported && !providerModule.isSupported(event)) {
+    return { processed: false, skipped: 'unsupported-event-type' };
+  }
+
+  try {
+    await providerModule.handleEvent({ Manager, ctx, parsed: event });
+    return { processed: true };
+  } catch (e) {
+    ctx.error(`marketing webhook: handler failed for ${provider} event ${event.eventId} (${eventType}):`, e);
+    return { processed: false, error: e };
+  }
+}