@escape-game-over/atlas 0.1.65 → 0.1.67

package/docs/checks.md

@@ -89,6 +89,13 @@ augmentation is real. Both examples carry one:
 two files in it, and [`b2b`](../examples/b2b/type-tests/wiring.ts) against one
 with none, where the union is empty and *every* path is rejected.
 
+Declared analytics events are the other augmentation, and the opposite case:
+nothing is inferred, so a declaration means the same thing here as in a project.
+`type-tests/declared-events.ts` writes one by the package's own name, as a
+project does, and asserts that an undeclared name, missing required data and
+data on an event declared without any all fail. The declaration holds for the
+whole program, so the runtime tests call the names it declares.
+
 ## Runtime tests
 
 ```bash
@@ -117,7 +124,7 @@ dependencies at all. Vitest type-checks them itself when it runs them.
 | `breadcrumbs.test.ts`      | the trail, a dropped ancestor, `orphanSegments`, and how a gap is reported                                                                                                                           |
 | `jsonld/*.test.ts`         | that a `</script>` in any value cannot close the block, each node's shape and `@id`, and how a price table becomes offers                                                                            |
 | `analytics.test.ts`        | Umami's attributes, its three-state booleans, the `domains` list that would record nothing, and that `consentRequired` answers exactly when a tag was emitted                                        |
-| `google-analytics.test.ts` | that consent is denied first and precedes every tag, one loader for many ids, dead `UA-` properties, and the preconnect — once, ahead of the block that writes the loader's URL, never `crossorigin` |
+| `google-analytics.test.ts` | that consent is denied first and precedes every tag, one loader for many ids, dead `UA-` properties, the preconnect — once, ahead of the block that writes the loader's URL, never `crossorigin` — and where `googleEvent` sends, per setting |
 | `contact.test.ts`          | the E.164 a `tel:` needs — trunk zero dropped, spacing stripped — and the displayed form kept                                                                                                        |
 | `hours.test.ts`            | collapsing a week into runs, week start changing the answer, and every impossible week that throws                                                                                                   |
 | `money.test.ts`            | a bare count widened to a band, the span of a table, and the gaps and overlaps that throw                                                                                                            |

package/docs/client-scripts.md

@@ -535,6 +535,88 @@ move before this pauses them. Left in, everything still works. `muted` is also
 set on attach, since no browser will start an unmuted video nobody pressed play
 on.
 
+## Events
+
+One function per vendor, all dropped silently where the vendor is not
+configured, not loaded or not permitted — an analytics call must never be the
+reason a page misbehaves.
+
+| Function       | Names                          | Consent                                    |
+| -------------- | ------------------------------ | ------------------------------------------ |
+| `googleEvent`  | GA4's recommended, or declared | Consent Mode, which Google already applies |
+| `metaEvent`    | Meta's standard, or declared   | the pixel loads only once granted          |
+| `tiktokEvent`  | TikTok's standard, or declared | the pixel loads only once granted          |
+| `snapEvent`    | Snap's standard only           | checked on every call                      |
+| `axonEvent`    | Axon's standard only           | checked on every call                      |
+| `umamiEvent`   | declared only                  | none needed: Umami sets no cookie          |
+| `dripEvent`    | declared only                  | checked on every call                      |
+| `clarityEvent` | declared only                  | none needed: cookieless until granted      |
+
+**A project declares its own events once**, for every site it builds, by
+merging into the interface each function reads — the arrangement
+`PublicFileRegistry` uses. Each name maps to the data it carries, `undefined` for
+none:
+
+```ts
+// src/events.ts — any file the project's tsconfig includes
+export {};
+
+declare module "@escape-game-over/atlas/client" {
+    interface GoogleCustomEvents {
+        form_submission_contact: undefined;
+        form_submission_quote: { readonly room: string };
+    }
+    interface UmamiEvents {
+        "franchise-enquiry": { readonly country: string };
+    }
+}
+```
+
+```ts
+googleEvent("form_submission_contact");
+googleEvent("form_submission_quote", { room: "Tomb" });
+googleEvent("form_submissions_contact"); // does not compile
+```
+
+A name nobody declared does not compile, so a typo cannot quietly become a
+second event in a report — which is why this is not a `string` with the standard
+names offered for autocomplete. Data declared with a required field is required
+at every call. The interfaces are `GoogleCustomEvents`, `MetaCustomEvents`,
+`TikTokCustomEvents`, `UmamiEvents`, `DripEvents` and `ClarityEvents`; Clarity
+carries a name only, so its entries are all `undefined`. Snap and Axon take no
+declarations because they accept no names but their own.
+
+**The file must be a module** — the `export {}` above. Without an import or an
+export, `declare module` *replaces* the package's types instead of adding to
+them, and every import from it breaks.
+
+**Declared data is sent as written, so it names what the visitor chose, never
+who they are.** Google's terms forbid sending it anything that identifies a
+person — a name, an email, a phone number, a free-text message — and its
+[guidance](https://support.google.com/analytics/answer/6366371) names event
+parameters as the usual leak. The standard parameter types have no field for
+any of those; a declaration is where one would have to be added, deliberately.
+
+### `googleEvent`: where it goes
+
+The deployment's `google` settings decide, not the caller. The head script
+defines a global — `GOOGLE_EVENT_GLOBAL`, beside `CONSENT_UPDATE_GLOBAL` and for
+the same reason — that sends:
+
+- with `tagIds`: `gtag("event", name, data)`, which `gtag.js` reads;
+- with `containerIds`: `dataLayer.push({ event: name, ...data })`, which is what
+  a Tag Manager *Custom Event* trigger listens for — the `dataLayer.push` a
+  marketing agency's brief asks for;
+- with both, both. A container that also runs a GA4 tag on the same event then
+  counts it twice; that is set up in Tag Manager, where lib cannot see it.
+
+The ecommerce events — `purchase`, `add_to_cart`, `view_item` and the rest — go
+to Tag Manager under an `ecommerce` key, after a `{ ecommerce: null }` that
+clears the previous one, which is the shape its GA4 tags read items and revenue
+from. `purchase` does not compile without `value`, `currency` and
+`transaction_id`: without them GA records a sale of nothing, and a reload
+records it again.
+
 ## Testing
 
 None of these tests has a document, and none needs one: every module under test

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.65",
+    "version": "0.1.67",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,

package/src/analytics/google-tag.ts

@@ -14,8 +14,13 @@ type ConsentGlobal = {
     ) => void;
 };
 
+// `googleEvent`'s way in, under the same arrangement.
+type EventGlobal = {
+    [Name in typeof import("./google.ts").GOOGLE_EVENT_GLOBAL]?: import("./google.ts").GoogleEventSink;
+};
+
 // biome-ignore lint/correctness/noUnusedVariables: merges into the global `Window`.
-interface Window extends ConsentGlobal {
+interface Window extends ConsentGlobal, EventGlobal {
     dataLayer: unknown[];
     gtag: (...args: unknown[]) => void;
 }
@@ -86,6 +91,24 @@ interface Window extends ConsentGlobal {
 
     defineGtag();
 
+    // An event, wherever this deployment's settings send one. Tag Manager
+    // reads a pushed object rather than a `gtag` call, and clears the previous
+    // `ecommerce` only when told to, as Google documents.
+    window.__googleEvent = (name, params, ecommerce) => {
+        if (config.tagIds.length > 0) {
+            if (params === undefined) window.gtag("event", name);
+            else window.gtag("event", name, params);
+        }
+        if (config.containerIds.length > 0) {
+            if (ecommerce) {
+                window.dataLayer.push({ ecommerce: null });
+                window.dataLayer.push({ event: name, ecommerce: params });
+            } else {
+                window.dataLayer.push({ event: name, ...params });
+            }
+        }
+    };
+
     // Ahead of everything, which is the entire point of emitting this here.
     for (const given of config.defaults) {
         window.gtag("consent", "default", given);

package/src/analytics/google.ts

@@ -217,6 +217,28 @@ const CONSENT_KEYS = {
  */
 export const CONSENT_UPDATE_GLOBAL = "__consent";
 
