@omega.js/client 0.1.0

package/dist/vendor/analytics/consent.js

@@ -0,0 +1,49 @@
+/**
+ * The consent seam.
+ *
+ * The gate answers ONE question — is this category granted right now — and the
+ * facade asks it once per provider before resolving. No UI, no storage, no
+ * region logic: stage B ([#383](https://github.com/Omega-JS-Stack/omega/issues/383))
+ * owns the banner and the timezone heuristic, and injects its state through
+ * `createConsentGate`.
+ *
+ * The provider function is read LIVE on every event, so a visitor who accepts
+ * mid-session is counted from that moment without anything re-configuring.
+ */
+
+// The two categories every provider belongs to (adapters export their own).
+const CATEGORIES = ['analytics', 'marketing'];
+
+/**
+ * Build a consent gate from a state provider.
+ * @param {Function} providerFn - () => ({ analytics: boolean, marketing: boolean }).
+ * @returns {{ granted: Function, state: Function }}
+ */
+function createConsentGate(providerFn) {
+  function state() {
+    const value = providerFn() || {};
+    const resolved = {};
+    for (const category of CATEGORIES) {
+      resolved[category] = value[category] === true;
+    }
+    return resolved;
+  }
+
+  return {
+    state,
+    /**
+     * Is this category granted?
+     * @param {string} category - 'analytics' | 'marketing'.
+     * @returns {boolean}
+     */
+    granted(category) {
+      return state()[category] === true;
+    },
+  };
+}
+
+// The default when no host injects one: everything granted. Stage B supplies
+// the real gate on web; desktop/extension/backend have no banner to gate on.
+const GRANT_ALL = createConsentGate(() => ({ analytics: true, marketing: true }));
+
+module.exports = { CATEGORIES, createConsentGate, GRANT_ALL };

package/dist/vendor/analytics/core.js

