@omega.js/manager 0.1.0

package/dist/services/campaigns/ensure/link-branding.js

@@ -0,0 +1,187 @@
+/**
+ * Ensure SendGrid link branding for the brand's domain — the `emailurl.`
+ * host every transactional link is rewritten through.
+ *
+ * A valid branding is converged proof. A missing one is created in one pass,
+ * exactly like its domain-auth sibling: brand the links in SendGrid (two
+ * CNAMEs), diff-sync those records into the Cloudflare apex zone UNPROXIED,
+ * then validate — interactive runs poll until SendGrid confirms;
+ * non-interactive/dry runs validate ONCE, report warned, and the rerun
+ * converges.
+ *
+ * The records are written HERE and not left to the edge service: on a fresh
+ * brand's FIRST walk, edge's live SendGrid read finds no authenticated domain
+ * at all, so it writes none of the SendGrid set — and a branding with no CNAME
+ * behind it can never validate.
+ *
+ * Once SendGrid says valid, the record may finally ride Cloudflare's proxy —
+ * so this operation patches it to proxied on the spot instead of leaving the
+ * flip to a later walk ([#693](https://github.com/Omega-JS-Stack/omega/issues/693)).
+ */
+const chalk = require('chalk').default;
+const { pollWithSpinner } = require('../../../vendor/devkit/flows.js');
+const { canPrompt, dryRunPlan } = require('../../../lib/run-gates.js');
+const { syncDnsRecords, manualRecordList } = require('../lib/dns-sync.js');
+
+// MUST match the name the edge record set builds (`emailurl.<domain>` in
+// services/edge/lib/dns-records-helpers.js) — the branding SendGrid validates
+// and the CNAME Cloudflare serves are the same host or neither works.
+const SUBDOMAIN = 'emailurl';
+
+// The record set SendGrid returns for a branded link
+const DNS_KEYS = ['domain_cname', 'owner_cname'];
+
+module.exports = async function ensureLinkBranding(context) {
+  const { sendgridApi: api, cloudflareApi, domain, apexDomain, isSubdomainProject, options = {} } = context;
+
+  // A subdomain project owns no apex records — the parent brand's walk does,
+  // which is why the edge service skips the whole SendGrid set for one. A
+  // branding created here would wait forever on CNAMEs this brand never writes.
+  if (isSubdomainProject) {
+    console.log(`      ${chalk.dim(`⊘ Subdomain project — the parent brand owns the link branding for ${apexDomain}`)}`);
+    return;
+  }
+
+  const host = `${SUBDOMAIN}.${domain}`;
+
+  // === READ: is the host already branded and valid? ===
+  const links = await api.getBrandedLinks();
+  let branding = findBranding(links, host);
+
+  if (branding?.valid) {
+    console.log(`      ${chalk.green('✓')} Link branding ${chalk.cyan(host)} validated`);
+    // Catch-up flip only: a branding THIS run did not validate is the edge
+    // service's to reconcile (its live read already desired the record
+    // proxied), so a grey record here is a raced walk, not a pending step —
+    // patch it when Cloudflare is reachable, and never warn about it.
+    if (cloudflareApi) {
+      await proxyRecord(cloudflareApi, apexDomain, host);
+    }
+    return { output: { linkBranding: { id: branding.id, valid: true } } };
+  }
+
+  if (options.dryRun) {
+    const planned = branding ? ['dns-records', 'validate', 'proxy-record'] : ['brand-links', 'dns-records', 'validate', 'proxy-record'];
+    return dryRunPlan(`${planned.join(' → ')}`, { output: { linkBranding: { planned } } });
+  }
+
+  // === Create the branding when missing ===
+  if (!branding) {
+    branding = await api.createBrandedLink(domain, SUBDOMAIN);
+    console.log(`      ${chalk.green('✓')} Created link branding for ${chalk.cyan(host)}`);
+  } else {
+    console.log(`      ${chalk.yellow('↻')} Link branding ${chalk.cyan(host)} exists but is not validated — reconciling DNS`);
+  }
+
+  const records = DNS_KEYS
+    .map((key) => ({ key, record: branding.dns?.[key] }))
+    .filter(({ record }) => record);
+
+  if (records.length === 0) {
+    throw new Error('SendGrid returned no DNS records for the link branding');
+  }
+
+  // === DNS via Cloudflare (or manual guidance) ===
+  // Written UNPROXIED, which is the only state SendGrid can validate: it
+  // resolves the host as a plain CNAME to sendgrid.net, and a proxied record
+  // answers with Cloudflare's own addresses instead.
+  const synced = await syncDnsRecords(cloudflareApi, apexDomain, records);
+
+  // === Validate — DNS may need a minute; interactive runs wait it out ===
+  const isValid = (validation) => validation?.valid === true;
+
+  let valid = isValid(await api.validateBrandedLink(branding.id));
+
+  if (!valid && canPrompt(options)) {
+    const result = await pollWithSpinner({
+      check: async () => {
+        try {
+          return isValid(await api.validateBrandedLink(branding.id)) ? { done: true } : { done: false };
+        } catch {
+          return { done: false };
+        }
+      },
+      intervalMs: 10000,
+      message: `Validating link branding (waiting for SendGrid to resolve ${host})`,
+      indent: '      ',
+    });
+    valid = result.success;
+  }
+
+  if (!valid) {
+    console.log(`      ${chalk.yellow('⚠')} Validation pending — DNS is likely still propagating, rerun in a few minutes`);
+    return {
+      status: 'warned',
+      reason: 'link branding validation pending — the emailurl CNAME stays unproxied',
+      output: { linkBranding: { id: branding.id, valid: false, ...(synced ? {} : { manualRecords: manualRecordList(records) }) } },
+    };
+  }
+
+  console.log(`      ${chalk.green('✓')} Link branding ${chalk.cyan(host)} validated`);
+
+  // === The flip: a validated branding may ride Cloudflare's proxy ===
+  // Edge stays the reconciler — its next live read sees `valid: true` and
+  // DESIRES the record proxied, so both services agree on the same state and
+  // the rerun is a no-op either way.
+  const proxied = await proxyRecord(cloudflareApi, apexDomain, host);
+
+  if (!proxied) {
+    return {
+      status: 'warned',
+      reason: 'link branding validated but the emailurl CNAME could not be proxied',
+      output: { linkBranding: { id: branding.id, valid: true, proxied: false } },
+    };
+  }
+
+  return { output: { linkBranding: { id: branding.id, valid: true, proxied: true } } };
+};
+
+/** The account's branding entry for this host (ids are account-scoped). */
+function findBranding(links, host) {
+  return (links || []).find((link) => `${link.subdomain}.${link.domain}`.toLowerCase() === host.toLowerCase()) || null;
+}
+
+/**
+ * Patch the branded-link CNAME to proxied.
+ *
+ * @returns {boolean} - true when the record rides the proxy, false when the
+ *   manual line was printed instead
+ */
+async function proxyRecord(cloudflareApi, apexDomain, host) {
+  if (!cloudflareApi) {
+    logManualFlip('No CLOUDFLARE_TOKEN', host);
+    return false;
+  }
+
+  const zone = await cloudflareApi.getZoneByName(apexDomain);
+  if (!zone) {
+    logManualFlip(`No Cloudflare zone for ${apexDomain}`, host);
+    return false;
+  }
+
+  const existing = await cloudflareApi.makeRequest(`/zones/${zone.id}/dns_records?type=CNAME&per_page=100`, { method: 'GET' });
+  const match = (existing.result || []).find((r) => r.type === 'CNAME' && r.name === host);
+
+  // The DNS sync above writes this record, so reaching here means the zone
+  // answered without it (a hand-deleted record, or a read that raced a write).
+  if (!match) {
+    console.log(`      ${chalk.yellow('⚠')} No ${chalk.cyan(`CNAME ${host}`)} record in the zone — add ${chalk.cyan(`${host} → sendgrid.net`)} first, then rerun ${chalk.cyan('omega manage')} and it flips to proxied.`);
+    return false;
+  }
+
+  if (match.proxied === true) {
+    console.log(`      ${chalk.dim('→')} ${chalk.cyan(host)} already proxied`);
+    return true;
+  }
+
+  await cloudflareApi.makeRequest(`/zones/${zone.id}/dns_records/${match.id}`, {
+    method: 'PATCH',
+    body: JSON.stringify({ type: 'CNAME', name: host, content: match.content, ttl: 1, proxied: true, comment: match.comment }),
+  });
+  console.log(`      ${chalk.green('✓')} Proxied ${chalk.cyan(host)} — emailed links now land on HTTPS`);
+  return true;
+}
+
+function logManualFlip(why, host) {
+  console.log(`      ${chalk.yellow('⚠')} ${why} — turn the proxy ON for ${chalk.cyan(`CNAME ${host}`)} manually (orange cloud), or rerun ${chalk.cyan('omega manage')} once Cloudflare is reachable.`);
+}

