@gradial/aci 0.1.28 → 0.1.30

package/dist/collect/gapbuffer.js

@@ -0,0 +1,134 @@
+// Consent-gap buffer (design/05, REQ-8): holds events captured while the
+// consent envelope grants personalization but the mint marker (aci_m) is
+// absent — the window between consent and the first identity-bearing HTML
+// response. Bounded at 50 (drop-oldest), persisted per-tab in
+// sessionStorage["aci:buf"], purged on withdrawal, flushed through the
+// normal batcher when the marker appears (checked at init and on every
+// flush tick). Flushed events keep their eventIds.
+export const GAP_BUFFER_KEY = "aci:buf";
+export const GAP_BUFFER_CAP = 50;
+const MINT_MARKER_COOKIE = "aci_m";
+export class GapBuffer {
+    events;
+    storage;
+    debug;
+    constructor(env) {
+        this.debug = env?.debug;
+        this.storage = env?.storage;
+        this.events = this.restore();
+    }
+    push(event) {
+        this.events.push(event);
+        if (this.events.length > GAP_BUFFER_CAP) {
+            this.events.splice(0, this.events.length - GAP_BUFFER_CAP);
+            this.debug?.("buffer", { reason: "cap_drop_oldest" });
+        }
+        this.persist();
+    }
+    /** drain returns and clears all buffered events, preserving order and ids. */
+    drain() {
+        const drained = this.events;
+        this.events = [];
+        this.persist();
+        return drained;
+    }
+    /** purge empties the buffer (consent withdrawal). */
+    purge() {
+        if (this.events.length > 0) {
+            this.debug?.("buffer", { reason: "purged", count: this.events.length });
+        }
+        this.events = [];
+        this.persist();
+    }
+    size() {
+        return this.events.length;
+    }
+    restore() {
+        const storage = this.storage;
+        if (!storage)
+            return [];
+        let raw;
+        try {
+            raw = storage.getItem(GAP_BUFFER_KEY);
+        }
+        catch (err) {
+            // Privacy modes can deny storage entirely: degrade to memory-only.
+            this.storage = undefined;
+            this.debug?.("buffer", { reason: "storage_unavailable", error: String(err) });
+            return [];
+        }
+        if (raw == null)
+            return [];
+        try {
+            const parsed = JSON.parse(raw);
+            if (Array.isArray(parsed))
+                return parsed;
+        }
+        catch {
+            // Corrupt content: reset below.
+        }
+        try {
+            storage.removeItem(GAP_BUFFER_KEY);
+        }
+        catch {
+            this.storage = undefined;
+        }
+        return [];
+    }
+    persist() {
+        const storage = this.storage;
+        if (!storage)
+            return;
+        try {
+            if (this.events.length === 0) {
+                storage.removeItem(GAP_BUFFER_KEY);
+            }
+            else {
+                storage.setItem(GAP_BUFFER_KEY, JSON.stringify(this.events));
+            }
+        }
+        catch (err) {
+            this.storage = undefined;
+            this.debug?.("buffer", { reason: "storage_unavailable", error: String(err) });
+        }
+    }
+}
+/** hasMintMarker reports whether the edge-set aci_m marker cookie exists. */
+export function hasMintMarker(doc) {
+    for (const part of doc.cookie.split(";")) {
+        const trimmed = part.trim();
+        if (trimmed.startsWith(MINT_MARKER_COOKIE + "=")) {
+            return trimmed.slice(MINT_MARKER_COOKIE.length + 1) !== "";
+        }
+    }
+    return false;
+}
+/**
+ * routeEvent implements the emit routing (design/05): events captured in
+ * the consent gap — envelope grants personalization AND the marker is
+ * absent — are buffered; everything else goes straight to the batcher (the
+ * collector enforces consent server-side).
+ */
+export function routeEvent(event, deps) {
+    if (deps.grants() && !deps.marker()) {
+        deps.gapBuffer.push(event);
+        return;
+    }
+    deps.batcher.push(event);
+}
+/**
+ * maybeFlushGapBuffer drains the buffer through the normal batcher once the
+ * mint marker appears. Runs at init and on every batcher flush tick, so a
+ * mint by another tab or navigation is noticed.
+ */
+export function maybeFlushGapBuffer(gapBuffer, batcher, marker, debug) {
+    if (gapBuffer.size() === 0)
+        return;
+    if (!marker())
+        return;
+    const events = gapBuffer.drain();
+    for (const event of events) {
+        batcher.push(event);
+    }
+    debug?.("buffer", { reason: "flushed", count: events.length });
+}

