backend-manager 5.0.118 → 5.0.119

package/CHANGELOG.md

@@ -14,6 +14,34 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - `Fixed` for any bug fixes.
 - `Security` in case of vulnerabilities.
 
+# [5.0.119] - 2026-03-07
+### Added
+- `POST /marketing/email-preferences` route for unsubscribe/resubscribe via SendGrid ASM suppression groups
+- HMAC signature verification (`UNSUBSCRIBE_HMAC_KEY`) on unsubscribe links to prevent forged requests
+- HMAC signature generation in email library when building unsubscribe URLs
+- `UNSUBSCRIBE_HMAC_KEY` environment variable in template `.env`
+- Test suite for email-preferences endpoint (10 tests covering sig verification, validation, auth)
+
+### Changed
+- Unsubscribe URL in emails no longer includes `appName` and `appUrl` params (replaced by HMAC sig)
+
+# [5.0.118] - 2026-03-06
+### Added
+- Chargebee payment processor with full pipeline support (intent, webhook, cancel, refund, portal).
+- Chargebee shared library (`payment/processors/chargebee.js`) with raw HTTP API wrapper, unified subscription/one-time transformers, and both Items model (new) and Plans model (legacy) product resolution.
+- Chargebee webhook processor supporting subscription lifecycle events (`subscription_created`, `subscription_cancelled`, `subscription_renewed`, `payment_failed`, `payment_refunded`, etc.) and one-time invoice events.
+- Chargebee intent processor for hosted page checkout (subscriptions and one-time purchases) with deterministic item price IDs (`{itemId}-{frequency}`).
+- Chargebee cancel processor with immediate cancellation during trials and end-of-term cancellation otherwise.
+- Chargebee refund processor with 7-day full/prorated refund logic (matching Stripe/PayPal behavior).
+- Chargebee portal processor for self-service subscription management via Chargebee Portal Sessions.
+- Backwards compatibility for legacy Chargebee subscriptions: reads `cf_clientorderid`/`cf_uid` custom fields alongside new `meta_data` JSON format.
+- Chargebee test suite: `to-unified-subscription`, `to-unified-one-time`, and `parse-webhook` group tests with fixtures covering all status mappings, product resolution (Items + legacy Plans), and edge cases.
+- Chargebee customer name extraction from `shipping_address`/`billing_address` in webhook on-write pipeline.
+- `chargebee` config keys in product templates (`itemId`, `legacyPlanIds`).
+
+### Changed
+- `CHARGEBEE_SITE` environment variable is now set from config in Manager init (matching PayPal pattern), so the Chargebee library doesn't need a Manager reference.
+
 # [5.0.111] - 2026-03-05
 ### Changed
 - PayPal client ID is now read from `backend-manager-config.json` (`payment.processors.paypal.clientId`) instead of requiring a `PAYPAL_CLIENT_ID` environment variable.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backend-manager",