+/**
+ * The global `googleEvent` calls to record an event:
+ * `__googleEvent("generate_lead", { value: 40 }, true)`.
+ *
+ * A global for the reason `CONSENT_UPDATE_GLOBAL` is one, and emitted here
+ * because only this side knows where an event goes: to `gtag.js` when there
+ * are tag ids, onto `dataLayer` as a Tag Manager event when there are
+ * containers. A client script deciding that would be a second copy of the
+ * settings.
+ */
+export const GOOGLE_EVENT_GLOBAL = "__googleEvent";
+
+/**
+ * What `GOOGLE_EVENT_GLOBAL` holds. `ecommerce` says the parameters go under
+ * Tag Manager's `ecommerce` key, where its GA4 tags read items and revenue.
+ */
+export type GoogleEventSink = (
+    name: string,
+    params: object | undefined,
+    ecommerce: boolean
+) => void;
+
 /** The signal keys of a set of defaults — not `region`, not `waitForUpdate`. */
 const SIGNAL_KEYS = [
     "adStorage",

package/src/astro/clarity-event.ts

@@ -1,3 +1,21 @@
+import type { DeclaredEvent } from "./event-data.ts";
+
+/**
+ * The project's Clarity events. Clarity carries a name and nothing else, so
+ * each is declared `undefined`. Nothing compiles until a project declares its
+ * own, once:
+ *
+ * ```ts
+ * declare module "@escape-game-over/atlas/client" {
+ *     interface ClarityEvents {
+ *         "form sent": undefined;
+ *     }
+ * }
+ * ```
+ */
+// biome-ignore lint/suspicious/noEmptyInterface: filled by each project's declaration.
+export interface ClarityEvents {}
+
 /** What `clarity.ts` defines once the page has loaded. */
 interface ClarityWindow {
     clarity?: (...args: unknown[]) => void;
@@ -10,6 +28,6 @@ interface ClarityWindow {
  * Sent with or without consent: Clarity records either way, and without it
  * sets no cookie. Dropped before Clarity loads, or where it is not configured.
  */
-export function clarityEvent(name: string): void {
+export function clarityEvent(name: DeclaredEvent<ClarityEvents>): void {
     (window as unknown as ClarityWindow).clarity?.("event", name);
 }

package/src/astro/client.ts

@@ -26,6 +26,7 @@ export {
 } from "./element.ts";
 export * from "./filters.ts";
 export * from "./filters-view.ts";
+export * from "./google-event.ts";
 export * from "./meta-event.ts";
 export { data, ref, refs } from "./ref.ts";
 export * from "./snap-event.ts";

package/src/astro/drip-event.ts

@@ -1,4 +1,21 @@
 import { readConsent } from "./consent.ts";
+import type { DeclaredEvent, EventDataArgs } from "./event-data.ts";
+
+/**
+ * The project's Drip events — the actions its workflows start on — each with
+ * the properties it carries, `undefined` for none. Drip's events are named by
+ * the site, so nothing compiles until a project declares its own, once:
+ *
+ * ```ts
+ * declare module "@escape-game-over/atlas/client" {
+ *     interface DripEvents {
+ *         "Bought a voucher": { readonly value: number };
+ *     }
+ * }
+ * ```
+ */
+// biome-ignore lint/suspicious/noEmptyInterface: filled by each project's declaration.
+export interface DripEvents {}
 
 /** What `drip.ts` defines once marketing is granted. */
 interface DripWindow {
@@ -7,15 +24,18 @@ interface DripWindow {
 
 /**
  * Records an event with Drip, to start a workflow — a lead sent, a voucher
- * bought. Drip's events are named by the site, so any name goes.
+ * bought.
  *
  * Dropped unless Drip loaded and marketing is still granted: Drip has no
  * consent call of its own, so the check is here. An analytics call must never
  * be the reason a page misbehaves, so a dropped event is silent.
  */
-export function dripEvent(
-    action: string,
-    properties?: Readonly<Record<string, string | number | boolean>>
+export function dripEvent<E extends DeclaredEvent<DripEvents>>(
+    action: E,
+    // Drip takes flat values; a nested object in a declaration fails here.
+    ...[properties]: EventDataArgs<
+        DripEvents[E] & Readonly<Record<string, string | number | boolean>>
+    >
 ): void {
     if (readConsent()?.marketing !== "granted") return;
     const queue = (window as unknown as DripWindow)._dcq;

package/src/astro/event-data.ts

@@ -0,0 +1,15 @@
+/**
+ * The arguments an event's declared data asks for: none when it is
+ * `undefined`, optional when every field is, required otherwise.
+ *
+ * Shared by every vendor whose events a project declares for itself, so
+ * `{ form_sent: undefined }` means the same thing in each.
+ */
+export type EventDataArgs<Data> = [Data] extends [undefined]
+    ? []
+    : Partial<Data> extends Data
+      ? [data?: Data]
+      : [data: Data];
+
+/** The event names a project declared, as the strings they are sent as. */
+export type DeclaredEvent<Declared> = Extract<keyof Declared, string>;

package/src/astro/google-event.ts

@@ -0,0 +1,119 @@
+import {
+    GOOGLE_EVENT_GLOBAL,
+    type GoogleEventSink,
+} from "../analytics/google.ts";
+import type { CurrencyCode } from "../money.ts";
+import type { DeclaredEvent, EventDataArgs } from "./event-data.ts";
+
+/** GA4's recommended events that carry items and revenue. */
+const ECOMMERCE_EVENTS = [
+    "add_payment_info",
+    "add_to_cart",
+    "add_to_wishlist",
+    "begin_checkout",
+    "purchase",
+    "select_item",
+    "select_promotion",
+    "view_cart",
+    "view_item",
+    "view_item_list",
+    "view_promotion",
+] as const;
+
+/** GA4's recommended events that a website sends, which its reports know by name. */
+export type GoogleRecommendedEvent =
+    | (typeof ECOMMERCE_EVENTS)[number]
+    | "generate_lead"
+    | "login"
+    | "search"
+    | "select_content"
+    | "share"
+    | "sign_up";
+
+/**
+ * The project's own events — what its Tag Manager triggers listen for — each
+ * with the data it carries, `undefined` for none. Empty here; a project fills
+ * it once, and a name it did not declare does not compile:
+ *
+ * ```ts
+ * declare module "@escape-game-over/atlas/client" {
+ *     interface GoogleCustomEvents {
+ *         form_submission_contact: undefined;
+ *         form_submission_quote: { readonly room: string };
+ *     }
+ * }
+ * ```
+ */
+// biome-ignore lint/suspicious/noEmptyInterface: filled by each project's declaration.
+export interface GoogleCustomEvents {}
+
+/** A recommended event, or one the project declared. */
+export type GoogleEventName =
+    | GoogleRecommendedEvent
+    | DeclaredEvent<GoogleCustomEvents>;
+
+/** One item of an ecommerce event. Google needs its id or its name. */
+export type GoogleItem = (
+    | { readonly item_id: string; readonly item_name?: string }
+    | { readonly item_id?: string; readonly item_name: string }
+) & {
+    readonly item_category?: string;
+    readonly item_variant?: string;
+    readonly price?: number;
+    readonly quantity?: number;
+    readonly coupon?: string;
+};
+
+/** GA4's standard parameters. What the visitor chose, never who they are. */
+export interface GoogleEventData {
+    readonly value?: number;
+    readonly currency?: CurrencyCode;
+    readonly transaction_id?: string;
+    readonly coupon?: string;
+    readonly items?: readonly GoogleItem[];
+    readonly search_term?: string;
+    readonly method?: string;
+    readonly content_type?: string;
+    readonly content_id?: string;
+}
+
+/**
+ * A recommended event takes GA4's parameters; `purchase` without its three
+ * reports a sale of nothing, possibly twice. A declared one takes what the
+ * project declared.
+ */
+type GoogleEventArgs<E extends GoogleEventName> =
+    E extends GoogleRecommendedEvent
+        ? E extends "purchase"
+            ? [
+                  data: GoogleEventData & {
+                      value: number;
+                      currency: CurrencyCode;
+                      transaction_id: string;
+                  },
+              ]
+            : [data?: GoogleEventData]
+        : EventDataArgs<GoogleCustomEvents[E & keyof GoogleCustomEvents]>;
+
+/**
+ * Records an event with Google — a lead sent, a booking made — through
+ * `gtag.js`, Tag Manager, or both, as the deployment's `google` settings say.
+ *
+ * Sent whatever the visitor answered: Consent Mode is how Google is told, and
+ * it already holds back what was not granted. Dropped where Google is not
+ * configured, since an analytics call must never be the reason a page
+ * misbehaves.
+ */
+export function googleEvent<E extends GoogleEventName>(
+    event: E,
+    ...[data]: GoogleEventArgs<E>
+): void {
+    const send = (
+        window as unknown as Record<string, GoogleEventSink | undefined>
+    )[GOOGLE_EVENT_GLOBAL];
+    send?.(
+        event,
+        data,
+        (ECOMMERCE_EVENTS as readonly string[]).includes(event)
+    );
+}

package/src/astro/meta-event.ts

@@ -1,24 +1,46 @@
 import type { CurrencyCode } from "../money.ts";
+import type { DeclaredEvent, EventDataArgs } from "./event-data.ts";
 
 /** Meta's standard events, which its ad optimisation understands by name. */
-export type MetaStandardEvent =
-    | "AddPaymentInfo"
-    | "AddToCart"
-    | "AddToWishlist"
-    | "CompleteRegistration"
-    | "Contact"
-    | "CustomizeProduct"
-    | "Donate"
-    | "FindLocation"
-    | "InitiateCheckout"
-    | "Lead"
-    | "Purchase"
-    | "Schedule"
-    | "Search"
-    | "StartTrial"
-    | "SubmitApplication"
-    | "Subscribe"
-    | "ViewContent";
+const META_STANDARD_EVENTS = [
+    "AddPaymentInfo",
+    "AddToCart",
+    "AddToWishlist",
+    "CompleteRegistration",
+    "Contact",
+    "CustomizeProduct",
+    "Donate",
+    "FindLocation",
+    "InitiateCheckout",
+    "Lead",
+    "Purchase",
+    "Schedule",
+    "Search",
+    "StartTrial",
+    "SubmitApplication",
+    "Subscribe",
+    "ViewContent",
+] as const;
+
+export type MetaStandardEvent = (typeof META_STANDARD_EVENTS)[number];
+
+/**
+ * The project's own events, sent as Meta's custom events, each with the data
+ * it carries, `undefined` for none. Empty here; a project fills it once:
+ *
+ * ```ts
+ * declare module "@escape-game-over/atlas/client" {
+ *     interface MetaCustomEvents {
+ *         VoucherViewed: undefined;
+ *     }
+ * }
+ * ```
+ */
+// biome-ignore lint/suspicious/noEmptyInterface: filled by each project's declaration.
+export interface MetaCustomEvents {}
+
+/** A standard event, or one the project declared. */
+export type MetaEventName = MetaStandardEvent | DeclaredEvent<MetaCustomEvents>;
 
 /** Meta's standard parameters. What the visitor chose, never who they are. */
 export interface MetaEventData {
@@ -33,10 +55,15 @@ export interface MetaEventData {
     readonly status?: boolean;
 }
 
-/** `Purchase` is the one event Meta rejects without a value and currency. */
-type MetaEventArgs<E extends MetaStandardEvent> = E extends "Purchase"
-    ? [data: MetaEventData & { value: number; currency: CurrencyCode }]
-    : [data?: MetaEventData];
+/**
+ * A standard event takes Meta's parameters; `Purchase` is the one it rejects
+ * without a value and currency. A declared one takes what the project declared.
+ */
+type MetaEventArgs<E extends MetaEventName> = E extends MetaStandardEvent
+    ? E extends "Purchase"
+        ? [data: MetaEventData & { value: number; currency: CurrencyCode }]
+        : [data?: MetaEventData]
+    : EventDataArgs<MetaCustomEvents[E & keyof MetaCustomEvents]>;
 
 /** What `meta-pixel.ts` defines once marketing is granted. */
 interface MetaWindow {
@@ -44,18 +71,22 @@ interface MetaWindow {
 }
 
 /**
- * Records a standard event with Meta's pixel — a lead sent, a booking made.
+ * Records an event with Meta's pixel — a lead sent, a booking made. A declared
+ * event is sent as Meta's custom event, which is how Meta tells them apart.
  *
  * `fbq` exists only once the visitor granted marketing and the pixel loaded.
  * Before that, without consent, or where Meta is not configured, the event is
  * dropped: no consent means nothing to send, and an analytics call must never
  * be the reason a page misbehaves.
  */
-export function metaEvent<E extends MetaStandardEvent>(
+export function metaEvent<E extends MetaEventName>(
     event: E,
     ...[data]: MetaEventArgs<E>
 ): void {
     const fbq = (window as unknown as MetaWindow).fbq;
-    if (data === undefined) fbq?.("track", event);
-    else fbq?.("track", event, data);
+    const method = (META_STANDARD_EVENTS as readonly string[]).includes(event)
+        ? "track"
+        : "trackCustom";
+    if (data === undefined) fbq?.(method, event);
+    else fbq?.(method, event, data);
 }

package/src/astro/tiktok-event.ts

@@ -1,4 +1,5 @@
 import type { CurrencyCode } from "../money.ts";
+import type { DeclaredEvent, EventDataArgs } from "./event-data.ts";
 
 /** TikTok's standard events, by their current names (May 2025 onwards). */
 export type TikTokStandardEvent =
@@ -18,6 +19,26 @@ export type TikTokStandardEvent =
     | "Subscribe"
     | "ViewContent";
 
+/**
+ * The project's own events, each with the data it carries, `undefined` for
+ * none. Empty here; a project fills it once:
+ *
+ * ```ts
+ * declare module "@escape-game-over/atlas/client" {
+ *     interface TikTokCustomEvents {
+ *         VoucherViewed: undefined;
+ *     }
+ * }
+ * ```
+ */
+// biome-ignore lint/suspicious/noEmptyInterface: filled by each project's declaration.
+export interface TikTokCustomEvents {}
+
+/** A standard event, or one the project declared. */
+export type TikTokEventName =
+    | TikTokStandardEvent
+    | DeclaredEvent<TikTokCustomEvents>;
+
 /** TikTok's standard parameters. What the visitor chose, never who they are. */
 export interface TikTokEventData {
     readonly value?: number;
@@ -31,10 +52,15 @@ export interface TikTokEventData {
     readonly description?: string;
 }
 
-/** `Purchase` needs a value and currency to be worth anything to TikTok. */
-type TikTokEventArgs<E extends TikTokStandardEvent> = E extends "Purchase"
-    ? [data: TikTokEventData & { value: number; currency: CurrencyCode }]
-    : [data?: TikTokEventData];
+/**
+ * A standard event takes TikTok's parameters; `Purchase` needs a value and
+ * currency to be worth anything. A declared one takes what the project declared.
+ */
+type TikTokEventArgs<E extends TikTokEventName> = E extends TikTokStandardEvent
+    ? E extends "Purchase"
+        ? [data: TikTokEventData & { value: number; currency: CurrencyCode }]
+        : [data?: TikTokEventData]
+    : EventDataArgs<TikTokCustomEvents[E & keyof TikTokCustomEvents]>;
 
 /** What `tiktok-pixel.ts` defines once marketing is granted. */
 interface TikTokWindow {
@@ -42,14 +68,15 @@ interface TikTokWindow {
 }
 
 /**
- * Records a standard event with TikTok's pixel — a lead sent, a booking made.
+ * Records an event with TikTok's pixel — a lead sent, a booking made. Declared
+ * events go through the same call.
  *
  * `ttq` exists only once the visitor granted marketing and the pixel loaded.
  * Before that, without consent, or where TikTok is not configured, the event is
  * dropped: no consent means nothing to send, and an analytics call must never
  * be the reason a page misbehaves.
  */
-export function tiktokEvent<E extends TikTokStandardEvent>(
+export function tiktokEvent<E extends TikTokEventName>(
     event: E,
     ...[data]: TikTokEventArgs<E>
 ): void {

package/src/astro/umami-event.ts

@@ -1,3 +1,21 @@
+import type { DeclaredEvent, EventDataArgs } from "./event-data.ts";
+
+/**
+ * The project's Umami events, each with the data it carries, `undefined` for
+ * none. Umami has no standard events, so nothing compiles until a project
+ * declares its own, once:
+ *
+ * ```ts
+ * declare module "@escape-game-over/atlas/client" {
+ *     interface UmamiEvents {
+ *         "franchise-enquiry": { readonly country: string };
+ *     }
+ * }
+ * ```
+ */
+// biome-ignore lint/suspicious/noEmptyInterface: filled by each project's declaration.
+export interface UmamiEvents {}
+
 /**
  * Records a named event with Umami — a form sent, a deck downloaded — from a
  * client script.
@@ -11,9 +29,10 @@
  * never who they are. For an event on a plain click, Umami's
  * `data-umami-event` attribute needs no script at all.
  */
-export function umamiEvent(
-    name: string,
-    data?: Readonly<Record<string, string>>
+export function umamiEvent<E extends DeclaredEvent<UmamiEvents>>(
+    name: E,
+    // Flat string values; anything else in a declaration fails here.
+    ...[data]: EventDataArgs<UmamiEvents[E] & Readonly<Record<string, string>>>
 ): void {
     const umami = (
         window as unknown as {