@@ -0,0 +1,141 @@
+/**
+ * core — the ONE place GA4 Measurement Protocol semantics live
+ * (C4 cp106b; Ian: "unify it and have it in one place").
+ *
+ * Pure functions, zero runtime assumptions: no DOM, no storage, no
+ * transport. @omega.js/client's browser engine and @omega.js/desktop's
+ * main-process lib both consume THIS module, so identity math and payload
+ * shape can never drift between surfaces again. It moved here from the client
+ * ([#382](https://github.com/Omega-JS-Stack/omega/issues/382)) so the server
+ * side reaches it without importing the frontend runtime.
+ *
+ * Cross-surface identity:
+ *   deviceId  = the host's stored id, its seed strategy, or a fresh uuidv4
+ *   client_id = uuidv5(deviceId, namespace)   — same device+surface, same GA client
+ *   namespace = uuidv5(projectId, uuidv5.URL)
+ *   user_id   = uuidv5(firebaseUid, namespace) — same human, every surface
+ * Raw uids/device ids never leave the machine; without a namespace the
+ * user_id stays null (never the raw value).
+ *
+ * `deriveDeviceId` is where the chain starts and the only step that touches a
+ * host's world — so its persistence and its seed strategy are INJECTED
+ * ([#396](https://github.com/Omega-JS-Stack/omega/issues/396)), which keeps this
+ * module as assumption-free as the rest of it.
+ *
+ * CJS on purpose: desktop's Electron main process require()s it directly
+ * (via the package's dist exports); the ESM browser module imports it with
+ * standard interop.
+ */
+
+const { v4: uuidv4, v5: uuidv5 } = require('uuid');
+
+const GA_ENDPOINT = 'https://www.google-analytics.com/mp/collect';
+
+/**
+ * The stable per-install device id every surface's client_id is hashed from —
+ * ONE derivation, on the `createRequest(deps)` mold: what differs per target is
+ * WHERE it persists and WHAT it seeds from, and both are handed in.
+ *
+ * The walk is stored → seed → uuidv4. Storage wins so an id survives whatever
+ * the seed does next (desktop stays put across a NIC swap or a VPN); the seed is
+ * what gives a wiped install continuity (desktop's first non-internal MAC), and
+ * a host with none — a browser, where nothing about the machine is readable —
+ * generates one and persists it. The floor is the `uuid` package's `v4`, which
+ * yields a REAL uuid in every runtime this ships to: it uses the platform's
+ * `crypto.randomUUID` where that exists and `getRandomValues` where it does not
+ * (an insecure origin), so no surface ever falls back to a random-looking string.
+ *
+ * @param {object} deps - The host's world.
+ * @param {function(): string|null} deps.get - Read the persisted id.
+ * @param {function(string): void} deps.set - Persist a freshly derived id.
+ * @param {function(): string|null} [deps.seed] - The target's id source, asked
+ *   only when nothing is stored. Anything falsy falls through to the uuid.
+ * @returns {string} The raw device id — never sent anywhere as-is.
+ */
+function deriveDeviceId(deps) {
+  if (typeof deps?.get !== 'function' || typeof deps?.set !== 'function') {
+    throw new Error('deriveDeviceId requires get and set deps');
+  }
+
+  const stored = deps.get();
+
+  if (stored) {
+    return stored;
+  }
+
+  const deviceId = (deps.seed ? deps.seed() : null) || uuidv4();
+
+  deps.set(deviceId);
+
+  return deviceId;
+}
+
+/** uuidv5 namespace for a project — null in, null out. */
+function deriveNamespace(projectId) {
+  return projectId ? uuidv5(String(projectId), uuidv5.URL) : null;
+}
+
+/** Stable GA client_id: hashed into the namespace when one exists. */
+function deriveClientId(deviceId, namespace) {
+  return namespace ? uuidv5(String(deviceId), namespace) : deviceId;
+}
+
+/** GA user_id from a raw uid — no namespace → null (raw uids never ship). */
+function deriveUserId(uid, namespace) {
+  return (uid && namespace) ? uuidv5(String(uid), namespace) : null;
+}
+
+/** GA4 event names: letters/digits/underscore, ≤40 chars, no edge underscores. */
+function normalizeEventName(name) {
+  if (!name || typeof name !== 'string') {
+    return null;
+  }
+
+  return name
+    .replace(/[^a-zA-Z0-9_]/g, '_')
+    .replace(/^_+|_+$/g, '')
+    .replace(/_+/g, '_')
+    .slice(0, 40);
+}
+
+/** GA4 user_properties wrapping: { plan: 'pro' } → { plan: { value: 'pro' } }. */
+function wrapUserProperties(properties = {}) {
+  const wrapped = {};
+  for (const [key, value] of Object.entries(properties)) {
+    wrapped[key] = { value };
+  }
+  return wrapped;
+}
+
+/** Measurement Protocol collect URL. */
+function buildCollectUrl(measurementId, secret) {
+  return `${GA_ENDPOINT}?measurement_id=${encodeURIComponent(measurementId)}&api_secret=${encodeURIComponent(secret)}`;
+}
+
+/**
+ * Measurement Protocol payload. userId/userProperties are omitted when
+ * empty — GA rejects nulls, and an empty user_properties block is noise.
+ */
+function buildPayload({ clientId, userId = null, userProperties = {}, eventName, params = {} }) {
+  return {
+    client_id: clientId,
+    ...(userId ? { user_id: userId } : {}),
+    ...(Object.keys(userProperties).length ? { user_properties: userProperties } : {}),
+    events: [{
+      name: eventName,
+      params,
+    }],
+  };
+}
+
+module.exports = {
+  GA_ENDPOINT,
+  deriveDeviceId,
+  deriveNamespace,
+  deriveClientId,
+  deriveUserId,
+  normalizeEventName,
+  wrapUserProperties,
+  buildCollectUrl,
+  buildPayload,
+};

package/dist/vendor/analytics/identity.js