package/dist/collect/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * init boots the SDK against a window. Idempotent (window.__aci_loaded);
+ * browsers missing the ~2019 baseline (sendBeacon, IntersectionObserver,
+ * crypto.getRandomValues) get a silent no-op.
+ */
+export declare function init(win?: Window): void;

package/dist/collect/index.js

@@ -0,0 +1,154 @@
+// Collect SDK entry point (design/05 init pseudocode). Bundled by esbuild
+// into the single IIFE artifact served at /_aci/aci.js. Everything hangs off
+// init(); every failure is swallowed after a debug record so the page is
+// never affected (QR-2/3).
+import { installCommandQueue } from "./api.js";
+import { Batcher } from "./batcher.js";
+import { createDebug, readTagConfig } from "./config.js";
+import { start as startC15t } from "./consent/adapters/c15t.js";
+import { start as startCookiebot } from "./consent/adapters/cookiebot.js";
+import { start as startOneTrust } from "./consent/adapters/onetrust.js";
+import { start as startTrustArc } from "./consent/adapters/trustarc.js";
+import { applyConsent, envelopeGrantsPersonalization, readConsentCookie, sanitizePurposes, } from "./consent/envelope.js";
+import { startDeclarative } from "./declarative.js";
+import { GapBuffer, hasMintMarker, maybeFlushGapBuffer, routeEvent, } from "./gapbuffer.js";
+import { startLinkClicks } from "./linkclicks.js";
+import { startPageViews } from "./pageviews.js";
+import { send } from "./transport.js";
+import { ulid } from "./ulid.js";
+import { startVariationViews } from "./variationviews.js";
+import { startWebVitals } from "./webvitals.js";
+const CMP_ADAPTERS = {
+    c15t: startC15t,
+    onetrust: startOneTrust,
+    cookiebot: startCookiebot,
+    trustarc: startTrustArc,
+};
+function hasBaseline(w) {
+    return (typeof w.navigator?.sendBeacon === "function" &&
+        typeof w.IntersectionObserver === "function" &&
+        typeof w.crypto?.getRandomValues === "function");
+}
+function safeSessionStorage(w) {
+    try {
+        return w.sessionStorage;
+    }
+    catch {
+        return undefined; // privacy modes can deny storage access entirely
+    }
+}
+/**
+ * init boots the SDK against a window. Idempotent (window.__aci_loaded);
+ * browsers missing the ~2019 baseline (sendBeacon, IntersectionObserver,
+ * crypto.getRandomValues) get a silent no-op.
+ */
+export function init(win) {
+    const w = (win ??
+        (typeof window !== "undefined" ? window : undefined));
+    if (!w)
+        return;
+    if (w.__aci_loaded)
+        return;
+    w.__aci_loaded = true;
+    if (!hasBaseline(w))
+        return;
+    const cfg = readTagConfig(w.document.currentScript);
+    const debug = createDebug(cfg.debug);
+    try {
+        const doc = w.document;
+        const gapBuffer = new GapBuffer({ storage: safeSessionStorage(w), debug });
+        const grants = () => {
+            try {
+                return envelopeGrantsPersonalization(readConsentCookie(doc));
+            }
+            catch {
+                return false;
+            }
+        };
+        const marker = () => {
+            try {
+                return hasMintMarker(doc);
+            }
+            catch {
+                return false;
+            }
+        };
+        const transportEnv = {
+            navigator: w.navigator,
+            fetch: typeof w.fetch === "function"
+                ? w.fetch.bind(w)
+                : undefined,
+            debug,
+        };
+        let batcher;
+        batcher = new Batcher({
+            send: (body) => send(body, transportEnv),
+            debug,
+            // The marker is re-checked on every flush tick, so a mint by another
+            // tab or navigation is noticed.
+            onTick: () => maybeFlushGapBuffer(gapBuffer, batcher, marker, debug),
+            timers: {
+                setInterval: (fn, ms) => w.setInterval(fn, ms),
+                clearInterval: (id) => w.clearInterval(id),
+            },
+            documentTarget: doc,
+            windowTarget: w,
+        });
+        const emit = (event) => {
+            routeEvent({
+                ...event,
+                eventId: ulid(undefined, (bytes) => w.crypto.getRandomValues(bytes)),
+            }, { grants, marker, gapBuffer, batcher });
+        };
+        installCommandQueue(w, cfg, {
+            track: (name, properties) => emit({ eventName: name, properties }),
+            consent: ({ p, src }) => {
+                const purposes = sanitizePurposes(p);
+                if (purposes === undefined) {
+                    debug("consent", { reason: "malformed_purposes" });
+                    return;
+                }
+                applyConsent(purposes, typeof src === "string" && src.trim() !== "" ? src.trim() : "manual", { document: doc, gapBuffer });
+            },
+        }, debug);
+        startPageViews(emit, w);
+        startDeclarative(emit, {
+            document: doc,
+            intersectionObserver: w.IntersectionObserver,
+            debug,
+        });
+        startLinkClicks(emit, { document: doc, debug });
+        startWebVitals(emit, {
+            performance: w.performance,
+            PerformanceObserver: w.PerformanceObserver,
+            window: w,
+            document: doc,
+            debug,
+        });
+        startVariationViews(emit, {
+            document: doc,
+            MutationObserver: w.MutationObserver,
+            debug,
+        });
+        if (cfg.preset !== "manual") {
+            CMP_ADAPTERS[cfg.preset]?.({
+                window: w,
+                document: doc,
+                categories: cfg.categories,
+                gapBuffer,
+                debug,
+                scheduler: {
+                    setTimeout: (fn, ms) => w.setTimeout(fn, ms),
+                    clearTimeout: (id) => w.clearTimeout(id),
+                },
+            });
+        }
+        batcher.start();
+        maybeFlushGapBuffer(gapBuffer, batcher, marker, debug);
+        debug("init", { config: cfg });
+    }
+    catch (err) {
+        debug("init", { error: String(err) });
+    }
+}
+init();

