@omega.js/manager 0.1.0

package/dist/services/advertising/ensure/sites.js

@@ -0,0 +1,101 @@
+/**
+ * Ensure the brand's domain is present in AdSense and report its approval
+ * state.
+ *
+ * The Management API v2 has no writes, so presence with a READY state is the
+ * converged proof and everything else is guidance: missing → interactive runs
+ * open the add-site console page and poll until the site appears,
+ * non-interactive/dry runs warn with the deep-link (rerun converges once it
+ * appears); non-READY → warned with what Google is waiting on.
+ */
+const chalk = require('chalk').default;
+const { openBrowserAndPoll } = require('../../../vendor/devkit/flows.js');
+const { canPrompt } = require('../../../lib/run-gates.js');
+
+// AdSense site approval states → run status + operator guidance
+const STATES = {
+  READY: { status: 'success', label: 'Ready (serving ads)' },
+  GETTING_READY: { status: 'warned', label: 'Getting ready — Google is reviewing the site; rerun once approved' },
+  REQUIRES_REVIEW: { status: 'warned', label: 'Requires review — request one in the AdSense console' },
+  NEEDS_ATTENTION: { status: 'warned', label: 'Needs attention — resolve the issues in the AdSense console' },
+};
+
+module.exports = async function ensureSites(context) {
+  const { adsenseApi, accountId, domain, options = {} } = context;
+
+  const sitesUrl = `https://adsense.google.com/adsense/u/0/${accountId}/sites/list?url=${domain}`;
+  // AdSense lists sites at the apex only, so an apex entry covers every
+  // subdomain of it (#631)
+  const matchesDomain = (entry) => entry.domain === domain || entry.domain === `www.${domain}` || domain.endsWith(`.${entry.domain}`);
+
+  const sites = await adsenseApi.listSites(accountId);
+  const site = sites.find(matchesDomain);
+
+  if (site) {
+    return reportSite(site, sitesUrl, domain);
+  }
+
+  console.log(`      ${chalk.yellow('⚠')} ${chalk.cyan(domain)} is not added to AdSense ${chalk.dim('(no API exists to add it)')}`);
+
+  // Interactive runs open the add-site page and poll until it appears
+  if (canPrompt(options)) {
+    const result = await openBrowserAndPoll({
+      url: sitesUrl,
+      label: 'the AdSense sites page',
+      promptMessage: `Add ${chalk.cyan(domain)} as a site in the AdSense console.`,
+      waitMessage: 'Waiting for the site to appear',
+      check: async () => {
+        const fresh = (await adsenseApi.listSites(accountId)).find(matchesDomain);
+        return fresh ? { done: true, result: fresh } : { done: false };
+      },
+      intervalMs: 5000,
+      indent: '        ',
+    });
+
+    if (result.success && result.result) {
+      return reportSite(result.result, sitesUrl, domain);
+    }
+  }
+
+  console.log(`      ${chalk.dim('→')} Add the site at: ${chalk.cyan(sitesUrl)}`);
+  console.log(`      ${chalk.dim('→')} (rerun converges once it appears)`);
+  return { status: 'warned', reason: 'site not added yet — add it in the AdSense console', output: { sites: { domain, state: null, addUrl: sitesUrl } } };
+};
+
+/**
+ * Report a present site's approval state (READY = success, anything else =
+ * warned with the console deep-link). A parent-domain match reports the
+ * apex's state and says so (#631).
+ */
+function reportSite(site, sitesUrl, domain) {
+  const state = site.state || 'STATE_UNSPECIFIED';
+  const display = STATES[state] || { status: 'warned', label: state };
+  const covered = site.domain !== domain && domain.endsWith(`.${site.domain}`);
+  const subject = covered
+    ? `${chalk.cyan(domain)} is covered by ${chalk.cyan(site.domain)}`
+    : chalk.cyan(site.domain);
+
+  if (display.status === 'success') {
+    console.log(`      ${chalk.green('✓')} ${subject}: ${display.label}`);
+  } else {
+    console.log(`      ${chalk.yellow('⚠')} ${subject}: ${display.label}`);
+    console.log(`      ${chalk.dim('→')} ${chalk.cyan(sitesUrl)}`);
+  }
+
+  if (site.autoAdsEnabled !== undefined) {
+    console.log(`      ${chalk.dim('→')} Auto ads: ${site.autoAdsEnabled ? 'enabled' : 'disabled'}`);
+  }
+
+  return {
+    status: display.status,
+    ...(display.status === 'warned' ? { reason: display.label } : {}),
+    output: {
+      sites: {
+        domain: site.domain,
+        state,
+        autoAdsEnabled: site.autoAdsEnabled,
+        ...(covered ? { coveredBy: site.domain } : {}),
+      },
+    },
+  };
+}

