@omega.js/manager 0.1.0

package/dist/services/analytics/lib/pixel-account.js

@@ -0,0 +1,78 @@
+/**
+ * Ad-account discovery for the pixel provisioning path (#417, Ian
+ * 2026-08-21: "auto-set accountId") — the near-zero-input half of the GA4
+ * standard, applied to the pixels.
+ *
+ * The token already names the accounts it can act on, so a brand should
+ * never have to look one up: with `analytics.providers.{provider}.accountId`
+ * missing, ask the platform which accounts this token sees. Exactly one is
+ * the answer (auto-selected, landed in omega.json5 — nothing to ask);
+ * several is a real choice (the standard selection flow, with the tri-state
+ * opt-out in the list); non-interactive runs print the candidates so the
+ * value can be pasted into config, and zero means the token has no ad-account
+ * access at all — guidance, never a failure.
+ *
+ * Only providers whose client can enumerate accounts take this path
+ * (spec.discoverAccounts); the others keep the configured-accountId gate.
+ */
+const chalk = require('chalk').default;
+
+const { landValue, resolveConfigValue } = require('../../../lib/config-flow.js');
+const { canPrompt, dryRunPlan } = require('../../../lib/run-gates.js');
+
+/**
+ * Resolve the ad account the pixel gets created on, landing it in config.
+ *
+ * @param {Object} context - Handler context (carries the client at spec.apiKey)
+ * @param {Object} spec - { key, label, envVar, apiKey, accountLabel, accountGuidance }
+ * @returns {Promise<string|null>} - The account id, or null when unresolved
+ */
+async function resolvePixelAccount(context, spec) {
+  const { options = {} } = context;
+  const path = `analytics.providers.${spec.key}.accountId`;
+  const accounts = await context[spec.apiKey].listAdAccounts();
+
+  if (accounts.length === 0) {
+    console.log(`      ${chalk.yellow('⚠')} No ${spec.accountLabel}s are visible to ${chalk.cyan(spec.envVar)}`);
+    console.log(`      ${chalk.dim('→')} ${spec.accountGuidance}`);
+    return null;
+  }
+
+  if (accounts.length === 1) {
+    const [only] = accounts;
+    const display = `${only.name} (${only.id})`;
+
+    if (options.dryRun) {
+      dryRunPlan(`set ${path} to ${only.id} (the only ${spec.accountLabel} ${spec.envVar} can see)`);
+      return only.id;
+    }
+
+    console.log(`      ${chalk.green('✓')} ${spec.label} ${spec.accountLabel}: ${chalk.cyan(display)} ${chalk.dim(`— the only one ${spec.envVar} can see`)}`);
+    landValue(context, path, only.id);
+    return only.id;
+  }
+
+  if (!canPrompt(options)) {
+    console.log(`      ${chalk.yellow('⚠')} ${accounts.length} ${spec.accountLabel}s visible — set ${chalk.cyan(path)} in omega.json5 (or rerun interactively to pick):`);
+    for (const account of accounts) {
+      console.log(`        ${chalk.dim('·')} ${account.name} ${chalk.dim(`(${account.id})`)}`);
+    }
+    return null;
+  }
+
+  // Several: the standard selection flow — brand matches sort first, and the
+  // inline opt-out lands `analytics.providers.{provider}: false`
+  return resolveConfigValue(context, {
+    path,
+    label: `${spec.label} ${spec.accountLabel}`,
+    message: `Select the ${spec.accountLabel} for ${spec.label}:`,
+    gate: false, // the provisioning flow already asked
+    choices: () => accounts,
+    getName: (account) => `${account.name} (${account.id})`,
+    getValue: (account) => account.id,
+    optOut: { label: `No ${spec.label} — don't ask again` },
+    disablePath: `analytics.providers.${spec.key}`,
+  });
+}
+
+module.exports = { resolvePixelAccount };

package/dist/services/analytics/lib/pixel-provision.js