package/dist/collect/linkclicks.d.ts

@@ -0,0 +1,12 @@
+import type { PendingEvent } from "./batcher.js";
+import type { DebugFn } from "./config.js";
+export declare const LINK_CLICK_EVENT = "rum.link_click";
+export interface LinkClickEnv {
+    document: Document;
+    debug?: DebugFn;
+}
+/**
+ * startLinkClicks installs one delegated click listener on document that
+ * emits rum.link_click for the closest a[href] ancestor of the click target.
+ */
+export declare function startLinkClicks(emit: (event: PendingEvent) => void, env: LinkClickEnv): void;

package/dist/collect/linkclicks.js

@@ -0,0 +1,35 @@
+// Link clicks (design/04): eventName "rum.link_click" with the current page
+// url and { linkText, linkHref } properties. One delegated click listener on
+// document; the closest a[href] ancestor of the click target is recorded.
+// target="_blank" links are still captured — the click event is useful RUM
+// even when the browser opens a new tab, and dropping them would lose a
+// measurable fraction of outbound intent. Errors are swallowed silently.
+export const LINK_CLICK_EVENT = "rum.link_click";
+/**
+ * startLinkClicks installs one delegated click listener on document that
+ * emits rum.link_click for the closest a[href] ancestor of the click target.
+ */
+export function startLinkClicks(emit, env) {
+    const { document: doc, debug } = env;
+    const loc = doc.defaultView?.location;
+    doc.addEventListener("click", (e) => {
+        try {
+            const target = e.target;
+            const el = target?.closest?.("a[href]");
+            if (!el)
+                return;
+            const anchor = el;
+            emit({
+                eventName: LINK_CLICK_EVENT,
+                url: loc?.href,
+                properties: {
+                    linkText: anchor.textContent?.trim() ?? "",
+                    linkHref: anchor.href,
+                },
+            });
+        }
+        catch (err) {
+            debug?.("capture", { reason: "link_click_failed", error: String(err) });
+        }
+    });
+}

