@omega.js/manager 0.1.0

package/dist/services/analytics/ensure/google-streams.js

@@ -0,0 +1,256 @@
+/**
+ * Ensure one GA4 web data stream per enabled target.
+ *
+ * Streams are found by URI (the source of truth — each target gets a unique
+ * subdomain of the brand domain, virtual for app targets): create when
+ * missing, rename on displayName drift, enhanced measurement DIFFED before
+ * patching (omega-manager blind-PATCHed it every run), and a clean
+ * Measurement Protocol secret per stream (no dashes/underscores — regenerated
+ * until clean). Every value is re-resolved from GA on each run — the stream
+ * ids and URIs are pure derivation, so nothing about them is persisted.
+ *
+ * GA's "User Data Collection Acknowledgement" gate on secret creation has no
+ * API — interactive runs open the settings page (Enter-gated, house rule)
+ * and retry-poll until the acknowledgement lands, so ONE run finishes the
+ * job; non-interactive runs warn with the URL and the rerun converges.
+ * Acknowledging is per-property, so the first stream's prompt clears the
+ * gate for every stream after it.
+ *
+ * The two halves land in their two homes as they resolve. Each stream's
+ * measurement ID goes to CONFIG, at
+ * `targets.{target}.analytics.providers.google.id` — the per-surface
+ * override every framework reads through the merge chain, the same shape the
+ * monitoring service uses for its per-target DSNs (#417). Each stream's
+ * Measurement Protocol secret goes to the brand .env, under
+ * `GOOGLE_ANALYTICS_SECRET_{TARGET}` (#434) — the delivery step composes it
+ * into each target's runtime env as GOOGLE_ANALYTICS_SECRET, so the pair
+ * travels together.
+ */
+const chalk = require('chalk').default;
+const { pressEnterToOpen } = require('../../../vendor/devkit/prompt.js');
+const { pollWithSpinner } = require('../../../vendor/devkit/flows.js');
+const { writeBrandConfig } = require('../../../lib/config-write.js');
+const { writeEnvValue } = require('../../../lib/env-secret.js');
+const { streamSecretEnvName } = require('../../../lib/analytics-secret.js');
+const { canPrompt, dryRunPlan } = require('../../../lib/run-gates.js');
+
+// target → stream URI subdomain (null = the root domain) + display name.
+// Subdomains for app targets are virtual — they exist only to give each
+// target a distinct stream URI. Unlisted targets default to their own name.
+const STREAM_TARGETS = {
+  web: { displayName: 'Website', subdomain: null },
+  backend: { displayName: 'Backend', subdomain: 'api' },
+  desktop: { displayName: 'Desktop App', subdomain: 'desktop' },
+  extension: { displayName: 'Browser Extension', subdomain: 'extension' },
+  mobile: { displayName: 'Mobile App', subdomain: 'mobile' },
+};
+
+const SECRET_NAME = 'Secret';
+const MAX_SECRET_ATTEMPTS = 20;
+
+// Secrets get embedded in .env files and URLs downstream — dashes and
+// underscores have burned enough tooling that omega-manager regenerated
+// until the value was clean; the port keeps that rule
+function isCleanSecret(secret) {
+  return !secret.includes('-') && !secret.includes('_');
+}
+
+module.exports = async function ensureGoogleStreams(context) {
+  const { analyticsApi: api, propertyId, accountId, domain, brand, brandConfig, brandRoot, options = {} } = context;
+
+  // Config drift check: a propertyId pointing at a deleted/inaccessible
+  // property should say so instead of erroring cryptically per stream
+  const property = await api.getProperty(propertyId);
+  if (!property) {
+    console.log(`      ${chalk.yellow('⚠')} GA property ${chalk.cyan(propertyId)} not found (deleted, or the authed account has no access)`);
+    return { status: 'warned', reason: `GA property ${propertyId} not found`, output: { streams: { error: `property ${propertyId} not found` } } };
+  }
+
+  const existing = await api.listDataStreams(propertyId);
+  console.log(`      ${chalk.dim('→')} Property ${chalk.cyan(propertyId)}: ${existing.length} existing stream(s)`);
+
+  const enhancedMeasurement = brandConfig.analytics?.providers?.google?.enhancedMeasurement || {};
+
+  const streams = {};
+  // What warned, by name (#643) — joined into the operation's reason
+  const warnings = [];
+  const planned = [];
+  const configEdits = {};
+
+  for (const target of brand.enabledTargets) {
+    const spec = STREAM_TARGETS[target] || { displayName: target, subdomain: target };
+    const uri = spec.subdomain ? `https://${spec.subdomain}.${domain}` : `https://${domain}`;
+    const displayName = `${brandConfig.brand.name} - ${spec.displayName}`;
+
+    let stream = existing.find((s) => s.type === 'WEB_DATA_STREAM' && s.webStreamData?.defaultUri === uri);
+
+    if (!stream) {
+      if (options.dryRun) {
+        dryRunPlan(`create ${target} stream (${uri})`);
+        planned.push({ target, action: 'create', uri });
+        continue;
+      }
+      console.log(`      ${chalk.dim('→')} Creating ${chalk.cyan(target)} stream (${uri})...`);
+      stream = await api.createWebDataStream(propertyId, { defaultUri: uri, displayName });
+      console.log(`      ${chalk.green('✓')} ${chalk.cyan(target)}: created`);
+    } else {
+      console.log(`      ${chalk.green('✓')} ${chalk.cyan(target)}: found by URI`);
+    }
+
+    const streamId = stream.name.split('/').pop();
+
+    // Rename on drift only
+    if (stream.displayName !== displayName) {
+      if (options.dryRun) {
+        planned.push({ target, action: 'rename', to: displayName });
+      } else {
+        await api.updateDataStream(propertyId, streamId, { displayName });
+        console.log(`        ${chalk.green('✓')} Renamed to "${chalk.cyan(displayName)}"`);
+      }
+    }
+
+    // Enhanced measurement — diff the configured keys against the live
+    // settings; omega-manager PATCHed unconditionally on every run
+    if (Object.keys(enhancedMeasurement).length > 0) {
+      const current = await api.getEnhancedMeasurementSettings(propertyId, streamId);
+      const drifted = Object.keys(enhancedMeasurement)
+        .filter((key) => current?.[key] !== enhancedMeasurement[key]);
+      if (drifted.length > 0) {
+        if (options.dryRun) {
+          planned.push({ target, action: 'enhanced-measurement', drifted });
+        } else {
+          await api.updateEnhancedMeasurementSettings(propertyId, streamId, enhancedMeasurement);
+          console.log(`        ${chalk.green('✓')} Enhanced measurement updated (${drifted.join(', ')})`);
+        }
+      }
+    }
+
+    // Measurement Protocol secret — the brand .env holds the last resolved
+    // value, so a failed listing below degrades to it instead of to nothing
+    const secretEnvName = streamSecretEnvName(target);
+    let apiSecret = process.env[secretEnvName] || null;
+    try {
+      const secrets = await api.listMeasurementProtocolSecrets(propertyId, streamId);
+      const found = secrets.find((s) => s.displayName === SECRET_NAME);
+
+      if (found && isCleanSecret(found.secretValue)) {
+        apiSecret = found.secretValue;
+      } else if (options.dryRun) {
+        planned.push({ target, action: found ? 'replace-unclean-secret' : 'create-secret' });
+      } else {
+        if (found) {
+          await api.deleteMeasurementProtocolSecret(propertyId, streamId, found.name.split('/').pop());
+          console.log(`        ${chalk.dim('↻')} Deleted unclean secret`);
+        }
+        apiSecret = await createCleanSecret(api, propertyId, streamId);
+        if (apiSecret) {
+          console.log(`        ${chalk.green('✓')} API secret created`);
+        } else {
+          console.log(`        ${chalk.yellow('⚠')} Could not generate a clean secret in ${MAX_SECRET_ATTEMPTS} attempts`);
+          warnings.push('could not generate a clean API secret');
+        }
+      }
+    } catch (error) {
+      if (error.message.includes('User Data Collection Acknowledgement')) {
+        // No API for the acknowledgement — point at the stream settings page
+        // (the account-scoped deep link needs accountId; fall back to the app)
+        const settingsUrl = accountId
+          ? `https://analytics.google.com/analytics/web/#/a${accountId}p${propertyId}/admin/streams/table/${streamId}`
+          : 'https://analytics.google.com/analytics/web/';
+        console.log(`        ${chalk.yellow('⚠')} Data collection acknowledgement required before secrets can be created`);
+
+        if (canPrompt(options)) {
+          await pressEnterToOpen(settingsUrl, 'the data-collection acknowledgement page');
+          const poll = await pollWithSpinner({
+            check: async () => {
+              try {
+                const secret = await createCleanSecret(api, propertyId, streamId);
+                return { done: true, result: secret };
+              } catch (retryError) {
+                if (retryError.message.includes('User Data Collection Acknowledgement')) {
+                  return { done: false };
+                }
+                return { done: true, error: retryError.message };
+              }
+            },
+            intervalMs: 5000,
+            message: 'Waiting for the acknowledgement',
+          });
+
+          if (poll.success && poll.result) {
+            apiSecret = poll.result;
+            console.log(`        ${chalk.green('✓')} API secret created`);
+          } else {
+            console.log(`        ${chalk.dim('→')} Still gated${poll.error ? chalk.dim(` (${poll.error})`) : ''} — rerun converges once acknowledged`);
+            warnings.push('API secret still gated — acknowledge it in the GA console');
+          }
+        } else {
+          console.log(`        ${chalk.dim('→')} Acknowledge at: ${chalk.cyan(settingsUrl)} — then rerun`);
+          warnings.push('API secret still gated — acknowledge it in the GA console');
+        }
+      } else {
+        console.log(`        ${chalk.yellow('⚠')} API secret${chalk.dim(`: ${error.message}`)}`);
+        warnings.push('could not read or create the API secret');
+      }
+    }
+
+    const measurementId = stream.webStreamData?.measurementId || null;
+
+    streams[target] = { streamId, measurementId };
+
+    // The resolved measurement id always wins — a hand-set stale value is
+    // drift and gets patched (the monitoring service's DSN rule)
+    if (measurementId && brandConfig.targets?.[target]?.analytics?.providers?.google?.id !== measurementId) {
+      configEdits[`targets.${target}.analytics.providers.google.id`] = measurementId;
+    }
+
+    // The secret's home is the brand .env — written only on drift, so a
+    // converged rerun leaves the file alone
+    if (apiSecret && !options.dryRun && process.env[secretEnvName] !== apiSecret) {
+      writeEnvValue(brandRoot, secretEnvName, apiSecret);
+      process.env[secretEnvName] = apiSecret;
+      console.log(`        ${chalk.green('✓')} .env ← ${chalk.cyan(secretEnvName)}`);
+    }
+  }
+
+  // Only touch omega.json5 when something actually drifted — a converged
+  // brand never opens the file
+  if (Object.keys(configEdits).length > 0) {
+    writeBrandConfig(context, configEdits);
+  }
+
+  // A Firebase web app measures through its OWN measurementId — if this GA
+  // property has no stream carrying it, Firebase is linked to a different
+  // property (expected for shared projects, a real misconfig otherwise)
+  const firebaseMeasurementId = brandConfig.cloud?.config?.measurementId;
+  if (firebaseMeasurementId && brandConfig.cloud?.shared !== true) {
+    const covered = existing.some((s) => s.webStreamData?.measurementId === firebaseMeasurementId)
+      || Object.values(streams).some((s) => s.measurementId === firebaseMeasurementId);
+    if (!covered) {
+      console.log(`      ${chalk.yellow('⚠')} Firebase SDK measures via ${chalk.cyan(firebaseMeasurementId)}, but property ${chalk.cyan(propertyId)} has no stream with that ID`);
+      console.log(`      ${chalk.dim('→')} Firebase is likely linked to a different GA property — unlink in Firebase Console and rerun`);
+      warnings.push('the Firebase measurement ID has no stream on this property');
+    }
+  }
+
+  const result = { output: { streams: { resolved: streams } } };
+  if (planned.length > 0) {
+    result.output.streams.planned = planned;
+  }
+  if (warnings.length > 0) {
+    result.status = 'warned';
+    result.reason = warnings.join('; ');
+  }
+  return result;
+};
+
+async function createCleanSecret(api, propertyId, streamId) {
+  for (let attempt = 1; attempt <= MAX_SECRET_ATTEMPTS; attempt++) {
+    const created = await api.createMeasurementProtocolSecret(propertyId, streamId, SECRET_NAME);
+    if (isCleanSecret(created.secretValue)) {
+      return created.secretValue;
+    }
+    await api.deleteMeasurementProtocolSecret(propertyId, streamId, created.name.split('/').pop());
+  }
+  return null;
+}