package/dist/services/campaigns/ensure/list.js

@@ -0,0 +1,50 @@
+/**
+ * Ensure the brand's SendGrid marketing list exists.
+ *
+ * Resolution order: marketing.campaigns.providers.sendgrid.listId from
+ * config → exact-name lookup → create. The resolved id is written back into
+ * omega.json5 (marketing.campaigns.providers.sendgrid.listId, its ONE
+ * authoritative home — comment-preserving).
+ */
+const chalk = require('chalk').default;
+const { writeBrandConfig } = require('../../../lib/config-write.js');
+const { dryRunPlan } = require('../../../lib/run-gates.js');
+
+module.exports = async function ensureList(context) {
+  const { sendgridApi: api, brandConfig, options = {} } = context;
+
+  const listName = brandConfig.brand.name;
+  const configuredId = brandConfig.marketing?.campaigns?.providers?.sendgrid?.listId;
+
+  // 1. Configured id — verify it still exists
+  if (configuredId) {
+    const list = await api.getList(configuredId);
+    if (list) {
+      console.log(`      ${chalk.green('✓')} List ${chalk.cyan(`"${list.name}"`)} ${chalk.dim(`(${list.id})`)}`);
+      if (list.id !== configuredId) {
+        writeBrandConfig(context, { 'marketing.campaigns.providers.sendgrid.listId': list.id });
+      }
+      return { state: { listId: list.id, listName: list.name } };
+    }
+    console.log(`      ${chalk.yellow('↻')} Configured listId ${chalk.cyan(configuredId)} no longer exists — falling back to name lookup`);
+  }
+
+  // 2. Exact-name lookup
+  const existing = await api.getListByName(listName);
+  if (existing) {
+    console.log(`      ${chalk.green('✓')} Matched list ${chalk.cyan(`"${listName}"`)} ${chalk.dim(`(${existing.id})`)}`);
+    writeBrandConfig(context, { 'marketing.campaigns.providers.sendgrid.listId': existing.id });
+    return { state: { listId: existing.id, listName } };
+  }
+
+  // 3. Create
+  if (options.dryRun) {
+    return dryRunPlan(`create list "${listName}"`, { output: { list: { planned: 'create', listName } } });
+  }
+
+  const created = await api.createList(listName);
+  console.log(`      ${chalk.green('✓')} Created list ${chalk.cyan(`"${listName}"`)} ${chalk.dim(`(${created.id})`)}`);
+  writeBrandConfig(context, { 'marketing.campaigns.providers.sendgrid.listId': created.id });
+
+  return { state: { listId: created.id, listName } };
+};

