@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/analytics-events.js

@@ -0,0 +1,650 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * The one GA4 event taxonomy, shared by the marketing site (tenant runtime)
+ * and the console (AGL-1561). See `docs/ANALYTICS.md` for the event map and
+ * which GTM-plan §6 metric each event serves.
+ *
+ * ## Why this module exists
+ *
+ * Before it, every GA event in the repo was an ad-hoc
+ * `;(window as any).gtag?.('event', 'name', {...})` — five of them across the
+ * marketing and commerce plugins, plus bare string literals passed to Firebase
+ * `logEvent` in the console. Nothing checked the names, nothing checked the
+ * params, and a typo produced a silently-missing metric rather than an error.
+ * That is the failure mode analytics is worst at surfacing: the number simply
+ * reads zero, and zero is indistinguishable from "nobody did it".
+ *
+ * So the names and their params are a TYPE here ({@link AnalyticsEventParams}),
+ * and `trackEvent` is generic over it: a misspelled event name or a missing
+ * required param is a compile error.
+ *
+ * That sweep missed five (AGL-1591, closed): the commerce plugin's
+ * `view_item` / `add_to_cart` / `begin_checkout` and the marketing runtime's
+ * `aglyn_overlay` / `aglyn_experiment`. `window.gtag` is now called in exactly
+ * two places in the repo — {@link deliver} below, and `readGaClientId` above,
+ * which reads rather than sends.
+ *
+ * ## Reserved names
+ *
+ * Where GA4 has a recommended event we use its exact name and its exact param
+ * spelling — `sign_up`, `login`, `generate_lead`, `begin_checkout`,
+ * `purchase`, `select_content` — so the built-in reports, the funnel
+ * explorations and the "key events" toggles work without custom definitions.
+ * Custom snake_case names appear only where GA4 has no standard: the four
+ * activation events, which are Aglyn-specific product milestones.
+ *
+ * ## Consent (AGL-1498) — the gate is that gtag never loads
+ *
+ * On tenant sites, including aglyn.com itself, `site-analytics.tsx` renders the
+ * gtag `<Script>` pair ONLY when the recorded consent state grants analytics.
+ * There is therefore no `window.gtag` at all for a visitor who has not granted,
+ * and {@link trackEvent} drops the event on the floor.
+ *
+ * It drops it — it does not QUEUE it. That distinction is the whole point and
+ * `analytics-events.spec.ts` asserts it: an event fired before consent is gone
+ * for good, and does not reappear when a later grant loads gtag. A queue would
+ * quietly convert "we did not track you" into "we tracked you and waited", and
+ * a replayed hit carries the pre-consent timestamp and page into GA, which is
+ * exactly the thing the consent gate exists to prevent. Deliberately no retry,
+ * no buffer, no flush-on-grant.
+ *
+ * ## No PII, enforced rather than promised
+ *
+ * Every payload passes through {@link sanitizeEventParams} before it reaches a
+ * transport: an exact-key denylist drops the identity-bearing params someone
+ * will eventually add by reflex (`email`, `org_name`, `first_name`, ...), any
+ * value that looks like an email address drops its key entirely, URLs are
+ * reduced to origin + pathname so query strings can never smuggle a token or
+ * an address, and strings are length-capped. The console separately sets a
+ * `user_id` — that is an opaque Firebase uid and is the one identifier GA is
+ * allowed to hold.
+ *
+ * Sanitizing here rather than at each call site is the point: a new call site
+ * cannot forget.
+ *
+ * ## Authored events (AGL-1587)
+ *
+ * One call site cannot use the taxonomy at all: the `trackGaEvent` action step,
+ * whose event name and params are typed by a SITE AUTHOR in the interaction
+ * builder. A closed union cannot contain a name nobody has written yet, so
+ * {@link trackAuthoredEvent} is the escape hatch — and it is deliberately the
+ * only one, so that untrusted input still passes {@link sanitizeEventParams}
+ * rather than reaching `window.gtag` raw.
+ *
+ * The test for which door an event uses is WHO NAMED IT, not whether GA4
+ * recommends the name. `aglyn_overlay` and `aglyn_experiment` are outside GA4's
+ * recommended set and were candidates for the hatch (AGL-1591); they are in the
+ * union instead, because a developer wrote their names and their keys, so they
+ * can have compile-time checking — and because the hatch guarantees the
+ * opposite of what they need. {@link resolveAuthoredEventName} refuses any name
+ * we send — the union AND the server-only names beside it — precisely so that
+ * "not one of ours" means "authored"; put our own events through the hatch and
+ * that stops being true, authored hits stop being separable from ours in
+ * reports, and an authored `aglyn_experiment` step starts voting in the
+ * experiment that decides which variant ships.
+ */ /**
+ * Read the browser's GA `client_id` — the identifier that ties a hit to a GA
+ * user and session.
+ *
+ * Needed because `purchase` is sent SERVER-side, from the Stripe webhook,
+ * where the authoritative money is (see `ga4-measurement-protocol.ts`). The
+ * Measurement Protocol requires a `client_id` and a server cannot know one,
+ * so it is captured here when checkout starts and carried on the Stripe
+ * object's metadata. Without it the revenue still lands, but attached to a
+ * synthetic user with no acquisition session — which is exactly the campaign
+ * attribution the whole exercise is for.
+ *
+ * Resolves to null rather than hanging when gtag is absent (no consent, an ad
+ * blocker, analytics not configured) or slow to answer. The 500ms cap matters:
+ * this sits directly in front of a checkout redirect, and analytics must never
+ * be able to delay a payment.
+ */ export function readGaClientId(measurementId) {
+    return new Promise((resolve)=>{
+        if (typeof window === 'undefined' || !measurementId) return resolve(null);
+        const gtag = window.gtag;
+        if (typeof gtag !== 'function') return resolve(null);
+        let settled = false;
+        const finish = (value)=>{
+            if (settled) return;
+            settled = true;
+            resolve(value);
+        };
+        // Never let a missing callback strand the checkout.
+        setTimeout(()=>finish(null), 500);
+        try {
+            ;
+            gtag('get', measurementId, 'client_id', (id)=>finish(typeof id === 'string' && id ? id : null));
+        } catch (unused) {
+            finish(null);
+        }
+    });
+}
+let configuredTransport = null;
+/**
+ * Register the transport for this surface. The console calls this once, with
+ * Firebase's `logEvent`, because the console's GA is Firebase-initialised and
+ * its `user_id`/user-property state lives on the Firebase Analytics instance —
+ * poking `window.gtag` directly there would emit hits that miss it.
+ *
+ * The tenant runtime deliberately does NOT call this: the plugin bundles run
+ * in their own realm and do not share this module instance with the host app,
+ * so a module-scope singleton would be invisible to exactly the call sites
+ * that need it (the form and newsletter elements). `window.gtag` is the only
+ * thing genuinely shared across that boundary, and it is also the consent
+ * gate, which makes the fallback the correct primary path there rather than a
+ * degraded one.
+ */ export function configureAnalyticsTransport(transport) {
+    configuredTransport = transport;
+}
+/** Test seam — drops the registered transport. */ export function resetAnalyticsTransport() {
+    configuredTransport = null;
+}
+/**
+ * Param keys that must never reach GA, matched EXACTLY. Substring matching
+ * would be wrong in both directions: it would drop the legitimate
+ * `form_name` / `item_name` / `link_domain`, and it would still miss a
+ * creatively-named new one. The value scan below is the backstop for those.
+ */ const DENIED_PARAM_KEYS = new Set([
+    'email',
+    'email_address',
+    'user_email',
+    'name',
+    'full_name',
+    'first_name',
+    'last_name',
+    'user_name',
+    'username',
+    'customer_name',
+    'org_name',
+    'organization_name',
+    'company',
+    'company_name',
+    'phone',
+    'phone_number',
+    'address',
+    'street',
+    'postal_code',
+    'zip',
+    'ip',
+    'ip_address'
+]);
+/** Deliberately loose — this is a "does it smell like an address" test. */ const EMAIL_SHAPED = /[^\s@]+@[^\s@]+\.[^\s@]+/;
+/**
+ * GA4 truncates param values at 100 chars anyway; do it ourselves, visibly.
+ *
+ * Exported because an AUTHOR types some of these (the `trackGaEvent` step's
+ * parameters), and the field they type into caps its input at the same number
+ * — the truncation point and the affordance that describes it have to be one
+ * value, or the editor promises a length the delivery quietly shortens.
+ */ export const ANALYTICS_PARAM_MAX_LENGTH = 100;
+function scrubValue(value) {
+    let candidate = value;
+    if (/^https?:\/\//i.test(candidate)) {
+        try {
+            const url = new URL(candidate);
+            // Origin + pathname only: a query string is where a session token, a
+            // signup email or a Stripe id ends up, and none of them belong in GA.
+            candidate = `${url.origin}${url.pathname}`;
+        } catch (unused) {
+            return null;
+        }
+    }
+    // AFTER the URL reduction, not before. A page URL routinely carries an
+    // address in its query (`?email=…` on a prefilled signup link), and testing
+    // the raw string would throw the whole URL away for PII that the reduction
+    // was about to remove — losing the legitimate page dimension to protect
+    // something already protected. Testing the REDUCED value still catches an
+    // address embedded in the path itself, which the reduction keeps.
+    if (EMAIL_SHAPED.test(candidate)) return null;
+    return candidate.slice(0, ANALYTICS_PARAM_MAX_LENGTH);
+}
+/**
+ * Strip anything identity-bearing from an event payload. Exported so
+ * `analytics-events.spec.ts` can assert the guarantee directly rather than
+ * only through `trackEvent`.
+ */ export function sanitizeEventParams(params) {
+    const safe = {};
+    if (!params) return safe;
+    for (const [key, value] of Object.entries(params)){
+        if (DENIED_PARAM_KEYS.has(key.toLowerCase())) continue;
+        if (value === undefined || value === null) continue;
+        if (typeof value === 'string') {
+            const scrubbed = scrubValue(value);
+            if (scrubbed === null || scrubbed === '') continue;
+            safe[key] = scrubbed;
+            continue;
+        }
+        if (typeof value === 'number' || typeof value === 'boolean') {
+            safe[key] = value;
+            continue;
+        }
+        if (Array.isArray(value)) {
+            // `items` — sanitize each entry with the same rules.
+            safe[key] = value.map((entry)=>entry && typeof entry === 'object' ? sanitizeEventParams(entry) : entry);
+            continue;
+        }
+        if (typeof value === 'object') {
+            safe[key] = sanitizeEventParams(value);
+        }
+    // Anything else (function, symbol) is dropped.
+    }
+    return safe;
+}
+/**
+ * Fire a GA4 event.
+ *
+ * Never throws and never queues. If the surface has no transport and no
+ * `window.gtag` — which on a tenant site means the visitor has not granted
+ * analytics consent — the event is DROPPED, permanently. See the module
+ * comment for why a queue would be the wrong answer.
+ */ export function trackEvent(name, params) {
+    deliver(name, sanitizeEventParams(params));
+}
+/**
+ * How long a navigation may be held waiting for a hit to reach gtag. Short
+ * enough to be invisible next to a Stripe redirect, long enough to cover a
+ * Firebase Analytics init that has not settled yet.
+ */ const NAVIGATION_FLUSH_TIMEOUT_MS = 300;
+/**
+ * Fire a GA4 event and resolve once it has been HANDED TO gtag — for the call
+ * sites that navigate away in the same tick (AGL-1580).
+ *
+ * ## What was actually losing the event
+ *
+ * Not the transport, which was the obvious suspect and the wrong one. Measured
+ * against real gtag.js with every transport interposed: gtag flushes its queue
+ * on pagehide through `fetch(..., { keepalive: true })`, which is precisely the
+ * mechanism that survives a document teardown. Once a hit reaches gtag, a
+ * navigation does not destroy it — and `transport_type: 'beacon'`, the standard
+ * answer, therefore fixes nothing here.
+ *
+ * What is lost is the hit that never REACHES gtag. Firebase's `logEvent` is
+ * `async` and awaits the SDK's initialization promise before calling gtag
+ * (`@firebase/analytics/dist/index.cjs.js`, `logEvent$1`). While that promise is
+ * already settled the continuation is a microtask, microtasks drain before the
+ * queued navigation task, and the hit gets out. While it is still PENDING — the
+ * first checkout of a fresh session, exactly the case that has never yet been
+ * seen in the property — the continuation is scheduled behind the navigation
+ * and never runs at all. Measured both ways: pending init loses the event,
+ * awaiting it delivers it, nothing else changed.
+ *
+ * ## Why a timeout rather than a bare await
+ *
+ * A bare `await` on `logEvent` hands the user's redirect to the analytics
+ * stack. When the analytics host is blocked — an ad blocker, a corporate proxy,
+ * a consent tool that never loads — Firebase's initialization promise can stay
+ * pending indefinitely, and the checkout would hang on a metric. So the wait is
+ * RACED against {@link NAVIGATION_FLUSH_TIMEOUT_MS}: a blocked analytics stack
+ * costs the redirect 300ms once and then it proceeds, which is the same outcome
+ * the caller had before this existed. Never rejects, for the same reason
+ * {@link trackEvent} never throws.
+ *
+ * On a surface with no registered transport — the tenant runtime and the plugin
+ * bundles, which go straight to `window.gtag` — delivery is synchronous, so
+ * this resolves immediately and costs the storefront checkout nothing at all.
+ */ export async function trackEventBeforeNavigation(name, params) {
+    const delivered = deliver(name, sanitizeEventParams(params));
+    // Synchronous transport (or none): already handed over, nothing to wait for.
+    if (!delivered || typeof delivered.then !== 'function') return;
+    await Promise.race([
+        // A transport that REJECTS must not become an unhandled rejection, and
+        // must not hold the navigation either — it has already failed.
+        Promise.resolve(delivered).catch(()=>undefined),
+        new Promise((resolve)=>setTimeout(resolve, NAVIGATION_FLUSH_TIMEOUT_MS))
+    ]);
+}
+/**
+ * Build the ONE `begin_checkout` payload, for every surface that starts a
+ * checkout (AGL-1591).
+ *
+ * ## Why a constructor and not just the type
+ *
+ * Two surfaces fire this name: the console, when a plan checkout starts, and a
+ * tenant storefront, when a cart checks out. Until AGL-1591 the storefront
+ * fired it raw and carried `value`/`currency` only, so ONE event name arrived
+ * in two shapes — and a `begin_checkout` breakdown showed two populations that
+ * could not be compared, with the storefront half missing the `items` the GA4
+ * ecommerce funnel is built on. Routing both through {@link trackEvent} makes
+ * the compiler settle the KEYS.
+ *
+ * It does not settle the NUMBER, which is the other way two call sites of one
+ * event diverge, and the more dangerous one because nothing about it looks
+ * wrong: the console's annual plans are priced per-month-billed-yearly, so its
+ * `value` is twelve of them, and that only stayed right because a comment said
+ * so. Here `value` DERIVES from the items unless a caller states a different
+ * one — a cart states its subtotal, which is authoritative after discounts —
+ * so "what the customer is about to be charged" has one definition rather than
+ * one per surface.
+ *
+ * Server-safe: pure, no DOM, so the Measurement Protocol sender can compose
+ * the matching `purchase` items from the same shapes.
+ */ export function buildBeginCheckoutParams(input) {
+    return _extends({}, priceItems(input), input.billingInterval ? {
+        billing_interval: input.billingInterval
+    } : {});
+}
+/**
+ * The `currency`/`value`/`items` triple every GA4 ecommerce step shares.
+ *
+ * Private, because a caller should reach for the named builder for the event
+ * it is about to send: the names differ in what they mean by `value` even
+ * though the arithmetic is identical, and the JSDoc on each is where that is
+ * written down.
+ */ function priceItems(input) {
+    var _input_items, _input_currency, _input_value;
+    const items = (_input_items = input.items) != null ? _input_items : [];
+    const summed = items.reduce((total, item)=>{
+        var _item_price, _item_quantity;
+        return total + ((_item_price = item.price) != null ? _item_price : 0) * ((_item_quantity = item.quantity) != null ? _item_quantity : 1);
+    }, 0);
+    return {
+        currency: (_input_currency = input.currency) != null ? _input_currency : 'USD',
+        // Money, so two decimals: a float sum of cents-derived prices produces
+        // `59.99999999999999`, and GA would report that verbatim.
+        value: Math.round(((_input_value = input.value) != null ? _input_value : summed) * 100) / 100,
+        items
+    };
+}
+/**
+ * Build `view_cart` — the shopper is looking at the cart's contents.
+ *
+ * `value` is the cart's subtotal as the SERVER priced it, which is what makes
+ * this comparable with the `begin_checkout` the same cart sends moments later:
+ * two steps of one funnel that disagreed about the size of the same cart would
+ * read as shoppers editing it between screens.
+ */ export function buildViewCartParams(input) {
+    return priceItems(input);
+}
+/**
+ * Build `add_to_cart` — one product going in, not the cart's new total.
+ *
+ * `value` is what was JUST ADDED (`price * quantity`), which is GA4's
+ * definition and the only one that makes the metric additive: summing a
+ * running cart total over a session would count the first item once per
+ * subsequent add.
+ *
+ * Callers that cannot price the line — a quick-add with no resolved variant —
+ * pass items alone and the pair is omitted rather than reported as zero. A
+ * zero here would read as a free product in the merchant's report.
+ */ export function buildAddToCartParams(input) {
+    const priced = priceItems(input);
+    if (!(priced.value > 0)) return {
+        items: priced.items
+    };
+    return priced;
+}
+/**
+ * Decide `site_published`'s `first_publish` from the host's routing map as it
+ * stood BEFORE the route being published was registered (AGL-1588).
+ *
+ * ## What "first" means, and why it is defined once
+ *
+ * Three call sites report `site_published` — `publishScreenRoute`, the
+ * besigner's one-click publish, and the scheduled publish executor, the last
+ * of which is server-side and sends over the Measurement Protocol. A
+ * breakdown is only worth registering if all three mean the same thing by it,
+ * and "first" has several plausible readings. This is the one they share:
+ *
+ * **The host had no live route at all before this one.** Not "first for the
+ * org" — that needs a cross-host query the server path cannot make, and the
+ * scheduled sender's client id is derived from the HOST anyway, so an org is
+ * not a thing it can see. Not "first for this screen" either, which would be
+ * true of every second page a site adds and would make the dimension a
+ * synonym for the event.
+ *
+ * So the metric it separates is the GTM §6 activation one: `first_publish:
+ * true` counts sites that came alive, where the event alone counts publishes.
+ *
+ * ## The one dishonesty, and why it does not matter
+ *
+ * Unpublishing every route and publishing again reports `true` a second time.
+ * Detecting that needs publish history the routing map does not keep. It is
+ * harmless for the metric it exists for, because activation is read as the
+ * share of USERS who ever sent `first_publish: true`, and a user counted twice
+ * is still one user.
+ *
+ * Callers pass what they already hold — the live-subscribed map in the
+ * console, a read snapshot on the server — and never a map read back AFTER
+ * the write, which is never empty.
+ */ export function isFirstPublishedRoute(routing) {
+    return Object.keys(routing != null ? routing : {}).length === 0;
+}
+/**
+ * The one delivery path, shared by {@link trackEvent} and
+ * {@link trackAuthoredEvent}. Takes an ALREADY-sanitized payload — every
+ * caller sanitizes first, which is what keeps "a new call site cannot forget"
+ * true of the authored path too.
+ */ function deliver(name, safe) {
+    try {
+        if (configuredTransport) {
+            // The transport's name parameter is the taxonomy union, which an
+            // authored name is by definition outside. Nominal only: the console is
+            // the sole surface that registers one and it has no authored events
+            // (the interaction runtime is tenant-side), and Firebase `logEvent`
+            // takes an arbitrary string regardless.
+            // Returned, not discarded (AGL-1580). A transport may be ASYNC —
+            // Firebase's `logEvent` awaits the SDK's initialization promise before it
+            // reaches gtag at all — and a caller that is about to navigate has to be
+            // able to wait for it. See `trackEventBeforeNavigation`.
+            return configuredTransport(name, safe);
+        }
+        if (typeof window === 'undefined') return;
+        const gtag = window.gtag;
+        if (typeof gtag !== 'function') return;
+        gtag('event', name, safe);
+    } catch (unused) {
+    // Analytics never breaks the page — the same posture as the error beacon
+    // and the pageview beacon.
+    }
+}
+/**
+ * The taxonomy's names at RUN time. A `Record<AnalyticsEventName, true>` rather
+ * than a hand-kept array so the compiler enforces both directions: adding an
+ * event to {@link AnalyticsEventParams} without adding it here is a missing-key
+ * error, and a name here that is not in the taxonomy is an excess-property one.
+ *
+ * It exists for {@link trackAuthoredEvent}, which has to refuse these names —
+ * a drifting copy would silently re-open the collision it is here to close.
+ */ const TAXONOMY_EVENT_NAMES = {
+    sign_up: true,
+    login: true,
+    generate_lead: true,
+    select_content: true,
+    org_created: true,
+    host_created: true,
+    site_published: true,
+    stripe_connected: true,
+    begin_checkout: true,
+    purchase: true,
+    view_item: true,
+    add_to_cart: true,
+    view_cart: true,
+    aglyn_overlay: true,
+    aglyn_experiment: true,
+    click: true,
+    assistant_message_sent: true,
+    assistant_feedback: true,
+    assistant_proposal_shown: true,
+    assistant_proposal_confirmed: true,
+    ai_job_completed: true,
+    ai_job_failed: true,
+    churn_survey_submitted: true,
+    downsell_accepted: true,
+    winback_discount_accepted: true,
+    cancellation_completed: true,
+    plan_downgrade_scheduled: true,
+    plan_upgraded: true
+};
+/** The taxonomy, enumerable. */ export const ANALYTICS_EVENT_NAMES = Object.keys(TAXONOMY_EVENT_NAMES);
+/**
+ * Event names WE send that this module's union cannot hold, because nothing
+ * client-side ever fires them: they are emitted only by the Measurement
+ * Protocol sender (`ga4-measurement-protocol.ts`), from a Stripe webhook.
+ *
+ * They still have to be RESERVED against authored names, and the reason is
+ * the same one that puts `purchase` in the union — only less obvious, which
+ * is why it was missed. `aglyn.com` is itself a tenant site, pointed at the
+ * platform measurement id (`site-analytics.tsx`), so an authored
+ * `trackGaEvent` step on our own marketing site lands in the SAME property as
+ * these server hits. An authored `refund` does not merely add noise: GA4
+ * treats `refund` as ecommerce and SUBTRACTS its `value` from reported
+ * revenue, so a mistyped step could walk real money out of the report — the
+ * `purchase` hazard, running in the direction nobody audits.
+ *
+ * Kept as a separate list rather than folded into {@link AnalyticsEventParams}
+ * on purpose: adding them to the union would give {@link trackEvent} a
+ * client-side door to events that must only ever come from the server, where
+ * the authoritative money is. A name here is ours, is never sent from a
+ * browser, and is never available to an author.
+ *
+ * This list is the reason "not in {@link ANALYTICS_EVENT_NAMES}" is NOT on its
+ * own a sound test for "authored" — use {@link isReservedAnalyticsEventName}.
+ */ const SERVER_ONLY_EVENT_NAMES = new Set([
+    'refund',
+    'subscription_cancelled'
+]);
+/**
+ * Every event name Aglyn itself sends, from any surface — the union plus the
+ * server-only names above. Exported so a caller can ask the question the two
+ * separate lists no longer answer alone.
+ */ export function isReservedAnalyticsEventName(name) {
+    return TAXONOMY_EVENT_NAMES[name] === true || SERVER_ONLY_EVENT_NAMES.has(name);
+}
+/**
+ * GA4's own reserved event names — GA drops a hit that uses one, so sending it
+ * is not pollution but silence, which is the worse failure of the two because
+ * nothing anywhere says so.
+ */ const GA4_RESERVED_EVENT_NAMES = new Set([
+    'ad_activeview',
+    'ad_click',
+    'ad_exposure',
+    'ad_impression',
+    'ad_query',
+    'ad_reward',
+    'adunit_exposure',
+    'app_background',
+    'app_clear_data',
+    'app_exception',
+    'app_install',
+    'app_remove',
+    'app_store_refund',
+    'app_store_subscription_cancel',
+    'app_store_subscription_convert',
+    'app_store_subscription_renew',
+    'app_update',
+    'app_upgrade',
+    'dynamic_link_app_open',
+    'dynamic_link_app_update',
+    'dynamic_link_first_open',
+    'error',
+    'first_open',
+    'first_visit',
+    'in_app_purchase',
+    'notification_dismiss',
+    'notification_foreground',
+    'notification_open',
+    'notification_receive',
+    'os_update',
+    'screen_view',
+    'session_start',
+    'user_engagement'
+]);
+/** GA4 reserves these prefixes outright, whatever follows them. */ const GA4_RESERVED_PREFIXES = [
+    'firebase_',
+    'google_',
+    'ga_'
+];
+/** GA4's hard limit on an event name. Over it, GA drops the event. */ const MAX_EVENT_NAME_LENGTH = 40;
+/**
+ * Put an authored event name through GA4's naming rules and our own.
+ *
+ * Normalization is forgiving on purpose: `"CTA Click!"` becomes `cta_click`
+ * and still reports, where GA would have dropped it. Names already sitting in
+ * published sites were never validated, so refusing them outright would delete
+ * working metrics from a paying customer's property to fix a formatting nit.
+ *
+ * Collisions, in contrast, are refused rather than rewritten. On a tenant site
+ * the authored events and OUR events (`generate_lead` from the form element,
+ * `select_content`/`click` from the link listener) land in the same property,
+ * so an authored `purchase` does not merely add noise — it mixes hand-authored
+ * hits into a real revenue number. Refusing is also what keeps authored events
+ * separable in reports: an event that is not one of {@link ANALYTICS_EVENT_NAMES}
+ * is, by construction, authored.
+ *
+ * Deliberately NOT prefixed (`site_*`) to achieve that separation. A prefix
+ * would rename events already flowing into customers' properties and break
+ * every report and key-event conversion configured on the old name — a
+ * migration cost paid by people who did nothing wrong.
+ */ export function resolveAuthoredEventName(raw) {
+    const normalized = String(raw != null ? raw : '').trim().toLowerCase()// Anything GA4 does not allow in a name becomes an underscore...
+    .replace(/[^a-z0-9_]+/g, '_')// ...and a name must START with a letter, so drop what precedes one.
+    .replace(/^[^a-z]+/, '').replace(/_{2,}/g, '_').slice(0, MAX_EVENT_NAME_LENGTH)// Truncation can leave a trailing underscore; so can the substitution.
+    .replace(/_+$/, '');
+    if (!normalized) return {
+        name: null,
+        reason: 'unusable'
+    };
+    if (isReservedAnalyticsEventName(normalized) || GA4_RESERVED_EVENT_NAMES.has(normalized) || GA4_RESERVED_PREFIXES.some((prefix)=>normalized.startsWith(prefix))) {
+        return {
+            name: null,
+            reason: 'reserved'
+        };
+    }
+    return {
+        name: normalized
+    };
+}
+/** One warning per distinct name per page load — an `everyTime` automation
+ * would otherwise fill the console with the same line. */ const warnedAuthoredNames = new Set();
+/**
+ * Fire an event whose name and params were written by a SITE AUTHOR, not by a
+ * developer — today only the `trackGaEvent` action step (AGL-1587).
+ *
+ * Same consent gate, same sanitizer, same drop-never-queue posture as
+ * {@link trackEvent}; the only difference is that the name is checked at run
+ * time instead of by the compiler, because there is no compiler between the
+ * interaction builder and here.
+ *
+ * A refused event is dropped and warned about in the console rather than
+ * surfaced in the page. Nothing here can reach the author — the code is
+ * running for a VISITOR of their site, and turning the author's configuration
+ * mistake into something a visitor sees would be a worse bug than the missing
+ * metric. The author-facing half lives in `validateHostAction`, which refuses
+ * to save a name this function would refuse to send, so a silent drop should
+ * only ever happen to a step authored before AGL-1587.
+ */ export function trackAuthoredEvent(name, params) {
+    const resolved = resolveAuthoredEventName(name);
+    if (!resolved.name) {
+        const key = String(name != null ? name : '');
+        if (!warnedAuthoredNames.has(key)) {
+            warnedAuthoredNames.add(key);
+            try {
+                console.warn(`[aglyn] analytics: the event "${key}" was not sent — ` + (resolved.reason === 'reserved' ? 'that name is reserved. Rename the step in the interaction builder.' : 'an event name must start with a letter.'));
+            } catch (unused) {
+            // A console that throws is still not worth breaking the page for.
+            }
+        }
+        return;
+    }
+    deliver(resolved.name, sanitizeEventParams(params != null ? params : undefined));
+}
+/** Test seam — forgets which authored names have already been warned about. */ export function resetAuthoredEventWarnings() {
+    warnedAuthoredNames.clear();
+}
+
+//# sourceMappingURL=analytics-events.js.map