package/dist/services/analytics/ensure/meta-pixel.js

@@ -0,0 +1,22 @@
+/**
+ * Ensure the Meta Pixel EXISTS and is configured with a Conversions API
+ * access token (META_ACCESS_TOKEN in the brand .env — the name
+ * @omega.js/backend reads, and the same system-user token the Marketing API
+ * create authenticates with).
+ *
+ * Near-zero input (#417, Ian 2026-08-21): one interactive pass acquires the
+ * token (Enter-gated open of the system-users page, then a paste-in),
+ * discovers the ad account that token can see (auto-selected when there's
+ * exactly one, landed in `analytics.providers.meta.accountId`), creates the
+ * pixel on it, and lands its id — so a brand configures Meta by saying Yes.
+ * `analytics.providers.meta: false` turns the whole thing off.
+ */
+const { ensurePixelToken } = require('../lib/pixel-token.js');
+const { provisionPixel } = require('../lib/pixel-provision.js');
+const { META_PIXEL } = require('../lib/pixel-specs.js');
+
+module.exports = async function ensureMetaPixel(context) {
+  const ended = await provisionPixel(context, META_PIXEL);
+
+  return ended || ensurePixelToken(context, META_PIXEL);
+};

package/dist/services/analytics/ensure/tiktok-pixel.js

