backend-manager 5.9.6 → 5.9.8

package/test/email/campaign-send.js

@@ -0,0 +1,45 @@
+/**
+ * Test: Single marketing campaign send
+ * Verifies the full marketing pipeline end-to-end: prepare → render → audience → SendGrid Single Send.
+ * Sends to test_admin segment only.
+ */
+module.exports = {
+  description: 'Marketing campaign send',
+  auth: 'admin',
+  skip: !process.env.TEST_EXTENDED_MODE ? 'TEST_EXTENDED_MODE not set' : false,
+  timeout: 60000,
+
+  async run({ http, assert }) {
+    const response = await http.post('backend-manager/marketing/campaign', {
+      name: '[TEST] Summer Sale — Free Users',
+      subject: 'Summer Sale — {discount.percent}% Off Your First Month!',
+      preheader: 'Limited time offer — upgrade to Premium today',
+      template: 'card',
+      data: {
+        content: {
+          title: 'Summer Sale!',
+          message: [
+            'You\'ve been using **{brand.name}** on our free plan — and we think you\'ll love what\'s on the other side.',
+            '',
+            'For a limited time, upgrade to Premium and get **{discount.percent}% off** your first month.',
+            '',
+            'Use code **{discount.code}** at checkout.',
+          ].join('\n'),
+          button: { text: 'Upgrade Now →', url: '{brand.url}/pricing' },
+          discountCode: 'UPGRADE15',
+        },
+      },
+      test: true,
+      sendAt: 'now',
+    });
+
+    assert.isSuccess(response, 'Should create and schedule campaign');
+    assert.ok(response.data.id, 'Should have campaign ID');
+
+    const sg = response.data?.providers?.campaigns;
+    assert.ok(sg, 'Should have campaigns result');
+    assert.equal(sg.success, true, 'Campaigns (SendGrid) should succeed');
+    assert.ok(sg.id, 'Should have Single Send ID');
+    assert.equal(sg.scheduled, true, 'Should be scheduled');
+  },
+};

package/test/email/consent-lifecycle.js

