@escape-game-over/atlas 0.1.1

package/src/analytics/google.ts

@@ -0,0 +1,351 @@
+import { warn } from "../warn.ts";
+import { type AnalyticsTags, literal } from "./tags.ts";
+
+/**
+ * Google's tags — Analytics and Tag Manager — and the consent state they read.
+ *
+ * The value here is *order*. `gtag()` does not talk to Google; it pushes onto
+ * `window.dataLayer`, which is a plain array. Google's library, whenever it
+ * arrives, replays that array from the start. So everything can be queued
+ * before the loader exists — and everything queued earlier is applied first.
+ *
+ * Which makes consent a sequencing problem. `gtag('consent','default',…)` has
+ * to be in the queue ahead of any tag that reads it; behind, and Google applies
+ * its *implicit* default, which is everything granted. Nothing errors, nothing
+ * warns, the numbers arrive — slightly more of them than should have. That is
+ * the failure this file exists to make unwritable.
+ */
+
+/** Granted or denied. Google's own vocabulary, and a closed one. */
+export type ConsentState = "granted" | "denied";
+
+/**
+ * One Consent Mode v2 default, queued before any tag loads.
+ *
+ * **The default, not the answer.** It says what holds before a visitor has
+ * chosen. Asking them, remembering the choice and calling
+ * `gtag('consent','update',…)` is the consuming project's half: it needs a
+ * banner, storage and a click, none of which is a head tag. lib guarantees the
+ * half that is invisible when wrong — that the default is already in the queue
+ * when the banner is still loading.
+ *
+ * The `gtag` the banner calls is the one this file defines, so the two halves
+ * meet on a global. That coupling is the price of the mechanism, not a choice.
+ *
+ * Reference:
+ * <https://developers.google.com/tag-platform/security/guides/consent>
+ */
+export interface ConsentDefaults {
+    /** Cookies for advertising. */
+    readonly adStorage?: ConsentState;
+    /** Sending user data to Google for advertising. */
+    readonly adUserData?: ConsentState;
+    /** Personalised advertising. */
+    readonly adPersonalization?: ConsentState;
+    /**
+     * Cookies for analytics — the one GA4 itself waits on.
+     *
+     * Denied does not mean silent: GA4 still sends a cookieless ping, so you
+     * keep rough counts and Google's modelling. It means no identifier and no
+     * stitching one visit to the next.
+     */
+    readonly analyticsStorage?: ConsentState;
+    /** Cookies the site needs to function. */
+    readonly functionalityStorage?: ConsentState;
+    /** Cookies remembering a visitor's preferences. */
+    readonly personalizationStorage?: ConsentState;
+    /** Cookies for authentication and fraud prevention. */
+    readonly securityStorage?: ConsentState;
+    /**
+     * Where this default applies — ISO 3166-2 codes such as `["ES", "US-CA"]`.
+     *
+     * Omitted, it applies everywhere. Several entries let a strict default
+     * cover the regions that require one and a looser default cover the rest,
+     * which is why the field takes a list of these rather than one.
+     */
+    readonly region?: readonly string[];
+    /**
+     * Milliseconds to hold tags while a consent tool decides.
+     *
+     * For a banner that loads asynchronously: without it a tag can fire on
+     * `denied` before the stored choice has been read back, and a visitor who
+     * had already agreed is counted as though they had not.
+     */
+    readonly waitForUpdate?: number;
+}
+
+export interface GoogleSettings {
+    /**
+     * Everything to `gtag('config', …)`, by its own prefix:
+     *
+     * - `G-` — a GA4 measurement id, the ordinary case.
+     * - `GT-` — a Google tag id, the newer unified form. One id, with its
+     *   destinations configured on Google's side rather than here.
+     * - `AW-` — a Google Ads conversion id, for conversion tracking and
+     *   remarketing.
+     * - `DC-` — Floodlight, for Campaign Manager.
+     *
+     * Not `GTM-`, which is a Tag Manager container and a different mechanism —
+     * `containerIds` below.
+     *
+     * Not `UA-` either, and that one is worth naming: Universal Analytics
+     * stopped processing data on 1 July 2023 for standard properties and
+     * 1 July 2024 for 360, and both lost their interface on the later date. A
+     * `UA-` id here is not a typo, it is a property that no longer exists —
+     * which is exactly the kind of thing that survives a config file for years
+     * because nothing complains.
+     *
+     * A list because a site can report to several at once: a venue's own
+     * property, the group's roll-up, an Ads account. The library is fetched
+     * once, for the first, and the rest are configured against it — Google's
+     * documented arrangement.
+     */
+    readonly tagIds?: readonly string[];
+    /**
+     * Tag Manager container ids — `GTM-XXXXXXX`.
+     *
+     * Note what a container *is*: a place where someone adds tags later,
+     * without touching this repo. The consent defaults below still govern them,
+     * which is most of why they are worth stating — they apply to tags nobody
+     * here has seen.
+     */
+    readonly containerIds?: readonly string[];
+    /**
+     * What holds before a visitor has chosen. **Denied unless stated.**
+     *
+     * Google's own implicit default is the opposite — no consent block means
+     * everything granted, cookies set, nobody asked. So lib states the safe one
+     * for you, and the permissive direction is the one that costs a deliberate
+     * act.
+     *
+     * That asymmetry is the whole design. Forgetting this field leaves
+     * analytics in cookieless mode: the counts survive, the identifiers do not,
+     * and the degradation is plain in the dashboard within a week. Getting it
+     * *wrong* the other way — cookies without consent — shows up nowhere at
+     * all. A default that fails visibly beats a required field that can be
+     * answered wrongly in silence.
+     *
+     * State it to loosen it, to add regions, or to tune `waitForUpdate` for a
+     * banner that loads slowly. See `DENIED_BY_DEFAULT` for exactly what the
+     * unstated case emits.
+     */
+    readonly consent?: readonly [ConsentDefaults, ...ConsentDefaults[]];
+}
+
+/**
+ * What a deployment gets for saying nothing: the four consent-gated signals
+ * denied, and the rest left to Google.
+ *
+ * The four are the ones Consent Mode v2 exists for — advertising and analytics
+ * storage, and the two ad signals that ride with them. The three not named
+ * here (`functionality`, `personalization`, `security`) are the site working,
+ * remembering a preference, and fraud prevention: denying those by default
+ * would break things a visitor never objected to, so they keep Google's
+ * default and a deployment denies them deliberately if it means to.
+ *
+ * No `waitForUpdate`. How long to hold tags is a fact about *this* project's
+ * banner — how fast it loads, whether it reads from storage — and a number
+ * guessed here would delay the first hit of every site that has no banner at
+ * all, for nothing.
+ */
+const DENIED_BY_DEFAULT: readonly [ConsentDefaults] = [
+    {
+        adStorage: "denied",
+        adUserData: "denied",
+        adPersonalization: "denied",
+        analyticsStorage: "denied",
+    },
+];
+
+/**
+ * What `gtag('config', …)` accepts, by prefix — see `GoogleSettings.tagIds`.
+ *
+ * A list rather than one check because they are four different products that
+ * happen to share a mechanism, and a site commonly has more than one.
+ */
+const GTAG_PREFIXES = ["G-", "GT-", "AW-", "DC-"] as const;
+
+/** Consent Mode's own spelling, which is snake_case and not ours. */
+const CONSENT_KEYS = {
+    adStorage: "ad_storage",
+    adUserData: "ad_user_data",
+    adPersonalization: "ad_personalization",
+    analyticsStorage: "analytics_storage",
+    functionalityStorage: "functionality_storage",
+    personalizationStorage: "personalization_storage",
+    securityStorage: "security_storage",
+    region: "region",
+    waitForUpdate: "wait_for_update",
+} as const satisfies Readonly<Record<keyof ConsentDefaults, string>>;
+
+/**
+ * The global a consent banner calls to change its mind: `__consent('granted')`.
+ *
+ * Emitted by lib rather than written in each project, because the *signals* it
+ * updates must be exactly the ones lib defaulted. A banner that built the
+ * payload itself would be a second copy of that list — free to grant something
+ * never denied, or to miss something that was, the moment either side changed.
+ * Here the list is derived from the same settings, so it cannot drift.
+ *
+ * A global, because that is how the two halves can meet at all: lib emits head
+ * script, the banner is a component, and neither imports the other. Exactly the
+ * arrangement `gtag` itself uses.
+ *
+ * What stays with the project is *when* to call it — the banner, the click, and
+ * whether the answer is remembered. None of that is a head tag.
+ */
+export const CONSENT_UPDATE_GLOBAL = "__consent";
+
+/** The signal keys of a set of defaults — not `region`, not `waitForUpdate`. */
+const SIGNAL_KEYS = [
+    "adStorage",
+    "adUserData",
+    "adPersonalization",
+    "analyticsStorage",
+    "functionalityStorage",
+    "personalizationStorage",
+    "securityStorage",
+] as const satisfies readonly (keyof ConsentDefaults)[];
+
+/**
+ * `window.__consent(state)`, updating precisely what was defaulted.
+ *
+ * Every signal any default mentioned, and nothing else. Updating one that was
+ * never defaulted is legal and pointless — Google reads it as a change from its
+ * own implicit grant, which was never in force here.
+ */
+function consentUpdater(defaults: readonly ConsentDefaults[]): string {
+    const signals = SIGNAL_KEYS.filter((key) =>
+        defaults.some((given) => given[key] !== undefined)
+    ).map((key) => `${literal(CONSENT_KEYS[key])}:s`);
+
+    if (signals.length === 0) return "";
+    return `window.${CONSENT_UPDATE_GLOBAL}=function(s){gtag('consent','update',{${signals.join(",")}})};`;
+}
+
+/** One `gtag('consent','default',{…})` per stated default, in order. */
+function consentCalls(defaults: readonly ConsentDefaults[]): string {
+    return defaults
+        .map((given) => {
+            const pairs = (
+                Object.entries(CONSENT_KEYS) as [
+                    keyof ConsentDefaults,
+                    string,
+                ][]
+            )
+                .filter(([key]) => given[key] !== undefined)
+                .map(
+                    ([key, name]) => `${literal(name)}:${literal(given[key])}`
+                );
+            return `gtag('consent','default',{${pairs.join(",")}});`;
+        })
+        .join("");
+}
+
+/**
+ * Google's tags: one inline block and the loader in the head, Tag Manager's
+ * `<noscript>` fallback in the body.
+ *
+ * One block rather than several because `dataLayer` is a queue — consent, the
+ * timestamp, every `config` and Tag Manager's own bootstrap can all be pushed
+ * before `gtag.js` arrives, and are replayed when it does. That removes the
+ * ordering problem rather than documenting it: there is no second script that
+ * could run first.
+ *
+ * The `<noscript>` iframe is Google's documented second half of a Tag Manager
+ * install, and belongs immediately after `<body>` — in the head it is ignored.
+ * It serves visitors with JavaScript off, who will not run the tags it backs
+ * up, so it records a bare pageview and nothing else. Small, and free now that
+ * there is a channel for it.
+ */
+export function googleScripts(
+    google: GoogleSettings | undefined,
+    at: string
+): AnalyticsTags {
+    const nothing: AnalyticsTags = { head: [], body: [] };
+    if (google === undefined) return nothing;
+
+    const tags = google.tagIds ?? [];
+    const containers = google.containerIds ?? [];
+    if (tags.length === 0 && containers.length === 0) return nothing;
+
+    // An id in the wrong field is the silent failure here: it is configured,
+    // it is emitted, and it reports nowhere — which reads as a quiet week.
+    for (const id of tags) {
+        if (id.startsWith("UA-")) {
+            warn(
+                at,
+                `"${id}" is a Universal Analytics property, and those stopped processing data on 1 July 2023 (1 July 2024 for 360). It reports nowhere. The GA4 property that replaced it starts with "G-". https://support.google.com/analytics/answer/11583528`
+            );
+        } else if (id.startsWith("GTM-")) {
+            warn(
+                at,
+                `"${id}" is a Tag Manager container, not something gtag can configure — it belongs in containerIds.`
+            );
+        } else if (!GTAG_PREFIXES.some((prefix) => id.startsWith(prefix))) {
+            warn(
+                at,
+                `"${id}" does not look like anything gtag configures: those start with ${GTAG_PREFIXES.join(", ")}.`
+            );
+        }
+    }
+    for (const id of containers) {
+        if (!id.startsWith("GTM-")) {
+            warn(
+                at,
+                `"${id}" is configured as a Tag Manager container but does not look like one — those start with "GTM-".`
+            );
+        }
+    }
+
+    const consent = google.consent ?? DENIED_BY_DEFAULT;
+    const inline = [
+        "window.dataLayer=window.dataLayer||[];",
+        "function gtag(){dataLayer.push(arguments)}",
+        // Ahead of everything, which is the entire point of emitting this here.
+        consentCalls(consent),
+        // And the way back out of it, covering exactly what was just denied.
+        consentUpdater(consent),
+        tags.length > 0 ? "gtag('js',new Date());" : "",
+        ...tags.map((id) => `gtag('config',${literal(id)});`),
+        // Tag Manager's own loader, once per container. It appends its script
+        // itself, so it runs after the consent calls already queued above.
+        ...containers.map(
+            (id) =>
+                `(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src='https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f)})(window,document,'script','dataLayer',${literal(id)});`
+        ),
+    ].join("");
+
+    // The library is fetched once, for the first id, and every id gets its own
+    // `config` above. That is Google's documented arrangement rather than a
+    // shortcut: *"A single Google tag can have multiple tag IDs"*, and their
+    // own example loads `gtag/js?id=G-XXXXXX` once and then configures
+    // `GT-XXXXXX` and `DC-ZZZZZZ` against it. The `?id=` only bootstraps the
+    // library; the `config` calls are what register a destination.
+    //
+    // Loading it per id would fetch the same script several times and re-run
+    // its bootstrap — more bytes for nothing, and a second copy of a global.
+    //
+    // <https://developers.google.com/tag-platform/gtagjs/configure>
+    const first = tags[0];
+    return {
+        head: [
+            { kind: "inline", content: inline },
+            ...(first === undefined
+                ? []
+                : [
+                      {
+                          kind: "external" as const,
+                          src: `https://www.googletagmanager.com/gtag/js?id=${encodeURIComponent(first)}`,
+                          attributes: {},
+                      },
+                  ]),
+        ],
+        // One per container, and only for Tag Manager: GA4 has no such
+        // fallback, because `gtag.js` is the only way it collects anything.
+        body: containers.map((id) => ({
+            kind: "noscriptFrame" as const,
+            src: `https://www.googletagmanager.com/ns.html?id=${encodeURIComponent(id)}`,
+        })),
+    };
+}