@@ -0,0 +1,22 @@
+/**
+ * Ensure the TikTok Pixel EXISTS (created on `analytics.providers.tiktok
+ * .accountId` — the advertiser account — when config has no id yet) and is
+ * configured with an Events API access token (TIKTOK_ACCESS_TOKEN in the
+ * brand .env — the name @omega.js/backend reads, and the same token the
+ * Business API create authenticates with).
+ *
+ * SCAFFOLD (#417, Ian 2026-08-21): the wiring is complete and the token is
+ * the gate, but TikTok's side is not provisioned — no brand carries the key,
+ * so the create path has never run against the live API and this pass always
+ * ends at the warned where-to-get guidance. lib/tiktok-api.js carries the
+ * call shapes it will use on the first real run.
+ */
+const { ensurePixelToken } = require('../lib/pixel-token.js');
+const { provisionPixel } = require('../lib/pixel-provision.js');
+const { TIKTOK_PIXEL } = require('../lib/pixel-specs.js');
+
+module.exports = async function ensureTikTokPixel(context) {
+  const ended = await provisionPixel(context, TIKTOK_PIXEL);
+
+  return ended || ensurePixelToken(context, TIKTOK_PIXEL);
+};

package/dist/services/analytics/index.js

@@ -0,0 +1,134 @@
+/**
+ * Analytics service — reconciles the brand's analytics providers to
+ * `analytics: {}` in omega.json5: one GA4 web data stream per enabled target
+ * (with enhanced measurement + a Measurement Protocol secret each), the
+ * GA property ↔ Firebase project link, and the Meta/TikTok pixels — created
+ * on their ad account when config has no id yet (#417), then checked for
+ * their access token.
+ *
+ * Google auth: GOOGLE_CLIENT_ID + GOOGLE_CLIENT_SECRET in the brand .env
+ * (OAuth2; tokens cache to .omega/auth/google-analytics-tokens.json — the
+ * analytics.edit scope is separate from the cloud service's tokens).
+ * The GA4 property itself is required config (`analytics.providers.google.
+ * propertyId`): interactive runs offer the account + property
+ * selection/creation flow (lib/property-flow.js) and land the ids in
+ * omega.json5. Without a propertyId (non-interactive/skipped)
+ * or without Google credentials the two google operations are filtered out.
+ *
+ * Pixel auth: META_ACCESS_TOKEN / TIKTOK_ACCESS_TOKEN in the brand .env (the
+ * names @omega.js/backend reads — one token per platform serves both the
+ * create and the conversions sender). A pixel operation runs whenever its
+ * provider has an id (token check) or an accountId to create under, and —
+ * Meta, whose token names its own ad accounts — whenever the token is in hand
+ * or the run can ask for one (lib/pixel-provision.js hasPixelWork). A missing
+ * token warns with guidance and never fails; `analytics.providers.{provider}:
+ * false` disables the provider and stops every ask.
+ */
+const { serviceInputSpec } = require('../../config.js');
+const { googleTokenStorePath } = require('../../lib/google-auth.js');
+const chalk = require('chalk').default;
+const { createServiceRunner } = require('../../lib/service-runner.js');
+const { requestServiceInput } = require('../../lib/service-input.js');
+const { GoogleAnalyticsAPI } = require('./lib/analytics-api.js');
+const { MetaMarketingAPI } = require('./lib/meta-api.js');
+const { TikTokBusinessAPI } = require('./lib/tiktok-api.js');
+const { resolveGoogleProperty } = require('./lib/property-flow.js');
+const { hasPixelWork } = require('./lib/pixel-provision.js');
+const { META_PIXEL, TIKTOK_PIXEL } = require('./lib/pixel-specs.js');
+
+// Operations that need the GA Admin API (and therefore propertyId + creds)
+const GOOGLE_OPERATIONS = new Set(['google-streams', 'google-firebase-link']);
+
+module.exports.run = createServiceRunner({
+  serviceDir: __dirname,
+  setup: async (context) => {
+    const analytics = context.brandConfig.analytics || {};
+
+    if (analytics.enabled === false) {
+      return { skip: true, reason: 'analytics.enabled = false' };
+    }
+
+    const domain = (context.brandConfig.brand?.url || '').replace(/^https?:\/\//, '').replace(/\/$/, '');
+    if (!domain) {
+      return { skip: true, reason: 'no brand.url configured' };
+    }
+
+    // The shared setup contract (#608) for the GOOGLE half only, and only
+    // once the brand has DECLARED it wants GA4 (a configured propertyId — the
+    // same gate REQUIRES.analytics.when reads): the pixel tokens are optional
+    // beside it and each pixel operation asks for its own in place
+    // (lib/pixel-token.js), so a pixel-only brand is never asked for a Google
+    // credential it has no use for.
+    if (!context.analyticsApi && analytics.providers?.google?.propertyId) {
+      await requestServiceInput(context, serviceInputSpec('analytics', {
+        names: ['GOOGLE_CLIENT_ID', 'GOOGLE_CLIENT_SECRET'],
+        label: 'Google Analytics',
+      }));
+    }
+
+    const haveGoogleAuth = Boolean(
+      context.analyticsApi
+      || (process.env.GOOGLE_CLIENT_ID && process.env.GOOGLE_CLIENT_SECRET),
+    );
+
+    // Missing property + creds available → offer the interactive account +
+    // property selection/creation flow (lands both ids in omega.json5, and
+    // in the in-memory config re-read just below)
+    if (!analytics.providers?.google?.propertyId && haveGoogleAuth) {
+      const flowApi = context.analyticsApi || new GoogleAnalyticsAPI({
+        tokenStorePath: googleTokenStorePath(context.brandRoot),
+      });
+      await resolveGoogleProperty(context, flowApi);
+    }
+
+    const providers = context.brandConfig.analytics?.providers || {};
+    const google = providers.google || {};
+    const meta = providers.meta || {};
+    const tiktok = providers.tiktok || {};
+
+    // A pixel half has work when its id is configured (token check), an
+    // account id names where to create it, or — Meta — a token in hand (or an
+    // interactive run that can ask for one) can discover the account itself
+    const metaWork = hasPixelWork(context.brandConfig, META_PIXEL, context.options);
+    const tiktokWork = hasPixelWork(context.brandConfig, TIKTOK_PIXEL, context.options);
+    const havePixelWork = metaWork || tiktokWork;
+
+    if (!google.propertyId && !havePixelWork) {
+      return { skip: true, reason: 'no analytics providers configured (analytics.providers.google.propertyId / meta.{id,accountId} / tiktok.{id,accountId})' };
+    }
+
+    // Decide whether the google operations can run this pass
+    let operations = context.operations;
+    if (!google.propertyId) {
+      console.log(chalk.dim('    ⊘ google operations skipped — no analytics.providers.google.propertyId (rerun interactively to select/create the property)'));
+      operations = operations.filter((op) => !GOOGLE_OPERATIONS.has(op.name));
+    } else if (!haveGoogleAuth) {
+      if (!havePixelWork) {
+        return { skip: true, reason: 'no GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET configured (set them in the brand .env)' };
+      }
+      console.log(chalk.dim('    ⊘ google operations skipped — no GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET in the brand .env'));
+      operations = operations.filter((op) => !GOOGLE_OPERATIONS.has(op.name));
+    }
+
+    const needsGoogleApi = operations.some((op) => GOOGLE_OPERATIONS.has(op.name));
+
+    // A pixel client is built only for a provisioning pass — a brand whose
+    // pixel id is already config never touches the platform's API
+    const needsPixelApi = (work, provider) => Boolean(work && !provider.id);
+
+    // Tests inject fake clients via context.analyticsApi/metaApi/tiktokApi
+    return {
+      analyticsApi: needsGoogleApi
+        ? (context.analyticsApi || new GoogleAnalyticsAPI({
+          tokenStorePath: googleTokenStorePath(context.brandRoot),
+        }))
+        : null,
+      metaApi: context.metaApi || (needsPixelApi(metaWork, meta) ? new MetaMarketingAPI() : null),
+      tiktokApi: context.tiktokApi || (needsPixelApi(tiktokWork, tiktok) ? new TikTokBusinessAPI() : null),
+      domain,
+      propertyId: google.propertyId || null,
+      accountId: google.accountId || null,
+      operations,
+    };
+  },
+});

package/dist/services/analytics/lib/analytics-api.js

@@ -0,0 +1,156 @@
+/**
+ * Google Analytics Admin API client (v1beta, plus the v1alpha enhanced-
+ * measurement endpoints that never made it into beta). 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 API_BASE = 'https://analyticsadmin.googleapis.com/v1beta';
+const API_BASE_ALPHA = 'https://analyticsadmin.googleapis.com/v1alpha';
+
+class GoogleAnalyticsAPI {
+  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(`${API_BASE}${endpoint}`, options);
+  }
+
+  // ========== Accounts / properties ==========
+
+  async listAccounts() {
+    const data = await this.makeRequest('/accounts');
+    return data.accounts || [];
+  }
+
+  async listProperties(accountId) {
+    const data = await this.makeRequest(`/properties?filter=parent:accounts/${accountId}`);
+    return data.properties || [];
+  }
+
+  /** Create a GA4 property under an account; returns the property resource */
+  async createProperty(accountId, { displayName, timeZone, currencyCode }) {
+    return this.makeRequest('/properties', {
+      method: 'POST',
+      body: JSON.stringify({
+        parent: `accounts/${accountId}`,
+        displayName,
+        timeZone,
+        currencyCode,
+      }),
+    });
+  }
+
+  async getProperty(propertyId) {
+    try {
+      return await this.makeRequest(`/properties/${propertyId}`);
+    } catch (error) {
+      if (error.message.includes('404')) {
+        return null;
+      }
+      throw error;
+    }
+  }
+
+  // ========== Data streams ==========
+
+  async listDataStreams(propertyId) {
+    const data = await this.makeRequest(`/properties/${propertyId}/dataStreams`);
+    return data.dataStreams || [];
+  }
+
+  async createWebDataStream(propertyId, { defaultUri, displayName }) {
+    return await this.makeRequest(`/properties/${propertyId}/dataStreams`, {
+      method: 'POST',
+      body: JSON.stringify({
+        type: 'WEB_DATA_STREAM',
+        webStreamData: { defaultUri },
+        displayName: displayName || 'Web Stream',
+      }),
+    });
+  }
+
+  /**
+   * Update a data stream. Nested paths (e.g. 'webStreamData.defaultUri') need
+   * an explicit update mask — Object.keys would produce just 'webStreamData'.
+   */
+  async updateDataStream(propertyId, dataStreamId, updates, updateMaskFields) {
+    const updateMask = (updateMaskFields || Object.keys(updates)).join(',');
+    return await this.makeRequest(
+      `/properties/${propertyId}/dataStreams/${dataStreamId}?updateMask=${updateMask}`,
+      { method: 'PATCH', body: JSON.stringify(updates) },
+    );
+  }
+
+  // ========== Enhanced measurement (v1alpha only) ==========
+
+  async getEnhancedMeasurementSettings(propertyId, dataStreamId) {
+    return this.auth.makeRequest(
+      `${API_BASE_ALPHA}/properties/${propertyId}/dataStreams/${dataStreamId}/enhancedMeasurementSettings`,
+    );
+  }
+
+  async updateEnhancedMeasurementSettings(propertyId, dataStreamId, settings) {
+    const updateMask = Object.keys(settings).join(',');
+    return this.auth.makeRequest(
+      `${API_BASE_ALPHA}/properties/${propertyId}/dataStreams/${dataStreamId}/enhancedMeasurementSettings?updateMask=${updateMask}`,
+      { method: 'PATCH', body: JSON.stringify(settings) },
+    );
+  }
+
+  // ========== Measurement Protocol secrets ==========
+
+  async listMeasurementProtocolSecrets(propertyId, dataStreamId) {
+    const data = await this.makeRequest(
+      `/properties/${propertyId}/dataStreams/${dataStreamId}/measurementProtocolSecrets`,
+    );
+    return data.measurementProtocolSecrets || [];
+  }
+
+  async createMeasurementProtocolSecret(propertyId, dataStreamId, displayName) {
+    return await this.makeRequest(
+      `/properties/${propertyId}/dataStreams/${dataStreamId}/measurementProtocolSecrets`,
+      { method: 'POST', body: JSON.stringify({ displayName }) },
+    );
+  }
+
+  async deleteMeasurementProtocolSecret(propertyId, dataStreamId, secretId) {
+    await this.makeRequest(
+      `/properties/${propertyId}/dataStreams/${dataStreamId}/measurementProtocolSecrets/${secretId}`,
+      { method: 'DELETE' },
+    );
+    return { deleted: true };
+  }
+
+  // ========== Firebase links ==========
+
+  async listFirebaseLinks(propertyId) {
+    const data = await this.makeRequest(`/properties/${propertyId}/firebaseLinks`);
+    return data.firebaseLinks || [];
+  }
+
+  async createFirebaseLink(propertyId, firebaseProjectId) {
+    return await this.makeRequest(`/properties/${propertyId}/firebaseLinks`, {
+      method: 'POST',
+      body: JSON.stringify({ project: `projects/${firebaseProjectId}` }),
+    });
+  }
+
+  async deleteFirebaseLink(propertyId, firebaseLinkId) {
+    await this.makeRequest(`/properties/${propertyId}/firebaseLinks/${firebaseLinkId}`, {
+      method: 'DELETE',
+    });
+    return { deleted: true };
+  }
+}
+
+module.exports = { GoogleAnalyticsAPI };