@@ -0,0 +1,152 @@
+/**
+ * Shared pixel PROVISIONING for the meta-pixel/tiktok-pixel operations — the
+ * create half of the pair whose check half is pixel-token.js, and the same
+ * reconcile shape the GA4 side uses (#417).
+ *
+ * The pixel id is public config, so a configured
+ * `analytics.providers.{provider}.id` is converged proof and nothing is
+ * called. A missing id reconciles idempotently in ONE interactive pass
+ * (Ian 2026-08-21, the GA4 near-zero-input standard): acquire the access
+ * token (pixel-token.js — guidance, the Enter-gated open, paste-in), resolve
+ * the ad account (pixel-account.js — auto-selected when the token sees
+ * exactly one, `meta.accountId` = the Meta AD ACCOUNT, `tiktok.accountId` =
+ * the TikTok ADVERTISER; the non-secret ids live in config beside
+ * `google.accountId`/`propertyId`, never in .env), find the brand's pixel BY
+ * NAME, create it when absent, then land the id in omega.json5
+ * (comment-preserving) and in the in-memory config, so the token check in the
+ * same pass reports the pixel it just made.
+ *
+ * The access token is still the gate. No token — nothing pasted, or a
+ * non-interactive run — means no provisioning this pass: warned with the same
+ * where-to-get guidance the token check prints, never a failure (Ian
+ * 2026-08-21: a manage walk must not break for a key that isn't filled in).
+ *
+ * Tri-state (#33): `analytics.providers.{provider}: false` disables the
+ * provider outright — no calls, no prompts, no warns — and every prompt this
+ * flow opens offers the choice that writes it.
+ *
+ * Clients hand back one normalized shape: `listPixels(accountId)` →
+ * `[{ id, name }]`, `createPixel(accountId, name)` → `{ id, name }`, and
+ * (when the spec declares discoverAccounts) `listAdAccounts()` →
+ * `[{ id, name }]`.
+ */
+const chalk = require('chalk').default;
+
+const { confirmSetup, landValue, readTriState } = require('../../../lib/config-flow.js');
+const { canPrompt, dryRunPlan } = require('../../../lib/run-gates.js');
+const { acquirePixelToken } = require('./pixel-token.js');
+const { resolvePixelAccount } = require('./pixel-account.js');
+
+/**
+ * Whether a provider has anything for the service to do: a configured id to
+ * check, an account to create under, or — for a provider that can discover
+ * its own account — a token in hand or an interactive run that can ask for
+ * one. A disabled provider never has work.
+ *
+ * @param {Object} brandConfig - The merged brand config
+ * @param {Object} spec - The provider spec
+ * @param {Object} [options] - Run options (dryRun gates the prompt path)
+ * @returns {boolean}
+ */
+function hasPixelWork(brandConfig, spec, options) {
+  const { optedOut, value } = readTriState(brandConfig, `analytics.providers.${spec.key}`);
+  if (optedOut) {
+    return false;
+  }
+
+  const provider = value || {};
+  if (provider.id || provider.accountId) {
+    return true;
+  }
+
+  return Boolean(spec.discoverAccounts && (process.env[spec.envVar] || canPrompt(options)));
+}
+
+/**
+ * Create the provider's pixel when config has no id yet.
+ *
+ * @param {Object} context - Handler context (carries the client at spec.apiKey)
+ * @param {Object} spec - { key, label, envVar, tokenSource, tokenUrl, apiKey,
+ *   accountLabel, accountGuidance, discoverAccounts, instructions }
+ * @returns {Promise<Object|null>} A handler return when the pass ENDS here (the
+ *   provider is disabled, no token to create with, no account to create on, or
+ *   a dry-run plan), or null when the id is in hand and the token check should
+ *   run.
+ */
+async function provisionPixel(context, spec) {
+  const { brandConfig, options = {} } = context;
+  const { optedOut, value } = readTriState(brandConfig, `analytics.providers.${spec.key}`);
+
+  if (optedOut) {
+    console.log(chalk.dim(`      ⊘ ${spec.label} disabled (analytics.providers.${spec.key}: false)`));
+    return {};
+  }
+
+  const provider = value || {};
+
+  // Configured id = converged; nothing configured and nothing to discover
+  // with = the token check keeps its clean "not configured" skip
+  if (provider.id || !hasPixelWork(brandConfig, spec, options)) {
+    return null;
+  }
+
+  // Nothing configured at all: ask permission before asking for a secret —
+  // the uniform gate, whose Disable lands `providers.{provider}: false`
+  let gated = false;
+  if (!provider.accountId && canPrompt(options)) {
+    const action = await confirmSetup(context, {
+      label: spec.label,
+      instructions: spec.instructions,
+      disablePath: `analytics.providers.${spec.key}`,
+    });
+    if (action !== 'yes') {
+      return {};
+    }
+    gated = true;
+  }
+
+  // When the gate above ran, the acquire must not open the same question
+  // twice; when it didn't (a configured accountId), the acquire owns it
+  if (!await acquirePixelToken(context, spec, gated ? { gate: false } : {})) {
+    console.log(`      ${chalk.dim('→')} ${spec.label} not created — rerun with ${chalk.cyan(spec.envVar)} set (or set ${chalk.cyan(`analytics.providers.${spec.key}: false`)} to stop asking)`);
+    return { status: 'warned', reason: `${spec.label} not created — no ${spec.envVar}`, output: { [spec.key]: { pixelId: null, tokenConfigured: false } } };
+  }
+
+  const accountId = provider.accountId || await resolvePixelAccount(context, spec);
+  if (!accountId) {
+    return { status: 'warned', reason: `${spec.label} not created — no account resolved`, output: { [spec.key]: { pixelId: null, tokenConfigured: true } } };
+  }
+
+  const api = context[spec.apiKey];
+  const name = brandConfig.brand.name;
+  const configPath = `analytics.providers.${spec.key}.id`;
+
+  const existing = await api.listPixels(accountId);
+  const found = existing.find((pixel) => pixel.name === name);
+
+  if (found) {
+    console.log(`      ${chalk.green('✓')} Matched ${spec.label} ${chalk.cyan(`"${name}"`)} ${chalk.dim(`(${found.id})`)}`);
+    landValue(context, configPath, found.id);
+    return null;
+  }
+
+  if (options.dryRun) {
+    return dryRunPlan(
+      `create ${spec.label} "${name}" on ${spec.accountLabel} ${accountId}`,
+      { output: { [spec.key]: { planned: 'create', name } } },
+    );
+  }
+
+  const created = await api.createPixel(accountId, name);
+  if (!created?.id) {
+    // The create answered 200 without an id: the response shape moved and
+    // landing `undefined` would poison the config — fail at the break
+    throw new Error(`${spec.label} create returned no id (${JSON.stringify(created)})`);
+  }
+
+  console.log(`      ${chalk.green('✓')} Created ${spec.label} ${chalk.cyan(`"${name}"`)} ${chalk.dim(`(${created.id})`)}`);
+  landValue(context, configPath, created.id);
+  return null;
+}
+
+module.exports = { hasPixelWork, provisionPixel };