@@ -0,0 +1,136 @@
+/**
+ * identity — the match keys a signed-in visitor is recognized BY, normalized the
+ * way each platform's own spec demands
+ * ([#328](https://github.com/Omega-JS-Stack/omega/issues/328)).
+ *
+ * Every ad platform matches on a SHA-256 of a NORMALIZED value, and normalized
+ * is not one rule. Meta's advanced matching wants a phone as bare digits —
+ * country code included, no `+`, no punctuation — while TikTok's pixel wants the
+ * E.164 form WITH the `+`. Same person, two digests, so the normalizer is per
+ * provider and only the hash is shared. Email is the one value everybody
+ * normalizes alike: trimmed and lowercased.
+ *
+ * RAW PII NEVER LEAVES: a caller hashes here and hands the pixel the digest.
+ * `external_id` is not PII, and it is per provider like the rest
+ * ([#410](https://github.com/Omega-JS-Stack/omega/issues/410)): META's spec only
+ * RECOMMENDS hashing and its own Pixel example passes a bare id, so Meta gets
+ * the RAW uid — exactly what the SERVER sends as `identity.externalId`
+ * (@omega.js/backend's `libraries/analytics/match-data.js`). TIKTOK's Events API
+ * REQUIRES the digest, so both halves send the SHA-256 of that same uid,
+ * normalized by `normalizeExternalId()` below. Either way the browser half and
+ * the server half of one person link only because both carry the same value.
+ *
+ * Pure and runtime-neutral like the rest of the package's pieces: no DOM, no
+ * transport, no state. CJS, so the backend can require() it and the browser
+ * bundles import it with standard interop.
+ */
+
+// The node digest's specifier, held in a VARIABLE on purpose: the web bundle is
+// built for the browser, where a builtin has no home, and esbuild fails the
+// whole build on a literally-named builtin it cannot resolve. Read through a
+// variable it is left alone — and the branch below only ever runs off-page.
+const NODE_CRYPTO = 'crypto';
+
+/**
+ * Is this runtime node? The node digest is chosen by the RUNTIME and never by
+ * `typeof require`: a bundler rewrites that name to a shim of its own, which IS
+ * a function and throws the moment it is called with a builtin — a rejection
+ * thrown at a visitor, exactly where this module promises a quiet null.
+ * @returns {boolean}
+ */
+function isNode() {
+  return typeof process !== 'undefined' && !!process.versions && !!process.versions.node;
+}
+
+/**
+ * SHA-256 hex — the digest every platform's match spec asks for.
+ *
+ * A page's only hash is `crypto.subtle`, which is asynchronous and absent on a
+ * non-secure origin; node's `crypto` covers the runtimes that have no secure
+ * context (the test runner, a Cloud Function, a plain-http page).
+ *
+ * @param {string} [value] - The ALREADY-normalized value.
+ * @returns {Promise<string|null>} Lowercase hex, or null when there is nothing
+ *   to hash and when no digest exists to hash it with.
+ */
+async function sha256(value) {
+  if (!value) {
+    return null;
+  }
+
+  const subtle = globalThis.crypto?.subtle;
+
+  if (subtle) {
+    const digest = await subtle.digest('SHA-256', new TextEncoder().encode(value));
+
+    return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, '0')).join('');
+  }
+
+  // A page with no secure context and no node under it has no digest at all,
+  // which means no identity — and silence, never a raise at a visitor (#306).
+  if (!isNode()) {
+    return null;
+  }
+
+  try {
+    return require(NODE_CRYPTO).createHash('sha256').update(value).digest('hex');
+  } catch (e) {
+    // A bundler that shims `require` throws here rather than resolving a
+    // builtin. Same answer as every other missing digest: no match key, no
+    // noise — the promise above holds in every shape this module is built into.
+    return null;
+  }
+}
+
+/**
+ * Email, normalized the one way every platform agrees on: trimmed, lowercased.
+ * @param {string} [email]
+ * @returns {string} The normalized address, or '' when there is none.
+ */
+function normalizeEmail(email) {
+  return `${email || ''}`.trim().toLowerCase();
+}
+
+/**
+ * External id: trimmed, and NOTHING else. TikTok's advanced-matching table is
+ * the only spec that states the rule ("Trim any leading and trailing spaces
+ * before hashing and ensure you are consistent with the External ID used"), and
+ * an id is case-SENSITIVE — lowercasing it the way an email is normalized would
+ * hand TikTok a digest of a uid that never existed (#410).
+ * @param {string} [uid] - The account's uid.
+ * @returns {string} The normalized id, or '' when there is none.
+ */
+function normalizeExternalId(uid) {
+  return `${uid || ''}`.trim();
+}
+
+/**
+ * Phone for META: digits only, country code included, no `+` and no punctuation
+ * (Meta's advanced-matching spec hashes the bare number).
+ * @param {string} [phone] - Any written form; Auth's `phoneNumber` is E.164.
+ * @returns {string} The digits, or '' when there is no number.
+ */
+function metaPhone(phone) {
+  return `${phone || ''}`.replace(/\D/g, '');
+}
+
+/**
+ * Phone for TIKTOK: the same digits in E.164, with the leading `+` its pixel
+ * spec requires. Nothing to normalize stays empty rather than becoming a lone
+ * `+`, which would hash to a match key shared by every phoneless account.
+ * @param {string} [phone] - Any written form; Auth's `phoneNumber` is E.164.
+ * @returns {string} The E.164 number, or '' when there is no number.
+ */
+function tiktokPhone(phone) {
+  const digits = metaPhone(phone);
+
+  return digits ? `+${digits}` : '';
+}
+
+module.exports = {
+  sha256,
+  normalizeEmail,
+  normalizeExternalId,
+  metaPhone,
+  tiktokPhone,
+};