package/dist/services/campaigns/ensure/segments.js

@@ -0,0 +1,109 @@
+/**
+ * Ensure @omega.js/backend's segments exist in SendGrid with the right query_dsl.
+ *
+ * The segment list comes from @omega.js/backend's marketing SSOT; each one's
+ * query_dsl is rebuilt from its conditions and compared against the live
+ * segment (the list endpoint omits query_dsl, so present segments cost one
+ * detail read each). Stale segments are PATCHed in place, falling back to
+ * delete + recreate when SendGrid rejects the PATCH. Orphaned `__temp_`
+ * segments (leaked by @omega.js/backend's brand-scoped campaign sends on crash) are swept.
+ * Segments @omega.js/backend doesn't own are never touched.
+ */
+const chalk = require('chalk').default;
+const { segmentsFor } = require('../../../lib/backend-marketing.js');
+const { buildQueryDsl } = require('../lib/segment-query.js');
+const { dryRunPlan } = require('../../../lib/run-gates.js');
+
+const SENDGRID_SEGMENTS = segmentsFor('sendgrid');
+
+module.exports = async function ensureSegments(context) {
+  const { sendgridApi: api, options = {} } = context;
+
+  const existing = await api.getSegments();
+
+  const orphans = existing.filter((s) => s.name.startsWith('__temp_'));
+  const existingByName = Object.fromEntries(
+    existing.filter((s) => !s.name.startsWith('__temp_')).map((s) => [s.name, s]),
+  );
+
+  // Rebuild every segment's query and diff against the live detail
+  const missing = [];
+  const stale = [];
+
+  for (const segment of SENDGRID_SEGMENTS) {
+    const queryDsl = buildQueryDsl(segment.conditions, segment.logic);
+    const sgSegment = existingByName[segment.name];
+
+    if (!sgSegment) {
+      missing.push({ ...segment, queryDsl });
+      continue;
+    }
+
+    const full = await api.getSegment(sgSegment.id);
+    if (full.query_dsl !== queryDsl) {
+      stale.push({ ...segment, queryDsl, existingId: sgSegment.id });
+    }
+  }
+
+  if (orphans.length === 0 && missing.length === 0 && stale.length === 0) {
+    console.log(`      ${chalk.green('✓')} All ${SENDGRID_SEGMENTS.length} segments exist`);
+    return { output: { segments: { total: SENDGRID_SEGMENTS.length, created: 0, updated: 0, orphansSwept: 0 } } };
+  }
+
+  if (options.dryRun) {
+    const planned = {
+      create: missing.map((s) => s.name),
+      update: stale.map((s) => s.name),
+      sweepOrphans: orphans.length,
+    };
+    return dryRunPlan(`create ${planned.create.length}, update ${planned.update.length}, sweep ${planned.sweepOrphans} orphan(s)`, { output: { segments: { planned } } });
+  }
+
+  // Sweep leaked __temp_ segments
+  for (const orphan of orphans) {
+    await api.deleteSegment(orphan.id);
+  }
+  if (orphans.length > 0) {
+    console.log(`      ${chalk.yellow('↻')} Swept ${orphans.length} orphaned __temp_ segment(s)`);
+  }
+
+  // Stale: PATCH in place, fall back to delete + recreate
+  let updated = 0;
+  for (const segment of stale) {
+    try {
+      await api.updateSegment(segment.existingId, segment.name, segment.queryDsl);
+      console.log(`      ${chalk.green('↻')} Updated ${chalk.cyan(segment.display)} in place`);
+      updated += 1;
+    } catch (patchError) {
+      await api.deleteSegment(segment.existingId);
+      missing.push(segment);
+      console.log(`      ${chalk.yellow('↻')} Recreating ${chalk.cyan(segment.display)} ${chalk.dim(`(PATCH rejected: ${patchError.message})`)}`);
+    }
+  }
+
+  for (const segment of missing) {
+    const created = await api.createSegment(segment.name, segment.queryDsl);
+    console.log(`      ${chalk.green('✓')} Created ${chalk.cyan(segment.display)} ${chalk.dim(`(${created.id})`)}`);
+  }
+
+  // Verify everything actually persisted
+  const verify = await api.getSegments();
+  const verifyByName = new Set(verify.map((s) => s.name));
+  const stillMissing = SENDGRID_SEGMENTS.filter((s) => !verifyByName.has(s.name));
+
+  if (stillMissing.length > 0) {
+    console.log(`      ${chalk.yellow('⚠')} ${stillMissing.length} segment(s) failed to persist: ${chalk.cyan(stillMissing.map((s) => s.display).join(', '))}`);
+    return { status: 'warned', reason: `${stillMissing.length} segment(s) failed to persist: ${stillMissing.map((s) => s.name).join(', ')}`, output: { segments: { total: SENDGRID_SEGMENTS.length, failed: stillMissing.map((s) => s.name) } } };
+  }
+
+  return {
+    output: {
+      segments: {
+        total: SENDGRID_SEGMENTS.length,
+        created: missing.length,
+        updated,
+        orphansSwept: orphans.length,
+      },
+    },
+  };
+};