@@ -0,0 +1,257 @@
+/**
+ * Test: Marketing Provider Lifecycle (end-to-end against live SendGrid + Beehiiv)
+ *
+ * Walks two long-lived test accounts through their full lifecycle and verifies
+ * provider state at every transition:
+ *
+ *   1. Pre-check    — both accounts should be absent from SendGrid + Beehiiv
+ *   2. Sync         — flip consent.marketing.status and call Marketing.sync()
+ *   3. Verify       — granted account present in both, declined account absent from both
+ *   4. Unsubscribe  — hit the email-preferences endpoint for the granted account
+ *   5. Verify       — granted account now absent from both
+ *
+ * The two accounts use the `_test.allow_*` prefix so they bypass the
+ * blocked-local-patterns gate (which blocks plain `_test.*` from reaching
+ * providers). They are the only accounts intentionally allowed to round-trip
+ * through SendGrid + Beehiiv.
+ *
+ * Run with TEST_EXTENDED_MODE=true (no-op otherwise). Requires SENDGRID_API_KEY
+ * and BEEHIIV_API_KEY in env. Total runtime is ~60-90s — most of it spent waiting
+ * for SendGrid's async upsert/delete background jobs to surface.
+ */
+const sendgridProvider = require('../../src/manager/libraries/email/providers/sendgrid.js');
+const beehiivProvider = require('../../src/manager/libraries/email/providers/beehiiv.js');
+
+const SETTLE_MS = 5000; // Beehiiv settles in 1-2s; SendGrid's background-job upsert can take 10-20s+
+const POLL_INTERVAL_MS = 2000;
+const POLL_MAX_MS = 90000; // SendGrid's delete-contact job can take 30-60s+ to surface
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Poll a provider lookup until it matches the expected state (present/absent).
+ * Returns the resolved value (contact object or null) once condition is met, or
+ * the last value seen after timing out.
+ *
+ * @param {Function} fetchFn - async function that returns contact or null
+ * @param {boolean} expectPresent - true = wait until present, false = wait until absent
+ */
+async function pollProvider(fetchFn, expectPresent) {
+  const start = Date.now();
+  let lastValue = null;
+
+  while (Date.now() - start < POLL_MAX_MS) {
+    lastValue = await fetchFn();
+    const present = !!lastValue;
+    if (present === expectPresent) {
+      return lastValue;
+    }
+    await sleep(POLL_INTERVAL_MS);
+  }
+
+  return lastValue;
+}
+
+module.exports = {
+  description: 'Marketing provider lifecycle (live SendGrid + Beehiiv round-trip)',
+  type: 'group',
+  skip: !process.env.TEST_EXTENDED_MODE
+    ? 'TEST_EXTENDED_MODE not set (this test hits live SendGrid + Beehiiv APIs)'
+    : false,
+  tests: [
+    // ─────────────────────────────────────────────────────────────────────
+    // Phase 1 — Pre-check: both accounts should be absent from providers
+    // ─────────────────────────────────────────────────────────────────────
+    {
+      name: 'phase-1-pre-check-both-accounts-absent',
+      auth: 'admin',
+      timeout: 180000,
+
+      async run({ accounts, assert }) {
+        const granted = accounts['consent-granted'];
+        const declined = accounts['consent-declined'];
+
+        // Force-clean any leftovers from a prior run (e.g. the previous phase-2a
+        // left a contact in SendGrid that THIS run's phase-1 needs to start
+        // without). SendGrid's delete is an async job, so wait for absence.
+        await sendgridProvider.removeContact(granted.email);
+        await sendgridProvider.removeContact(declined.email);
+        await beehiivProvider.removeContact(granted.email);
+        await beehiivProvider.removeContact(declined.email);
+
+        const grantedSg = await pollProvider(() => sendgridProvider.findContact(granted.email), false);
+        const declinedSg = await pollProvider(() => sendgridProvider.findContact(declined.email), false);
+        const grantedBh = await pollProvider(() => beehiivProvider.findContact(granted.email), false);
+        const declinedBh = await pollProvider(() => beehiivProvider.findContact(declined.email), false);
+
+        assert.equal(grantedSg, null, 'granted account should be absent from SendGrid');
+        assert.equal(declinedSg, null, 'declined account should be absent from SendGrid');
+        assert.equal(grantedBh, null, 'granted account should be absent from Beehiiv');
+        assert.equal(declinedBh, null, 'declined account should be absent from Beehiiv');
+      },
+    },
+
+    // ─────────────────────────────────────────────────────────────────────
+    // Phase 2 — Sync granted account → both providers
+    // ─────────────────────────────────────────────────────────────────────
+    {
+      name: 'phase-2a-granted-account-syncs-to-both-providers',
+      auth: 'admin',
+      timeout: 180000,
+
+      async run({ accounts, assert, Manager, assistant, config }) {
+        const granted = accounts['consent-granted'];
+        const admin = Manager.libraries.admin;
+
+        // Set consent.marketing.status = 'granted' on the user doc
+        await admin.firestore().doc(`users/${granted.uid}`).set({
+          consent: {
+            marketing: {
+              status: 'granted',
+              grantedAt: {
+                timestamp: new Date().toISOString(),
+                timestampUNIX: Math.floor(Date.now() / 1000),
+                source: 'test',
+                ip: null,
+                text: 'consent-lifecycle test',
+              },
+            },
+            legal: {
+              status: 'granted',
+              grantedAt: {
+                timestamp: new Date().toISOString(),
+                timestampUNIX: Math.floor(Date.now() / 1000),
+                source: 'test',
+                ip: null,
+                text: 'consent-lifecycle test',
+              },
+            },
+          },
+        }, { merge: true });
+
+        // Trigger marketing sync via the Email() surface
+        const result = await Manager.Email(assistant).sync(granted.uid);
+        assert.ok(result, 'sync should return a result');
+        assert.notEqual(result.blocked, 'validation', 'sync should not be blocked by validation (uses _test.allow_*)');
+
+        // Poll providers until they reflect the upsert. SendGrid's upsert is
+        // an async background job (returns a job_id, not the inserted contact)
+        // so a single check 5s later isn't enough — it can take 10-20s to
+        // surface. Beehiiv is usually instant but uses the same poll for symmetry.
+        const sgContact = await pollProvider(() => sendgridProvider.findContact(granted.email), true);
+        const bhContact = await pollProvider(() => beehiivProvider.findContact(granted.email), true);
+
+        assert.ok(sgContact, 'granted account should now exist in SendGrid');
+        if (config.marketing?.newsletter?.publicationId) {
+          assert.ok(bhContact, 'granted account should now exist in Beehiiv');
+        }
+      },
+    },
+
+    // ─────────────────────────────────────────────────────────────────────
+    // Phase 2b — Declined account: verify it stays out of providers when we
+    // DON'T call sync (which is what the signup route does for declined
+    // marketing consent).
+    // ─────────────────────────────────────────────────────────────────────
+    {
+      name: 'phase-2b-declined-account-stays-out-of-providers',
+      auth: 'admin',
+      timeout: 180000,
+
+      async run({ accounts, assert, Manager, assistant }) {
+        const declined = accounts['consent-declined'];
+        const admin = Manager.libraries.admin;
+
+        // Set consent.marketing.status = 'revoked' on the user doc.
+        // We deliberately do NOT call sync — the production signup route gates
+        // on consent.marketing.status === 'granted' before calling sync, so a
+        // declined user simply never gets a sync call. We verify that contract
+        // by NOT calling sync and asserting the user stays absent.
+        await admin.firestore().doc(`users/${declined.uid}`).set({
+          consent: {
+            marketing: {
+              status: 'revoked',
+              grantedAt: { timestamp: null, timestampUNIX: null, source: null, ip: null, text: null },
+              revokedAt: {
+                timestamp: new Date().toISOString(),
+                timestampUNIX: Math.floor(Date.now() / 1000),
+                source: 'test',
+                ip: null,
+                text: null,
+              },
+            },
+            legal: {
+              status: 'granted',
+              grantedAt: {
+                timestamp: new Date().toISOString(),
+                timestampUNIX: Math.floor(Date.now() / 1000),
+                source: 'test',
+                ip: null,
+                text: 'consent-lifecycle test',
+              },
+            },
+          },
+        }, { merge: true });
+
+        await sleep(SETTLE_MS);
+
+        const sgContact = await sendgridProvider.findContact(declined.email);
+        const bhContact = await beehiivProvider.findContact(declined.email);
+
+        assert.equal(sgContact, null, 'declined account should remain absent from SendGrid');
+        assert.equal(bhContact, null, 'declined account should remain absent from Beehiiv');
+      },
+    },
+
+    // ─────────────────────────────────────────────────────────────────────
+    // Phase 3 — Unsubscribe: granted account is removed via Manager.Email().remove
+    // ─────────────────────────────────────────────────────────────────────
+    {
+      name: 'phase-3-granted-account-unsubscribe-removes-from-both',
+      auth: 'admin',
+      timeout: 180000,
+
+      async run({ accounts, assert, Manager, assistant }) {
+        const granted = accounts['consent-granted'];
+
+        // Trigger removal — simulates the email-preferences opt-out flow
+        const result = await Manager.Email(assistant).remove(granted.email);
+        assert.ok(result, 'remove should return a result');
+
+        // Poll for absence — SendGrid's contact delete is also an async job.
+        const sgContact = await pollProvider(() => sendgridProvider.findContact(granted.email), false);
+        const bhContact = await pollProvider(() => beehiivProvider.findContact(granted.email), false);
+
+        assert.equal(sgContact, null, 'granted account should now be absent from SendGrid');
+        assert.equal(bhContact, null, 'granted account should now be absent from Beehiiv');
+      },
+    },
+
+    // ─────────────────────────────────────────────────────────────────────
+    // Phase 4 — Validation gate: _test.* (non-allow) is blocked by validate()
+    // ─────────────────────────────────────────────────────────────────────
+    {
+      name: 'phase-4-non-allow-test-email-blocked-by-validation',
+      auth: 'admin',
+      timeout: 30000,
+
+      async run({ assert, Manager, assistant }) {
+        // _test.never-reaches-providers@... is NOT _test.allow_* → should be blocked
+        const blockedEmail = '_test.never-reaches-providers@somiibo.com';
+
+        const result = await Manager.Email(assistant).add({ email: blockedEmail });
+
+        assert.equal(result.blocked, 'validation', 'non-allow _test.* email should be blocked by validation');
+
+        // And the provider lookup should show nothing
+        const sgContact = await sendgridProvider.findContact(blockedEmail);
+        const bhContact = await beehiivProvider.findContact(blockedEmail);
+
+        assert.equal(sgContact, null, 'blocked email should never appear in SendGrid');
+        assert.equal(bhContact, null, 'blocked email should never appear in Beehiiv');
+      },
+    },
+  ],
+};

