@escape-game-over/atlas 0.1.54 → 0.1.56

package/package.json

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

package/src/analytics/index.ts

@@ -1,7 +1,9 @@
 import type { MetaTag } from "../meta/tag.ts";
 import type { HttpsUrl } from "../url.ts";
 import { type GoogleSettings, googleEmits, googleScripts } from "./google.ts";
+import { checkMetaPixel, type MetaPixelSettings } from "./meta-pixel.ts";
 import type { AnalyticsTags } from "./tags.ts";
+import { checkTikTokPixel, type TikTokPixelSettings } from "./tiktok-pixel.ts";
 import {
     checkUmamiDomains,
     type UmamiSettings,
@@ -29,7 +31,9 @@ export {
     type ConsentState,
     type GoogleSettings,
 } from "./google.ts";
+export type { MetaPixelSettings } from "./meta-pixel.ts";
 export type { AnalyticsTags } from "./tags.ts";
+export type { TikTokPixelSettings } from "./tiktok-pixel.ts";
 export type {
     UmamiReplay,
     UmamiSettings,
@@ -40,6 +44,10 @@ export type {
 export interface AnalyticsSettings {
     readonly umami?: UmamiSettings;
     readonly google?: GoogleSettings;
+    /** Loaded by `ConsentBanner`, after marketing is granted. */
+    readonly meta?: MetaPixelSettings;
+    /** Loaded by `ConsentBanner`, after marketing is granted. */
+    readonly tiktok?: TikTokPixelSettings;
 }
 
 /**
@@ -60,6 +68,8 @@ export function analyticsScripts(
     if (analytics === undefined) return { head: [], body: [] };
 
     checkUmamiDomains(analytics.umami, origin);
+    checkMetaPixel(analytics.meta, origin);
+    checkTikTokPixel(analytics.tiktok, origin);
     const google = googleScripts(analytics.google, origin);
     return {
         head: [...google.head, ...umamiScripts(analytics.umami)],
@@ -98,6 +108,10 @@ export function consentVendors(
         umami: false,
         // Consent Mode, but only once there is a tag reading it.
         google: googleEmits(analytics.google),
+        // No cookieless mode: nothing loads until marketing is granted.
+        meta: analytics.meta !== undefined,
+        // Its Cookie Consent Mode holds events back; it is not cookieless.
+        tiktok: analytics.tiktok !== undefined,
     };
 
     return (Object.keys(VENDORS) as (keyof AnalyticsSettings)[]).filter(

package/src/analytics/meta-pixel.ts

@@ -0,0 +1,23 @@
+import type { NonEmpty } from "../types.ts";
+import { warn } from "../warn.ts";
+
+/** Meta's pixel. Marketing: it loads only once a visitor grants that. */
+export interface MetaPixelSettings {
+    /** From Events Manager: 15 or 16 digits. Several share one script. */
+    readonly pixelIds: NonEmpty<string>;
+}
+
+/** Warns about an id that is not a pixel id: it would report nowhere. */
+export function checkMetaPixel(
+    meta: MetaPixelSettings | undefined,
+    at: string
+): void {
+    for (const id of meta?.pixelIds ?? []) {
+        if (!/^\d{15,16}$/.test(id)) {
+            warn(
+                at,
+                `Meta pixel id "${id}" is not 15 or 16 digits, so it reports nowhere. Copy it from Events Manager.`
+            );
+        }
+    }
+}

package/src/analytics/tiktok-pixel.ts

@@ -0,0 +1,23 @@
+import type { NonEmpty } from "../types.ts";
+import { warn } from "../warn.ts";
+
+/** TikTok's pixel. Marketing: it loads only once a visitor grants that. */
+export interface TikTokPixelSettings {
+    /** From TikTok Events Manager: 20 capital letters and digits. */
+    readonly pixelIds: NonEmpty<string>;
+}
+
+/** Warns about an id that is not a pixel id: it would report nowhere. */
+export function checkTikTokPixel(
+    tiktok: TikTokPixelSettings | undefined,
+    at: string
+): void {
+    for (const id of tiktok?.pixelIds ?? []) {
+        if (!/^[A-Z0-9]{20}$/.test(id)) {
+            warn(
+                at,
+                `TikTok pixel id "${id}" is not 20 capital letters and digits, so it reports nowhere. Copy it from TikTok Events Manager.`
+            );
+        }
+    }
+}

package/src/astro/ConsentBanner.astro

@@ -5,12 +5,14 @@
  * buttons.
  *
  * Renders nothing — and ships no script — when this site's analytics need no
- * permission. Otherwise the banner starts hidden and shows only to a visitor
+ * permission. Also loads the vendors that wait for consent, such as Meta's and TikTok's pixels. Otherwise the banner starts hidden and shows only to a visitor
  * with no answer on record, or when a `data-consent-reopen` control is pressed.
  */
 import type { HTMLAttributes } from "astro/types";
 import { type AnalyticsSettings, consentRequired } from "../analytics/index.ts";
 import ConsentElement from "./ConsentElement.astro";
+import MetaPixel from "./MetaPixel.astro";
+import TikTokPixel from "./TikTokPixel.astro";
 
 type Props = HTMLAttributes<"div"> & {
     readonly analytics: AnalyticsSettings | undefined;
@@ -20,7 +22,11 @@ const { analytics, ...attrs } = Astro.props;
 ---
 
 {consentRequired(analytics) && (
-    <ConsentElement {...attrs}>
-        <slot />
-    </ConsentElement>
+    <>
+        <ConsentElement {...attrs}>
+            <slot />
+        </ConsentElement>
+        {analytics?.meta && <MetaPixel settings={analytics.meta} />}
+        {analytics?.tiktok && <TikTokPixel settings={analytics.tiktok} />}
+    </>
 )}

package/src/astro/MetaPixel.astro

@@ -0,0 +1,18 @@
+---
+/** Internal to `ConsentBanner.astro`, so the pixel's script ships only where it is configured. */
+import type { MetaPixelSettings } from "../analytics/meta-pixel.ts";
+import AtlasElement from "./AtlasElement.astro";
+import { metaPixelElement } from "./meta-pixel.ts";
+
+interface Props {
+    readonly settings: MetaPixelSettings;
+}
+---
+
+<script src="./meta-pixel.ts" />
+
+<AtlasElement
+    of={metaPixelElement}
+    data-pixel-ids={JSON.stringify(Astro.props.settings.pixelIds)}
+    hidden
+/>

package/src/astro/TikTokPixel.astro

@@ -0,0 +1,18 @@
+---
+/** Internal to `ConsentBanner.astro`, so the pixel's script ships only where it is configured. */
+import type { TikTokPixelSettings } from "../analytics/tiktok-pixel.ts";
+import AtlasElement from "./AtlasElement.astro";
+import { tiktokPixelElement } from "./tiktok-pixel.ts";
+
+interface Props {
+    readonly settings: TikTokPixelSettings;
+}
+---
+
+<script src="./tiktok-pixel.ts" />
+
+<AtlasElement
+    of={tiktokPixelElement}
+    data-pixel-ids={JSON.stringify(Astro.props.settings.pixelIds)}
+    hidden
+/>

package/src/astro/append-script.ts

@@ -0,0 +1,8 @@
+/** Fetches a vendor's script without blocking the page. */
+export function appendScript(src: string): HTMLScriptElement {
+    const script = document.createElement("script");
+    script.async = true;
+    script.src = src;
+    document.head.append(script);
+    return script;
+}

package/src/astro/client.ts

@@ -23,6 +23,8 @@ export {
 } from "./element.ts";
 export * from "./filters.ts";
 export * from "./filters-view.ts";
+export * from "./meta-event.ts";
 export { data, ref, refs } from "./ref.ts";
+export * from "./tiktok-event.ts";
 export * from "./umami-event.ts";
 export * from "./youtube.ts";

package/src/astro/consent-gate.ts

@@ -0,0 +1,48 @@
+import {
+    CONSENT_EVENT,
+    type ConsentCategory,
+    type ConsentChoices,
+    readConsent,
+} from "./consent.ts";
+
+/** What a vendor does as its category is granted and withdrawn. */
+export interface ConsentGated {
+    /** After `load`, each time the category is granted: a stored answer, or one given now. */
+    readonly grant: () => void;
+    /** Each time a grant is withdrawn on this page. */
+    readonly revoke?: () => void;
+}
+
+/** Runs `vendor` as the visitor's answer for `category` says, until `signal` aborts. */
+export function whenGranted(
+    category: ConsentCategory,
+    vendor: ConsentGated,
+    signal?: AbortSignal
+): void {
+    let granted = readConsent()?.[category] === "granted";
+
+    // After `load`, so a vendor does not compete with the page. Checked again
+    // then: an answer withdrawn before `load` cancels the grant.
+    const grantAfterLoad = () => {
+        const run = () => {
+            if (granted) vendor.grant();
+        };
+        if (document.readyState === "complete") run();
+        else addEventListener("load", run, { once: true, signal });
+    };
+
+    if (granted) grantAfterLoad();
+
+    addEventListener(
+        CONSENT_EVENT,
+        (event) => {
+            const choices = (event as CustomEvent<ConsentChoices>).detail;
+            const now = choices[category] === "granted";
+            if (now === granted) return;
+            granted = now;
+            if (now) grantAfterLoad();
+            else vendor.revoke?.();
+        },
+        { signal }
+    );
+}

package/src/astro/google-map.ts

@@ -1,5 +1,6 @@
 /// <reference types="google.maps" />
 import type { MapFrame } from "../map.ts";
+import { appendScript } from "./append-script.ts";
 import { reportDevError } from "./dev-log.ts";
 import { element } from "./element.ts";
 import { data } from "./ref.ts";
@@ -33,17 +34,19 @@ export function loadGoogleMaps(apiKey: string): Promise<typeof google.maps> {
     loading ??= new Promise((resolve, reject) => {
         (window as unknown as Record<string, () => void>)[CALLBACK] = () =>
             resolve(google.maps);
-        const script = document.createElement("script");
-        script.src = `https://maps.googleapis.com/maps/api/js?${new URLSearchParams(
-            { key: apiKey, v: "weekly", loading: "async", callback: CALLBACK }
-        )}`;
-        script.async = true;
-        script.onerror = () => {
+        const params = {
+            key: apiKey,
+            v: "weekly",
+            loading: "async",
+            callback: CALLBACK,
+        };
+        appendScript(
+            `https://maps.googleapis.com/maps/api/js?${new URLSearchParams(params)}`
+        ).onerror = () => {
             // So the next click tries again.
             loading = undefined;
             reject(new Error("the Maps JavaScript API failed to load"));
         };
-        document.head.append(script);
     });
     return loading;
 }

package/src/astro/meta-event.ts

@@ -0,0 +1,61 @@
+import type { CurrencyCode } from "../money.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";
+
+/** Meta's standard parameters. What the visitor chose, never who they are. */
+export interface MetaEventData {
+    readonly value?: number;
+    readonly currency?: CurrencyCode;
+    readonly content_name?: string;
+    readonly content_category?: string;
+    readonly content_ids?: readonly string[];
+    readonly content_type?: "product" | "product_group";
+    readonly num_items?: number;
+    readonly search_string?: string;
+    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];
+
+/** What `meta-pixel.ts` defines once marketing is granted. */
+interface MetaWindow {
+    fbq?: (...args: unknown[]) => void;
+}
+
+/**
+ * Records a standard event with Meta's pixel — a lead sent, a booking made.
+ *
+ * `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>(
+    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);
+}

package/src/astro/meta-pixel.ts

@@ -0,0 +1,74 @@
+import { appendScript } from "./append-script.ts";
+import type { ConsentGated } from "./consent-gate.ts";
+import { whenGranted } from "./consent-gate.ts";
+import { element } from "./element.ts";
+import { data } from "./ref.ts";
+
+/** Meta's `fbq`: a queue until `fbevents.js` arrives and replays it. */
+interface Fbq {
+    (...args: unknown[]): void;
+    callMethod?: (...args: unknown[]) => void;
+    queue: unknown[];
+    push: Fbq;
+    loaded: boolean;
+    version: string;
+}
+
+interface PixelWindow {
+    fbq?: Fbq;
+    _fbq?: Fbq;
+}
+
+const SCRIPT = "https://connect.facebook.net/en_US/fbevents.js";
+
+/** Meta's own base code, as it defines `fbq` before the script loads. */
+function defineFbq(): Fbq {
+    const global = window as unknown as PixelWindow;
+    if (global.fbq !== undefined) return global.fbq;
+    const fbq = function () {
+        // biome-ignore lint/complexity/noArguments: Meta's queue takes the arguments object, as its snippet pushes it.
+        if (fbq.callMethod) Reflect.apply(fbq.callMethod, fbq, arguments);
+        // biome-ignore lint/complexity/noArguments: as above.
+        else fbq.queue.push(arguments);
+    } as Fbq;
+    fbq.push = fbq;
+    fbq.loaded = true;
+    fbq.version = "2.0";
+    fbq.queue = [];
+    global.fbq = fbq;
+    global._fbq ??= fbq;
+    return fbq;
+}
+
+/** The pixel: loaded on the first grant, paused and resumed by later answers. */
+export function metaPixel(pixelIds: readonly string[]): ConsentGated {
+    let loaded = false;
+    return {
+        grant: () => {
+            const fbq = defineFbq();
+            if (loaded) {
+                fbq("consent", "grant");
+                return;
+            }
+            loaded = true;
+            for (const id of pixelIds) fbq("init", id);
+            fbq("track", "PageView");
+            appendScript(SCRIPT);
+        },
+        revoke: () => {
+            (window as unknown as PixelWindow).fbq?.("consent", "revoke");
+        },
+    };
+}
+
+/** Internal to `MetaPixel.astro`. */
+export const metaPixelElement = element(
+    "atlas-meta-pixel",
+    ({ root, signal }) => {
+        whenGranted(
+            "marketing",
+            metaPixel(JSON.parse(data(root, "pixel-ids"))),
+            signal
+        );
+    }
+);

package/src/astro/tiktok-event.ts

@@ -0,0 +1,59 @@
+import type { CurrencyCode } from "../money.ts";
+
+/** TikTok's standard events, by their current names (May 2025 onwards). */
+export type TikTokStandardEvent =
+    | "AddPaymentInfo"
+    | "AddToCart"
+    | "AddToWishlist"
+    | "CompleteRegistration"
+    | "Contact"
+    | "Download"
+    | "InitiateCheckout"
+    | "Lead"
+    | "Login"
+    | "Purchase"
+    | "Search"
+    | "StartTrial"
+    | "SubmitApplication"
+    | "Subscribe"
+    | "ViewContent";
+
+/** TikTok's standard parameters. What the visitor chose, never who they are. */
+export interface TikTokEventData {
+    readonly value?: number;
+    readonly currency?: CurrencyCode;
+    readonly content_id?: string;
+    readonly content_type?: "product" | "product_group";
+    readonly content_name?: string;
+    readonly content_category?: string;
+    readonly quantity?: number;
+    readonly query?: string;
+    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];
+
+/** What `tiktok-pixel.ts` defines once marketing is granted. */
+interface TikTokWindow {
+    ttq?: { track(event: string, data?: object): void };
+}
+
+/**
+ * Records a standard event with TikTok's pixel — a lead sent, a booking made.
+ *
+ * `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>(
+    event: E,
+    ...[data]: TikTokEventArgs<E>
+): void {
+    const ttq = (window as unknown as TikTokWindow).ttq;
+    if (data === undefined) ttq?.track(event);
+    else ttq?.track(event, data);
+}

package/src/astro/tiktok-pixel.ts

@@ -0,0 +1,112 @@
+import { appendScript } from "./append-script.ts";
+import type { ConsentGated } from "./consent-gate.ts";
+import { whenGranted } from "./consent-gate.ts";
+import { element } from "./element.ts";
+import { data } from "./ref.ts";
+
+/** TikTok's `ttq`: a queue of calls until `events.js` arrives and replays it. */
+interface Ttq extends Array<unknown> {
+    methods: readonly string[];
+    setAndDefer(target: unknown[], method: string): void;
+    instance(id: string): unknown[];
+    load(id: string, options?: object): void;
+    _i: Record<string, unknown[] & { _u?: string }>;
+    _t: Record<string, number>;
+    _o: Record<string, object>;
+    [method: string]: unknown;
+}
+
+interface PixelWindow {
+    ttq?: Ttq;
+    TiktokAnalyticsObject?: string;
+}
+
+const SCRIPT = "https://analytics.tiktok.com/i18n/pixel/events.js";
+
+const METHODS = [
+    "page",
+    "track",
+    "identify",
+    "instances",
+    "debug",
+    "on",
+    "off",
+    "once",
+    "ready",
+    "alias",
+    "group",
+    "enableCookie",
+    "disableCookie",
+    "holdConsent",
+    "revokeConsent",
+    "grantConsent",
+] as const;
+
+/** TikTok's own base code, as it defines `ttq` before the script loads. */
+function defineTtq(): Ttq {
+    const global = window as unknown as PixelWindow;
+    if (global.ttq !== undefined) return global.ttq;
+    global.TiktokAnalyticsObject = "ttq";
+    const ttq = [] as unknown as Ttq;
+    ttq.methods = METHODS;
+    ttq.setAndDefer = (target, method) => {
+        (target as unknown as Record<string, unknown>)[method] = (
+            ...args: unknown[]
+        ) => target.push([method, ...args]);
+    };
+    for (const method of METHODS) ttq.setAndDefer(ttq, method);
+    ttq.instance = (id) => {
+        const queue = ttq._i?.[id] ?? [];
+        for (const method of METHODS) ttq.setAndDefer(queue, method);
+        return queue;
+    };
+    ttq.load = (id, options = {}) => {
+        ttq._i ??= {};
+        ttq._i[id] = Object.assign([], { _u: SCRIPT });
+        ttq._t ??= {};
+        ttq._t[id] = Date.now();
+        ttq._o ??= {};
+        ttq._o[id] = options;
+        appendScript(
+            `${SCRIPT}?${new URLSearchParams({ sdkid: id, lib: "ttq" })}`
+        );
+    };
+    global.ttq = ttq;
+    return ttq;
+}
+
+const call = (ttq: Ttq, method: (typeof METHODS)[number], ...args: unknown[]) =>
+    (ttq[method] as (...args: unknown[]) => void)(...args);
+
+/** The pixel: loaded on the first grant, paused and resumed by later answers. */
+export function tiktokPixel(pixelIds: readonly string[]): ConsentGated {
+    let loaded = false;
+    return {
+        grant: () => {
+            const ttq = defineTtq();
+            // Also lifts the hold of TikTok's Cookie Consent Mode, where a
+            // pixel has it on in Events Manager.
+            call(ttq, "grantConsent");
+            if (loaded) return;
+            loaded = true;
+            for (const id of pixelIds) ttq.load(id);
+            call(ttq, "page");
+        },
+        revoke: () => {
+            const ttq = (window as unknown as PixelWindow).ttq;
+            if (ttq !== undefined) call(ttq, "revokeConsent");
+        },
+    };
+}
+
+/** Internal to `TikTokPixel.astro`. */
+export const tiktokPixelElement = element(
+    "atlas-tiktok-pixel",
+    ({ root, signal }) => {
+        whenGranted(
+            "marketing",
+            tiktokPixel(JSON.parse(data(root, "pixel-ids"))),
+            signal
+        );
+    }
+);

package/src/index.ts

@@ -28,6 +28,8 @@ export {
     consentRequired,
     consentVendors,
     type GoogleSettings,
+    type MetaPixelSettings,
+    type TikTokPixelSettings,
     type UmamiReplay,
     type UmamiSettings,
     type UmamiTracker,