@gradial/aci 0.1.28 → 0.1.30

package/dist/collect/consent/adapters/trustarc.js

@@ -0,0 +1,65 @@
+// TrustArc adapter: implemented against the documented
+// window.truste.cma.callApi("getConsentDecision", domain) surface, which
+// returns { consentDecision: <bucket level>, source }. Bucket levels map to
+// cumulative categories: 1 = required, 2 = +functional, 3 = +advertising.
+// Level 0 (no decision) writes nothing (fail closed). Consent changes are
+// detected via TrustArc's PrivacyManagerAPI postMessage traffic, which
+// triggers a re-read. TrustArc's client surfaces vary by deployment; this
+// is the simplest documented shape (noted in the implementation report).
+import { guard, handleCmpState, pollForGlobal, } from "../mapping.js";
+const PRESET = "trustarc";
+const BUCKET_LEVELS = {
+    required: 1,
+    functional: 2,
+    advertising: 3,
+};
+const API_MARKER = "PrivacyManagerAPI";
+function readCma(w) {
+    const truste = w.truste;
+    const cma = truste?.cma;
+    const callApi = cma?.callApi;
+    return typeof callApi === "function"
+        ? callApi.bind(cma)
+        : undefined;
+}
+function normalizeDecision(result) {
+    if (typeof result !== "object" || result === null)
+        return undefined;
+    const decision = result.consentDecision;
+    if (typeof decision !== "number" || !Number.isFinite(decision) || decision < 1) {
+        return undefined; // no asserted decision: fail closed
+    }
+    const categories = {};
+    for (const [name, level] of Object.entries(BUCKET_LEVELS)) {
+        categories[name] = decision >= level;
+    }
+    return { categories };
+}
+function mentionsPrivacyManager(data) {
+    if (typeof data === "string")
+        return data.includes(API_MARKER);
+    return typeof data === "object" && data !== null && API_MARKER in data;
+}
+function hostnameOf(w) {
+    const location = w.location;
+    return typeof location?.hostname === "string" ? location.hostname : undefined;
+}
+export function start(deps) {
+    const readAndHandle = () => {
+        const callApi = readCma(deps.window);
+        if (!callApi)
+            return;
+        const state = normalizeDecision(callApi("getConsentDecision", hostnameOf(deps.window)));
+        if (state)
+            handleCmpState(state, PRESET, deps);
+    };
+    const target = deps.window;
+    if (typeof target.addEventListener === "function") {
+        target.addEventListener("message", (ev) => guard(deps.debug, () => {
+            if (!mentionsPrivacyManager(ev?.data))
+                return;
+            readAndHandle();
+        }));
+    }
+    pollForGlobal(() => readCma(deps.window), () => guard(deps.debug, readAndHandle), deps);
+}

package/dist/collect/consent/envelope.d.ts

@@ -0,0 +1,49 @@
+export declare const PERSONALIZATION_PURPOSE = "personalization";
+export declare const CONSENT_COOKIE = "aci_consent";
+export declare const CONSENT_ENVELOPE_VERSION = 1;
+/** Consent persistence horizon; the CMP remains the source of truth. */
+export declare const CONSENT_MAX_AGE_S: number;
+export interface CookieDocument {
+    cookie: string;
+    location?: {
+        protocol?: string;
+    };
+}
+export interface ConsentWriteDeps {
+    document: CookieDocument;
+    now?: () => number;
+}
+export interface Purgeable {
+    purge(): void;
+}
+export interface ApplyConsentDeps extends ConsentWriteDeps {
+    gapBuffer?: Purgeable;
+}
+/**
+ * writeConsent builds the {v:1, p, t, src} envelope, URL-encodes it and sets
+ * the aci_consent cookie (Path=/, SameSite=Lax, Secure on https).
+ */
+export declare function writeConsent(purposes: string[], src: string, deps: ConsentWriteDeps): void;
+/**
+ * applyConsent is the single write path for every consent decision — CMP
+ * adapters and the manual JS API alike. Any decision where personalization
+ * is absent purges the gap buffer (REQ-8), and the envelope is still
+ * written: withdrawal must reach the server.
+ */
+export declare function applyConsent(purposes: string[], src: string, deps: ApplyConsentDeps): void;
+/** readConsentCookie returns the raw (still URL-encoded) cookie value. */
+export declare function readConsentCookie(doc: {
+    cookie: string;
+}): string | undefined;
+/**
+ * envelopeGrantsPersonalization mirrors the server-side check: URL-decode,
+ * accept legacy bare tokens, else parse the JSON envelope and look for the
+ * personalization purpose. Anything unreadable grants nothing.
+ */
+export declare function envelopeGrantsPersonalization(raw: string | undefined): boolean;
+/**
+ * sanitizePurposes validates a caller-supplied purposes value (the manual
+ * consent API): an array of strings, trimmed. Anything else is undefined
+ * and the command is ignored.
+ */
+export declare function sanitizePurposes(raw: unknown): string[] | undefined;

