@escape-game-over/atlas 0.1.64 → 0.1.66

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.64",
+    "version": "0.1.66",
     "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/analytics/umami.ts

@@ -36,7 +36,16 @@ export interface UmamiTracker {
     readonly performance?: boolean;
     /** Leave `?query` out of recorded URLs. */
     readonly excludeSearch?: boolean;
-    /** Leave `#hash` out of recorded URLs. */
+    /**
+     * Leave `#hash` out of recorded URLs. **Defaults to on here.**
+     *
+     * Umami's own default is off, and the tracker counts a pageview whenever
+     * the URL it compares changes. So anything on the page that rewrites the
+     * fragment (a gallery, a tab, an anchor link) is recorded as another visit
+     * to a page nobody left.
+     *
+     * `false` turns it off, and writes the word rather than omitting it.
+     */
     readonly excludeHash?: boolean;
     /** Honour the browser's Do Not Track setting. */
     readonly doNotTrack?: boolean;
@@ -267,15 +276,15 @@ export function umamiScripts(
             src: at(umami.tracker?.path ?? "/script.js"),
             attrs: stated({
                 ...common,
-                // The one default lib overrides — see `UmamiTracker`. The
+                // The two defaults lib overrides — see `UmamiTracker`. The
                 // others are left to Umami: `auto-track` and `auto-pageview`
                 // are already on unless the word `false` appears, so stating
                 // them would be bytes that change nothing, and whether to
                 // honour Do Not Track or drop query strings is a decision about
                 // this business rather than about this kind of site.
                 "data-performance": flag(umami.tracker?.performance ?? true),
+                "data-exclude-hash": flag(umami.tracker?.excludeHash ?? true),
                 "data-exclude-search": flag(umami.tracker?.excludeSearch),
-                "data-exclude-hash": flag(umami.tracker?.excludeHash),
                 "data-do-not-track": flag(umami.tracker?.doNotTrack),
                 "data-auto-track": flag(umami.tracker?.autoTrack),
                 "data-auto-pageview": flag(umami.tracker?.autoPageview),

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 {