@omega.js/manager 0.1.0

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

@@ -0,0 +1,140 @@
+/**
+ * Ensure @omega.js/backend's segments exist on the Beehiiv publication.
+ *
+ * Beehiiv has NO segment-create API — the read side lists what exists,
+ * and creation happens through the dashboard UI. Interactive runs offer
+ * to drive that UI via the companion Chrome extension (trusted-event
+ * browser automation; see lib/segment-automation.js) or to open the
+ * dashboard for manual creation, then RE-verify against the API so
+ * "created" means Beehiiv says so. Non-interactive and dry runs never
+ * mutate: missing segments warn with human-readable conditions.
+ */
+const chalk = require('chalk').default;
+const { select } = require('../../../vendor/devkit/prompt.js');
+const { openBrowserAndPoll } = require('../../../vendor/devkit/flows.js');
+const { segmentsFor } = require('../../../lib/backend-marketing.js');
+const { AutomationClient } = require('../../../lib/automation-client.js');
+const { formatCondition, automateCreateSegment } = require('../lib/segment-automation.js');
+const { canPrompt } = require('../../../lib/run-gates.js');
+
+const BEEHIIV_SEGMENTS = segmentsFor('beehiiv');
+const SEGMENTS_URL = 'https://app.beehiiv.com/segments';
+
+/** Names of the @omega.js/backend segments missing from the publication. */
+async function listMissing(api, publicationId) {
+  const existing = await api.getSegments(publicationId);
+  const existingByName = new Set(existing.map((s) => s.name));
+  return BEEHIIV_SEGMENTS.filter((s) => !existingByName.has(s.name));
+}
+
+module.exports = async function ensureSegments(context) {
+  const { beehiivApi: api, serviceData, options = {} } = context;
+
+  const publicationId = serviceData.publicationId;
+  if (!publicationId) {
+    console.log(chalk.dim('      ⊘ No publication yet — nothing to verify segments on'));
+    return {};
+  }
+
+  const missing = await listMissing(api, publicationId);
+
+  if (missing.length === 0) {
+    console.log(`      ${chalk.green('✓')} All ${BEEHIIV_SEGMENTS.length} segments exist`);
+    return { output: { segments: { total: BEEHIIV_SEGMENTS.length, missing: [] } } };
+  }
+
+  console.log(`      ${chalk.yellow('⚠')} ${missing.length} segment(s) missing — Beehiiv has no segment-create API:`);
+  for (const segment of missing) {
+    const joiner = segment.logic === 'or' ? ' OR ' : ' AND ';
+    const criteria = segment.conditions.map((c) => formatCondition(c)).join(joiner);
+    console.log(`        ${chalk.dim('•')} ${chalk.cyan(segment.display)} ${chalk.dim(`(${segment.name})`)}`);
+    console.log(`          ${chalk.dim('→')} ${criteria}`);
+  }
+
+  const warned = (created = []) => ({
+    status: 'warned',
+    reason: `${missing.length} segment(s) missing: ${missing.map((s) => s.name).join(', ')}`,
+    output: { segments: { total: BEEHIIV_SEGMENTS.length, missing: missing.map((s) => s.name), ...(created.length ? { created } : {}) } },
+  });
+
+  // Headless/dry runs stop at the instructions (build them at SEGMENTS_URL)
+  if (!canPrompt(options)) {
+    console.log(`        ${chalk.dim(`→ Build them at ${SEGMENTS_URL}`)}`);
+    return warned();
+  }
+
+  const action = await select({
+    message: 'Create missing segments?',
+    choices: [
+      { name: 'Automate via extension', value: 'automate' },
+      { name: 'Open dashboard (manual)', value: 'manual' },
+      { name: 'Skip', value: 'skip' },
+    ],
+    default: 'automate',
+  });
+
+  if (action === 'skip') {
+    return warned();
+  }
+
+  const created = [];
+
+  if (action === 'manual') {
+    await openBrowserAndPoll({
+      url: SEGMENTS_URL,
+      label: 'the Beehiiv segments page',
+      promptMessage: `Create ${missing.length} missing segment(s) in Beehiiv`,
+      waitMessage: 'Press ENTER when done',
+      manualOnly: true,
+    });
+  } else {
+    // Automate via extension — open the dashboard first so the user can
+    // select the right publication before the automation drives the UI
+    await openBrowserAndPoll({
+      url: SEGMENTS_URL,
+      label: 'the Beehiiv segments page',
+      promptMessage: 'Select the correct publication in Beehiiv, then confirm to start automation',
+      waitMessage: 'Press ENTER when ready',
+      manualOnly: true,
+    });
+
+    console.log(`      ${chalk.dim('Connecting to extension...')}`);
+    const client = new AutomationClient();
+
+    try {
+      await client.connect();
+      console.log(`      ${chalk.dim('→')} Extension connected`);
+
+      for (const segment of missing) {
+        try {
+          console.log(`      ${chalk.dim(`Creating ${segment.display}...`)}`);
+          await automateCreateSegment(client, segment);
+          console.log(`      ${chalk.green('✓')} Created ${chalk.cyan(segment.display)}`);
+          created.push(segment.name);
+        } catch (e) {
+          console.log(`      ${chalk.red('✗')} Failed to create ${chalk.cyan(segment.display)}: ${e.message}`);
+        }
+      }
+    } catch (e) {
+      console.log(`      ${chalk.red('✗')} Automation failed: ${e.message}`);
+    } finally {
+      await client.disconnect();
+    }
+  }
+
+  // Re-verify — "created" is what Beehiiv reports, not what the automation
+  // believes it did
+  const remaining = await listMissing(api, publicationId);
+
+  if (remaining.length === 0) {
+    console.log(`      ${chalk.green('✓')} All ${BEEHIIV_SEGMENTS.length} segments exist`);
+    return { output: { segments: { total: BEEHIIV_SEGMENTS.length, missing: [], ...(created.length ? { created } : {}) } } };
+  }
+
+  console.log(`      ${chalk.yellow('⚠')} ${remaining.length} segment(s) still missing: ${remaining.map((s) => s.name).join(', ')}`);
+  return {
+    status: 'warned',
+    reason: `${remaining.length} segment(s) still missing: ${remaining.map((s) => s.name).join(', ')}`,
+    output: { segments: { total: BEEHIIV_SEGMENTS.length, missing: remaining.map((s) => s.name), ...(created.length ? { created } : {}) } },
+  };
+};

