@escape-game-over/atlas 0.1.66 → 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.66",
+    "version": "0.1.67",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,