-  "version": "5.0.118",
+  "version": "5.0.119",
   "description": "Quick tools for developing Firebase functions",
   "main": "src/manager/index.js",
   "bin": {

package/src/manager/libraries/email.js

@@ -161,7 +161,11 @@ Email.prototype.build = async function (settings) {
   const sendAt = normalizeSendAt(settings.sendAt);
 
   // Build unsubscribe URL
-  const unsubscribeUrl = `${Manager.project.websiteUrl}/portal/account/email-preferences?email=${encode(to[0].email)}&asmId=${encode(groupId)}&templateId=${encode(templateId)}&appName=${brandData.name}&appUrl=${brandData.url}`;
+  // Generate HMAC signature for unsubscribe link verification
+  const crypto = require('crypto');
+  const unsubSig = crypto.createHmac('sha256', process.env.UNSUBSCRIBE_HMAC_KEY).update(to[0].email.toLowerCase()).digest('hex');
+
+  const unsubscribeUrl = `${Manager.project.websiteUrl}/portal/email-preferences?email=${encode(to[0].email)}&asmId=${encode(groupId)}&templateId=${encode(templateId)}&sig=${unsubSig}`;
 
   // Build signoff
   const signoff = settings?.data?.signoff || {};

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

@@ -0,0 +1,108 @@
+/**
+ * POST /marketing/email-preferences - Update email preferences
+ * Public endpoint — no authentication required
+ *
+ * Supports two actions:
+ * - "unsubscribe": Adds email to SendGrid ASM suppression group
+ * - "resubscribe": Removes email from SendGrid ASM suppression group
+ */
+const fetch = require('wonderful-fetch');
+const crypto = require('crypto');
+
+const RATE_LIMIT = 5;
+
+module.exports = async ({ assistant, Manager, settings, analytics }) => {
+
+  // Extract parameters
+  const email = (settings.email || '').trim().toLowerCase();
+  const asmId = parseInt(settings.asmId, 10);
+  const action = settings.action || 'unsubscribe';
+
+  // Validate email
+  if (!email) {
+    return assistant.respond('Email is required', { code: 400 });
+  }
+
+  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+  if (!emailRegex.test(email)) {
+    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') {
+    return assistant.respond('Invalid action', { code: 400 });
+  }
+
+  // Verify HMAC signature (proves the link was generated by our server)
+  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)
+  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 });
+  }
+  usage.increment('email-preferences');
+  await usage.update();
+
+  // Skip external API calls in test mode unless TEST_EXTENDED_MODE is set
+  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)');
+    return assistant.respond({ success: true });
+  }
+
+  // Call SendGrid ASM API
+  try {
+    if (action === 'unsubscribe') {
+      // Add email to suppression group
+      await fetch(`https://api.sendgrid.com/v3/asm/groups/${asmId}/suppressions`, {
+        method: 'POST',
+        response: 'json',
+        headers: {
+          'Authorization': `Bearer ${process.env.SENDGRID_API_KEY}`,
+        },
+        timeout: 10000,
+        body: {
+          recipient_emails: [email],
+        },
+      });
+    } else {
+      // Remove email from suppression group
+      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}`,
+        },
+        timeout: 10000,
+      });
+    }
+  } catch (e) {
+    assistant.log(`SendGrid ASM ${action} error:`, e);
+    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 });
+
+  // Generic success (no sensitive info leakage)
+  return assistant.respond({ success: true });
+};

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

@@ -0,0 +1,9 @@
+/**
+ * Schema for POST /marketing/email-preferences
+ */
+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 },
+});

package/templates/_.env

@@ -23,6 +23,7 @@ RECAPTCHA_SECRET_KEY=""
 SENDGRID_API_KEY=""
 BEEHIIV_API_KEY=""
 ZEROBOUNCE_API_KEY=""
+UNSUBSCRIBE_HMAC_KEY=""
 
 # ========== Custom Values ==========
 # Add your custom environment variables below this line

package/test/routes/marketing/email-preferences.js

@@ -0,0 +1,216 @@
+/**
+ * Test: POST /marketing/email-preferences
+ * Tests the email preferences endpoint for unsubscribe/resubscribe via SendGrid ASM
+ *
+ * Set TEST_EXTENDED_MODE=true to run tests against real SendGrid ASM API
+ * (requires SENDGRID_API_KEY env var)
+ */
+const crypto = require('crypto');
+
+const TEST_EMAIL = 'rachel.greene+bem-unsub@gmail.com';
+const TEST_ASM_ID = '24077';
+
+function generateSig(email) {
+  return crypto.createHmac('sha256', process.env.UNSUBSCRIBE_HMAC_KEY).update(email.toLowerCase()).digest('hex');
+}
+
+module.exports = {
+  description: 'Marketing email-preferences (POST unsubscribe/resubscribe)',
+  type: 'group',
+  tests: [
+    // Test 1: Successful unsubscribe with valid sig
+    {
+      name: 'unsubscribe-valid-sig-succeeds',
+      auth: 'none',
+      timeout: 15000,
+
+      async run({ http, assert }) {
+        const sig = generateSig(TEST_EMAIL);
+
+        const response = await http.post('marketing/email-preferences', {
+          email: TEST_EMAIL,
+          asmId: TEST_ASM_ID,
+          action: 'unsubscribe',
+          sig: sig,
+        });
+
+        assert.isSuccess(response, 'Unsubscribe with valid sig should succeed');
+        assert.propertyEquals(response, 'data.success', true, 'success should be true');
+      },
+    },
+
+    // Test 2: Successful resubscribe with valid sig
+    {
+      name: 'resubscribe-valid-sig-succeeds',
+      auth: 'none',
+      timeout: 15000,
+
+      async run({ http, assert }) {
+        const sig = generateSig(TEST_EMAIL);
+
+        const response = await http.post('marketing/email-preferences', {
+          email: TEST_EMAIL,
+          asmId: TEST_ASM_ID,
+          action: 'resubscribe',
+          sig: sig,
+        });
+
+        assert.isSuccess(response, 'Resubscribe with valid sig should succeed');
+        assert.propertyEquals(response, 'data.success', true, 'success should be true');
+      },
+    },
+
+    // Test 3: Invalid sig rejected
+    {
+      name: 'invalid-sig-rejected',
+      auth: 'none',
+      timeout: 15000,
+
+      async run({ http, assert }) {
+        const response = await http.post('marketing/email-preferences', {
+          email: TEST_EMAIL,
+          asmId: TEST_ASM_ID,
+          action: 'unsubscribe',
+          sig: 'invalid-signature-value',
+        });
+
+        assert.isError(response, 403, 'Invalid sig should return 403');
+      },
+    },
+
+    // Test 4: Missing sig rejected (schema requires it)
+    {
+      name: 'missing-sig-rejected',
+      auth: 'none',
+      timeout: 15000,
+
+      async run({ http, assert }) {
+        const response = await http.post('marketing/email-preferences', {
+          email: TEST_EMAIL,
+          asmId: TEST_ASM_ID,
+          action: 'unsubscribe',
+        });
+
+        assert.isError(response, 400, 'Missing sig should return 400');
+      },
+    },
+
+    // Test 5: Missing email rejected
+    {
+      name: 'missing-email-rejected',
+      auth: 'none',
+      timeout: 15000,
+
+      async run({ http, assert }) {
+        const response = await http.post('marketing/email-preferences', {
+          asmId: TEST_ASM_ID,
+          action: 'unsubscribe',
+          sig: 'anything',
+        });
+
+        assert.isError(response, 400, 'Missing email should return 400');
+      },
+    },
+
+    // Test 6: Invalid email format rejected
+    {
+      name: 'invalid-email-rejected',
+      auth: 'none',
+      timeout: 15000,
+
+      async run({ http, assert }) {
+        const sig = generateSig('not-an-email');
+
+        const response = await http.post('marketing/email-preferences', {
+          email: 'not-an-email',
+          asmId: TEST_ASM_ID,
+          action: 'unsubscribe',
+          sig: sig,
+        });
+
+        assert.isError(response, 400, 'Invalid email format should return 400');
+      },
+    },
+
+    // Test 7: Missing asmId rejected
+    {
+      name: 'missing-asmid-rejected',
+      auth: 'none',
+      timeout: 15000,
+
+      async run({ http, assert }) {
+        const sig = generateSig(TEST_EMAIL);
+
+        const response = await http.post('marketing/email-preferences', {
+          email: TEST_EMAIL,
+          action: 'unsubscribe',
+          sig: sig,
+        });
+
+        assert.isError(response, 400, 'Missing asmId should return 400');
+      },
+    },
+
+    // Test 8: Invalid action rejected
+    {
+      name: 'invalid-action-rejected',
+      auth: 'none',
+      timeout: 15000,
+
+      async run({ http, assert }) {
+        const sig = generateSig(TEST_EMAIL);
+
+        const response = await http.post('marketing/email-preferences', {
+          email: TEST_EMAIL,
+          asmId: TEST_ASM_ID,
+          action: 'delete',
+          sig: sig,
+        });
+
+        assert.isError(response, 400, 'Invalid action should return 400');
+      },
+    },
+
+    // Test 9: Sig for different email rejected (proves per-email sig)
+    {
+      name: 'wrong-email-sig-rejected',
+      auth: 'none',
+      timeout: 15000,
+
+      async run({ http, assert }) {
+        // Generate sig for a different email
+        const sig = generateSig('someone-else@gmail.com');
+
+        const response = await http.post('marketing/email-preferences', {
+          email: TEST_EMAIL,
+          asmId: TEST_ASM_ID,
+          action: 'unsubscribe',
+          sig: sig,
+        });
+
+        assert.isError(response, 403, 'Sig for different email should return 403');
+      },
+    },
+
+    // Test 10: Authenticated user also works (sig is checked regardless of auth)
+    {
+      name: 'authenticated-user-with-valid-sig-succeeds',
+      auth: 'user',
+      timeout: 15000,
+
+      async run({ http, assert }) {
+        const sig = generateSig(TEST_EMAIL);
+
+        const response = await http.post('marketing/email-preferences', {
+          email: TEST_EMAIL,
+          asmId: TEST_ASM_ID,
+          action: 'unsubscribe',
+          sig: sig,
+        });
+
+        assert.isSuccess(response, 'Authenticated user with valid sig should succeed');
+        assert.propertyEquals(response, 'data.success', true, 'success should be true');
+      },
+    },
+  ],
+};