package/src/analytics/index.ts

@@ -0,0 +1,102 @@
+import type { HttpsUrl } from "../url.ts";
+import { type GoogleSettings, googleScripts } from "./google.ts";
+import type { AnalyticsTag, AnalyticsTags } from "./tags.ts";
+import {
+    checkUmamiDomains,
+    type UmamiSettings,
+    umamiScripts,
+} from "./umami.ts";
+
+/**
+ * Analytics, as head tags.
+ *
+ * Here rather than in each consuming repo because it is the same decisions
+ * every time — which host serves the script, which setting spells which
+ * attribute, and in what order the consent state has to reach the queue — and a
+ * decision made in four repos is a decision made differently in four repos.
+ *
+ * The precedent is `SiteVerification`, which is equally vendor-specific: lib
+ * already knows the string `google-site-verification` and emits that tag. What
+ * lib refuses is a *passthrough* — a slot a consumer pours arbitrary tags
+ * through — not knowledge of a named vendor it can build something from. A
+ * project states ids; lib decides everything that follows from them.
+ */
+
+export {
+    CONSENT_UPDATE_GLOBAL,
+    type ConsentDefaults,
+    type ConsentState,
+    type GoogleSettings,
+} from "./google.ts";
+export type { AnalyticsTag, AnalyticsTags } from "./tags.ts";
+export type {
+    UmamiReplay,
+    UmamiSettings,
+    UmamiTracker,
+} from "./umami.ts";
+
+/** What a project may switch on. A vendor is a key here. */
+export interface AnalyticsSettings {
+    readonly umami?: UmamiSettings;
+    readonly google?: GoogleSettings;
+}
+
+/**
+ * Every analytics tag this deployment loads, split by where it goes and ordered
+ * within each.
+ *
+ * Google first in the head — not because it matters to Umami, but because its
+ * consent defaults are the one thing here that must precede something else, and
+ * putting them first leaves no room for the question. Within Google the order
+ * is fixed by `googleScripts`; across vendors nothing is coupled.
+ *
+ * `origin` is the site's own URL, which Umami checks its `domains` against.
+ */
+export function analyticsScripts(
+    analytics: AnalyticsSettings | undefined,
+    origin: HttpsUrl
+): AnalyticsTags {
+    if (analytics === undefined) return { head: [], body: [] };
+
+    checkUmamiDomains(analytics.umami, origin);
+    const google = googleScripts(analytics.google, origin);
+    return {
+        head: [...google.head, ...umamiScripts(analytics.umami)],
+        // Umami has no body half — its tracker is a single fetched script, and
+        // there is nothing for a visitor without JavaScript to fall back to.
+        body: google.body,
+    };
+}
+
+/**
+ * The tag a 404 grouped under, so the misses can be read on their own.
+ *
+ * Umami's `data-tag` replaces rather than adds — it is one string — so a
+ * project's own tag does not survive on this page. That is the right way round:
+ * on a 404 the fact worth grouping by is that it *is* one.
+ */
+export const NOT_FOUND_TAG = "404";
+
+/**
+ * What a 404 loads. Umami only, and deliberately.
+ *
+ * The point of measuring a 404 is *finding a broken link* — a redirect somebody
+ * forgot when a slug moved, a printed URL that no longer resolves. Cloudflare
+ * serves this page at the address that was asked for, so Umami records
+ * `/old-pricing` rather than `/404`: the report names the redirect to write.
+ * Someone typing nonsense is noise you scroll past, and it is obvious which is
+ * which by whether one path repeats.
+ *
+ * **No Google.** Nothing here needs advertising or conversion tracking, and
+ * bringing GA would bring its consent gate — which needs a banner, on a page
+ * whose whole job is to be passed through in a second. Umami sets no cookies,
+ * so it has nothing to ask.
+ *
+ * No `checkUmamiDomains` either: the pages already ran it, and one mistake
+ * deserves one warning.
+ */
+export function notFoundAnalytics(
+    analytics: AnalyticsSettings | undefined
+): readonly AnalyticsTag[] {
+    return umamiScripts(analytics?.umami, NOT_FOUND_TAG);
+}