package/dist/services/advertising/index.js

@@ -0,0 +1,101 @@
+/**
+ * Advertising service — verifies the brand's domain is added to the
+ * configured AdSense account and reports its approval state.
+ *
+ * The Management API v2 is read-only (sites can't be added or configured
+ * programmatically), so this service proves presence + state and deep-links
+ * the console for the manual half; interactive runs open the add-site page
+ * and poll until the site appears. Never mutates AdSense — dry-run is
+ * identical to a normal run.
+ *
+ * Config home: `advertising.providers.adsense` (the provider-neutral
+ * advertising section — never a brand-named top-level key). `client`
+ * (ca-pub-…) is required config; the API accountId is the same id without
+ * the `ca-` prefix. omega-manager defaulted the account to the company's
+ * shared one (company-level config supplies that now). Interactive runs
+ * offer the account selection flow when it's missing (create-new opens the
+ * AdSense signup) and land it in omega.json5.
+ * Auth: GOOGLE_CLIENT_ID + GOOGLE_CLIENT_SECRET in the brand .env
+ * (adsense.readonly scope, own token cache).
+ */
+const { serviceInputSpec } = require('../../config.js');
+const { googleTokenStorePath } = require('../../lib/google-auth.js');
+const { createServiceRunner } = require('../../lib/service-runner.js');
+const { requestServiceInput } = require('../../lib/service-input.js');
+const { GoogleAdsenseAPI } = require('./lib/adsense-api.js');
+const { resolveConfigValue } = require('../../lib/config-flow.js');
+
+const CREATE_ACCOUNT_URL = 'https://adsense.google.com/start/';
+
+module.exports.run = createServiceRunner({
+  serviceDir: __dirname,
+  setup: async (context) => {
+    // No provider entry = deliberate absence — never resolve or write back an
+    // account the brand didn't opt into (wave-5 F10; authoring
+    // `advertising: { providers: { adsense: {} } }` opts in).
+    const provider = context.brandConfig.advertising?.providers?.adsense;
+    if (!provider) {
+      return { skip: true, reason: 'no advertising.providers.adsense section in omega.json5 (author it — even empty — to opt in)' };
+    }
+
+    const domain = (context.brandConfig.brand?.url || '').replace(/^https?:\/\//, '').replace(/\/$/, '');
+    if (!domain) {
+      return { skip: true, reason: 'no brand.url configured' };
+    }
+
+    // The shared setup contract (#608): ask for the Google OAuth client right
+    // here — provide, skip this run, or disable AdSense for good.
+    let gate = null;
+    if (!context.adsenseApi) {
+      gate = await requestServiceInput(context, serviceInputSpec('advertising'));
+    }
+    const haveCreds = Boolean(
+      context.adsenseApi
+      || (process.env.GOOGLE_CLIENT_ID && process.env.GOOGLE_CLIENT_SECRET),
+    );
+
+    // Tests inject a fake client via context.adsenseApi
+    const makeApi = () => context.adsenseApi || new GoogleAdsenseAPI({
+      tokenStorePath: googleTokenStorePath(context.brandRoot),
+    });
+
+    // Missing client id → offer the interactive selection flow (lands in
+    // omega.json5); needs credentials. The Management API wants the bare
+    // pub-… account id — `client` carries the embed-ready ca-pub-… form.
+    let client = provider.client;
+    if (!client && haveCreds) {
+      const flowApi = makeApi();
+      client = await resolveConfigValue(context, {
+        path: 'advertising.providers.adsense.client',
+        // Disable must NOT land `client: false` — client is schema-typed as a
+        // string and the config would hard-fail validation forever. It opts
+        // the PROVIDER out instead (the chatsy/slapform shape): a falsy
+        // provider entry is the deliberate-absence skip above, and there is no
+        // second `enabled` switch to land it on since #527.
+        disablePath: 'advertising.providers.adsense',
+        label: 'AdSense account',
+        choices: () => flowApi.listAccounts(),
+        getName: (account) => {
+          const id = account.name.replace('accounts/', '');
+          return `${account.displayName || id} (${id})`;
+        },
+        getValue: (account) => `ca-${account.name.replace('accounts/', '')}`,
+        createNew: { label: 'account', url: CREATE_ACCOUNT_URL, refreshChoices: true },
+      });
+    }
+    if (!client) {
+      return { skip: true, reason: 'no advertising.providers.adsense.client configured (ca-pub-… from https://adsense.google.com → Settings → Account information — or rerun interactively)' };
+    }
+    const accountId = client.replace(/^ca-/, '');
+
+    if (!haveCreds) {
+      return gate || { skip: true, reason: 'no GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET configured (set them in the brand .env)' };
+    }
+
+    return {
+      adsenseApi: makeApi(),
+      accountId,
+      domain,
+    };
+  },
+});

package/dist/services/advertising/lib/adsense-api.js

@@ -0,0 +1,41 @@
+/**
+ * Google AdSense Management API v2 client — read-only by design (the API has
+ * no site-management writes at all; the `adsense.readonly` scope makes that
+ * explicit). Named-method surface over the shared GoogleOAuth2Client so
+ * tests can fake it method-for-method.
+ *
+ * Auth: GOOGLE_CLIENT_ID + GOOGLE_CLIENT_SECRET in the brand .env; the ONE
+ * shared token store (GOOGLE_SCOPES union — one consent covers everything).
+ */
+const { GoogleOAuth2Client, GOOGLE_SCOPES } = require('../../../lib/google-auth.js');
+
+const ADSENSE_API_BASE = 'https://adsense.googleapis.com/v2';
+
+class GoogleAdsenseAPI {
+  constructor(options = {}) {
+    this.auth = new GoogleOAuth2Client({
+      clientId: options.clientId || process.env.GOOGLE_CLIENT_ID,
+      clientSecret: options.clientSecret || process.env.GOOGLE_CLIENT_SECRET,
+      tokenStorePath: options.tokenStorePath,
+      scopes: GOOGLE_SCOPES,
+    });
+  }
+
+  async makeRequest(endpoint, options = {}) {
+    return this.auth.makeRequest(`${ADSENSE_API_BASE}${endpoint}`, options);
+  }
+
+  /** AdSense accounts visible to the authed user (name: 'accounts/pub-…') */
+  async listAccounts() {
+    const data = await this.makeRequest('/accounts');
+    return data.accounts || [];
+  }
+
+  /** accountId: 'pub-…' (the accounts/ prefix already stripped) */
+  async listSites(accountId) {
+    const data = await this.makeRequest(`/accounts/${accountId}/sites`);
+    return data.sites || [];
+  }
+}
+
+module.exports = { GoogleAdsenseAPI };

package/dist/services/ai/ensure/keys.js

@@ -0,0 +1,21 @@
+/**
+ * Report which AI providers this brand can call. The setup gate already
+ * acquired what was missing (or skipped the whole service), so by here the
+ * environment IS the answer — this names it, so the run record says which
+ * providers the backend has credentials for instead of leaving it implicit.
+ *
+ * Names only: a value never reaches the log.
+ */
+const chalk = require('chalk').default;
+
+const { serviceInputSpec } = require('../../../config.js');
+
+module.exports = () => {
+  const configured = serviceInputSpec('ai').inputs
+    .filter((input) => process.env[input.name])
+    .map((input) => input.name);
+
+  console.log(`      ${chalk.green('✓')} Configured: ${chalk.cyan(configured.join(', '))}`);
+
+  return { output: { configured } };
+};

package/dist/services/ai/index.js

@@ -0,0 +1,36 @@
+/**
+ * AI service (#639) — the ONE key per AI provider, asked once.
+ *
+ * It provisions nothing: there is no AI platform API to reconcile a brand
+ * against, only two credentials the backend needs before it can call OpenAI
+ * or Anthropic (contact inference, content + newsletter generation). The
+ * legacy split — a company-wide `OMEGA_*` key beside the brand's bare one —
+ * is gone: the bare name is the only name, and a company-wide value is simply
+ * the COMPANY layer of the .env cascade under that same name.
+ *
+ * So the whole service is the shared setup contract's gate (lib/service-input.js,
+ * the server/forms/chat/email shape): a brand that wants AI pastes the keys
+ * mid-walk, a brand that does not answers Disable once (`ai.enabled: false`)
+ * and is never asked again. Both keys are OPTIONAL in the registry
+ * (`gates: false`), so preflight never gates a run on them.
+ *
+ * It runs before the delivery lane: the keys must be in the brand .env before
+ * a target's runtime env composes from it.
+ */
+const { serviceInputSpec } = require('../../config.js');
+const { createServiceRunner } = require('../../lib/service-runner.js');
+const { requestServiceInput } = require('../../lib/service-input.js');
+
+module.exports.run = createServiceRunner({
+  serviceDir: __dirname,
+  setup: async (context) => {
+    if (context.brandConfig.ai?.enabled === false) {
+      return { skip: true, reason: 'ai.enabled = false' };
+    }
+
+    const gate = await requestServiceInput(context, serviceInputSpec('ai'));
+    if (gate) return gate;
+
+    return {};
+  },
+});

package/dist/services/analytics/ensure/google-firebase-link.js

@@ -0,0 +1,230 @@
+/**
+ * Ensure the GA4 property is linked to the brand's Firebase project.
+ *
+ * Runs after the firebase service so the project exists. A property holds at
+ * most one FirebaseLink, and a Firebase project links to at most one
+ * property — so when our project is linked to the WRONG property, it's
+ * unlinked there and linked here (config is the source of truth). Links may
+ * store the project NUMBER rather than the ID; the number comes from config
+ * (cloud.config.messagingSenderId IS the project number) — no second API
+ * client needed.
+ *
+ * omega-manager retried "link still propagating" failures with blind sleeps and
+ * a Firebase-API fallback; this one WAITS on the condition instead — an
+ * interactive run polls the create until GA releases the link it just deleted
+ * (skip allowed), and only a skipped or headless run reports warned (#662).
+ *
+ * Also normalizes the stream Firebase auto-creates when linking ("Web App",
+ * often with no URI) to the naming convention — diff-gated.
+ */
+const chalk = require('chalk').default;
+const { pollWithSpinner } = require('../../../vendor/devkit/flows.js');
+const { canPrompt, dryRunPlan } = require('../../../lib/run-gates.js');
+
+// GA holds a just-deleted link for a moment before the property is free
+const LINK_RELEASE_INTERVAL_MS = 5000;
+
+module.exports = async function ensureGoogleFirebaseLink(context) {
+  const { analyticsApi: api, propertyId, brandConfig, options = {} } = context;
+
+  // Same derivation as the cloud service: ONE home (#23) — the client web
+  // config names the project (cp100)
+  const projectId = brandConfig.cloud?.config?.projectId;
+
+  if (brandConfig.cloud?.shared === true) {
+    console.log(chalk.dim('      ⊘ Shared Firebase project — the link belongs to its owning brand'));
+    return {};
+  }
+
+  if (!projectId) {
+    console.log(chalk.dim('      ⊘ No cloud.config.projectId configured — nothing to link'));
+    return {};
+  }
+
+  // Links can reference the project by ID or number
+  const projectNumber = brandConfig.cloud?.config?.messagingSenderId || null;
+  const isOurProject = (linkedProject) => linkedProject === projectId
+    || (projectNumber && linkedProject === projectNumber);
+
+  // === READ: the configured property's link ===
+  const links = await api.listFirebaseLinks(propertyId);
+
+  if (links.length > 0) {
+    const linkedProject = (links[0].project || '').replace('projects/', '');
+
+    if (isOurProject(linkedProject)) {
+      console.log(`      ${chalk.green('✓')} GA property linked to this Firebase project`);
+      const streamResult = await normalizeFirebaseStream(api, propertyId, brandConfig.brand.name, projectId, options);
+      return { output: { firebaseLink: { propertyId, linked: true, streamUpdated: streamResult } } };
+    }
+
+    // The property belongs to another project — that's not ours to break
+    console.log(`      ${chalk.yellow('⚠')} GA property ${chalk.cyan(propertyId)} is linked to a DIFFERENT Firebase project: ${chalk.cyan(linkedProject)}`);
+    console.log(`      ${chalk.dim('→')} Unlink it in GA Admin (or fix analytics.providers.google.propertyId), then rerun`);
+    return { status: 'warned', reason: `the GA property is linked to a different Firebase project (${linkedProject})`, output: { firebaseLink: { error: `property linked to different project: ${linkedProject}` } } };
+  }
+
+  // === No link on our property — find where (if anywhere) our project is linked ===
+  console.log(`      ${chalk.dim('→')} No link on property ${chalk.cyan(propertyId)} — searching all GA properties...`);
+  const elsewhere = await findExistingLink(api, isOurProject, propertyId);
+
+  if (options.dryRun) {
+    const plannedActions = elsewhere
+      ? [`unlink from property ${elsewhere.propertyId}`, `link to property ${propertyId}`]
+      : [`link to property ${propertyId}`];
+    return dryRunPlan(`${plannedActions.join(', then ')}`, { output: { firebaseLink: { planned: plannedActions } } });
+  }
+
+  if (elsewhere) {
+    console.log(`      ${chalk.yellow('⚠')} Firebase project is linked to the wrong GA property ${chalk.cyan(elsewhere.propertyId)} — unlinking...`);
+    await api.deleteFirebaseLink(elsewhere.propertyId, elsewhere.linkId);
+    console.log(`      ${chalk.green('✓')} Unlinked from property ${chalk.cyan(elsewhere.propertyId)}`);
+  }
+
+  // === WRITE: create the link (a just-deleted link can take a moment to
+  // release — GA answers with a precondition failure; the create is retried
+  // in THIS walk rather than left to a rerun, #662) ===
+  console.log(`      ${chalk.dim('→')} Linking GA property ${chalk.cyan(propertyId)} to Firebase project ${chalk.cyan(projectId)}...`);
+  let link;
+  try {
+    link = await api.createFirebaseLink(propertyId, projectId);
+  } catch (error) {
+    if (!isLinkNotReady(error)) {
+      throw error;
+    }
+
+    console.log(`      ${chalk.yellow('⚠')} Link not ready yet${chalk.dim(`: ${error.message}`)}`);
+    link = canPrompt(options) ? await waitForLink(api, propertyId, projectId) : null;
+
+    if (!link) {
+      console.log(`      ${chalk.dim('→')} Still not ready — rerun in a minute`);
+      return { status: 'warned', reason: 'the Firebase link is not ready yet — rerun in a minute', output: { firebaseLink: { error: error.message } } };
+    }
+  }
+
+  console.log(`      ${chalk.green('✓')} Created Firebase link`);
+
+  const streamResult = await normalizeFirebaseStream(api, propertyId, brandConfig.brand.name, projectId, options);
+
+  return { output: { firebaseLink: { propertyId, linked: true, linkName: link.name || null, streamUpdated: streamResult } } };
+};
+
+/** GA's answer while a just-deleted link still holds the property. */
+function isLinkNotReady(error) {
+  return error.message.includes('Precondition') || error.message.includes('already linked');
+}
+
+/**
+ * Retry the create until GA releases the deleted link (ENTER checks now, `s`
+ * skips). Any OTHER error is the caller's to throw — a poll must not turn a
+ * real failure into a wait.
+ *
+ * @returns {Promise<object|null>} - The created link, or null when the wait
+ *   was skipped.
+ */
+async function waitForLink(api, propertyId, projectId) {
+  let fatal = null;
+
+  const result = await pollWithSpinner({
+    check: async () => {
+      try {
+        return { done: true, result: await api.createFirebaseLink(propertyId, projectId) };
+      } catch (error) {
+        if (isLinkNotReady(error)) {
+          return { done: false };
+        }
+        fatal = error;
+        return { done: true, error: error.message };
+      }
+    },
+    intervalMs: LINK_RELEASE_INTERVAL_MS,
+    message: 'Waiting for GA to release the previous Firebase link',
+    indent: '      ',
+  });
+
+  if (fatal) {
+    throw fatal;
+  }
+
+  return result.success ? result.result : null;
+}
+
+/**
+ * Search every accessible account/property for a FirebaseLink pointing at
+ * our project (skipping the target property, already known to be linkless).
+ *
+ * @returns {Object|null} - { propertyId, linkId } or null
+ */
+async function findExistingLink(api, isOurProject, targetPropertyId) {
+  const accounts = await api.listAccounts();
+
+  for (const account of accounts) {
+    const properties = await api.listProperties(account.name.replace('accounts/', ''));
+
+    for (const property of properties) {
+      const propId = property.name.replace('properties/', '');
+      if (propId === targetPropertyId) {
+        continue;
+      }
+
+      const links = await api.listFirebaseLinks(propId);
+      const ours = links.find((link) => isOurProject((link.project || '').replace('projects/', '')));
+      if (ours) {
+        console.log(`      ${chalk.dim('→')} Found: linked to property ${chalk.cyan(propId)} (${property.displayName})`);
+        return { propertyId: propId, linkId: ours.name.split('/').pop() };
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Normalize the stream Firebase auto-creates when linking: rename "Web App"
+ * to "{Brand} - Firebase" and set the URI when missing. Diff-gated; a
+ * correct stream is untouched.
+ */
+async function normalizeFirebaseStream(api, propertyId, brandName, projectId, options) {
+  const streams = await api.listDataStreams(propertyId);
+  const expectedName = `${brandName} - Firebase`;
+
+  const stream = streams.find((s) => {
+    const uri = s.webStreamData?.defaultUri || '';
+    return s.displayName === 'Web App'
+      || s.displayName === expectedName
+      || uri.includes('.firebaseapp.com')
+      || uri.includes('.web.app');
+  });
+
+  if (!stream) {
+    return null;
+  }
+
+  const streamId = stream.name.split('/').pop();
+  const needsRename = stream.displayName !== expectedName;
+  const needsUri = !stream.webStreamData?.defaultUri;
+
+  if (!needsRename && !needsUri) {
+    return { alreadyCorrect: true, streamId };
+  }
+
+  if (options.dryRun) {
+    return { planned: { renamed: needsRename, uriSet: needsUri }, streamId };
+  }
+
+  const updates = {};
+  const updateMaskFields = [];
+  if (needsRename) {
+    updates.displayName = expectedName;
+    updateMaskFields.push('displayName');
+  }
+  if (needsUri) {
+    updates.webStreamData = { defaultUri: `https://${projectId}.firebaseapp.com` };
+    updateMaskFields.push('webStreamData.defaultUri');
+  }
+
+  await api.updateDataStream(propertyId, streamId, updates, updateMaskFields);
+  console.log(`      ${chalk.green('✓')} Normalized the Firebase stream${needsRename ? ` ("${stream.displayName}" → "${expectedName}")` : ''}`);
+
+  return { updated: true, streamId, renamed: needsRename, uriSet: needsUri };
+}