package/dist/vendor/analytics/index.js

@@ -0,0 +1,170 @@
+/**
+ * @omega.js/analytics — the ONE analytics consumption surface.
+ *
+ * Client code and backend code alike call `analytics.event('<canonical>', params)`
+ * ([#328](https://github.com/Omega-JS-Stack/omega/issues/328) §Architecture).
+ * What differs underneath — page globals on a browser, the Measurement
+ * Protocol and the conversion APIs on a server — is the TRANSPORT, injected by
+ * the host and invisible to callers.
+ *
+ * One fire walks three steps per provider:
+ *   1. consent — a blocked category's providers never even resolve
+ *   2. adapter — the catalog mapping, or null when the provider has none
+ *   3. transport — the host's seam; a missing global is a silent no-op (#306)
+ *
+ * In development the whole walk prints as ONE line per fire, which is the job
+ * `setupTrackingInterceptors()` did in web core's `libs/dev.js` (they retired
+ * with the rewire).
+ *
+ * Environment is INJECTED, never sniffed — the same seam the rest of the
+ * ecosystem uses (`@omega.js/client`'s `config.environment === 'development'`).
+ * The default is 'production': an unconfigured runtime must never throw an
+ * event-name error at a visitor.
+ */
+
+const { CATALOG, entryFor } = require('./catalog.js');
+const { createConsentGate, GRANT_ALL, CATEGORIES } = require('./consent.js');
+const { createLogger } = require('./logger.js');
+const core = require('./core.js');
+const identity = require('./identity.js');
+const ga4 = require('./adapters/ga4.js');
+const meta = require('./adapters/meta.js');
+const tiktok = require('./adapters/tiktok.js');
+const browser = require('./transports/browser.js');
+
+const logger = createLogger('events');
+
+// Every provider, in fire order. A new platform joins here and in the catalog.
+const ADAPTERS = [ga4, meta, tiktok];
+
+const DEFAULTS = {
+  // No transport = resolve and log, deliver nothing. A host that never calls
+  // configure() is inert rather than guessing at page globals.
+  transport: null,
+  consent: GRANT_ALL,
+  context: {},
+  environment: 'production',
+};
+
+let state = { ...DEFAULTS };
+
+/**
+ * Inject the host's seams. Merges, so a host can wire the transport at boot
+ * and swap the consent gate later.
+ *
+ * @param {object} [options]
+ * @param {object} [options.transport] - { send(descriptor) => boolean }.
+ * @param {object} [options.consent] - A gate from `createConsentGate`.
+ * @param {object} [options.context] - { attribution, consent, runtime } handed to adapters.
+ * @param {string} [options.environment] - 'development' | 'production'.
+ * @returns {object} The resolved state.
+ */
+function configure(options = {}) {
+  state = { ...state, ...options };
+  return { ...state };
+}
+
+/**
+ * Is this runtime in development? Mirrors the client's `config.environment` seam.
+ * @returns {boolean}
+ */
+function isDevelopment() {
+  return state.environment === 'development';
+}
+
+// Walk one provider. Returns { provider, outcome, descriptor? } — never throws.
+function fire(adapter, canonicalName, params, { eventId, providers }) {
+  const provider = adapter.provider;
+
+  // Selection comes before consent: a provider this half does not own was never
+  // going to be asked, whatever the visitor consented to (the same order the
+  // backend's deliverConversion walks).
+  if (providers && !providers.includes(provider)) {
+    return { provider, outcome: 'skipped (not selected)' };
+  }
+
+  if (!state.consent.granted(adapter.CONSENT_CATEGORY)) {
+    return { provider, outcome: `skipped (consent: ${adapter.CONSENT_CATEGORY})` };
+  }
+
+  const descriptor = adapter.resolve(canonicalName, params, state.context);
+  if (!descriptor) {
+    return { provider, outcome: 'skipped (no mapping)' };
+  }
+
+  // The dedupe id rides ON the descriptor, which is what a transport executes:
+  // Meta takes it as the pixel's `eventID` option and TikTok as `event_id`, so
+  // a browser half and a server half of the same conversion collapse into one.
+  if (eventId) {
+    descriptor.eventId = eventId;
+  }
+
+  if (!state.transport) {
+    return { provider, outcome: 'skipped (no transport)', descriptor };
+  }
+
+  // A transport that returns false could not deliver (a blocked or missing
+  // page global). It is a no-op by contract, so the dev log is its only trace.
+  const delivered = state.transport.send(descriptor);
+
+  return { provider, outcome: delivered === false ? 'blocked (no global)' : 'sent', descriptor };
+}
+
+/**
+ * Fire a canonical event across every provider that maps it.
+ *
+ * An unknown name is a PROGRAMMER error — a typo must not silently cost a
+ * conversion — so it throws in development and is logged-and-skipped in
+ * production, where throwing would take the customer's action with it.
+ *
+ * @param {string} canonicalName - A name declared in the catalog.
+ * @param {object} [params] - The canonical params for that event.
+ * @param {object} [options] - The fire's own options.
+ * @param {string} [options.eventId] - The platform dedupe id, for an event whose
+ *   other half fires server-side. Both halves MUST name the same string.
+ * @param {string[]} [options.providers] - Restrict the fire to these providers.
+ *   For a `placement: 'both'` event whose halves do not all deduplicate — this
+ *   half names the providers it owns. Absent = every provider the catalog maps.
+ * @returns {{ event: string, results: object[] }} One result per provider.
+ */
+function event(canonicalName, params = {}, options = {}) {
+  const entry = entryFor(canonicalName);
+
+  if (!entry) {
+    if (isDevelopment()) {
+      throw new Error(`Unknown analytics event "${canonicalName}" — every event is declared in the catalog (@omega.js/analytics/catalog)`);
+    }
+
+    logger.warn(`Unknown event "${canonicalName}" — not in the catalog, skipped`);
+    return { event: canonicalName, results: [] };
+  }
+
+  const results = ADAPTERS.map((adapter) => fire(adapter, canonicalName, params, options));
+
+  if (isDevelopment()) {
+    logger.log(`${canonicalName} → ${results.map((result) => `${result.provider} ${result.outcome}`).join(', ')}`);
+  }
+
+  return { event: canonicalName, results };
+}
+
+module.exports = {
+  // The consumption surface
+  event,
+  configure,
+  isDevelopment,
+
+  // The pure pieces, for the hosts that need one without the facade
+  catalog: CATALOG,
+  entryFor,
+  adapters: { ga4, meta, tiktok },
+  transports: { browser },
+  core,
+  // Identity is not an event, so it never walks the catalog: a host hashes the
+  // signed-in visitor's match keys with these and sets them on its own pixels.
+  identity,
+
+  // The consent seam
+  createConsentGate,
+  CONSENT_CATEGORIES: CATEGORIES,
+};