package/dist/services/analytics/lib/pixel-specs.js

@@ -0,0 +1,57 @@
+/**
+ * The two pixel providers, declared once — the SSOT the ensure handlers
+ * (ensure/meta-pixel.js, ensure/tiktok-pixel.js) run on and the service setup
+ * reads to decide whether a provider has work and needs a client at all.
+ *
+ * Each spec names: the config key under `analytics.providers`, the .env key
+ * @omega.js/backend reads, the context key its API client rides on, and what
+ * the platform calls the account the pixel lives on. `discoverAccounts` marks
+ * a provider whose client can enumerate the accounts its token sees
+ * (lib/pixel-account.js) — the others stay gated on a configured accountId.
+ *
+ * WHERE a human gets the token is NOT here: the REQUIRES registry
+ * (src/config.js) owns every env descriptor — label, mint URL, hint — so the
+ * shared setup contract (#608) and the preflight walkthrough read one home.
+ * `acquire` names the provider whose token is MINTED rather than pasted
+ * (TikTok's portal exchange, #448); without it the generic paste lane runs.
+ */
+const chalk = require('chalk').default;
+
+const { acquireTikTokToken } = require('./tiktok-auth.js');
+
+const META_PIXEL = {
+  key: 'meta',
+  label: 'Meta Pixel',
+  idLabel: 'Meta Pixel ID',
+  envVar: 'META_ACCESS_TOKEN',
+  apiKey: 'metaApi',
+  accountLabel: 'ad account',
+  discoverAccounts: true,
+  accountGuidance: 'Assign an ad account to the system user in Business Settings → Users → System users → Add assets',
+  instructions: [
+    `1. Mint a Business Manager SYSTEM USER token with ${chalk.cyan('ads_management')} (the next step opens the page)`,
+    '2. The ad account that token can see is selected for you, and the pixel is created on it',
+    `3. The same token signs the Conversions API events ${chalk.cyan('@omega.js/backend')} sends`,
+  ],
+};
+
+// SCAFFOLD (#417): no discoverAccounts until TikTok's app is provisioned and
+// the shapes are proven — the advertiser id stays required config, and the
+// create path waits for a configured accountId. The token, though, is no
+// longer a standing key: `acquire` mints it through the portal exchange (#448).
+const TIKTOK_PIXEL = {
+  key: 'tiktok',
+  label: 'TikTok Pixel',
+  idLabel: 'TikTok Pixel Code',
+  envVar: 'TIKTOK_ACCESS_TOKEN',
+  apiKey: 'tiktokApi',
+  accountLabel: 'advertiser',
+  acquire: acquireTikTokToken,
+  instructions: [
+    `1. Set the developer app's id at ${chalk.cyan('analytics.providers.tiktok.appId')} in omega.json5`,
+    '2. Paste its app secret once — it authorizes the portal and is never saved',
+    `3. The exchange runs here and saves only ${chalk.cyan('TIKTOK_ACCESS_TOKEN')}`,
+  ],
+};
+
+module.exports = { META_PIXEL, TIKTOK_PIXEL };