package/dist/collect/pageviews.d.ts

@@ -0,0 +1,22 @@
+import type { PendingEvent } from "./batcher.js";
+export declare const PAGE_VIEW_EVENT = "rum.page_view";
+interface HistoryLike {
+    pushState(...args: unknown[]): unknown;
+    replaceState(...args: unknown[]): unknown;
+}
+export interface PageViewWindow {
+    location: {
+        href: string;
+    };
+    document: {
+        referrer: string;
+    };
+    history: HistoryLike;
+    addEventListener(type: string, fn: () => void): void;
+}
+/**
+ * startPageViews emits the initial page view and hooks
+ * pushState/replaceState/popstate for SPA route changes.
+ */
+export declare function startPageViews(emit: (event: PendingEvent) => void, win: PageViewWindow): void;
+export {};

package/dist/collect/pageviews.js

@@ -0,0 +1,42 @@
+// Page views (design/04): eventName "rum.page_view" with url (the full href
+// including query) and referrer — the SDK never populates utm, ingest
+// derives it from the URL. One event per document load plus one per
+// history-API route change; hash-only changes and same-URL repeats never
+// double count.
+export const PAGE_VIEW_EVENT = "rum.page_view";
+function stripHash(href) {
+    const i = href.indexOf("#");
+    return i === -1 ? href : href.slice(0, i);
+}
+/**
+ * startPageViews emits the initial page view and hooks
+ * pushState/replaceState/popstate for SPA route changes.
+ */
+export function startPageViews(emit, win) {
+    const view = () => emit({
+        eventName: PAGE_VIEW_EVENT,
+        url: win.location.href,
+        referrer: win.document.referrer,
+    });
+    let last = stripHash(win.location.href);
+    view();
+    const onNavigate = () => {
+        const current = stripHash(win.location.href);
+        if (current === last)
+            return; // hash-only change or same-URL repeat
+        last = current;
+        view();
+    };
+    const history = win.history;
+    const wrap = (method) => {
+        const original = history[method].bind(history);
+        history[method] = (...args) => {
+            const result = original(...args);
+            onNavigate();
+            return result;
+        };
+    };
+    wrap("pushState");
+    wrap("replaceState");
+    win.addEventListener("popstate", onNavigate);
+}

package/dist/collect/transport.d.ts

@@ -0,0 +1,22 @@
+import type { DebugFn } from "./config.js";
+export declare const COLLECT_PATH = "/collect";
+export interface BeaconNavigator {
+    sendBeacon?: (url: string, data: Blob) => boolean;
+}
+export type FetchLike = (input: string, init?: {
+    method?: string;
+    body?: Blob;
+    keepalive?: boolean;
+}) => Promise<unknown>;
+export interface TransportEnv {
+    /** Present key (even if undefined) overrides the global for tests. */
+    navigator?: BeaconNavigator | undefined;
+    fetch?: FetchLike | undefined;
+    debug?: DebugFn;
+}
+/**
+ * send posts one serialized batch envelope to the relative collect path.
+ * Every failure is swallowed after a structured debug record — the page is
+ * never affected.
+ */
+export declare function send(body: string, env?: TransportEnv): void;

package/dist/collect/transport.js

@@ -0,0 +1,52 @@
+// Transport (design/05): navigator.sendBeacon("/collect", Blob text/plain)
+// with a keepalive-fetch fallback. Fire-and-forget — no retry loop in v1;
+// eventIds make a future retry layer safe. The path is RELATIVE so requests
+// stay exactly same-origin (data-plane design/04).
+export const COLLECT_PATH = "/collect";
+/**
+ * send posts one serialized batch envelope to the relative collect path.
+ * Every failure is swallowed after a structured debug record — the page is
+ * never affected.
+ */
+export function send(body, env) {
+    const debug = env?.debug;
+    const nav = env !== undefined && "navigator" in env
+        ? env.navigator
+        : globalThis.navigator;
+    const fetchFn = env !== undefined && "fetch" in env
+        ? env.fetch
+        : globalThis.fetch;
+    let blob;
+    try {
+        blob = new Blob([body], { type: "text/plain" });
+    }
+    catch {
+        debug?.("flush", { reason: "no_blob" });
+        return;
+    }
+    if (nav?.sendBeacon) {
+        try {
+            if (nav.sendBeacon(COLLECT_PATH, blob))
+                return;
+        }
+        catch {
+            // Fall through to the fetch fallback.
+        }
+    }
+    if (!fetchFn) {
+        debug?.("flush", { reason: "no_transport" });
+        return;
+    }
+    try {
+        void fetchFn(COLLECT_PATH, {
+            method: "POST",
+            body: blob,
+            keepalive: true,
+        }).catch((err) => {
+            debug?.("flush", { reason: "fetch_failed", error: String(err) });
+        });
+    }
+    catch (err) {
+        debug?.("flush", { reason: "fetch_failed", error: String(err) });
+    }
+}

