@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/analytics-events.d.ts

@@ -0,0 +1,744 @@
+/**
+ * @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 declare function readGaClientId(measurementId: string | undefined | null): Promise<string | null>;
+/** Which door an account was created through (AGL-1497 enumerates all four). */
+export type SignUpMethod = 'password' | 'google_popup' | 'google_redirect' | 'google_signin';
+/** How a returning user authenticated. */
+export type LoginMethod = 'password' | 'google_popup' | 'google_redirect' | 'sso' | 'passkey';
+/**
+ * A GA4 `items` entry. Only the fields we actually populate — GA accepts more,
+ * but an unpopulated field is a column of nulls in every report.
+ */
+export interface AnalyticsItem {
+    /** Opaque identifier — a price id, plan key or marketplace listing id. */
+    item_id: string;
+    /** Human-readable product name. NEVER a customer or org name. */
+    item_name: string;
+    /** Distinguishes the revenue lines: `subscription` vs `marketplace`. */
+    item_category?: string;
+    price?: number;
+    quantity?: number;
+}
+/**
+ * The taxonomy. Adding an event means adding a line here first — which is what
+ * makes `docs/ANALYTICS.md` checkable against the code rather than aspirational.
+ */
+export interface AnalyticsEventParams {
+    /**
+     * GA4 recommended. Real account creation only, never a sign-in.
+     *
+     * The three campaign params are optional and come from
+     * `campaignEventParams` (AGL-1731) — present when the signup URL named a
+     * campaign, absent entirely otherwise. They are what lets a September ad
+     * spend be evaluated: without them a paid click, an organic visit and a
+     * partner link arrive indistinguishable and the money cannot be traced to
+     * an account. Named `campaign_*` rather than `utm_*` because these are our
+     * own registered dimensions and the `utm_` spellings belong to GA's
+     * automatic campaign collection.
+     */
+    sign_up: {
+        method: SignUpMethod;
+        campaign_source?: string;
+        campaign_medium?: string;
+        campaign_name?: string;
+    };
+    /** GA4 recommended. Returning user only. */
+    login: {
+        method: LoginMethod;
+    };
+    /**
+     * GA4 recommended. Fired on a SUCCESSFUL form submission — never on click,
+     * never on a validation failure. `form_name` is the author-given form name,
+     * which is site content and not personal data.
+     */
+    generate_lead: {
+        form_name: string;
+        form_location?: string;
+    };
+    /**
+     * GA4 recommended. A CTA click, with the section that produced it.
+     *
+     * Fired by `analytics-link-clicks.ts` (AGL-1562) from a delegated listener,
+     * not per call site: an authored page has no code to add a handler to.
+     */
+    select_content: {
+        content_type: string;
+        content_id: string;
+        /** Which product surface — see `click.surface`. */
+        surface?: string;
+    };
+    /** Custom: no GA4 equivalent. A new organization exists. */
+    org_created: {
+        plan?: string;
+    };
+    /** Custom: no GA4 equivalent. A new site/host exists. */
+    host_created: Record<string, never>;
+    /**
+     * Custom: no GA4 equivalent, and the GTM plan's headline activation metric.
+     * A site actually went live.
+     */
+    site_published: {
+        first_publish?: boolean;
+    };
+    /** Custom: no GA4 equivalent. Stripe Connect onboarding completed. */
+    stripe_connected: Record<string, never>;
+    /** GA4 recommended. A plan checkout started. */
+    begin_checkout: {
+        currency: string;
+        value: number;
+        items: AnalyticsItem[];
+        /** `monthly` | `annual` — feeds the §6 annual-mix metric. */
+        billing_interval?: string;
+    };
+    /**
+     * GA4 recommended. A payment actually succeeded. `transaction_id` is the
+     * Stripe object id and is what makes the event idempotent in GA: GA4
+     * de-duplicates purchases by transaction id, so a webhook retry cannot
+     * inflate revenue.
+     */
+    purchase: {
+        transaction_id: string;
+        currency: string;
+        value: number;
+        items: AnalyticsItem[];
+        billing_interval?: string;
+        /**
+         * GA4's shipping charged on the transaction, in currency units. Optional
+         * because only a tenant STOREFRONT purchase ships anything — a plan or a
+         * marketplace purchase has no shipping to report and omits it.
+         *
+         * There is deliberately no sibling `tax` (AGL-1639, AGL-1641). The
+         * asymmetry is the point and is not an inconsistency to tidy away:
+         * `shipping` is a COMPONENT of the `value` beside it, so reporting it
+         * describes that value; `tax` is not, because `value` is already ex-tax,
+         * so reporting it would assert a relationship that does not hold and
+         * invite the subtraction that removes tax a second time.
+         */
+        shipping?: number;
+    };
+    /**
+     * GA4 recommended. A product detail page was viewed on a tenant storefront.
+     *
+     * Only `items`, and only `item_id`/`item_name` within it: those are the two
+     * fields the storefront actually has at this point, and an unpopulated
+     * `price`/`item_category` would be a column of nulls in the merchant's
+     * reports. The item id is the PRODUCT id — the same id `add_to_cart` and
+     * `begin_checkout` use — which is what lets GA join the three into one
+     * per-product funnel.
+     */
+    view_item: {
+        items: AnalyticsItem[];
+    };
+    /**
+     * GA4 recommended. A storefront product was added to the cart.
+     *
+     * `currency`/`value` are optional because GA4 pairs them — a `value` with no
+     * `currency` is dropped by GA — so they travel together or not at all, and
+     * {@link buildAddToCartParams} is what keeps that true. They are populated
+     * wherever the surface holds a server-priced figure: the product detail
+     * block knows the resolved variant's price and the chosen quantity, so the
+     * merchant's "value added to cart" is a real number rather than the empty
+     * column an items-only hit produces.
+     */
+    add_to_cart: {
+        currency?: string;
+        value?: number;
+        items: AnalyticsItem[];
+    };
+    /**
+     * GA4 recommended. The shopper looked at their cart — the funnel step
+     * between {@link AnalyticsEventParams.add_to_cart} and
+     * {@link AnalyticsEventParams.begin_checkout}, and the one GA4's own
+     * shopping-behavior report reads to tell "never opened the cart" apart from
+     * "opened it and did not check out". Without it those two collapse into one
+     * drop, and the merchant cannot tell a discovery problem from a pricing one.
+     *
+     * Fired when the cart is actually ON SCREEN carrying lines — a drawer that
+     * opened, or an inline cart block that resolved — never on the badge render
+     * that every page of a storefront performs. An empty cart is not a view of
+     * anything and reports nothing.
+     */
+    view_cart: {
+        currency: string;
+        value: number;
+        items: AnalyticsItem[];
+    };
+    /**
+     * Custom: no GA4 equivalent. An announcement bar or popup was shown,
+     * dismissed or clicked on a tenant site (AGL-200/271).
+     *
+     * In the taxonomy rather than {@link trackAuthoredEvent} even though it is
+     * not a GA4 recommended name: the name and every key here are written by US,
+     * which is exactly what the closed union is for. See the note on
+     * {@link trackAuthoredEvent} for why the two must not be mixed.
+     */
+    aglyn_overlay: {
+        overlay_action: string;
+        overlay_id?: string;
+    };
+    /**
+     * Custom: no GA4 equivalent. An experiment exposure or conversion
+     * (AGL-253). `experiment_action` is `exposure` | `conversion`.
+     *
+     * Being in the union also makes the name RESERVED against authored events,
+     * which matters more here than anywhere else in this file: these are the
+     * counts that decide which variant wins, and a hand-authored
+     * `aglyn_experiment` step would silently vote in that election.
+     */
+    aglyn_experiment: {
+        experiment_id: string;
+        variant_id: string;
+        experiment_action: string;
+    };
+    /**
+     * GA4 recommended-ish. Outbound click to docs, GitHub, etc. Fired by
+     * `analytics-link-clicks.ts` (AGL-1562) rather than at a call site.
+     */
+    click: {
+        link_domain: string;
+        link_id?: string;
+        /**
+         * Which product surface produced the click. GA's built-in Hostname
+         * dimension already separates the DOMAINS; this separates surfaces that
+         * could share one, and keeps the shared click listener from having to
+         * know anything about either.
+         *
+         * `site` — a tenant published site — is the only value ever SENT. `docs`
+         * was designed for (AGL-1579) and is not emitted: `apps/docs` cannot
+         * import `libs/`, so this listener is not installed there
+         * (docs/ANALYTICS.md decision 7 has the Vercel setting that would change
+         * that). Registering `surface` as a dimension and reading a one-value
+         * breakdown is the trap — the absent `docs` row means "no listener", not
+         * "no clicks".
+         */
+        surface?: string;
+    };
+    /**
+     * Custom: no GA4 equivalent. One Aglyn Assist message sent (AGL-1860).
+     * `tier` is the capability tier served (`free` | `entitled`);
+     * `grounded` says whether docs retrieval found sections to cite —
+     * ungrounded questions at volume are the docs-gap signal the data loop
+     * mines. No question text: params carry no user content.
+     */
+    assistant_message_sent: {
+        tier: string;
+        grounded: boolean;
+    };
+    /**
+     * Custom: no GA4 equivalent. Explicit thumbs on an Assist answer
+     * (AGL-1860). `feedback` is `up` | `down`.
+     */
+    assistant_feedback: {
+        feedback: string;
+    };
+    /**
+     * Custom: no GA4 equivalent. Aglyn Assist offered to open a page for the
+     * user (AGL-1988, level 2). `action` is the registry action id — a closed
+     * set, so it carries no user content.
+     *
+     * The pair below is the only read on whether the confirm gate is a real
+     * choice or a speed bump people click through. A shown-to-confirmed ratio
+     * near 1 means the card is not being read, and the copy has to change
+     * BEFORE the ladder goes anywhere near a write.
+     */
+    assistant_proposal_shown: {
+        action: string;
+    };
+    /** Custom: no GA4 equivalent. The user confirmed and was navigated. */
+    assistant_proposal_confirmed: {
+        action: string;
+    };
+    /**
+     * Custom: no GA4 equivalent. An AI generation job reached `done`
+     * (AGL-2904), observed from the console's jobs drawer. `kind` is the
+     * closed `AiJobKind` set and `credits` the job's spend at the plan's
+     * credit rate — no brief, no output: params carry no user content.
+     */
+    ai_job_completed: {
+        kind: string;
+        credits: number;
+    };
+    /**
+     * Custom: no GA4 equivalent. An AI generation job reached `failed`
+     * (AGL-2904). `kind` only; the failure text is a fixed customer-safe
+     * sentence and says nothing a rate could use.
+     */
+    ai_job_failed: {
+        kind: string;
+    };
+    /**
+     * Custom: no GA4 equivalent. The churn survey was answered — step 1 of the
+     * cancellation/deletion funnel, and the DENOMINATOR every step below is a
+     * rate against. Fired for both leave paths.
+     *
+     * `reason` is the closed `ChurnSurveyReason` set, never the free-text
+     * detail: the detail is customer-written prose, it belongs in Firestore
+     * where the data loop reads it, and shipping it to GA would put user
+     * content in analytics params. `surface` separates a subscription cancel
+     * from an account delete — counting only one understates churn by exactly
+     * the orgs that chose the other.
+     */
+    churn_survey_submitted: {
+        reason: string;
+        surface: string;
+        plan?: string;
+    };
+    /**
+     * Custom: no GA4 equivalent. The customer took the smaller tier instead of
+     * leaving — a SAVE, at reduced ARPA. `from_plan`/`to_plan` are what makes
+     * that tradeoff measurable rather than a win recorded without its cost.
+     */
+    downsell_accepted: {
+        from_plan: string;
+        to_plan: string;
+        surface: string;
+    };
+    /**
+     * Custom: no GA4 equivalent. The time-boxed winback discount was accepted.
+     *
+     * `percent_off` and `duration_months` are reported because the discount is
+     * bounded and the bound is the entire point (AGL-1620/AGL-1863): a retained
+     * org and the margin it was retained at are one fact, and a save recorded
+     * without its price reads as free.
+     */
+    winback_discount_accepted: {
+        percent_off: number;
+        duration_months: number;
+        plan?: string;
+        surface: string;
+    };
+    /**
+     * Custom: no GA4 equivalent. They left anyway — the funnel's terminal step,
+     * and the numerator for churn.
+     *
+     * `funnel_completed` is false when the cancel arrived without a funnelId
+     * (support ops, Stripe dashboard). It mirrors the `funnelSkipped` marker
+     * the routes write, so the GA funnel and the Firestore record agree instead
+     * of quietly disagreeing about how many departures were ever surveyed.
+     */
+    cancellation_completed: {
+        surface: string;
+        plan?: string;
+        funnel_completed: boolean;
+    };
+    /**
+     * Custom: no GA4 equivalent. A downgrade was confirmed and SCHEDULED from
+     * the billing plan grid — the same economic event `downsell_accepted`
+     * records, arrived at by the other door.
+     *
+     * Why this has to exist separately: all four retention events above fire
+     * from `retention-funnel.dialog.tsx` and from nowhere else. A customer who
+     * moves Pro → Starter through the cancel funnel is counted; a customer who
+     * moves Pro → Starter by clicking Downgrade on the plan card was counted by
+     * nothing. So "how many orgs moved down" was unanswerable, and the number
+     * that WAS answerable — `downsell_accepted` — undercounted by exactly the
+     * share that took the direct route while reading like a total. A save rate
+     * computed against it is wrong in the flattering direction, which is the
+     * worst direction for a retention number to be wrong in.
+     *
+     * `effective_at` is the whole point of the event's name: this is the
+     * asymmetric-friction arm of AGL-1859 §2, and a downgrade that has been
+     * SCHEDULED is not a downgrade that has HAPPENED. Reported as the server's
+     * ISO date so the gap between decision and effect — up to a full cycle, and
+     * the window in which "keep my plan" can still save the org — is visible in
+     * the data instead of being collapsed into the decision day.
+     *
+     * No amount, price or fee: pricing is locked for Sept 1, money belongs to
+     * `purchase`/`refund`, and a tier pair already says what changed.
+     */
+    plan_downgrade_scheduled: {
+        from_plan: string;
+        to_plan: string;
+        interval: string;
+        effective_at?: string;
+    };
+    /**
+     * Custom: no GA4 equivalent. An existing subscriber moved UP in place.
+     *
+     * Not `app_upgrade` — that name is GA4-RESERVED (it means an app binary
+     * version bump) and a hit using it is dropped, which is silence rather than
+     * pollution and therefore the harder failure to notice.
+     *
+     * `purchase` covers only the Checkout path, so before this, expansion
+     * revenue from customers who ALREADY had a subscription was dark: the
+     * in-place switch never opens a Checkout and never mints a new
+     * subscription, so nothing in the revenue taxonomy saw it. Upgrades are the
+     * half of AGL-1859 §2 that is supposed to be frictionless, and an
+     * unmeasured half cannot be shown to be.
+     */
+    plan_upgraded: {
+        from_plan: string;
+        to_plan: string;
+        interval: string;
+    };
+}
+export type AnalyticsEventName = keyof AnalyticsEventParams;
+/**
+ * Where a sanitized event goes. The console registers a Firebase
+ * `logEvent` transport; the tenant runtime and the plugin bundles have none
+ * and fall through to `window.gtag`, which only exists once consent has been
+ * granted.
+ */
+export type AnalyticsTransport = (name: AnalyticsEventName, params: Record<string, unknown>) => void | Promise<void>;
+/**
+ * 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 declare function configureAnalyticsTransport(transport: AnalyticsTransport | null): void;
+/** Test seam — drops the registered transport. */
+export declare function resetAnalyticsTransport(): void;
+/**
+ * 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 declare const ANALYTICS_PARAM_MAX_LENGTH = 100;
+/**
+ * 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 declare function sanitizeEventParams(params: Record<string, unknown> | undefined): Record<string, unknown>;
+/**
+ * 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 declare function trackEvent<K extends AnalyticsEventName>(name: K, params: AnalyticsEventParams[K]): void;
+/**
+ * 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 declare function trackEventBeforeNavigation<K extends AnalyticsEventName>(name: K, params: AnalyticsEventParams[K]): Promise<void>;
+/**
+ * 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 declare function buildBeginCheckoutParams(input: {
+    items: AnalyticsItem[];
+    /**
+     * The amount actually being charged. Defaults to the sum of the items'
+     * `price * quantity`, which is right whenever nothing has adjusted it.
+     */
+    value?: number;
+    /** ISO 4217. Defaults to `USD`, the only currency either surface bills in. */
+    currency?: string;
+    /** `monthly` | `annual`. Subscriptions only — a storefront cart has none. */
+    billingInterval?: string;
+}): AnalyticsEventParams['begin_checkout'];
+/**
+ * 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 declare function buildViewCartParams(input: {
+    items: AnalyticsItem[];
+    value?: number;
+    currency?: string;
+}): AnalyticsEventParams['view_cart'];
+/**
+ * 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 declare function buildAddToCartParams(input: {
+    items: AnalyticsItem[];
+    value?: number;
+    currency?: string;
+}): AnalyticsEventParams['add_to_cart'];
+/**
+ * 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 declare function isFirstPublishedRoute(routing: Record<string, unknown> | null | undefined): boolean;
+/** The taxonomy, enumerable. */
+export declare const ANALYTICS_EVENT_NAMES: AnalyticsEventName[];
+/**
+ * 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 declare function isReservedAnalyticsEventName(name: string): boolean;
+/**
+ * The outcome of putting an authored name through GA4's rules, so the
+ * interaction builder can say WHY it refused a name and the runtime can drop
+ * the event for the same reason.
+ */
+export interface ResolvedAuthoredEventName {
+    /** The name to send, or null when the event must not be sent at all. */
+    name: string | null;
+    /**
+     * `reserved` — collides with the taxonomy or with GA4's own names.
+     * `unusable` — nothing survives normalization (empty, or no leading letter).
+     */
+    reason?: 'reserved' | 'unusable';
+}
+/**
+ * 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 declare function resolveAuthoredEventName(raw: string | undefined | null): ResolvedAuthoredEventName;
+/**
+ * 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 declare function trackAuthoredEvent(name: string | undefined | null, params?: Record<string, unknown> | null): void;
+/** Test seam — forgets which authored names have already been warned about. */
+export declare function resetAuthoredEventWarnings(): void;