package/src/analytics/tags.ts

@@ -0,0 +1,57 @@
+/**
+ * What an analytics vendor comes to, as data.
+ *
+ * A list rather than a set, because **order is part of the answer**. Google's
+ * consent defaults have to be queued before any tag that reads them, and a tag
+ * that fires first does not error — it simply applies the permissive implicit
+ * default and sets cookies nobody agreed to. Returning a sequence makes that
+ * ordering something lib decides once, rather than something a layout could
+ * shuffle.
+ */
+export type AnalyticsTag =
+    | {
+          readonly kind: "external";
+          readonly src: string;
+          readonly attributes: Readonly<Record<string, string>>;
+      }
+    | {
+          readonly kind: "inline";
+          readonly content: string;
+      }
+    /**
+     * A hidden iframe inside `<noscript>` — Tag Manager's fallback, and so far
+     * only that.
+     *
+     * Structured rather than a string of HTML, for the reason `externalScript`
+     * is: a field holding markup is a passthrough, and lib does not have those.
+     * A `src` is all this shape can carry, so it is all anyone can put in it.
+     */
+    | {
+          readonly kind: "noscriptFrame";
+          readonly src: string;
+      };
+
+/**
+ * Where a tag goes. Two channels, because two tags genuinely differ.
+ *
+ * Most of what lib emits belongs in `<head>`. Tag Manager's `<noscript>`
+ * fallback does not — Google's install puts it immediately after `<body>`, and
+ * an iframe in the head is ignored. Returning the two separately means a layout
+ * cannot put one where the other goes.
+ */
+export interface AnalyticsTags {
+    readonly head: readonly AnalyticsTag[];
+    readonly body: readonly AnalyticsTag[];
+}
+
+/**
+ * A value, as a JavaScript literal that cannot escape the string it sits in.
+ *
+ * `JSON.stringify` handles quotes and backslashes. The `<` escape handles the
+ * one thing it cannot: a `</script` anywhere in the text ends the element,
+ * whatever JavaScript makes of it. `<` is a valid escape inside a JS
+ * string and invisible to anything reading the value — the same bargain
+ * `serializeJsonLd` strikes, for the same reason.
+ */
+export const literal = (value: unknown): string =>
+    JSON.stringify(value).replaceAll("<", "\\u003c");