package/dist/vendor/analytics/logger.js

@@ -0,0 +1,40 @@
+/**
+ * The analytics package's log tag — the ONE identity tag every OMEGA surface
+ * prints: `[@omega.js/analytics:<module>]` ([#12](https://github.com/Omega-JS-Stack/omega/issues/12)).
+ *
+ * This package runs on BOTH surfaces (a browser bundle and a Cloud Function),
+ * so it follows the runtime shape: no timestamp — devtools and Cloud Logging
+ * both stamp their own lines. The twin of @omega.js/client's createLogger,
+ * emitting this package's segment.
+ *
+ * CJS like the rest of the package: the desktop main process and the backend
+ * require() it, the browser bundles import it with standard interop.
+ */
+
+// The package segment — this file IS @omega.js/analytics, so it is a literal.
+const PACKAGE = '@omega.js/analytics';
+
+/**
+ * Create a tagged console for one module, e.g. createLogger('events').
+ * @param {string} module - The module identity segment.
+ * @returns {object} A console-shaped logger whose calls carry the tag.
+ */
+function createLogger(module) {
+  const tag = `[${PACKAGE}:${module}]`;
+
+  // GETTERS returning a BOUND console method, not wrapper arrows: devtools
+  // attributes a line to the frame that called console, so a wrapper would make
+  // every line read as coming from this file. Resolution stays at ACCESS time,
+  // so a test (or a consumer) that swaps console[method] still sees its own stub.
+  const logger = { tag };
+  for (const method of ['log', 'info', 'warn', 'error', 'debug']) {
+    Object.defineProperty(logger, method, {
+      get: () => console[method].bind(console, tag),
+      enumerable: true,
+    });
+  }
+
+  return logger;
+}
+
+module.exports = { createLogger };