package/dist/services/campaigns/ensure/sender-identity.js

@@ -0,0 +1,153 @@
+/**
+ * Ensure a verified SendGrid sender identity for the brand.
+ *
+ * Single Sends require a registered sender (not an inline from address);
+ * each brand gets one: offers@{contact-email domain} with the brand's name.
+ * It auto-verifies because domain-auth runs first. @omega.js/backend resolves the sender
+ * id at runtime by from_email, so nothing lands in state.
+ *
+ * CAN-SPAM requires a physical mailing address — brand.address in
+ * omega.json5. omega-manager silently stamped the company's address on
+ * every brand; the port ASKS for the brand's own (#635) and warns only when
+ * nobody can be asked.
+ */
+const chalk = require('chalk').default;
+const { input } = require('../../../vendor/devkit/prompt.js');
+const { canPrompt, dryRunPlan } = require('../../../lib/run-gates.js');
+const { confirmSetup, landValue } = require('../../../lib/config-flow.js');
+
+// The five fields brand.address carries. Only the three SendGrid cannot
+// create a sender without are required — an address with no region or postal
+// code is a real address in plenty of countries.
+const ADDRESS_FIELDS = [
+  { key: 'line1', message: 'Street address:', required: true },
+  { key: 'city', message: 'City:', required: true },
+  { key: 'region', message: 'State / region:' },
+  { key: 'postalCode', message: 'Postal code:' },
+  { key: 'country', message: 'Country:', required: true },
+];
+
+/**
+ * Ask for the brand's mailing address and land it as ONE brand.address object
+ * (#635). Five fields behind ONE gate — asking the Provide / Skip / Disable
+ * question per field would be the same question five times. The campaigns
+ * service already gated on its API key, so this gate is about the address.
+ *
+ * @param {Object} context - Handler context.
+ * @returns {Promise<Object|null>} The landed address, or null when the user
+ *   stepped aside or left a required field empty.
+ */
+async function askBrandAddress(context) {
+  const action = await confirmSetup(context, {
+    label: 'Mailing address (CAN-SPAM)',
+    instructions: ['Every marketing email must carry a physical mailing address — it lands in brand.address'],
+    disablePath: 'marketing.campaigns.enabled',
+  });
+  if (action !== 'yes') {
+    return null;
+  }
+
+  const address = {};
+  for (const field of ADDRESS_FIELDS) {
+    const value = (await input({ message: field.message }) || '').trim();
+    if (!value) {
+      if (field.required) {
+        return null;
+      }
+      continue;
+    }
+    address[field.key] = value;
+  }
+
+  landValue(context, 'brand.address', address);
+  return address;
+}
+
+module.exports = async function ensureSenderIdentity(context) {
+  const { sendgridApi: api, brandConfig, options = {} } = context;
+
+  const brandName = brandConfig.brand.name;
+  const contactEmail = brandConfig.brand?.contact?.email;
+  const contactDomain = contactEmail?.split('@')[1];
+
+  if (!contactDomain) {
+    console.log(chalk.dim('      ⊘ No brand.contact.email configured — nothing to register'));
+    return {};
+  }
+
+  const fromEmail = `offers@${contactDomain}`;
+
+  const senders = await api.getVerifiedSenders();
+  const match = senders.find((s) => s.from_email === fromEmail);
+  // The nickname is the managed handle (unique per SendGrid account) — a
+  // sender with this brand's nickname but another address is a stale
+  // derivation (contact.email changed) and would 400 the create below
+  const stale = senders.find((s) => s.nickname === brandName && s.from_email !== fromEmail);
+
+  if (match && match.verified !== false) {
+    console.log(`      ${chalk.green('✓')} Verified sender ${chalk.cyan(fromEmail)} ${chalk.dim(`(id: ${match.id})`)}`);
+    return { output: { senderIdentity: { id: match.id, fromEmail, verified: true } } };
+  }
+
+  // The physical address is required for creation — and it must be the
+  // brand's own (no company default to fall back on), so a run that can ask
+  // ASKS for it here rather than warning and stepping aside (#635).
+  const complete = (candidate) => Boolean(candidate?.line1 && candidate?.city && candidate?.country);
+
+  let address = brandConfig.brand?.address;
+  if (!complete(address) && canPrompt(options)) {
+    address = await askBrandAddress(context);
+  }
+
+  if (!complete(address)) {
+    console.log(`      ${chalk.yellow('⚠')} No sender ${chalk.cyan(fromEmail)} yet, and CAN-SPAM requires a physical mailing address`);
+    console.log(`      ${chalk.dim('→')} Set brand.address (line1, city, region, postalCode, country) in omega.json5, then rerun`);
+    return { status: 'warned', reason: 'no sender yet — brand.address is required by CAN-SPAM', output: { senderIdentity: { fromEmail, missingAddress: true } } };
+  }
+
+  if (options.dryRun) {
+    const planned = match ? 'recreate-unverified-sender' : stale ? 'replace-stale-nickname-sender' : 'create-sender';
+    return dryRunPlan(`${planned} (${fromEmail})`, { output: { senderIdentity: { planned, fromEmail } } });
+  }
+
+  // An unverified leftover can't be verified retroactively — recreate it
+  // cleanly now that domain authentication is in place
+  if (match) {
+    await api.deleteVerifiedSender(match.id);
+    console.log(`      ${chalk.yellow('↻')} Deleted unverified sender ${chalk.cyan(fromEmail)} for recreation`);
+  }
+
+  if (stale) {
+    if (stale.verified === false) {
+      await api.deleteVerifiedSender(stale.id);
+      console.log(`      ${chalk.yellow('↻')} Deleted stale unverified sender ${chalk.cyan(stale.from_email)} — the contact domain changed`);
+    } else {
+      console.log(`      ${chalk.yellow('⚠')} Verified sender ${chalk.cyan(stale.from_email)} already uses the nickname ${chalk.cyan(brandName)} — delete it in SendGrid or align brand.contact.email, then rerun`);
+      return { status: 'warned', reason: 'a verified sender already uses the brand nickname', output: { senderIdentity: { fromEmail, staleNickname: stale.from_email } } };
+    }
+  }
+
+  const sender = await api.createVerifiedSender({
+    nickname: brandName,
+    fromEmail,
+    fromName: brandName,
+    replyToEmail: contactEmail,
+    replyToName: brandName,
+    address: {
+      street: address.line1,
+      street2: address.line2 || '',
+      city: address.city,
+      state: address.region,
+      zip: address.postalCode,
+      country: address.country,
+    },
+  });
+
+  if (sender.verified === false) {
+    console.log(`      ${chalk.yellow('⚠')} Created sender ${chalk.cyan(fromEmail)} but it did not auto-verify — ensure domain authentication is valid, then rerun`);
+    return { status: 'warned', reason: 'the created sender did not auto-verify', output: { senderIdentity: { id: sender.id, fromEmail, verified: false } } };
+  }
+
+  console.log(`      ${chalk.green('✓')} Created verified sender ${chalk.cyan(fromEmail)} ${chalk.dim(`(id: ${sender.id})`)}`);
+  return { output: { senderIdentity: { id: sender.id, fromEmail, verified: true } } };
+};