package/test/email/feedback-and-plain-send.js

@@ -0,0 +1,52 @@
+/**
+ * Test: Send feedback + plain template emails
+ * Quick visual test — sends one of each to verify rendering.
+ */
+module.exports = {
+  description: 'Feedback + plain template send',
+  type: 'group',
+  skip: !process.env.TEST_EXTENDED_MODE ? 'TEST_EXTENDED_MODE not set' : false,
+  tests: [
+    {
+      name: 'feedback-template',
+      auth: 'admin',
+      timeout: 30000,
+      async run({ http, assert, config }) {
+        const response = await http.post('backend-manager/admin/email', {
+          subject: '[TEST] Feedback template',
+          to: `_test-email-send@${config.domain}`,
+          template: 'feedback',
+          sender: 'hello',
+          copy: false,
+          data: { signoff: { type: 'personal' } },
+        });
+
+        assert.isSuccess(response, 'Should send feedback email');
+        assert.equal(response.data.status, 'sent', 'Status should be sent');
+      },
+    },
+    {
+      name: 'plain-template-with-markdown',
+      auth: 'admin',
+      timeout: 30000,
+      async run({ http, assert, config }) {
+        const response = await http.post('backend-manager/admin/email', {
+          subject: '[TEST] Plain template with markdown',
+          to: `_test-email-send@${config.domain}`,
+          template: 'plain',
+          sender: 'hello',
+          copy: false,
+          data: {
+            content: {
+              message: '# Quick Update\n\nHey Ian,\n\nJust wanted to let you know that your **account settings** have been updated successfully.\n\nHere is what changed:\n\n- Email notifications: **enabled**\n- Two-factor auth: **enabled**\n- API key: [regenerated](https://example.com/account)\n\nIf you didn\'t make these changes, please [contact support](https://example.com/support) immediately.\n\nThanks!',
+            },
+            signoff: { type: 'personal' },
+          },
+        });
+
+        assert.isSuccess(response, 'Should send plain email');
+        assert.equal(response.data.status, 'sent', 'Status should be sent');
+      },
+    },
+  ],
+};