package/dist/services/analytics/lib/meta-api.js

@@ -0,0 +1,83 @@
+/**
+ * Meta Marketing API client (Graph API) — the ad account's pixels/datasets.
+ * Named-method surface over fetch so tests can fake it method-for-method,
+ * normalized to the shared pixel shape ({ id, name }) the provisioning flow
+ * consumes (lib/pixel-provision.js).
+ *
+ * Auth: META_ACCESS_TOKEN in the brand .env — a Business Manager SYSTEM-USER
+ * token with ads_management on the ad account. ONE Meta token per brand: the
+ * same key @omega.js/backend's Conversions API sender reads, on the same
+ * Graph API version.
+ */
+const META_API_VERSION = 'v21.0'; // matches @omega.js/backend's conversions sender
+const API_BASE = `https://graph.facebook.com/${META_API_VERSION}`;
+
+/**
+ * Ad-account ids are configured BARE (the number Ads Manager shows); the
+ * Graph edge is `act_<id>`, and a value pasted with the prefix still works.
+ */
+function adAccountRef(adAccountId) {
+  const id = String(adAccountId);
+  return id.startsWith('act_') ? id : `act_${id}`;
+}
+
+class MetaMarketingAPI {
+  constructor(options = {}) {
+    // Null unless passed explicitly: the env is read at REQUEST time, because
+    // an interactive run pastes META_ACCESS_TOKEN after this client was built
+    this.accessToken = options.accessToken || null;
+  }
+
+  async makeRequest(endpoint, options = {}) {
+    const response = await fetch(`${API_BASE}${endpoint}`, {
+      ...options,
+      headers: {
+        'Authorization': `Bearer ${this.accessToken || process.env.META_ACCESS_TOKEN}`,
+        'Content-Type': 'application/json',
+        ...options.headers,
+      },
+    });
+
+    const text = await response.text();
+    const data = text ? JSON.parse(text) : null;
+
+    if (!response.ok) {
+      // Graph errors are { error: { message, type, code } } and the message
+      // is the human half ("(#200) Requires ads_management permission")
+      throw new Error(`Meta API error (${response.status}): ${data?.error?.message || response.statusText}`);
+    }
+
+    return data;
+  }
+
+  /**
+   * Ad accounts this token can act on — the auto-discovery source (#417).
+   * `id` comes back as `act_<number>` and `account_id` as the bare number
+   * config carries, so the normalized id is the one a human reads in Ads
+   * Manager.
+   */
+  async listAdAccounts() {
+    const data = await this.makeRequest('/me/adaccounts?fields=id,name,account_id&limit=100');
+    return (data?.data || []).map((account) => ({
+      id: account.account_id || String(account.id).replace(/^act_/, ''),
+      name: account.name,
+    }));
+  }
+
+  /** Pixels on the ad account — id + name only (name is the match key). */
+  async listPixels(adAccountId) {
+    const data = await this.makeRequest(`/${adAccountRef(adAccountId)}/adspixels?fields=id,name&limit=100`);
+    return (data?.data || []).map((pixel) => ({ id: pixel.id, name: pixel.name }));
+  }
+
+  /** Create a pixel/dataset on the ad account (the create echoes id only). */
+  async createPixel(adAccountId, name) {
+    const created = await this.makeRequest(`/${adAccountRef(adAccountId)}/adspixels`, {
+      method: 'POST',
+      body: JSON.stringify({ name }),
+    });
+    return { id: created?.id, name };
+  }
+}
+
+module.exports = { MetaMarketingAPI };