package/dist/services/campaigns/ensure/unsubscribe-groups.js

@@ -0,0 +1,116 @@
+/**
+ * Ensure the SendGrid unsubscribe groups (ASM) @omega.js/backend sends through
+ * exist, and land their ids in config.
+ *
+ * The KEYS come from @omega.js/backend's email SSOT — its send path names a
+ * group by key — and the recipient-facing name + description of each live
+ * HERE, the provider side. Groups are matched by NAME, never by id: ASM ids
+ * are per SendGrid ACCOUNT, so sibling brands sharing one account converge on
+ * the same seven groups and land the same ids.
+ *
+ * Each resolved id is written into omega.json5 at
+ * marketing.campaigns.providers.sendgrid.groups.<key>, its ONE authoritative
+ * home (comment-preserving) — @omega.js/backend reads it there and fails loudly
+ * at send time when one is missing
+ * ([#649](https://github.com/Omega-JS-Stack/omega/issues/649)).
+ */
+const chalk = require('chalk').default;
+const { BEM_GROUP_KEYS } = require('../../../lib/backend-marketing.js');
+const { writeBrandConfig } = require('../../../lib/config-write.js');
+const { dryRunPlan } = require('../../../lib/run-gates.js');
+
+// The recipient-facing group name + description, one row per @omega.js/backend
+// group key. Brand-neutral on purpose: the NAME is the match key, so two
+// brands on one SendGrid account resolve the same group instead of each
+// creating their own.
+const GROUP_DEFINITIONS = {
+  orders: {
+    name: 'OMEGA - Order Updates',
+    description: 'Receipts, renewals, refunds, and changes to your plan.',
+  },
+  hello: {
+    name: 'OMEGA - Onboarding',
+    description: 'Welcome emails and getting-started tips for your first weeks.',
+  },
+  account: {
+    name: 'OMEGA - Account',
+    description: 'Account actions you asked for: deletions, data requests, and confirmations.',
+  },
+  marketing: {
+    name: 'OMEGA - Marketing & Promotions',
+    description: 'Offers, discounts, product news, and reminders.',
+  },
+  security: {
+    name: 'OMEGA - Security',
+    description: 'Password resets, sign-in codes, and security alerts.',
+  },
+  newsletter: {
+    name: 'OMEGA - Newsletter',
+    description: 'The regular newsletter: feature announcements and industry news.',
+  },
+  internal: {
+    name: 'OMEGA - Internal Alerts',
+    description: 'Operational alerts sent to the team.',
+  },
+};
+
+module.exports = async function ensureUnsubscribeGroups(context) {
+  const { sendgridApi: api, options = {} } = context;
+
+  // A key @omega.js/backend added without a row here would send through a group
+  // this service never provisions — loud, at the top, not at send time.
+  const undefinedKeys = BEM_GROUP_KEYS.filter((key) => !GROUP_DEFINITIONS[key]);
+  if (undefinedKeys.length > 0) {
+    throw new Error(`@omega.js/backend group key(s) with no name+description row here: ${undefinedKeys.join(', ')}`);
+  }
+
+  const existing = await api.getUnsubscribeGroups();
+  const existingByName = Object.fromEntries(existing.map((group) => [group.name, group]));
+
+  const missing = BEM_GROUP_KEYS.filter((key) => !existingByName[GROUP_DEFINITIONS[key].name]);
+
+  if (missing.length > 0 && options.dryRun) {
+    return dryRunPlan(
+      `create ${missing.length} unsubscribe group(s): ${missing.map((key) => GROUP_DEFINITIONS[key].name).join(', ')}`,
+      { output: { unsubscribeGroups: { planned: { create: missing.map((key) => GROUP_DEFINITIONS[key].name) } } } },
+    );
+  }
+
+  const ids = {};
+
+  for (const key of BEM_GROUP_KEYS) {
+    const { name, description } = GROUP_DEFINITIONS[key];
+    const found = existingByName[name];
+
+    if (found) {
+      ids[key] = found.id;
+      continue;
+    }
+
+    const created = await api.createUnsubscribeGroup(name, description);
+    console.log(`      ${chalk.green('✓')} Created group ${chalk.cyan(`"${name}"`)} ${chalk.dim(`(${created.id})`)}`);
+    ids[key] = created.id;
+  }
+
+  if (missing.length === 0) {
+    console.log(`      ${chalk.green('✓')} All ${BEM_GROUP_KEYS.length} unsubscribe groups exist`);
+  }
+
+  // Already-equal ids are skipped by the editor, so a converged brand leaves
+  // omega.json5 byte-identical.
+  const written = writeBrandConfig(context, Object.fromEntries(
+    BEM_GROUP_KEYS.map((key) => [`marketing.campaigns.providers.sendgrid.groups.${key}`, ids[key]]),
+  ));
+
+  return {
+    output: {
+      unsubscribeGroups: {
+        total: BEM_GROUP_KEYS.length,
+        created: missing.length,
+        written: written.length,
+      },
+    },
+  };
+};
+
+module.exports.GROUP_DEFINITIONS = GROUP_DEFINITIONS;