package/dist/vendor/analytics/transports/browser.js

@@ -0,0 +1,110 @@
+/**
+ * The browser transport — executes descriptors against the page's own pixel
+ * globals, absorbing the guard semantics of
+ * [#306](https://github.com/Omega-JS-Stack/omega/issues/306).
+ *
+ * `gtag`, `fbq` and `ttq` are page-level snippets, and an ad blocker does not
+ * stub them: it keeps them from ever being defined, so a BARE call throws a
+ * ReferenceError. Every one of these calls sits in front of the thing the
+ * customer just pressed, so that throw takes the action with it (the bug
+ * [#283](https://github.com/Omega-JS-Stack/omega/issues/283) fixed inside the
+ * billing card, found again in 19 other files).
+ *
+ * `typeof` against an undeclared name is the one check that does not throw, and
+ * every provider is checked on its own: blockers are per-list, so a page that
+ * lost Meta still counts Google. A missing or blocked global is a SILENT no-op,
+ * never a throw — the return value is the only trace, so the facade's dev log
+ * can tell "delivered" from "blocked" without anything reaching a visitor.
+ */
+
+// Google Analytics 4 — one command function; the event command is 'event'.
+function sendGoogle(descriptor) {
+  if (typeof gtag !== 'function') {
+    return false;
+  }
+
+  gtag('event', descriptor.name, descriptor.payload);
+  return true;
+}
+
+// Facebook Pixel — one command function; the kind picks the command, which is
+// the whole point of the catalog's standard/custom distinction.
+//
+// A descriptor carrying an `eventId` is one half of a conversion whose other
+// half fires server-side: the Pixel's fourth argument is where its `eventID`
+// goes, and Meta deduplicates on the (event_name, event_id) PAIR. It is passed
+// only when there is one — an `{ eventID: undefined }` option object reads to
+// the Pixel as an id we tried and failed to send.
+function sendMeta(descriptor) {
+  if (typeof fbq !== 'function') {
+    return false;
+  }
+
+  const command = descriptor.kind === 'custom' ? 'trackCustom' : 'track';
+
+  if (descriptor.eventId) {
+    fbq(command, descriptor.name, descriptor.payload, { eventID: descriptor.eventId });
+  } else {
+    fbq(command, descriptor.name, descriptor.payload);
+  }
+
+  return true;
+}
+
+// TikTok Pixel — an object of methods, so the method gets its own check. Its
+// dedupe key is `event_id` in the third argument (the Events API half sends the
+// same string).
+//
+// A descriptor carrying a `method` is the signal TikTok manages ITSELF rather
+// than exposing as a trackable name: the page view, whose documented surface is
+// `ttq.page()` and nothing else ([#409](https://github.com/Omega-JS-Stack/omega/issues/409)).
+// It takes no name and no payload — the pixel reads the page — and a build that
+// does not have the method is the same silent no-op a blocked global is (#306).
+function sendTikTok(descriptor) {
+  if (typeof ttq === 'undefined') {
+    return false;
+  }
+
+  if (descriptor.method) {
+    if (typeof ttq[descriptor.method] !== 'function') {
+      return false;
+    }
+
+    ttq[descriptor.method]();
+    return true;
+  }
+
+  if (typeof ttq.track !== 'function') {
+    return false;
+  }
+
+  if (descriptor.eventId) {
+    ttq.track(descriptor.name, descriptor.payload, { event_id: descriptor.eventId });
+  } else {
+    ttq.track(descriptor.name, descriptor.payload);
+  }
+
+  return true;
+}
+
+const SENDERS = {
+  ga4: sendGoogle,
+  meta: sendMeta,
+  tiktok: sendTikTok,
+};
+
+/**
+ * Execute one descriptor against the page globals.
+ * @param {object} descriptor - { provider, name, kind, payload, userData }.
+ * @returns {boolean} true when the provider's global was there to take it.
+ */
+function send(descriptor) {
+  const sender = SENDERS[descriptor.provider];
+  if (!sender) {
+    return false;
+  }
+
+  return sender(descriptor);
+}
+
+module.exports = { send };