package/dist/collect/ulid.d.ts

@@ -0,0 +1,6 @@
+/**
+ * ulid returns a 26-character uppercase Crockford-base32 ULID. The clock and
+ * the random source are injectable for deterministic tests; the defaults are
+ * Date.now() and crypto.getRandomValues.
+ */
+export declare function ulid(now?: number, fillRandom?: (bytes: Uint8Array) => void): string;

package/dist/collect/ulid.js

@@ -0,0 +1,36 @@
+// Client-side ULID for event ids (design/05): 26-char Crockford base32,
+// 48-bit millisecond timestamp + 80 random bits from the platform CSPRNG.
+const ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+const TIME_CHARS = 10;
+const RANDOM_BYTES = 10; // 80 bits -> 16 base32 chars
+function defaultFillRandom(bytes) {
+    globalThis.crypto.getRandomValues(bytes);
+}
+/**
+ * ulid returns a 26-character uppercase Crockford-base32 ULID. The clock and
+ * the random source are injectable for deterministic tests; the defaults are
+ * Date.now() and crypto.getRandomValues.
+ */
+export function ulid(now, fillRandom) {
+    let ms = now ?? Date.now();
+    let time = "";
+    for (let i = 0; i < TIME_CHARS; i++) {
+        time = ALPHABET[ms % 32] + time;
+        ms = Math.floor(ms / 32);
+    }
+    const bytes = new Uint8Array(RANDOM_BYTES);
+    (fillRandom ?? defaultFillRandom)(bytes);
+    // Pack 80 bits into 16 5-bit groups, most significant bit first.
+    let random = "";
+    let bitBuffer = 0;
+    let bitCount = 0;
+    for (const byte of bytes) {
+        bitBuffer = (bitBuffer << 8) | byte;
+        bitCount += 8;
+        while (bitCount >= 5) {
+            random += ALPHABET[(bitBuffer >>> (bitCount - 5)) & 31];
+            bitCount -= 5;
+        }
+    }
+    return time + random;
+}

package/dist/collect/variationviews.d.ts

@@ -0,0 +1,31 @@
+import type { PendingEvent } from "./batcher.js";
+import type { DebugFn } from "./config.js";
+export declare const VARIATION_VIEW_EVENT = "rum.variation_view";
+interface NodeLike {
+    nodeType: number;
+    element?: Element;
+}
+interface MutationRecordLike {
+    addedNodes: ArrayLike<NodeLike>;
+}
+interface MutationObserverLike {
+    observe(target: Node, options: {
+        subtree?: boolean;
+        childList?: boolean;
+    }): void;
+    disconnect(): void;
+}
+type MutationCallback = (records: MutationRecordLike[], observer: MutationObserverLike) => void;
+type MutationObserverCtor = new (callback: MutationCallback) => MutationObserverLike;
+export interface VariationViewEnv {
+    document: Document;
+    MutationObserver?: MutationObserverCtor | undefined;
+    debug?: DebugFn;
+}
+/**
+ * startVariationViews observes document.body for elements tagged with
+ * data-aci-variation and emits rum.variation_view once per element per page
+ * view. Returns silently when MutationObserver is unavailable.
+ */
+export declare function startVariationViews(emit: (event: PendingEvent) => void, env: VariationViewEnv): void;
+export {};

package/dist/collect/variationviews.js