package/dist/services/analytics/lib/pixel-token.js

@@ -0,0 +1,88 @@
+/**
+ * Shared pixel-token machinery for the meta-pixel/tiktok-pixel operations —
+ * ONE acquisition flow, used by both halves of the pair: the CREATE path
+ * needs the token before it can provision (lib/pixel-provision.js) and the
+ * CHECK path needs it before the frontend can send conversions.
+ *
+ * The pixel ID is public config (`analytics.providers.{provider}.id` — it
+ * ships in the frontend); the conversions/events access token is a secret
+ * and lives in the brand .env under the exact name @omega.js/backend reads.
+ * There's no practical validation API for either token, so this is a
+ * presence check plus an ask — and the ask is the SHARED setup contract
+ * (#608, lib/service-input.js): provide (the Enter-gated open of the exact
+ * page that mints one, then a masked paste saved to the brand .env), skip
+ * this run, or disable the provider for good (`analytics.providers.
+ * {provider}: false`). Non-interactive runs never prompt and keep the warned
+ * guidance. The backend's stage step composes the saved token out of the
+ * brand .env into its dist/.env.
+ *
+ * A provider whose token is MINTED rather than pasted names its own acquire
+ * on the spec (TikTok's portal exchange, #448) — the outcomes are identical.
+ */
+const chalk = require('chalk').default;
+
+const { serviceInputSpec } = require('../../../config.js');
+const { requestServiceInput } = require('../../../lib/service-input.js');
+
+/**
+ * Make sure the provider's access token is in the environment, asking for
+ * it when the run can prompt. Silent when the token is already set — the
+ * caller reports it (the create path stays quiet, the check path prints its
+ * ✓ line).
+ *
+ * @param {Object} context - Handler context
+ * @param {Object} spec - A pixel spec ({ key, label, envVar, acquire?, instructions? })
+ * @param {Object} [options] - { gate: false } when the caller already ran the
+ *   Provide / Skip / Disable gate for this provider.
+ * @returns {Promise<boolean>} - Whether the token is now in process.env
+ */
+async function acquirePixelToken(context, spec, options = {}) {
+  if (process.env[spec.envVar]) {
+    return true;
+  }
+
+  if (spec.acquire) {
+    return spec.acquire(context, spec, options);
+  }
+
+  const gate = await requestServiceInput(context, serviceInputSpec('analytics', {
+    names: [spec.envVar],
+    label: spec.label,
+    instructions: spec.instructions,
+    gate: options.gate,
+  }));
+
+  return gate === null;
+}
+
+/**
+ * Check one provider's pixel config + access token.
+ *
+ * @param {Object} context - Handler context
+ * @param {Object} spec - { key, label, idLabel, envVar }
+ * @returns {Object} - Handler return ({ output } / warned)
+ */
+async function ensurePixelToken(context, spec) {
+  const { brandConfig } = context;
+  const pixelId = brandConfig.analytics?.providers?.[spec.key]?.id;
+
+  if (!pixelId) {
+    console.log(chalk.dim(`      ⊘ ${spec.label} not configured (analytics.providers.${spec.key}.id)`));
+    return {};
+  }
+
+  console.log(`      ${chalk.green('✓')} ${spec.idLabel}: ${chalk.cyan(pixelId)}`);
+
+  const alreadySet = Boolean(process.env[spec.envVar]);
+  if (!await acquirePixelToken(context, spec)) {
+    return { status: 'warned', reason: `no ${spec.envVar} — the access token is not configured`, output: { [spec.key]: { pixelId, tokenConfigured: false } } };
+  }
+
+  if (alreadySet) {
+    console.log(`      ${chalk.green('✓')} Access token configured (${chalk.cyan(spec.envVar)})`);
+  }
+
+  return { output: { [spec.key]: { pixelId, tokenConfigured: true } } };
+}
+
+module.exports = { acquirePixelToken, ensurePixelToken };