package/test/email/fixtures/clean.json

@@ -0,0 +1,30 @@
+{
+  "_comment": "Predefined fixture for the `clean` template. Loaded via NEWSLETTER_FIXTURE=clean. Edit freely — no AI involved. Classic content shape: intro + sections[{title, body, cta, image_prompt}].",
+  "subject": "Identity is the new growth lever",
+  "preheader": "Three platform shifts to lock in this week.",
+  "summary": "LinkedIn, YouTube, and the broader creator stack are all tightening identity controls this week. The operators with documented attribution histories will outrun the rest. Documentation is no longer overhead — it's the moat.",
+  "tags": ["linkedin", "youtube", "platform-policy", "creator-economy", "operator-tools"],
+  "intro": "Identity matters because trust is the new growth lever. Teams that handle this well will spend less time cleaning up later.",
+  "sections": [
+    {
+      "title": "LinkedIn ships verified-profile gates for business accounts",
+      "body": "LinkedIn now requires verified identity attestations on any business profile claiming more than 500 followers. Accounts with documented attribution histories sail through verification in under twelve hours. The practical implication is to lock down your attribution log this week, not next.",
+      "image_prompt": "Abstract geometric illustration of a verification checkmark inside a layered profile card."
+    },
+    {
+      "title": "Documentation is the new operator moat",
+      "body": "Operator playbooks are now the difference between an account that recovers from a flag and one that gets permanently restricted. Teams running documented processes recover in days. The ones without burn weeks negotiating with support queues.",
+      "image_prompt": "Stack of geometric document layers casting clean shadows on a flat surface."
+    },
+    {
+      "title": "YouTube tests creator-attribution metadata on uploads",
+      "body": "A subset of channels saw a new upload checkbox this week asking whether content was assisted by automation. The checkbox is optional today. Reading the room: it will not stay optional. Creators with clear internal workflows will adapt in an afternoon.",
+      "image_prompt": "Minimalist play button morphing into a label tag, flat geometric style."
+    }
+  ],
+  "signoff": "Best,\nThe Somiibo Team",
+  "citations": [
+    { "note": "LinkedIn flagged 12,000 impersonation attempts in the verified-profile beta.", "source": "Reported by LinkedIn product team, May 2026" },
+    { "note": "Operator playbook adoption up 38% week-over-week in Q2.", "source": "Per platform analytics, May 2026" }
+  ]
+}