@@ -0,0 +1,80 @@
+// Variation views (design/04): eventName "rum.variation_view" with
+// { variantKey }. A MutationObserver on document.body watches for elements
+// tagged with data-aci-variation (value = variation/experience key) and emits
+// once per element per page view (WeakSet, same shape as declarative visible
+// tracking). If MutationObserver is missing the collector is a no-op. Errors
+// are swallowed silently.
+export const VARIATION_VIEW_EVENT = "rum.variation_view";
+const VARIATION_ATTR = "data-aci-variation";
+/**
+ * startVariationViews observes document.body for elements tagged with
+ * data-aci-variation and emits rum.variation_view once per element per page
+ * view. Returns silently when MutationObserver is unavailable.
+ */
+export function startVariationViews(emit, env) {
+    const { document: doc, debug } = env;
+    const Observer = env.MutationObserver;
+    if (typeof Observer !== "function")
+        return;
+    const loc = doc.defaultView?.location;
+    const seen = new WeakSet();
+    const emitFor = (el) => {
+        const key = el.getAttribute(VARIATION_ATTR);
+        if (key == null)
+            return;
+        if (seen.has(el))
+            return;
+        seen.add(el);
+        emit({
+            eventName: VARIATION_VIEW_EVENT,
+            url: loc?.href,
+            properties: { variantKey: key },
+        });
+    };
+    const scan = (root) => {
+        try {
+            if (root.hasAttribute(VARIATION_ATTR))
+                emitFor(root);
+            for (const el of Array.from(root.querySelectorAll(`[${VARIATION_ATTR}]`))) {
+                emitFor(el);
+            }
+        }
+        catch (err) {
+            debug?.("capture", { reason: "variation_scan_failed", error: String(err) });
+        }
+    };
+    try {
+        const body = doc.body ?? doc.documentElement;
+        if (body)
+            scan(body);
+    }
+    catch (err) {
+        debug?.("capture", { reason: "variation_initial_scan_failed", error: String(err) });
+    }
+    try {
+        const body = doc.body ?? doc.documentElement;
+        if (!body)
+            return;
+        const observer = new Observer((records) => {
+            try {
+                for (const record of records) {
+                    for (let i = 0; i < record.addedNodes.length; i++) {
+                        const node = record.addedNodes[i];
+                        if (node?.nodeType !== 1)
+                            continue;
+                        const el = node.element;
+                        if (el)
+                            scan(el);
+                    }
+                }
+            }
+            catch (err) {
+                debug?.("capture", { reason: "variation_observer_failed", error: String(err) });
+            }
+        });
+        observer.observe(body, { subtree: true, childList: true });
+    }
+    catch (err) {
+        debug?.("capture", { reason: "variation_observe_failed", error: String(err) });
+    }
+}

package/dist/collect/webvitals.d.ts

@@ -0,0 +1,38 @@
+import type { PendingEvent } from "./batcher.js";
+import type { DebugFn } from "./config.js";
+export declare const WEB_VITAL_EVENT = "rum.web_vital";
+interface PerformanceEntryLike {
+    entryType: string;
+    name?: string;
+    startTime: number;
+    value?: number;
+    responseStart?: number;
+    requestStart?: number;
+    hadRecentInput?: boolean;
+}
+interface PerformanceLike {
+    getEntriesByType(type: string): PerformanceEntryLike[];
+}
+interface WindowLike {
+    location: {
+        href: string;
+    };
+    addEventListener(type: string, fn: () => void): void;
+}
+interface DocumentLike {
+    visibilityState?: string;
+    addEventListener(type: string, fn: () => void): void;
+}
+export interface WebVitalsEnv {
+    performance?: PerformanceLike;
+    PerformanceObserver?: typeof PerformanceObserver | undefined;
+    window?: WindowLike | undefined;
+    document?: DocumentLike | undefined;
+    debug?: DebugFn;
+}
+/**
+ * startWebVitals observes Core Web Vitals and emits one rum.web_vital per
+ * vital. Returns silently when PerformanceObserver is unavailable.
+ */
+export declare function startWebVitals(emit: (event: PendingEvent) => void, env: WebVitalsEnv): void;
+export {};