@omega.js/manager 0.1.0

package/dist/services/bookmark/ensure/sync.js

@@ -0,0 +1,255 @@
+/**
+ * Sync the brand's bookmarks to the companion Chrome extension.
+ *
+ * Starts the WebSocket server the extension auto-connects to (it retries
+ * every 5s), sends one OMEGA_BOOKMARK_SYNC message, and waits for the
+ * extension's ack. Interactive sessions only — a headless run has no
+ * Chrome to talk to, so it skips instead of burning the connect wait.
+ * Dry runs print the link groups that would sync without opening the
+ * server (and without the gcloud function-log lookup — no live reads).
+ *
+ * Link sources are config + state; groups with unmet inputs are simply
+ * absent (a brand without analytics IDs gets no Analytics folder).
+ */
+const { execFileSync } = require('node:child_process');
+const chalk = require('chalk').default;
+const { WebSocketServer } = require('ws');
+const { brandRepo } = require('../../../vendor/config/index.js');
+const { isInteractive } = require('../../../vendor/devkit/prompt.js');
+const { resolveExtensionPort } = require('../../../lib/automation-client.js');
+
+const CONNECT_TIMEOUT = 10000;
+
+/**
+ * Deployed Cloud Function names for the project (for per-function log
+ * links). Shells out to gcloud; any failure (no gcloud, no auth, no
+ * project) is just "no function links".
+ */
+function getDeployedFunctions(projectId) {
+  try {
+    const output = execFileSync(
+      'gcloud',
+      ['functions', 'list', `--project=${projectId}`, '--format=value(name)'],
+      { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'ignore'] },
+    );
+    return output.trim().split('\n').filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Build the bookmark link groups from brand config.
+ *
+ * @param {Object} brandConfig - Merged brand config
+ * @param {Array} targets - Discovered target dirs ({ target } consulted)
+ * @param {Object} [extras] - { deployedFunctions } (injectable; defaults to none)
+ * @returns {Object} { Category: [{ title, url }] }
+ */
+function generateLinks(brandConfig, targets = [], extras = {}) {
+  const links = {};
+
+  const brandUrl = brandConfig.brand?.url;
+  const domain = brandUrl?.replace(/^https?:\/\//, '');
+  const firebaseProjectId = brandConfig.cloud?.config?.projectId;
+  const google = brandConfig.analytics?.providers?.google || {};
+  const github = brandConfig.repo?.providers?.github || {};
+  const deployedFunctions = extras.deployedFunctions || [];
+
+  // Cloud Console
+  if (firebaseProjectId) {
+    const functionLogUrl = (fnName) =>
+      `https://console.cloud.google.com/logs/query;query=--%20Date:%20%0A--%20Reason:%20%0Aresource.labels.function_name%3D%22${fnName}%22%0A--%20textPayload:%22%22;duration=P7D?project=${firebaseProjectId}`;
+
+    links.Cloud = [
+      { title: 'Dashboard', url: `https://console.cloud.google.com/home/dashboard?project=${firebaseProjectId}` },
+      { title: 'APIs & Services', url: `https://console.cloud.google.com/apis/dashboard?project=${firebaseProjectId}` },
+      { title: 'IAM', url: `https://console.cloud.google.com/iam-admin/iam?project=${firebaseProjectId}` },
+    ];
+
+    if (deployedFunctions.length > 0) {
+      links.Cloud.push({ title: '───────────', url: `https://console.cloud.google.com/functions/list?project=${firebaseProjectId}` });
+      for (const fn of deployedFunctions) {
+        links.Cloud.push({ title: `${fn}()`, url: functionLogUrl(fn) });
+      }
+    }
+  }
+
+  // Firebase Console
+  if (firebaseProjectId) {
+    links.Firebase = [
+      { title: 'Overview', url: `https://console.firebase.google.com/project/${firebaseProjectId}/overview` },
+      { title: 'Settings', url: `https://console.firebase.google.com/project/${firebaseProjectId}/settings/general` },
+      { title: 'Authentication', url: `https://console.firebase.google.com/project/${firebaseProjectId}/authentication/users` },
+      { title: 'App Check', url: `https://console.firebase.google.com/project/${firebaseProjectId}/appcheck` },
+      { title: 'Firestore Database', url: `https://console.firebase.google.com/project/${firebaseProjectId}/firestore` },
+      { title: 'Realtime Database', url: `https://console.firebase.google.com/project/${firebaseProjectId}/database` },
+      { title: 'Storage', url: `https://console.firebase.google.com/project/${firebaseProjectId}/storage` },
+      { title: 'Hosting', url: `https://console.firebase.google.com/project/${firebaseProjectId}/hosting` },
+      { title: 'Functions', url: `https://console.firebase.google.com/project/${firebaseProjectId}/functions` },
+    ];
+  }
+
+  // Analytics
+  if (google.accountId && google.propertyId) {
+    links.Analytics = [
+      { title: 'Reports', url: `https://analytics.google.com/analytics/web/#/a${google.accountId}p${google.propertyId}/reports/intelligenthome` },
+      { title: 'Realtime', url: `https://analytics.google.com/analytics/web/#/a${google.accountId}p${google.propertyId}/reports/dashboard?params=_u..nav%3Dmaui` },
+      { title: 'Data Streams', url: `https://analytics.google.com/analytics/web/#/a${google.accountId}p${google.propertyId}/admin/streams` },
+    ];
+  }
+
+  // Search Console
+  if (domain) {
+    links.Search = [
+      { title: 'Performance', url: `https://search.google.com/search-console/performance/search-analytics?resource_id=sc-domain:${domain}` },
+      { title: 'Indexing', url: `https://search.google.com/search-console/index?resource_id=sc-domain:${domain}` },
+      { title: 'Sitemaps', url: `https://search.google.com/search-console/sitemaps?resource_id=sc-domain:${domain}` },
+    ];
+  }
+
+  // Stripe Dashboard — per-brand keys, so the key's own account is the
+  // dashboard default (no account slug in the URL)
+  if (brandConfig.payment?.providers?.stripe) {
+    const s = 'https://dashboard.stripe.com';
+    links.Stripe = [
+      { title: 'Dashboard', url: `${s}/dashboard` },
+      { title: 'Products', url: `${s}/products?active=true` },
+      { title: 'Customers', url: `${s}/customers` },
+      { title: 'Subscriptions', url: `${s}/subscriptions?status=active` },
+      { title: 'Radar', url: `${s}/radar` },
+      { title: '───────────', url: `${s}/settings` },
+      { title: 'Account', url: `${s}/settings/account` },
+      { title: 'Profile', url: `${s}/settings/profile` },
+      { title: 'Billing', url: `${s}/settings/billing/subscriptions` },
+      { title: 'Emails', url: `${s}/settings/emails` },
+      { title: 'Payouts', url: `${s}/settings/payouts` },
+    ];
+  }
+
+  // GitHub — one brand monorepo
+  if (github.org) {
+    // BOTH halves from the one derivation: an `owner/name` slug houses the repo
+    // under its own owner, which `repo.providers.github.org` does not name.
+    const { repo } = brandRepo(brandConfig);
+    links.GitHub = [
+      { title: 'Repository', url: `https://github.com/${repo}` },
+      { title: 'Actions', url: `https://github.com/${repo}/actions` },
+    ];
+  }
+
+  // Live URLs
+  const liveLinks = [];
+  if (brandUrl) {
+    liveLinks.push({ title: 'Website', url: brandUrl });
+  }
+  if (domain && targets.some((entry) => entry.target === 'backend')) {
+    liveLinks.push({ title: 'API', url: `https://api.${domain}` });
+  }
+  if (liveLinks.length > 0) {
+    links.Live = liveLinks;
+  }
+
+  return links;
+}
+
+module.exports = async function ensureSync(context) {
+  const { brandConfig, targets, options = {} } = context;
+
+  const brandId = brandConfig.brand.id;
+  const brandName = brandConfig.brand.name || brandId;
+  const groupCount = (links) => Object.keys(links).length;
+  const linkCount = (links) => Object.values(links).flat().length;
+
+  if (options.dryRun) {
+    const links = generateLinks(brandConfig, targets);
+    console.log(`      ${chalk.yellow('[DRY RUN]')} Would sync ${chalk.cyan(linkCount(links))} bookmarks in ${chalk.cyan(groupCount(links))} groups: ${Object.keys(links).join(', ') || '(none)'}`);
+    return { output: { sync: { planned: Object.keys(links) } } };
+  }
+
+  if (!isInteractive()) {
+    console.log(chalk.dim('      ⊘ Interactive sessions only — the sync needs a running Chrome with the Omega extension connected'));
+    return { output: { sync: { reason: 'non-interactive' } } };
+  }
+
+  const firebaseProjectId = brandConfig.cloud?.config?.projectId;
+  const links = generateLinks(brandConfig, targets, {
+    deployedFunctions: firebaseProjectId ? getDeployedFunctions(firebaseProjectId) : [],
+  });
+
+  const message = {
+    type: 'OMEGA_BOOKMARK_SYNC',
+    brand: { id: brandId, name: brandName, url: brandConfig.brand?.url },
+    links,
+  };
+
+  const port = resolveExtensionPort();
+  const connectTimeout = Number(process.env.OMEGA_EXTENSION_TIMEOUT) || CONNECT_TIMEOUT;
+
+  return new Promise((resolve) => {
+    // Loopback only — the extension connects from this machine; binding all
+    // interfaces would expose the sync socket to the LAN for its lifetime
+    const wss = new WebSocketServer({ host: '127.0.0.1', port });
+    let resolved = false;
+
+    const cleanup = (result) => {
+      if (resolved) return;
+      resolved = true;
+
+      for (const client of wss.clients) {
+        client.terminate();
+      }
+      wss.close(() => resolve(result));
+    };
+
+    const timeout = setTimeout(() => {
+      console.log(`      ${chalk.yellow('⚠')} Extension not connected (timeout) — install/enable it from ${chalk.cyan('extension/')} (chrome://extensions → Load unpacked → extension/dist)`);
+      cleanup({ status: 'warned', reason: 'extension not connected', output: { sync: { reason: 'extension not connected' } } });
+    }, connectTimeout);
+
+    wss.on('error', (error) => {
+      clearTimeout(timeout);
+      const reason = error.code === 'EADDRINUSE'
+        ? `port ${port} already in use (another manager run or the extension MCP server?)`
+        : error.message;
+      console.log(`      ${chalk.yellow('⚠')} WebSocket server failed: ${reason}`);
+      cleanup({ status: 'warned', reason, output: { sync: { reason } } });
+    });
+
+    wss.on('connection', (ws) => {
+      console.log(`      ${chalk.dim('→')} Extension connected, sending ${chalk.cyan(brandName)} bookmarks (${linkCount(links)} links)...`);
+
+      ws.send(JSON.stringify(message));
+
+      ws.on('message', (data) => {
+        clearTimeout(timeout);
+
+        let response = null;
+        try {
+          response = JSON.parse(data.toString());
+        } catch {
+          // Non-JSON ack — treat as synced
+        }
+
+        if (response && response.success === false) {
+          console.log(`      ${chalk.yellow('⚠')} Sync failed${chalk.dim(`: ${response.error}`)}`);
+          cleanup({ status: 'warned', reason: 'extension reported a sync failure', output: { sync: { reason: response.error || 'extension reported failure' } } });
+          return;
+        }
+
+        console.log(`      ${chalk.green('✓')} Bookmarks synced for ${chalk.cyan(brandName)}`);
+        cleanup({ output: { sync: { synced: true, links: linkCount(links) } } });
+      });
+
+      // Extension closed without answering — the send went out; call it synced
+      ws.on('close', () => {
+        clearTimeout(timeout);
+        cleanup({ output: { sync: { synced: true, links: linkCount(links) } } });
+      });
+    });
+
+    console.log(`      ${chalk.dim('→')} Waiting for the extension on ${chalk.cyan(`ws://localhost:${port}`)}...`);
+  });
+};
+
+module.exports.generateLinks = generateLinks;

package/dist/services/bookmark/index.js

@@ -0,0 +1,17 @@
+/**
+ * Bookmark service — pushes the brand's console/dashboard bookmarks to
+ * the companion Chrome extension (extension/) over the WebSocket
+ * protocol; the extension files them under Ω / {Brand} / {Category}.
+ *
+ * The links are derived from the brand's own config + state (new-world
+ * shapes: the single brand monorepo repo instead of omega-manager's
+ * per-target repos, unslugged Stripe dashboard URLs instead of the
+ * ITW platform-account deep links). The sync itself is interactive-only:
+ * it needs a running Chrome with the extension connected, so headless
+ * runs skip cleanly instead of sitting in the connect wait.
+ */
+const { createServiceRunner } = require('../../lib/service-runner.js');
+
+module.exports.run = createServiceRunner({
+  serviceDir: __dirname,
+});

package/dist/services/campaigns/ensure/contact-person.js

@@ -0,0 +1,40 @@
+/**
+ * Ensure the brand names the human its transactional email signs off as —
+ * `brand.contact.person.name` ([#694](https://github.com/Omega-JS-Stack/omega/issues/694)).
+ *
+ * @omega.js/backend's personal sends (welcome, discount nudge, checkup) resolve
+ * their signoff from it and throw a coded 400 without it. Found live: the first
+ * real signup on a launched brand returned 200 while all three sends failed in
+ * function logs nobody was watching, because nothing checked the value before
+ * the launch. SENDGRID_API_KEY is what turns those sends on, and this service
+ * only runs with it (or an injected client), so the SendGrid walk is the launch
+ * gate that catches the hole — and it FAILS, because a silent nudge is exactly
+ * what the runtime already does.
+ *
+ * Last in the operation order on purpose: the value is a precondition of
+ * @omega.js/backend's sends, not of anything provisioned here, so every SendGrid
+ * operation still converges and the run ends failed with the key named.
+ * The runtime error stays as it is — it names the key correctly already.
+ */
+const chalk = require('chalk').default;
+
+const CONFIG_PATH = 'brand.contact.person.name';
+
+module.exports = async function ensureContactPerson(context) {
+  const { brandConfig } = context;
+  const person = brandConfig.brand?.contact?.person || {};
+
+  if (person.name) {
+    console.log(`      ${chalk.green('✓')} Email signoff: ${chalk.cyan(person.name)}`);
+    return {};
+  }
+
+  console.log(`      ${chalk.red('✗')} No ${chalk.cyan(CONFIG_PATH)} — every personal send (welcome, discount nudge, checkup) fails at runtime`);
+  console.log(`      ${chalk.dim('→')} Set ${chalk.cyan(CONFIG_PATH)} in config/omega.json5, then rerun`);
+
+  return {
+    status: 'error',
+    error: `Missing ${CONFIG_PATH} in config/omega.json5 — @omega.js/backend's welcome, discount-nudge and checkup emails cannot send without it`,
+    output: { contactPerson: { missing: CONFIG_PATH } },
+  };
+};

package/dist/services/campaigns/ensure/custom-fields.js

@@ -0,0 +1,84 @@
+/**
+ * Ensure @omega.js/backend's custom fields exist in SendGrid with the right types.
+ *
+ * The field list comes from @omega.js/backend's marketing SSOT — its OWN
+ * per-provider view of the catalog (#695), the same derivation the backend's
+ * contact sync writes through, so what is provisioned here and what is sent
+ * there are one list (SendGrid has first/last name built in, so the catalog
+ * skips them on both sides). A type mismatch can't be patched in SendGrid, so
+ * the field is deleted and recreated. Fields @omega.js/backend doesn't own are
+ * never touched.
+ */
+const chalk = require('chalk').default;
+const { fieldsFor } = require('../../../lib/backend-marketing.js');
+const { dryRunPlan } = require('../../../lib/run-gates.js');
+
+const SENDGRID_FIELDS = fieldsFor('sendgrid');
+
+// @omega.js/backend type → SendGrid field_type
+const TYPE_MAP = { text: 'Text', number: 'Number', date: 'Date' };
+
+module.exports = async function ensureCustomFields(context) {
+  const { sendgridApi: api, options = {} } = context;
+
+  const existing = await api.getCustomFields();
+  const existingByName = Object.fromEntries(existing.map((f) => [f.name, f]));
+
+  const missing = [];
+  const mismatched = [];
+
+  for (const field of SENDGRID_FIELDS) {
+    const sgField = existingByName[field.name];
+
+    if (!sgField) {
+      missing.push(field);
+    } else if (sgField.field_type !== TYPE_MAP[field.type]) {
+      mismatched.push({ ...field, existingId: sgField.id, existingType: sgField.field_type });
+    }
+  }
+
+  if (missing.length === 0 && mismatched.length === 0) {
+    console.log(`      ${chalk.green('✓')} All ${SENDGRID_FIELDS.length} custom fields exist`);
+    return { output: { customFields: { total: SENDGRID_FIELDS.length, created: 0, recreated: 0 } } };
+  }
+
+  if (options.dryRun) {
+    const planned = {
+      create: missing.map((f) => f.name),
+      recreate: mismatched.map((f) => `${f.name} (${f.existingType} → ${TYPE_MAP[f.type]})`),
+    };
+    return dryRunPlan(`create ${planned.create.length}, recreate ${planned.recreate.length} field(s)`, { output: { customFields: { planned } } });
+  }
+
+  // Type mismatches: delete, then recreate alongside the missing ones
+  for (const field of mismatched) {
+    await api.deleteCustomField(field.existingId);
+    console.log(`      ${chalk.yellow('↻')} Deleted ${chalk.cyan(field.name)} ${chalk.dim(`(was ${field.existingType}, need ${TYPE_MAP[field.type]})`)}`);
+    missing.push(field);
+  }
+
+  for (const field of missing) {
+    const created = await api.createCustomField(field.name, TYPE_MAP[field.type]);
+    console.log(`      ${chalk.green('✓')} Created ${chalk.cyan(field.name)} ${chalk.dim(`(${created.id})`)}`);
+  }
+
+  // Verify everything actually persisted
+  const verify = await api.getCustomFields();
+  const verifyByName = new Set(verify.map((f) => f.name));
+  const stillMissing = SENDGRID_FIELDS.filter((f) => !verifyByName.has(f.name));
+
+  if (stillMissing.length > 0) {
+    console.log(`      ${chalk.yellow('⚠')} ${stillMissing.length} field(s) failed to persist: ${chalk.cyan(stillMissing.map((f) => f.name).join(', '))}`);
+    return { status: 'warned', reason: `${stillMissing.length} field(s) failed to persist: ${stillMissing.map((f) => f.name).join(', ')}`, output: { customFields: { total: SENDGRID_FIELDS.length, failed: stillMissing.map((f) => f.name) } } };
+  }
+
+  return {
+    output: {
+      customFields: {
+        total: SENDGRID_FIELDS.length,
+        created: missing.length - mismatched.length,
+        recreated: mismatched.length,
+      },
+    },
+  };
+};

package/dist/services/campaigns/ensure/domain-auth.js

@@ -0,0 +1,92 @@
+/**
+ * Ensure SendGrid domain authentication for the brand's domain.
+ *
+ * A valid authentication is converged proof. A missing one is created in one
+ * pass: authenticate in SendGrid (automatic_security → 3 CNAMEs), diff-sync
+ * the records into the Cloudflare apex zone (exact-match = untouched, wrong
+ * content = patched, missing = created), then validate — interactive runs
+ * poll until DNS propagates and SendGrid confirms; non-interactive/dry runs
+ * validate ONCE, report warned, and the rerun converges. No Cloudflare token
+ * → the records to add manually, and validation is still attempted so a
+ * manual fix converges on rerun.
+ */
+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');
+
+const SUBDOMAIN = 'emailauth';
+
+// The record set automatic_security returns
+const DNS_KEYS = ['mail_cname', 'dkim1', 'dkim2'];
+
+module.exports = async function ensureDomainAuth(context) {
+  const { sendgridApi: api, cloudflareApi, domain, apexDomain, options = {} } = context;
+
+  // === READ: is the domain already authenticated and valid? ===
+  const domains = await api.getAuthenticatedDomains();
+  let domainAuth = domains.find((d) => d.domain === domain);
+
+  if (domainAuth?.valid) {
+    console.log(`      ${chalk.green('✓')} Domain ${chalk.cyan(domain)} authenticated`);
+    return { output: { domainAuth: { id: domainAuth.id, valid: true } } };
+  }
+
+  if (options.dryRun) {
+    const planned = domainAuth ? ['dns-records', 'validate'] : ['authenticate-domain', 'dns-records', 'validate'];
+    return dryRunPlan(`${planned.join(' → ')}`, { output: { domainAuth: { planned } } });
+  }
+
+  // === Create the authentication when missing ===
+  if (!domainAuth) {
+    domainAuth = await api.authenticateDomain(domain, SUBDOMAIN);
+    console.log(`      ${chalk.green('✓')} Created domain authentication for ${chalk.cyan(domain)}`);
+  } else {
+    console.log(`      ${chalk.yellow('↻')} Domain ${chalk.cyan(domain)} exists but is not validated — reconciling DNS`);
+  }
+
+  const records = DNS_KEYS
+    .map((key) => ({ key, record: domainAuth.dns?.[key] }))
+    .filter(({ record }) => record);
+
+  if (records.length === 0) {
+    throw new Error('SendGrid returned no DNS records for the domain authentication');
+  }
+
+  // === DNS via Cloudflare (or manual guidance) ===
+  const synced = await syncDnsRecords(cloudflareApi, apexDomain, records);
+
+  // === Validate — DNS may need a minute; interactive runs wait it out ===
+  const isValid = (validation) => Boolean(validation?.validation_results
+    && Object.values(validation.validation_results).every((r) => r.valid));
+
+  let valid = isValid(await api.validateDomain(domainAuth.id));
+
+  if (!valid && canPrompt(options)) {
+    const result = await pollWithSpinner({
+      check: async () => {
+        try {
+          return isValid(await api.validateDomain(domainAuth.id)) ? { done: true } : { done: false };
+        } catch {
+          return { done: false };
+        }
+      },
+      intervalMs: 10000,
+      message: 'Validating domain authentication (waiting for DNS propagation)',
+      indent: '      ',
+    });
+    valid = result.success;
+  }
+
+  if (valid) {
+    console.log(`      ${chalk.green('✓')} Domain ${chalk.cyan(domain)} validated`);
+    return { output: { domainAuth: { id: domainAuth.id, valid: true } } };
+  }
+
+  console.log(`      ${chalk.yellow('⚠')} Validation pending — DNS is likely still propagating, rerun in a few minutes`);
+  return {
+    status: 'warned',
+    reason: 'domain validation pending — DNS is still propagating',
+    output: { domainAuth: { id: domainAuth.id, valid: false, ...(synced ? {} : { manualRecords: manualRecordList(records) }) } },
+  };
+};

package/dist/services/campaigns/ensure/event-webhook.js

@@ -0,0 +1,89 @@
+/**
+ * Ensure the account-global SendGrid Event Webhook points at the parent
+ * @omega.js/backend's forwarder with the consent-pipeline events enabled.
+ *
+ * SendGrid supports ONE Event Webhook per account, so it always targets the
+ * parent brand (`parent` in omega.json5 — 'self' when this brand IS the
+ * parent); the parent fans events out to each brand's own
+ * /marketing/webhook endpoint. Sibling brands sharing the account all
+ * converge on the same URL + toggle set. Only the consent toggles are
+ * managed — tracking toggles (open/click/delivered/…) are not ours to touch.
+ * Drift is patched with the minimum diff.
+ */
+const chalk = require('chalk').default;
+const { dryRunPlan } = require('../../../lib/run-gates.js');
+
+// The consent-pipeline events @omega.js/backend must receive
+const DESIRED_TOGGLES = {
+  bounce: true,
+  dropped: true,
+  spam_report: true,
+  unsubscribe: true,
+  group_unsubscribe: true,
+};
+
+module.exports = async function ensureEventWebhook(context) {
+  const { sendgridApi: api, brandConfig, domain, options = {} } = context;
+
+  const parent = brandConfig.parent;
+  if (parent === false) {
+    // Tri-state: explicit false = deliberate opt-out, no nudge
+    console.log(chalk.dim('      ⊘ parent = false — Event Webhook opted out'));
+    return {};
+  }
+  if (!parent) {
+    console.log(chalk.dim('      ⊘ No parent configured — nothing to point the Event Webhook at'));
+    console.log(chalk.dim("      → Set parent in omega.json5 ('self' when this brand runs the central backend)"));
+    return {};
+  }
+
+  if (!process.env.OMEGA_WEBHOOK_KEY) {
+    // Unreachable by design (#635): the key is OMEGA's own (`generated:` in
+    // the env schema) and the campaigns service's setup mints it through the
+    // shared contract before any operation runs. Absent here = broken wiring.
+    throw new Error('OMEGA_WEBHOOK_KEY absent after the campaigns setup ran — its REQUIRES entry or its requestServiceInput call is missing');
+  }
+
+  const parentHost = parent === 'self'
+    ? domain
+    : parent.replace(/^https?:\/\//, '').replace(/\/$/, '');
+  const desiredUrl = `https://api.${parentHost}/omega/marketing/webhook/forward?provider=sendgrid&key=${process.env.OMEGA_WEBHOOK_KEY}`;
+
+  const current = await api.getEventWebhookSettings();
+
+  const patch = {};
+  if (current.url !== desiredUrl) {
+    patch.url = desiredUrl;
+  }
+  if (current.enabled !== true) {
+    patch.enabled = true;
+  }
+  for (const [toggle, value] of Object.entries(DESIRED_TOGGLES)) {
+    if (current[toggle] !== value) {
+      patch[toggle] = value;
+    }
+  }
+
+  if (Object.keys(patch).length === 0) {
+    console.log(`      ${chalk.green('✓')} Event Webhook up to date`);
+    console.log(`      ${chalk.dim('→')} ${chalk.dim(`https://api.${parentHost}/omega/marketing/webhook/forward`)}`);
+    return { output: { eventWebhook: { url: 'converged' } } };
+  }
+
+  if (options.dryRun) {
+    return dryRunPlan(`patch: ${Object.keys(patch).join(', ')}`, { output: { eventWebhook: { planned: Object.keys(patch) } } });
+  }
+
+  if (patch.url) {
+    console.log(`      ${chalk.yellow('↻')} Pointing Event Webhook at ${chalk.cyan(`api.${parentHost}`)}'s forwarder`);
+  }
+  const enablingToggles = Object.keys(patch).filter((key) => key !== 'url' && key !== 'enabled');
+  if (enablingToggles.length > 0) {
+    console.log(`      ${chalk.yellow('↻')} Enabling events: ${chalk.cyan(enablingToggles.join(', '))}`);
+  }
+
+  await api.updateEventWebhookSettings(patch);
+  console.log(`      ${chalk.green('✓')} Event Webhook updated`);
+
+  return { output: { eventWebhook: { updated: Object.keys(patch) } } };
+};