package/dist/services/newsletter/ensure/webhook.js

@@ -0,0 +1,108 @@
+/**
+ * Ensure the publication's webhook delivers subscription events to the
+ * parent @omega.js/backend's forwarder.
+ *
+ * Publications can be shared across sibling brands, so the webhook always
+ * points at the parent (`parent` in omega.json5, 'self' for the parent
+ * brand) — the parent reads the brands collection and fans each event out.
+ * The webhook is matched by its managed description first (stable across
+ * parent moves), then by URL; drift in url/event_types/enabled is patched
+ * with the minimum diff.
+ */
+const chalk = require('chalk').default;
+const { dryRunPlan } = require('../../../lib/run-gates.js');
+
+// Subscription events @omega.js/backend's consent pipeline consumes (they flip
+// consent.marketing.status to 'revoked' and propagate the unsub to SendGrid)
+const DESIRED_EVENT_TYPES = [
+  'subscription.unsubscribed',
+  'subscription.deleted',
+  'subscription.paused',
+];
+
+const WEBHOOK_DESCRIPTION = '@omega.js/backend consent pipeline (managed by OMEGA — do not edit manually)';
+
+module.exports = async function ensureWebhook(context) {
+  const { beehiivApi: api, brandConfig, domain, serviceData, options = {} } = context;
+
+  const publicationId = serviceData.publicationId;
+  if (!publicationId) {
+    console.log(chalk.dim('      ⊘ No publication yet — nothing to configure a webhook on'));
+    return {};
+  }
+
+  const parent = brandConfig.parent;
+  if (parent === false) {
+    // Tri-state: explicit false = deliberate opt-out, no nudge
+    console.log(chalk.dim('      ⊘ parent = false — webhook opted out'));
+    return {};
+  }
+  if (!parent) {
+    console.log(chalk.dim('      ⊘ No parent configured — nothing to point the 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 newsletter 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 newsletter 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=beehiiv&key=${process.env.OMEGA_WEBHOOK_KEY}`;
+
+  const webhooks = await api.listWebhooks(publicationId);
+
+  // The managed description is the primary key — it survives URL changes
+  // when a brand moves parents
+  const existing = webhooks.find((wh) => wh.description === WEBHOOK_DESCRIPTION)
+    || webhooks.find((wh) => wh.url === desiredUrl);
+
+  if (existing) {
+    const patch = {};
+    if (existing.url !== desiredUrl) {
+      patch.url = desiredUrl;
+    }
+    const currentEvents = new Set(existing.event_types || []);
+    const eventsMatch = DESIRED_EVENT_TYPES.every((e) => currentEvents.has(e))
+      && (existing.event_types || []).every((e) => DESIRED_EVENT_TYPES.includes(e));
+    if (!eventsMatch) {
+      patch.event_types = DESIRED_EVENT_TYPES;
+    }
+    if (existing.enabled === false) {
+      patch.enabled = true;
+    }
+
+    if (Object.keys(patch).length === 0) {
+      console.log(`      ${chalk.green('✓')} Webhook up to date ${chalk.dim(`(${existing.id})`)}`);
+      return { output: { webhook: { id: existing.id, url: 'converged' } } };
+    }
+
+    if (options.dryRun) {
+      return dryRunPlan(`patch: ${Object.keys(patch).join(', ')}`, { output: { webhook: { planned: Object.keys(patch) } } });
+    }
+
+    await api.updateWebhook(publicationId, existing.id, patch);
+    console.log(`      ${chalk.green('✓')} Webhook updated ${chalk.dim(`(${existing.id})`)}`);
+    return { output: { webhook: { id: existing.id, updated: Object.keys(patch) } } };
+  }
+
+  if (options.dryRun) {
+    return dryRunPlan('create the consent-pipeline webhook', { output: { webhook: { planned: ['create'] } } });
+  }
+
+  const created = await api.createWebhook(publicationId, {
+    url: desiredUrl,
+    event_types: DESIRED_EVENT_TYPES,
+    description: WEBHOOK_DESCRIPTION,
+  });
+  const newId = created?.data?.id || created?.id || '(unknown id)';
+  console.log(`      ${chalk.green('✓')} Webhook created ${chalk.dim(`(${newId})`)}`);
+  console.log(`      ${chalk.dim('→')} ${chalk.dim(`https://api.${parentHost}/omega/marketing/webhook/forward`)}`);
+
+  return { output: { webhook: { id: newId, created: true } } };
+};

package/dist/services/newsletter/index.js

@@ -0,0 +1,64 @@
+/**
+ * Newsletter service (Beehiiv provider) — the brand's newsletter publication: access verified (or
+ * auto-matched by name), @omega.js/backend's custom fields provisioned, @omega.js/backend's segments
+ * ensured (Beehiiv has no segment-create API — missing ones get readable
+ * instructions, and interactive runs offer to create them by driving the
+ * dashboard UI through the companion Chrome extension), and the
+ * publication webhook pointed at the parent @omega.js/backend's forwarder.
+ *
+ * Publications are created manually in the dashboard (no API) — the service
+ * prints the exact values to copy when none matches.
+ *
+ * Auth: BEEHIIV_API_KEY in the brand .env; the webhook operation
+ * additionally needs OMEGA_WEBHOOK_KEY, which the setup MINTS through the
+ * shared contract (it is OMEGA's own key, #635). No API key → clean skip.
+ */
+const { chosenProvider } = require('../../vendor/config/index.js');
+
+const { serviceInputSpec } = require('../../config.js');
+const { createServiceRunner } = require('../../lib/service-runner.js');
+const { requestServiceInput } = require('../../lib/service-input.js');
+const { BeehiivAPI } = require('./lib/beehiiv-api.js');
+
+module.exports.run = createServiceRunner({
+  serviceDir: __dirname,
+  setup: async (context) => {
+    const newsletter = context.brandConfig.marketing?.newsletter || {};
+
+    if (newsletter.enabled === false) {
+      return { skip: true, reason: 'marketing.newsletter.enabled = false' };
+    }
+
+    // The vendor is a KEY under marketing.newsletter.providers (#425) — no
+    // entry means none chosen and this service skips.
+    const provider = chosenProvider(newsletter.providers);
+    if (!provider) {
+      return { skip: true, reason: 'no marketing.newsletter.providers entry' };
+    }
+    if (provider !== 'beehiiv') {
+      return { skip: true, reason: `marketing.newsletter.providers.${provider} is not a known newsletter provider` };
+    }
+
+    const domain = (context.brandConfig.brand?.url || '').replace(/^https?:\/\//, '').replace(/\/$/, '');
+    if (!domain) {
+      return { skip: true, reason: 'no brand.url configured' };
+    }
+
+    if (!context.beehiivApi) {
+      const gate = await requestServiceInput(context, serviceInputSpec('newsletter', { names: ['BEEHIIV_API_KEY'] }));
+      if (gate) return gate;
+    }
+
+    // The webhook key is OMEGA's OWN (#635): the shared helper mints it in
+    // place when this service runs before the workspace one did, so the
+    // webhook operation can read it unconditionally.
+    const webhookKeyGate = await requestServiceInput(context, serviceInputSpec('newsletter', { names: ['OMEGA_WEBHOOK_KEY'] }));
+    if (webhookKeyGate) return webhookKeyGate;
+
+    // Tests inject a fake client via context.beehiivApi
+    return {
+      beehiivApi: context.beehiivApi || new BeehiivAPI(),
+      domain,
+    };
+  },
+});

package/dist/services/newsletter/lib/beehiiv-api.js

@@ -0,0 +1,124 @@
+/**
+ * Beehiiv v2 API client — publications, custom fields, segments (list-only;
+ * Beehiiv has no segment-create API), and per-publication webhooks. Named-
+ * method surface so tests can fake it method-for-method.
+ *
+ * Auth: BEEHIIV_API_KEY in the brand .env.
+ */
+const BEEHIIV_API_BASE = 'https://api.beehiiv.com/v2';
+
+class BeehiivAPI {
+  constructor(options = {}) {
+    this.apiKey = options.apiKey || process.env.BEEHIIV_API_KEY;
+  }
+
+  async makeRequest(endpoint, options = {}) {
+    const response = await fetch(`${BEEHIIV_API_BASE}${endpoint}`, {
+      ...options,
+      headers: {
+        'Authorization': `Bearer ${this.apiKey}`,
+        'Content-Type': 'application/json',
+        ...options.headers,
+      },
+    });
+
+    if (response.status === 204) {
+      return null;
+    }
+
+    const data = await response.json();
+
+    if (!response.ok) {
+      const message = data.message || data.error || response.statusText;
+      throw new Error(`Beehiiv API error (${response.status}): ${message}`);
+    }
+
+    return data;
+  }
+
+  /** Fetch every page of a paginated collection endpoint. */
+  async getAllPages(basePath) {
+    const all = [];
+    let page = 1;
+
+    while (true) {
+      const data = await this.makeRequest(`${basePath}?page=${page}&limit=100`);
+      all.push(...(data.data || []));
+
+      if (page >= (data.total_pages || 1)) {
+        break;
+      }
+      page += 1;
+    }
+
+    return all;
+  }
+
+  // ========== Publications ==========
+
+  async getPublication(publicationId) {
+    try {
+      const data = await this.makeRequest(`/publications/${publicationId}`);
+      return data.data;
+    } catch (error) {
+      if (error.message.includes('404') || error.message.includes('not found')) {
+        return null;
+      }
+      throw error;
+    }
+  }
+
+  async listPublications() {
+    const data = await this.makeRequest('/publications');
+    return data.data || [];
+  }
+
+  // ========== Custom fields ==========
+
+  async getCustomFields(publicationId) {
+    return this.getAllPages(`/publications/${publicationId}/custom_fields`);
+  }
+
+  /** kind: 'string' | 'integer' | 'boolean' | 'datetime' */
+  async createCustomField(publicationId, name, display, kind) {
+    return this.makeRequest(`/publications/${publicationId}/custom_fields`, {
+      method: 'POST',
+      body: JSON.stringify({ name, display, kind }),
+    });
+  }
+
+  async deleteCustomField(publicationId, fieldId) {
+    return this.makeRequest(`/publications/${publicationId}/custom_fields/${fieldId}`, {
+      method: 'DELETE',
+    });
+  }
+
+  // ========== Segments (list-only — Beehiiv has no create API) ==========
+
+  async getSegments(publicationId) {
+    return this.getAllPages(`/publications/${publicationId}/segments`);
+  }
+
+  // ========== Webhooks (per-publication) ==========
+
+  async listWebhooks(publicationId) {
+    return this.getAllPages(`/publications/${publicationId}/webhooks`);
+  }
+
+  /** payload: { url, event_types[], description?, http_method? } */
+  async createWebhook(publicationId, payload) {
+    return this.makeRequest(`/publications/${publicationId}/webhooks`, {
+      method: 'POST',
+      body: JSON.stringify(payload),
+    });
+  }
+
+  async updateWebhook(publicationId, webhookId, payload) {
+    return this.makeRequest(`/publications/${publicationId}/webhooks/${webhookId}`, {
+      method: 'PATCH',
+      body: JSON.stringify(payload),
+    });
+  }
+}
+
+module.exports = { BeehiivAPI };