package/dist/services/analytics/lib/property-flow.js

@@ -0,0 +1,77 @@
+/**
+ * Interactive GA account + property selection/creation (config-landing
+ * flow): when analytics.providers.google.propertyId is missing in an
+ * interactive run, pick the GA account (create-new opens the provision
+ * page), then pick or create the GA4 property via the Admin API — both land
+ * in omega.json5 (comment-preserving writeback). An accountId already in
+ * config is used as-is without prompting — and when it arrived through the
+ * COMPANY layer (company omega.json5 `analytics.providers.google.accountId`,
+ * merged under the brand file so an explicit brand value always wins), the
+ * flow says so with a dim note instead of silently proceeding. The
+ * interactive picker stays the fallback when nothing is configured anywhere.
+ */
+const chalk = require('chalk').default;
+const { resolveConfigValue } = require('../../../lib/config-flow.js');
+
+const CREATE_ACCOUNT_URL = 'https://analytics.google.com/analytics/web/#/provision/create';
+
+/**
+ * Resolve (or interactively land) the GA4 property id.
+ *
+ * @param {Object} context - Service context
+ * @param {Object} api - GoogleAnalyticsAPI client
+ * @returns {Promise<string|null>} - propertyId, or null when skipped
+ */
+async function resolveGoogleProperty(context, api) {
+  // When the account flow just ran (and the user said Yes), the property
+  // selection rides that gate instead of asking "Set up now?" twice
+  const configuredAccountId = context.brandConfig.analytics?.providers?.google?.accountId;
+  const accountPreConfigured = Boolean(configuredAccountId);
+
+  // Company-default GA account (Ian 2026-07-21): a company-managed brand
+  // inherits the company's accountId through the merge chain — note the
+  // provenance instead of prompting (an explicit brand-level accountId
+  // wins in the merge before this ever runs)
+  const companyAccountId = context.companyConfig?.analytics?.providers?.google?.accountId;
+  if (configuredAccountId && companyAccountId && configuredAccountId === companyAccountId) {
+    console.log(`    ${chalk.dim(`→ Google Analytics account ${configuredAccountId} — defaulting to company account`)}`);
+  }
+
+  const accountId = await resolveConfigValue(context, {
+    path: 'analytics.providers.google.accountId',
+    label: 'Google Analytics account',
+    choices: () => api.listAccounts(),
+    getName: (account) => `${account.displayName} (${account.name.replace('accounts/', '')})`,
+    getValue: (account) => account.name.replace('accounts/', ''),
+    createNew: { label: 'account', url: CREATE_ACCOUNT_URL, refreshChoices: true },
+  });
+
+  if (!accountId) {
+    return null;
+  }
+
+  return resolveConfigValue(context, {
+    path: 'analytics.providers.google.propertyId',
+    label: 'GA4 property',
+    gate: accountPreConfigured,
+    choices: () => api.listProperties(accountId),
+    getName: (property) => `${property.displayName} (${property.name.replace('properties/', '')})`,
+    getValue: (property) => property.name.replace('properties/', ''),
+    createNew: {
+      label: 'property',
+      handler: async () => {
+        const { brand } = context.brandConfig;
+        const google = context.brandConfig.analytics.providers.google;
+        const domain = brand.url.replace(/^https?:\/\//, '').replace(/\/$/, '');
+        const property = await api.createProperty(accountId, {
+          displayName: `${brand.name} (${domain})`,
+          timeZone: google.timeZone,
+          currencyCode: google.currency,
+        });
+        return property.name.replace('properties/', '');
+      },
+    },
+  });
+}
+
+module.exports = { resolveGoogleProperty };

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

@@ -0,0 +1,157 @@
+/**
+ * TikTok Business API client (v1.3) — the advertiser account's pixels.
+ * Named-method surface over fetch, normalized to the same { id, name } shape
+ * as the Meta client so one provisioning flow drives both
+ * (lib/pixel-provision.js). TikTok's "pixel code" IS the public pixel id the
+ * frontends embed, so it fills the `id` slot.
+ *
+ * Auth: TIKTOK_ACCESS_TOKEN in the brand .env (the `Access-Token` header) —
+ * the long-lived token the portal authorization mints (#448, lib/tiktok-auth.js),
+ * the same key @omega.js/backend's Events API sender reads. The exchange that
+ * MINTS it lives here too, as a free function: it is the one call that runs
+ * without a token, so it can never be a method on the authenticated client.
+ *
+ * SCAFFOLD (#417, Ian 2026-08-21): the endpoints below are the documented
+ * v1.3 pixel shapes, never yet exercised against the live API — Ian's TikTok
+ * app is not provisioned, so no brand carries the token and the ensure step
+ * cannot reach this client. Treat a first live run as the proving run.
+ */
+const API_BASE = 'https://business-api.tiktok.com/open_api/v1.3';
+// Where a developer app (and so its app id) is created — the page the setup
+// walks to when a brand has no `analytics.providers.tiktok.appId` yet (#635).
+const TIKTOK_APPS_URL = 'https://business-api.tiktok.com/portal/apps';
+
+/**
+ * The app's own page in the developer portal. Its Basic Information shows the
+ * "Advertiser authorization URL" TikTok built for the app (app id, state, and
+ * the redirect URI configured ON the app), so the setup opens THIS page and the
+ * human clicks that link there (Ian 2026-08-27): the redirect URI is the app's
+ * setting, never brand config, and manage never asks for it.
+ *
+ * @param {string} appId - The TikTok developer app id (public config).
+ * @returns {string} The app page URL.
+ */
+// The portal's authorization endpoint — what the app page's "Advertiser
+// authorization URL" starts with. Only used to check a pasted URL is that link.
+const TIKTOK_AUTH_BASE = 'https://business-api.tiktok.com/portal/auth';
+
+/**
+ * Whether a pasted URL is the app's own advertiser authorization link.
+ *
+ * @param {string} url - The pasted URL.
+ * @param {string} appId - The app id it must carry.
+ * @returns {boolean}
+ */
+function isAuthUrlFor(url, appId) {
+  try {
+    const parsed = new URL(url);
+    return `${parsed.origin}${parsed.pathname}` === TIKTOK_AUTH_BASE && parsed.searchParams.get('app_id') === String(appId);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The auth_code out of a pasted redirect URL, or the bare code when the human
+ * pasted just that.
+ *
+ * @param {string} pasted - A redirect URL carrying `auth_code`, or the code.
+ * @returns {string} The code, or '' when neither.
+ */
+function parseAuthCode(pasted) {
+  if (!pasted) {
+    return '';
+  }
+  try {
+    return new URL(pasted).searchParams.get('auth_code') || '';
+  } catch {
+    // Not a URL: the bare code
+    return pasted;
+  }
+}
+
+function TIKTOK_APP_URL(appId) {
+  return `${TIKTOK_APPS_URL}/${encodeURIComponent(appId)}`;
+}
+
+/**
+ * Exchange a portal `auth_code` for the long-lived access token (#448). The
+ * app secret is a MINT-TIME credential — it is passed here and never stored.
+ *
+ * @param {object} params - { appId, secret, authCode }.
+ * @param {Function} [fetchImpl] - Test seam; defaults to global fetch.
+ * @returns {Promise<string>} The long-lived access token.
+ */
+async function exchangeAuthCode({ appId, secret, authCode }, fetchImpl = fetch) {
+  const response = await fetchImpl(`${API_BASE}/oauth2/access_token/`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ app_id: appId, secret, auth_code: authCode }),
+  });
+
+  const text = await response.text();
+  const body = text ? JSON.parse(text) : null;
+
+  // Same rule as the client: TikTok answers 200 with a non-zero `code`
+  if (!response.ok || (body && body.code !== 0)) {
+    throw new Error(`TikTok API error (${body?.code ?? response.status}): ${body?.message || response.statusText}`);
+  }
+
+  const token = body?.data?.access_token;
+  if (!token) {
+    // A 200 with code 0 and no token means the response shape moved —
+    // persisting `undefined` would poison the brand .env
+    throw new Error(`TikTok token exchange returned no access_token (${JSON.stringify(body?.data)})`);
+  }
+
+  return token;
+}
+
+class TikTokBusinessAPI {
+  constructor(options = {}) {
+    this.accessToken = options.accessToken || process.env.TIKTOK_ACCESS_TOKEN;
+  }
+
+  async makeRequest(endpoint, options = {}) {
+    const response = await fetch(`${API_BASE}${endpoint}`, {
+      ...options,
+      headers: {
+        'Access-Token': this.accessToken,
+        'Content-Type': 'application/json',
+        ...options.headers,
+      },
+    });
+
+    const text = await response.text();
+    const body = text ? JSON.parse(text) : null;
+
+    // TikTok answers HTTP 200 with a non-zero `code` for real failures, so
+    // the status alone never proves success
+    if (!response.ok || (body && body.code !== 0)) {
+      throw new Error(`TikTok API error (${body?.code ?? response.status}): ${body?.message || response.statusText}`);
+    }
+
+    return body?.data || null;
+  }
+
+  /** Pixels on the advertiser account, normalized to { id, name }. */
+  async listPixels(advertiserId) {
+    const data = await this.makeRequest(`/pixel/list/?advertiser_id=${encodeURIComponent(advertiserId)}`);
+    return (data?.pixels || []).map((pixel) => ({ id: pixel.pixel_code, name: pixel.pixel_name }));
+  }
+
+  /** Create a pixel on the advertiser account. */
+  async createPixel(advertiserId, name) {
+    const created = await this.makeRequest('/pixel/create/', {
+      method: 'POST',
+      body: JSON.stringify({
+        advertiser_id: String(advertiserId),
+        pixel_name: name,
+        pixel_mode: 'STANDARD_MODE',
+      }),
+    });
+    return { id: created?.pixel_code, name: created?.pixel_name || name };
+  }
+}
+
+module.exports = { TikTokBusinessAPI, exchangeAuthCode, TIKTOK_APP_URL, TIKTOK_APPS_URL, TIKTOK_AUTH_BASE, isAuthUrlFor, parseAuthCode };