package/test/email/fixtures/editorial.json

@@ -0,0 +1,30 @@
+{
+  "_comment": "Predefined fixture for the `editorial` template. Loaded via NEWSLETTER_FIXTURE=editorial. Same classic content shape as clean.json — both templates render the same data.",
+  "subject": "Identity is the new growth lever",
+  "preheader": "Three platform shifts to lock in this week.",
+  "summary": "LinkedIn, YouTube, and the broader creator stack are all tightening identity controls this week. The operators with documented attribution histories will outrun the rest. Documentation is no longer overhead — it's the moat.",
+  "tags": ["linkedin", "youtube", "platform-policy", "creator-economy", "operator-tools"],
+  "intro": "Identity matters because trust is the new growth lever. Teams that handle this well will spend less time cleaning up later, and the patterns emerging this week tell you exactly where to focus.",
+  "sections": [
+    {
+      "title": "LinkedIn ships verified-profile gates for business accounts",
+      "body": "LinkedIn now requires verified identity attestations on any business profile claiming more than 500 followers. The rollout is fast and uneven — some accounts hit the gate inside two days of profile activity, others sit unchallenged for weeks. The pattern that matters is this: accounts with documented attribution histories sail through verification in under twelve hours. Accounts without get queued. The practical implication is to lock down your attribution log this week, not next.",
+      "image_prompt": "Abstract geometric illustration of a verification checkmark inside a layered profile card."
+    },
+    {
+      "title": "Documentation is the new operator moat",
+      "body": "Operator playbooks — once dismissed as overhead — are now the difference between an account that recovers from a flag and one that gets permanently restricted. The teams already running on documented processes recover in days. The ones without burn weeks negotiating with support queues. Treat your playbook as a compliance artifact, not a knowledge-management nice-to-have.",
+      "image_prompt": "Stack of geometric document layers casting clean shadows on a flat surface."
+    },
+    {
+      "title": "YouTube tests creator-attribution metadata on uploads",
+      "body": "A subset of channels saw a new upload checkbox this week asking whether content was assisted by automation. The checkbox is optional today. Reading the room: it will not stay optional. Creators with clear internal workflows already labeled will adapt in an afternoon. Everyone else will spend a quarter retrofitting.",
+      "image_prompt": "Minimalist play button morphing into a label tag, flat geometric style."
+    }
+  ],
+  "signoff": "Best,\nThe Somiibo Team",
+  "citations": [
+    { "note": "LinkedIn flagged 12,000 impersonation attempts in the verified-profile beta.", "source": "Reported by LinkedIn product team, May 2026" },
+    { "note": "Operator playbook adoption up 38% week-over-week in Q2.", "source": "Per platform analytics, May 2026" }
+  ]
+}

package/test/email/fixtures/field-report.json