package/dist/collect/consent/envelope.js

@@ -0,0 +1,100 @@
+// Consent envelope writer (design/04, D-ONB-4): the aci_consent cookie
+// carries URL-encoded JSON {v:1, p, t, src} — cookie values cannot carry
+// quotes. The collector and the edge URL-decode before parsing, with a
+// legacy bare-token fallback during the deprecation window.
+export const PERSONALIZATION_PURPOSE = "personalization";
+export const CONSENT_COOKIE = "aci_consent";
+export const CONSENT_ENVELOPE_VERSION = 1;
+/** Consent persistence horizon; the CMP remains the source of truth. */
+export const CONSENT_MAX_AGE_S = 365 * 24 * 60 * 60;
+/** Mirrors the server-side grandfathered tokens (audience collect_signals). */
+const LEGACY_GRANT_TOKENS = new Set([
+    "true",
+    "all",
+    "granted",
+    "yes",
+    "personalization",
+    "personalized",
+]);
+/**
+ * writeConsent builds the {v:1, p, t, src} envelope, URL-encodes it and sets
+ * the aci_consent cookie (Path=/, SameSite=Lax, Secure on https).
+ */
+export function writeConsent(purposes, src, deps) {
+    const envelope = {
+        v: CONSENT_ENVELOPE_VERSION,
+        p: purposes,
+        t: new Date((deps.now ?? Date.now)()).toISOString(),
+        src,
+    };
+    const value = encodeURIComponent(JSON.stringify(envelope));
+    let cookie = `${CONSENT_COOKIE}=${value}; Path=/; Max-Age=${CONSENT_MAX_AGE_S}; SameSite=Lax`;
+    if (deps.document.location?.protocol === "https:") {
+        cookie += "; Secure";
+    }
+    deps.document.cookie = cookie;
+}
+/**
+ * applyConsent is the single write path for every consent decision — CMP
+ * adapters and the manual JS API alike. Any decision where personalization
+ * is absent purges the gap buffer (REQ-8), and the envelope is still
+ * written: withdrawal must reach the server.
+ */
+export function applyConsent(purposes, src, deps) {
+    if (!purposes.includes(PERSONALIZATION_PURPOSE)) {
+        deps.gapBuffer?.purge();
+    }
+    writeConsent(purposes, src, deps);
+}
+/** readConsentCookie returns the raw (still URL-encoded) cookie value. */
+export function readConsentCookie(doc) {
+    for (const part of doc.cookie.split(";")) {
+        const trimmed = part.trim();
+        if (trimmed.startsWith(CONSENT_COOKIE + "=")) {
+            return trimmed.slice(CONSENT_COOKIE.length + 1);
+        }
+    }
+    return undefined;
+}
+/**
+ * envelopeGrantsPersonalization mirrors the server-side check: URL-decode,
+ * accept legacy bare tokens, else parse the JSON envelope and look for the
+ * personalization purpose. Anything unreadable grants nothing.
+ */
+export function envelopeGrantsPersonalization(raw) {
+    if (raw === undefined || raw === "")
+        return false;
+    let decoded = raw;
+    try {
+        decoded = decodeURIComponent(raw);
+    }
+    catch {
+        // Not URL-encoded; evaluate as-is.
+    }
+    if (LEGACY_GRANT_TOKENS.has(decoded.trim().toLowerCase()))
+        return true;
+    try {
+        const envelope = JSON.parse(decoded);
+        return (Array.isArray(envelope.p) &&
+            envelope.p.includes(PERSONALIZATION_PURPOSE));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * sanitizePurposes validates a caller-supplied purposes value (the manual
+ * consent API): an array of strings, trimmed. Anything else is undefined
+ * and the command is ignored.
+ */
+export function sanitizePurposes(raw) {
+    if (!Array.isArray(raw))
+        return undefined;
+    const purposes = [];
+    for (const item of raw) {
+        if (typeof item !== "string")
+            return undefined;
+        purposes.push(item.trim());
+    }
+    return purposes;
+}

package/dist/collect/consent/mapping.d.ts

@@ -0,0 +1,62 @@
+import type { DebugFn } from "../config.js";
+import { type CookieDocument, type Purgeable } from "./envelope.js";
+/** A CMP state normalized by its adapter: category -> granted. */
+export interface NormalizedCmpState {
+    categories: Record<string, boolean>;
+}
+/** Sane per-preset defaults for the flat category list (design/04). */
+export declare const PRESET_DEFAULT_CATEGORIES: Record<string, string>;
+/**
+ * resolveCategories parses the configured flat comma list (or the preset
+ * default) into normalized category tokens. Returns null when the list is
+ * unparseable — the caller writes NOTHING (fail closed).
+ */
+export declare function resolveCategories(preset: string, raw: string | undefined): string[] | null;
+/**
+ * mapCategories maps a normalized CMP state through the configured category
+ * list: the personalization purpose is granted when any recognized category
+ * is granted (single-purpose world, DD-ONB-6).
+ */
+export declare function mapCategories(state: NormalizedCmpState, categories: string[]): string[];
+export interface ConsentTargetDeps {
+    document: CookieDocument;
+    /** Raw configured category list (tag attribute); preset default when absent. */
+    categories?: string | undefined;
+    gapBuffer?: Purgeable | undefined;
+    debug?: DebugFn | undefined;
+    now?: (() => number) | undefined;
+}
+/**
+ * handleCmpState is the shared onCmpChange: resolve the mapping, reject the
+ * two fail-closed cases, then apply the decision through the single write
+ * path. Nothing thrown inside ever escapes to the CMP or the page.
+ */
+export declare function handleCmpState(state: NormalizedCmpState, preset: string, deps: ConsentTargetDeps): void;
+export interface PollScheduler {
+    setTimeout(fn: () => void, ms: number): unknown;
+    clearTimeout(id: unknown): void;
+}
+export interface AdapterDeps extends ConsentTargetDeps {
+    /** The page window hosting the CMP global. */
+    window: Record<string, unknown>;
+    /** Injectable clock for the CMP poll. */
+    scheduler?: PollScheduler | undefined;
+}
+export declare const CMP_POLL_INTERVAL_MS = 250;
+export declare const CMP_POLL_TIMEOUT_MS = 10000;
+/**
+ * pollForGlobal waits for a CMP global to appear: an immediate read, then a
+ * poll every CMP_POLL_INTERVAL_MS for up to CMP_POLL_TIMEOUT_MS, then give
+ * up silently (D-ONB-8). A throwing read counts as a sabotaged CMP and
+ * stops the poll.
+ */
+export declare function pollForGlobal<T>(read: () => T | undefined, onReady: (value: T) => void, deps?: {
+    scheduler?: PollScheduler | undefined;
+    debug?: DebugFn | undefined;
+}): void;
+/**
+ * guard contains adapter callbacks: any exception from a CMP surface is
+ * swallowed after a debug record — no cookie write happens, nothing escapes
+ * to the page (the sabotaged-adapter contract).
+ */
+export declare function guard(debug: DebugFn | undefined, fn: () => void): void;

package/dist/collect/consent/mapping.js

@@ -0,0 +1,129 @@
+// Shared consent-mapping core (design/05, D-ONB-8): every CMP adapter is a
+// thin subscription over this module. Three-case writer semantics (REQ-7):
+// (a) an unparseable mapping or an unrecognized CMP state writes NOTHING
+// (fail closed); (b) a genuine revoke writes the empty-purposes envelope and
+// purges the gap buffer; (c) a grant writes the purposes.
+import { applyConsent, PERSONALIZATION_PURPOSE, } from "./envelope.js";
+const CMP_SOURCE_PREFIX = "cmp-";
+const CATEGORY_TOKEN = /^[a-z0-9._-]+$/;
+/** Sane per-preset defaults for the flat category list (design/04). */
+export const PRESET_DEFAULT_CATEGORIES = {
+    c15t: "measurement,marketing",
+    onetrust: "c0002,c0004",
+    cookiebot: "statistics,marketing",
+    trustarc: "functional,advertising",
+};
+/**
+ * resolveCategories parses the configured flat comma list (or the preset
+ * default) into normalized category tokens. Returns null when the list is
+ * unparseable — the caller writes NOTHING (fail closed).
+ */
+export function resolveCategories(preset, raw) {
+    const source = raw ?? PRESET_DEFAULT_CATEGORIES[preset];
+    if (source === undefined)
+        return null;
+    const tokens = source
+        .split(",")
+        .map((token) => token.trim().toLowerCase())
+        .filter((token) => token !== "");
+    if (tokens.length === 0)
+        return null;
+    for (const token of tokens) {
+        if (!CATEGORY_TOKEN.test(token))
+            return null; // one bad token poisons the mapping
+    }
+    return tokens;
+}
+/**
+ * mapCategories maps a normalized CMP state through the configured category
+ * list: the personalization purpose is granted when any recognized category
+ * is granted (single-purpose world, DD-ONB-6).
+ */
+export function mapCategories(state, categories) {
+    const known = categories.filter((c) => c in state.categories);
+    return known.some((c) => state.categories[c] === true)
+        ? [PERSONALIZATION_PURPOSE]
+        : [];
+}
+/**
+ * handleCmpState is the shared onCmpChange: resolve the mapping, reject the
+ * two fail-closed cases, then apply the decision through the single write
+ * path. Nothing thrown inside ever escapes to the CMP or the page.
+ */
+export function handleCmpState(state, preset, deps) {
+    try {
+        const categories = resolveCategories(preset, deps.categories);
+        if (categories === null) {
+            deps.debug?.("consent", { reason: "unparseable_mapping", preset });
+            return;
+        }
+        const known = categories.filter((c) => c in state.categories);
+        if (known.length === 0) {
+            deps.debug?.("consent", { reason: "unmappable_cmp_state", preset });
+            return;
+        }
+        const purposes = mapCategories(state, categories);
+        applyConsent(purposes, CMP_SOURCE_PREFIX + preset, {
+            document: deps.document,
+            gapBuffer: deps.gapBuffer,
+            now: deps.now,
+        });
+        deps.debug?.("consent", { reason: "written", preset, purposes });
+    }
+    catch (err) {
+        deps.debug?.("consent", {
+            reason: "consent_bridge_failed",
+            preset,
+            error: String(err),
+        });
+    }
+}
+export const CMP_POLL_INTERVAL_MS = 250;
+export const CMP_POLL_TIMEOUT_MS = 10_000;
+/**
+ * pollForGlobal waits for a CMP global to appear: an immediate read, then a
+ * poll every CMP_POLL_INTERVAL_MS for up to CMP_POLL_TIMEOUT_MS, then give
+ * up silently (D-ONB-8). A throwing read counts as a sabotaged CMP and
+ * stops the poll.
+ */
+export function pollForGlobal(read, onReady, deps) {
+    const scheduler = deps?.scheduler ?? {
+        setTimeout: (fn, ms) => setTimeout(fn, ms),
+        clearTimeout: (id) => clearTimeout(id),
+    };
+    let remaining = Math.floor(CMP_POLL_TIMEOUT_MS / CMP_POLL_INTERVAL_MS);
+    const attempt = () => {
+        let value;
+        try {
+            value = read();
+        }
+        catch (err) {
+            deps?.debug?.("consent", { reason: "cmp_read_failed", error: String(err) });
+            return;
+        }
+        if (value !== undefined) {
+            onReady(value);
+            return;
+        }
+        remaining -= 1;
+        if (remaining <= 0) {
+            deps?.debug?.("consent", { reason: "cmp_not_found" });
+            return;
+        }
+        scheduler.setTimeout(attempt, CMP_POLL_INTERVAL_MS);
+    };
+    attempt();
+}
+/**
+ * guard contains adapter callbacks: any exception from a CMP surface is
+ * swallowed after a debug record — no cookie write happens, nothing escapes
+ * to the page (the sabotaged-adapter contract).
+ */
+export function guard(debug, fn) {
+    try {
+        fn();
+    }
+    catch (err) {
+        debug?.("consent", { reason: "adapter_failed", error: String(err) });
+    }
+}

package/dist/collect/declarative.d.ts

@@ -0,0 +1,35 @@
+import type { PendingEvent } from "./batcher.js";
+import type { DebugFn } from "./config.js";
+interface ObserverEntryLike {
+    target: Element;
+    isIntersecting: boolean;
+    intersectionRatio: number;
+}
+interface ObserverLike {
+    observe(el: Element): void;
+    unobserve(el: Element): void;
+    disconnect(): void;
+}
+type ObserverCtor = new (callback: (entries: ObserverEntryLike[], observer: ObserverLike) => void, options?: {
+    threshold?: number | number[];
+}) => ObserverLike;
+export interface DeclarativeEnv {
+    document: Document;
+    /** IntersectionObserver constructor; absent means no visible triggers. */
+    intersectionObserver?: ObserverCtor | undefined;
+    debug?: DebugFn;
+}
+/**
+ * toCustomEventName normalizes a declared or API-supplied event name into
+ * the custom.* namespace: trimmed, lowercased, prefix enforced (never
+ * duplicated). Returns undefined for malformed names (empty, whitespace,
+ * slashes, non-strings), which callers ignore silently.
+ */
+export declare function toCustomEventName(raw: unknown): string | undefined;
+/**
+ * startDeclarative installs the delegated click listener and, when the
+ * environment has an IntersectionObserver, observes every visible-declared
+ * element present at start.
+ */
+export declare function startDeclarative(emit: (event: PendingEvent) => void, env: DeclarativeEnv): void;
+export {};

package/dist/collect/declarative.js

@@ -0,0 +1,100 @@
+// Declarative events (design/04): elements opt in via data-aci-event, with
+// data-aci-on=click|visible (visible = first intersection >= 50%, once per
+// element per page view) and data-aci-prop-* string properties. One
+// delegated click listener + one IntersectionObserver regardless of element
+// count. Malformed declarations are ignored silently.
+const EVENT_ATTR = "data-aci-event";
+const ON_ATTR = "data-aci-on";
+const PROP_ATTR_PREFIX = "data-aci-prop-";
+const CUSTOM_PREFIX = "custom.";
+const VISIBLE_THRESHOLD = 0.5;
+/**
+ * toCustomEventName normalizes a declared or API-supplied event name into
+ * the custom.* namespace: trimmed, lowercased, prefix enforced (never
+ * duplicated). Returns undefined for malformed names (empty, whitespace,
+ * slashes, non-strings), which callers ignore silently.
+ */
+export function toCustomEventName(raw) {
+    if (typeof raw !== "string")
+        return undefined;
+    const name = raw.trim().toLowerCase();
+    if (name === "" || /[\s/]/.test(name))
+        return undefined;
+    return name.startsWith(CUSTOM_PREFIX) ? name : CUSTOM_PREFIX + name;
+}
+function extractProps(el) {
+    let props;
+    for (const attr of Array.from(el.attributes)) {
+        if (!attr.name.startsWith(PROP_ATTR_PREFIX))
+            continue;
+        const key = attr.name.slice(PROP_ATTR_PREFIX.length);
+        if (key === "")
+            continue;
+        (props ??= {})[key] = attr.value;
+    }
+    return props;
+}
+function declaredEvent(el, debug) {
+    const eventName = toCustomEventName(el.getAttribute(EVENT_ATTR));
+    if (eventName === undefined) {
+        debug?.("capture", { reason: "malformed_declaration", attr: EVENT_ATTR });
+        return undefined;
+    }
+    return { eventName, properties: extractProps(el) };
+}
+function trigger(el) {
+    return el.getAttribute(ON_ATTR)?.trim().toLowerCase() ?? "click";
+}
+/**
+ * startDeclarative installs the delegated click listener and, when the
+ * environment has an IntersectionObserver, observes every visible-declared
+ * element present at start.
+ */
+export function startDeclarative(emit, env) {
+    const { document: doc, debug } = env;
+    doc.addEventListener("click", (e) => {
+        try {
+            const target = e.target;
+            const el = target?.closest?.(`[${EVENT_ATTR}]`);
+            if (!el)
+                return;
+            if (trigger(el) !== "click")
+                return; // visible or malformed trigger
+            const event = declaredEvent(el, debug);
+            if (event)
+                emit(event);
+        }
+        catch (err) {
+            debug?.("capture", { reason: "click_handler_failed", error: String(err) });
+        }
+    });
+    const Observer = env.intersectionObserver;
+    if (typeof Observer !== "function")
+        return;
+    const visibleElements = Array.from(doc.querySelectorAll(`[${EVENT_ATTR}]`)).filter((el) => trigger(el) === "visible");
+    if (visibleElements.length === 0)
+        return;
+    const fired = new WeakSet();
+    const observer = new Observer((entries, obs) => {
+        try {
+            for (const entry of entries) {
+                if (!entry.isIntersecting)
+                    continue;
+                if (entry.intersectionRatio < VISIBLE_THRESHOLD)
+                    continue;
+                if (fired.has(entry.target))
+                    continue;
+                fired.add(entry.target);
+                obs.unobserve(entry.target); // once per element per page view
+                const event = declaredEvent(entry.target, debug);
+                if (event)
+                    emit(event);
+            }
+        }
+        catch (err) {
+            debug?.("capture", { reason: "visible_handler_failed", error: String(err) });
+        }
+    }, { threshold: VISIBLE_THRESHOLD });
+    for (const el of visibleElements)
+        observer.observe(el);
+}

package/dist/collect/gapbuffer.d.ts

@@ -0,0 +1,55 @@
+import type { CollectEvent } from "./batcher.js";
+import type { DebugFn } from "./config.js";
+export declare const GAP_BUFFER_KEY = "aci:buf";
+export declare const GAP_BUFFER_CAP = 50;
+export interface StorageLike {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+export interface GapBufferEnv {
+    storage?: StorageLike | undefined;
+    debug?: DebugFn | undefined;
+}
+export declare class GapBuffer {
+    private events;
+    private storage;
+    private readonly debug;
+    constructor(env?: GapBufferEnv);
+    push(event: CollectEvent): void;
+    /** drain returns and clears all buffered events, preserving order and ids. */
+    drain(): CollectEvent[];
+    /** purge empties the buffer (consent withdrawal). */
+    purge(): void;
+    size(): number;
+    private restore;
+    private persist;
+}
+/** hasMintMarker reports whether the edge-set aci_m marker cookie exists. */
+export declare function hasMintMarker(doc: {
+    cookie: string;
+}): boolean;
+export interface EventSink {
+    push(event: CollectEvent): void;
+}
+export interface RouteDeps {
+    /** Whether the consent envelope currently grants personalization. */
+    grants: () => boolean;
+    /** Whether the mint marker cookie is present. */
+    marker: () => boolean;
+    gapBuffer: GapBuffer;
+    batcher: EventSink;
+}
+/**
+ * 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 declare function routeEvent(event: CollectEvent, deps: RouteDeps): void;
+/**
+ * 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 declare function maybeFlushGapBuffer(gapBuffer: GapBuffer, batcher: EventSink, marker: () => boolean, debug?: DebugFn): void;