@@ -0,0 +1,53 @@
+{
+  "_comment": "Predefined fixture for the `field-report` template. Loaded via NEWSLETTER_FIXTURE=field-report. Wire-service content shape: tldr + dateline + dispatches[{kicker, headline, byline, location, lede, dispatch, dataPoints, image_prompt}].",
+  "subject": "LinkedIn tightens identity — operators document everything",
+  "preheader": "Three filings from this week's platform front lines.",
+  "summary": "Wire from the platform front: LinkedIn is rolling identity verification across every business profile, YouTube is piloting upload-time attribution metadata, and the operators with clean documentation are outrunning everyone else.",
+  "tags": ["linkedin", "youtube", "platform-policy", "verification", "operator-playbook"],
+  "tldr": "LinkedIn is rolling out verified-account scrutiny across every business profile. Operators with paper trails will outrun the rest. Documentation is the new growth lever.",
+  "dateline": "OAKLAND",
+  "signoff": "— Stay sharp,\nThe Somiibo Desk",
+  "citations": [
+    { "note": "LinkedIn flagged 12,000 impersonation attempts in the verified-profile beta.", "source": "Reported by LinkedIn product team, May 2026" },
+    { "note": "Operator playbook adoption up 38% week-over-week in Q2.", "source": "Per platform analytics, May 2026" }
+  ],
+  "dispatches": [
+    {
+      "kicker": "LEAD DISPATCH",
+      "headline": "LinkedIn ships verified-profile gates for every business account",
+      "byline": "Filed by The Somiibo platform desk",
+      "location": "OAKLAND",
+      "lede": "A wave of identity-verification gates is rolling out across LinkedIn business profiles this week — and the platform is not asking politely.",
+      "dispatch": "LinkedIn now requires verified identity attestations on any business profile claiming more than 500 followers. The rollout is fast and uneven: some accounts hit the gate inside two days of profile activity, others sit unchallenged for weeks. The pattern that matters is this — accounts with documented attribution histories sail through verification in under twelve hours. Accounts without get queued. The practical implication is to lock down your attribution log this week, not next.",
+      "dataPoints": [
+        { "label": "PROFILES FLAGGED", "value": "12.4K" },
+        { "label": "AVG REVIEW TIME", "value": "14HR" },
+        { "label": "WoW APPROVAL", "value": "+38%" }
+      ],
+      "image_prompt": "Abstract geometric illustration of a verification checkmark inside a layered profile card."
+    },
+    {
+      "kicker": "FIELD NOTES",
+      "headline": "Documentation is the new operator moat",
+      "byline": "Filed by The Somiibo growth desk",
+      "location": "REMOTE",
+      "lede": "The teams surviving this round of platform scrutiny share one habit: they write everything down.",
+      "dispatch": "Operator playbooks — once dismissed as overhead — are now the difference between an account that recovers from a flag and one that gets permanently restricted. The teams already running on documented processes recover in days. The ones without burn weeks negotiating with support queues. Treat your playbook as a compliance artifact, not a knowledge-management nice-to-have.",
+      "dataPoints": [
+        { "label": "RECOVERY (DOCUMENTED)", "value": "4D" },
+        { "label": "RECOVERY (UNDOC)", "value": "21D" }
+      ],
+      "image_prompt": "Stack of geometric document layers casting clean shadows on a flat surface."
+    },
+    {
+      "kicker": "WATCH",
+      "headline": "YouTube tests creator-attribution metadata on uploads",
+      "byline": "Filed by The Somiibo signals desk",
+      "location": "NEW YORK",
+      "lede": "A small pilot suggests YouTube will soon ask creators to declare automated tooling and cross-posting workflows at upload time.",
+      "dispatch": "A subset of channels saw a new upload checkbox this week asking whether content was assisted by automation. The checkbox is optional today. Reading the room: it will not stay optional. Creators with clear internal workflows already labeled will adapt in an afternoon. Everyone else will spend a quarter retrofitting.",
+      "dataPoints": [],
+      "image_prompt": "Minimalist play button morphing into a label tag, flat geometric style."
+    }
+  ]
+}

package/test/email/marketing-lifecycle.js

@@ -0,0 +1,132 @@
+/**
+ * Test: Marketing lifecycle (add → sync → remove)
+ * End-to-end suite testing the full marketing contact flow via routes
+ *
+ * Requires TEST_EXTENDED_MODE=true and SENDGRID_API_KEY / BEEHIIV_API_KEY env vars.
+ * These tests hit real external APIs.
+ */
+module.exports = {
+  description: 'Marketing lifecycle (add → sync → remove)',
+  type: 'suite',
+  timeout: 60000,
+  skip: !process.env.TEST_EXTENDED_MODE ? 'TEST_EXTENDED_MODE not set' : false,
+
+  tests: [
+    // Step 0: Pre-clean test contacts from providers (in case a previous run left them)
+    {
+      name: 'pre-clean-test-contacts',
+      auth: 'admin',
+
+      async run({ http, config, state }) {
+        const testEmail = `lifecycle.test+bem@${config.domain}`;
+        state.testEmail = testEmail;
+
+        // Delete from all providers — handles "not found" gracefully
+        await http.delete('backend-manager/marketing/contact', { email: testEmail }).catch(() => {});
+      },
+    },
+
+    // Step 1: Add a contact via POST /marketing/contact
+    {
+      name: 'add-contact',
+      auth: 'admin',
+
+      async run({ http, assert, state, config }) {
+        const response = await http.post('backend-manager/marketing/contact', {
+          email: state.testEmail,
+          firstName: 'Lifecycle',
+          lastName: 'Test',
+          source: 'bem-test-lifecycle',
+        });
+
+        assert.isSuccess(response, 'Add contact should succeed');
+        assert.propertyEquals(response, 'data.success', true, 'success should be true');
+
+        if (process.env.SENDGRID_API_KEY) {
+          assert.hasProperty(response, 'data.providers.campaigns', 'Should have SendGrid result');
+          assert.propertyEquals(response, 'data.providers.campaigns.success', true, 'SendGrid add should succeed');
+        }
+
+        if (process.env.BEEHIIV_API_KEY && config.marketing?.newsletter?.publicationId) {
+          assert.hasProperty(response, 'data.providers.newsletter', 'Should have Beehiiv result');
+          assert.propertyEquals(response, 'data.providers.newsletter.success', true, 'Beehiiv add should succeed');
+        }
+      },
+    },
+
+    // Step 2: Sync by UID via PUT /marketing/contact
+    // Tests the full sync pipeline: UID resolution → buildFields → upsert with custom fields
+    {
+      name: 'sync-contact-by-uid',
+      auth: 'admin',
+
+      async run({ http, assert, accounts, config, Manager }) {
+        // Dedicated journey account — its _test.allow_* prefix bypasses validation, and the
+        // cleanup step's DELETE revokes its doc consent, so it must not be a shared sentinel
+        // (consent-granted is used by the signup + consent-lifecycle suites).
+        const grantedUid = accounts['journey-marketing-sync'].uid;
+        const admin = Manager.libraries.admin;
+        await admin.firestore().doc(`users/${grantedUid}`).set({
+          consent: { marketing: { status: 'granted' } },
+        }, { merge: true });
+
+        const response = await http.put('backend-manager/marketing/contact', {
+          uid: grantedUid,
+        });
+
+        assert.isSuccess(response, 'Sync contact should succeed');
+        assert.propertyEquals(response, 'data.success', true, 'success should be true');
+
+        if (process.env.SENDGRID_API_KEY) {
+          assert.hasProperty(response, 'data.providers.campaigns', 'Should have SendGrid result');
+          assert.propertyEquals(response, 'data.providers.campaigns.success', true, 'SendGrid sync should succeed');
+        }
+
+        if (process.env.BEEHIIV_API_KEY && config.marketing?.newsletter?.publicationId) {
+          assert.hasProperty(response, 'data.providers.newsletter', 'Should have Beehiiv result');
+          assert.propertyEquals(response, 'data.providers.newsletter.success', true, 'Beehiiv sync should succeed');
+        }
+      },
+    },
+
+    // Step 3: Remove the contact via DELETE /marketing/contact
+    {
+      name: 'remove-contact',
+      auth: 'admin',
+
+      async run({ http, assert, state, config }) {
+        const response = await http.delete('backend-manager/marketing/contact', {
+          email: state.testEmail,
+        });
+
+        assert.isSuccess(response, 'Remove contact should succeed');
+        assert.propertyEquals(response, 'data.success', true, 'success should be true');
+
+        if (process.env.SENDGRID_API_KEY) {
+          assert.hasProperty(response, 'data.providers.campaigns', 'Should have SendGrid result');
+          assert.propertyEquals(response, 'data.providers.campaigns.success', true, 'SendGrid remove should succeed');
+        }
+
+        if (process.env.BEEHIIV_API_KEY && config.marketing?.newsletter?.publicationId) {
+          assert.hasProperty(response, 'data.providers.newsletter', 'Should have Beehiiv result');
+          assert.propertyEquals(response, 'data.providers.newsletter.success', true, 'Beehiiv remove should succeed');
+        }
+      },
+    },
+
+    // Step 4: Clean up the contact the sync step added to the live providers.
+    // DELETE also mirrors revoked consent to the matching user doc — which is why this
+    // targets the dedicated journey account (step 2 re-seeds granted before syncing, so
+    // the suite is self-healing across runs).
+    {
+      name: 'cleanup-synced-contact',
+      auth: 'admin',
+
+      async run({ http, accounts }) {
+        await http.delete('backend-manager/marketing/contact', {
+          email: accounts['journey-marketing-sync'].email,
+        }).catch(() => {});
+      },
+    },
+  ],
+};