@gradial/aci 0.1.28 → 0.1.30

package/README.md

@@ -94,6 +94,53 @@ List available templates:
 npx @gradial/aci@0.1.27 init --list
 ```
 
+## Personalization: The One-Tag Install
+
+Personalization collection is one script tag. Externally rendered sites paste
+it once, verbatim; Gradial-rendered sites (Next `createPage`, the Astro
+starter layout) emit the same tag automatically and never hand-write it:
+
+```html
+<script defer src="/_aci/aci.js" data-aci-consent="c15t"></script>
+```
+
+**Boundary (v1):** the site MUST be served through a Gradial edge binding
+(CloudFront, Vercel, or the local adapter). The edge serves the SDK at the
+stable `/_aci/aci.js` URL, provides `/collect`, and mints visitor identity —
+none of which exist on fully external hosting, which is out of scope pending
+OQ-6 (REQ-13).
+
+Tag attributes (the tag is the only per-site configuration surface):
+
+| Attribute | Meaning |
+| --- | --- |
+| `data-aci-consent` | CMP preset: `c15t`, `onetrust`, `cookiebot`, `trustarc`, or `manual` (default `manual` — only the JS consent API `aci('consent', …)` writes envelopes) |
+| `data-aci-consent-categories` | Flat comma list of CMP categories that imply the personalization purpose (e.g. `measurement,marketing`); each preset ships a sane default |
+| `data-aci-site` | Optional site ID, debug only — the edge binding is the site authority |
+| `data-aci-debug` | `1` enables structured `console.debug` diagnostics |
+
+For Gradial-rendered sites the tag is driven by an optional block on the
+site config doc (`/config/site.json`); absent block = disabled, no tag:
+
+```json
+{
+  "personalization": {
+    "collect": true,
+    "consentPreset": "c15t",
+    "consentCategories": "measurement,marketing"
+  }
+}
+```
+
+The starter kits default to the `c15t` preset. The Next kit ships a working
+c15t setup (`ConsentManager` in `src/app/_components/`, offline mode by
+default, hosted mode via `NEXT_PUBLIC_C15T_BACKEND_URL`) plus the bridge
+that mirrors the c15t store onto `window.c15t`, where the SDK reads it. c15t
+has no Astro UI package, so the Astro kit ships the bridge only (in
+`SiteLayout.astro`): add a banner via a React island (`@astrojs/react` +
+`@c15t/react`) or any setup built on c15t's store and the bridge picks it
+up; until then only the `manual` JS consent API writes envelopes.
+
 ## Verify Locally
 
 From `packages/sdk`:

package/dist/astro/index.d.ts

@@ -38,6 +38,7 @@ export declare function getPageRuntimeRenderInput(request: Request): RenderInput
 export { createRegistry, registryLookup } from '../registry.js';
 export type { Registry, RegistryEntry, AnyComponent } from '../registry.js';
 export type { BlockRef } from '../types/block-ref.js';
+export { collectScriptTagHTML, collectTagAttributes, COLLECT_SCRIPT_SRC, type CollectTagAttributes, type PersonalizationSiteConfig, type SitePersonalizationConfig, } from '../content/personalization.js';
 export interface RenderableBlock {
     Component: AnyComponent | undefined;
     props: Record<string, unknown>;

package/dist/astro/index.js

@@ -36,6 +36,13 @@ export function getPageRuntimeRenderInput(request) {
 // Registry helpers
 // ---------------------------------------------------------------------------
 export { createRegistry, registryLookup } from '../registry.js';
+// ---------------------------------------------------------------------------
+// Personalization collect tag — the Astro integration has no attribute-
+// bearing HTML-emission seam (injectScript injects script *content*, not a
+// tag with data attributes), so the kit layout emits the contract tag via
+// this snippet builder (design/04; design/09 Task 9b).
+// ---------------------------------------------------------------------------
+export { collectScriptTagHTML, collectTagAttributes, COLLECT_SCRIPT_SRC, } from '../content/personalization.js';
 export function createRenderChildren(registry) {
     function renderChildren(blocks) {
         return blocks.map((block) => {

package/dist/collect/api.d.ts

@@ -0,0 +1,24 @@
+import type { DebugFn } from "./config.js";
+export interface CommandHandlers {
+    /** Receives the normalized custom.* event name. */
+    track: (name: string, properties?: Record<string, unknown>) => void;
+    /** Manual consent write; only reachable under the manual preset. */
+    consent: (envelope: {
+        p: unknown;
+        src: unknown;
+    }) => void;
+}
+export interface CommandQueueConfig {
+    preset: string;
+}
+interface AciHost {
+    aci?: unknown;
+}
+/**
+ * installCommandQueue replaces any pre-load stub on window.aci with the live
+ * dispatcher, draining queued calls in order first. Malformed or unknown
+ * commands are ignored after a debug record; the CMP preset is authoritative
+ * over consent commands (manual mode only).
+ */
+export declare function installCommandQueue(win: AciHost, cfg: CommandQueueConfig, handlers: CommandHandlers, debug?: DebugFn): void;
+export {};

package/dist/collect/api.js

@@ -0,0 +1,63 @@
+// Browser command API (design/04): window.aci is a write-only command
+// queue. Pre-load calls push onto aci.q via the documented array-push stub;
+// installCommandQueue drains that queue in order and becomes the live
+// dispatcher. Commands return undefined — nothing is readable back.
+import { toCustomEventName } from "./declarative.js";
+function isPlainObjectLike(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * installCommandQueue replaces any pre-load stub on window.aci with the live
+ * dispatcher, draining queued calls in order first. Malformed or unknown
+ * commands are ignored after a debug record; the CMP preset is authoritative
+ * over consent commands (manual mode only).
+ */
+export function installCommandQueue(win, cfg, handlers, debug) {
+    const dispatch = (...args) => {
+        try {
+            const [command, ...rest] = args;
+            if (command === "track") {
+                const name = toCustomEventName(rest[0]);
+                if (name === undefined) {
+                    debug?.("capture", { reason: "malformed_track_name", name: rest[0] });
+                    return undefined;
+                }
+                const properties = rest[1];
+                if (properties !== undefined && !isPlainObjectLike(properties)) {
+                    debug?.("capture", { reason: "malformed_track_properties", name });
+                    return undefined;
+                }
+                handlers.track(name, properties);
+                return undefined;
+            }
+            if (command === "consent") {
+                if (cfg.preset !== "manual") {
+                    // The CMP is authoritative (design/04 consent-writer precedence).
+                    debug?.("consent", { reason: "preset_authoritative", preset: cfg.preset });
+                    return undefined;
+                }
+                const envelope = rest[0];
+                if (!isPlainObjectLike(envelope)) {
+                    debug?.("consent", { reason: "malformed_consent_envelope" });
+                    return undefined;
+                }
+                handlers.consent({ p: envelope.p, src: envelope.src });
+                return undefined;
+            }
+            debug?.("capture", { reason: "unknown_command", command });
+        }
+        catch (err) {
+            debug?.("capture", { reason: "command_failed", error: String(err) });
+        }
+        return undefined;
+    };
+    const stub = win.aci;
+    const queued = stub?.q;
+    win.aci = dispatch;
+    if (queued == null)
+        return;
+    for (const call of Array.from(queued)) {
+        const args = Array.from(call);
+        dispatch(...args);
+    }
+}

package/dist/collect/batcher.d.ts

@@ -0,0 +1,65 @@
+import type { DebugFn } from "./config.js";
+/** One collect event on the wire (personalization-data-plane design/04). */
+export interface CollectEvent {
+    eventId: string;
+    eventName: string;
+    occurredAt?: string;
+    properties?: Record<string, unknown>;
+    url?: string;
+    referrer?: string;
+}
+/** An event at capture time, before the eventId is stamped. */
+export type PendingEvent = Omit<CollectEvent, "eventId">;
+/** Planning threshold: full serialized envelope, UTF-8 bytes. */
+export declare const MAX_BATCH_BYTES: number;
+/** Flush interval (build-time constant, design/04 config table). */
+export declare const FLUSH_INTERVAL_MS = 5000;
+export interface BatcherTimers {
+    setInterval(fn: () => void, ms: number): unknown;
+    clearInterval(id: unknown): void;
+}
+interface ListenerTarget {
+    addEventListener(type: string, fn: () => void): void;
+}
+export interface BatcherOptions {
+    /** Transport for one serialized batch envelope. */
+    send: (body: string) => void;
+    debug?: DebugFn;
+    /** Runs at the start of every flush tick (gap-buffer marker re-check). */
+    onTick?: () => void;
+    maxBatchBytes?: number;
+    flushIntervalMs?: number;
+    timers?: BatcherTimers;
+    documentTarget?: ListenerTarget & {
+        visibilityState?: string;
+    };
+    windowTarget?: ListenerTarget;
+}
+export declare class Batcher {
+    private readonly options;
+    private readonly maxBytes;
+    private queue;
+    private queuedBytes;
+    private flushing;
+    private intervalId;
+    constructor(options: BatcherOptions);
+    get pending(): number;
+    push(event: CollectEvent): void;
+    /**
+     * flush is one tick: run the onTick hook (which may push more events, e.g.
+     * a gap-buffer drain), then send everything queued in threshold-sized
+     * envelopes. Re-entrant pushes are drained in the same tick.
+     */
+    flush(): void;
+    /**
+     * start installs the interval and lifecycle flush triggers, then flushes
+     * immediately: init queues the initial page view before start (index.ts),
+     * and holding it for the first interval tick would delay the session's
+     * first signal by up to FLUSH_INTERVAL_MS.
+     */
+    start(): void;
+    stop(): void;
+    private envelopeBytes;
+    private drain;
+}
+export {};

package/dist/collect/batcher.js

@@ -0,0 +1,127 @@
+// Batcher (design/05): queue events, split so no request exceeds the 60 KiB
+// planning threshold (64 KiB wire ceiling), flush on start, size, interval,
+// visibilitychange and pagehide. Byte accounting is incremental — a running
+// per-event size computed at enqueue — so a flush stays O(n).
+/** Planning threshold: full serialized envelope, UTF-8 bytes. */
+export const MAX_BATCH_BYTES = 60 * 1024;
+/** Flush interval (build-time constant, design/04 config table). */
+export const FLUSH_INTERVAL_MS = 5000;
+const ENVELOPE_PREFIX = '{"events":[';
+const ENVELOPE_SUFFIX = "]}";
+const ENVELOPE_OVERHEAD = ENVELOPE_PREFIX.length + ENVELOPE_SUFFIX.length;
+const encoder = new TextEncoder();
+const utf8ByteLength = (s) => encoder.encode(s).length;
+export class Batcher {
+    options;
+    maxBytes;
+    queue = [];
+    queuedBytes = 0;
+    flushing = false;
+    intervalId;
+    constructor(options) {
+        this.options = options;
+        this.maxBytes = options.maxBatchBytes ?? MAX_BATCH_BYTES;
+    }
+    get pending() {
+        return this.queue.length;
+    }
+    push(event) {
+        const json = JSON.stringify(event);
+        const bytes = utf8ByteLength(json);
+        this.queue.push({ json, bytes, eventId: event.eventId });
+        this.queuedBytes += bytes;
+        if (!this.flushing && this.envelopeBytes() >= this.maxBytes) {
+            this.flush();
+        }
+    }
+    /**
+     * flush is one tick: run the onTick hook (which may push more events, e.g.
+     * a gap-buffer drain), then send everything queued in threshold-sized
+     * envelopes. Re-entrant pushes are drained in the same tick.
+     */
+    flush() {
+        if (this.flushing)
+            return;
+        this.flushing = true;
+        try {
+            this.options.onTick?.();
+            this.drain();
+        }
+        finally {
+            this.flushing = false;
+        }
+    }
+    /**
+     * start installs the interval and lifecycle flush triggers, then flushes
+     * immediately: init queues the initial page view before start (index.ts),
+     * and holding it for the first interval tick would delay the session's
+     * first signal by up to FLUSH_INTERVAL_MS.
+     */
+    start() {
+        const timers = this.options.timers ?? {
+            setInterval: (fn, ms) => setInterval(fn, ms),
+            clearInterval: (id) => clearInterval(id),
+        };
+        this.intervalId = timers.setInterval(() => this.flush(), this.options.flushIntervalMs ?? FLUSH_INTERVAL_MS);
+        const doc = this.options.documentTarget ??
+            (typeof document !== "undefined" ? document : undefined);
+        doc?.addEventListener("visibilitychange", () => {
+            if (doc.visibilityState === "hidden")
+                this.flush();
+        });
+        const win = this.options.windowTarget ??
+            (typeof window !== "undefined" ? window : undefined);
+        win?.addEventListener("pagehide", () => this.flush());
+        this.flush();
+    }
+    stop() {
+        if (this.intervalId !== undefined) {
+            const timers = this.options.timers;
+            if (timers) {
+                timers.clearInterval(this.intervalId);
+            }
+            else {
+                clearInterval(this.intervalId);
+            }
+            this.intervalId = undefined;
+        }
+    }
+    envelopeBytes() {
+        const commas = this.queue.length > 1 ? this.queue.length - 1 : 0;
+        return ENVELOPE_OVERHEAD + this.queuedBytes + commas;
+    }
+    drain() {
+        while (this.queue.length > 0) {
+            const head = this.queue[0];
+            if (ENVELOPE_OVERHEAD + head.bytes > this.maxBytes) {
+                // A single event whose own encoding exceeds the threshold: drop it
+                // with a debug record and keep going — never loop on it.
+                this.queue.shift();
+                this.queuedBytes -= head.bytes;
+                this.options.debug?.("flush", {
+                    reason: "oversize_event",
+                    eventId: head.eventId,
+                    bytes: head.bytes,
+                });
+                continue;
+            }
+            const parts = [];
+            let size = ENVELOPE_OVERHEAD;
+            while (this.queue.length > 0) {
+                const next = this.queue[0];
+                if (ENVELOPE_OVERHEAD + next.bytes > this.maxBytes)
+                    break; // oversize: outer loop drops it
+                const nextSize = size + next.bytes + (parts.length > 0 ? 1 : 0);
+                if (nextSize > this.maxBytes)
+                    break;
+                parts.push(next.json);
+                size = nextSize;
+                this.queue.shift();
+                this.queuedBytes -= next.bytes;
+            }
+            if (parts.length === 0)
+                continue;
+            this.options.send(ENVELOPE_PREFIX + parts.join(",") + ENVELOPE_SUFFIX);
+        }
+    }
+}

package/dist/collect/config.d.ts

@@ -0,0 +1,30 @@
+export type ConsentPreset = "c15t" | "onetrust" | "cookiebot" | "trustarc" | "manual";
+export interface TagConfig {
+    /** Optional site id, for debug and a future multi-site surface. */
+    site: string | undefined;
+    /** CMP preset; "manual" means only the JS consent API writes envelopes. */
+    preset: ConsentPreset;
+    /** Raw flat comma list of CMP categories implying personalization. */
+    categories: string | undefined;
+    /** Structured console.debug diagnostics enabled (data-aci-debug="1"). */
+    debug: boolean;
+}
+/**
+ * Structured diagnostics kinds (design/05): stable event-shaped records a
+ * future debug overlay can render. "init" covers configuration and swallowed
+ * init failures.
+ */
+export type DebugKind = "init" | "capture" | "consent" | "flush" | "buffer";
+export type DebugFn = (kind: DebugKind, detail: unknown) => void;
+/**
+ * readTagConfig parses the data-aci-* attributes off the SDK's own script
+ * element (document.currentScript). Missing or unrecognized values fall back
+ * to safe defaults; unknown attributes are tolerated.
+ */
+export declare function readTagConfig(script: Element | null | undefined): TagConfig;
+/**
+ * createDebug returns the structured debug emitter: {t, kind, detail}
+ * records via console.debug when enabled, a no-op otherwise. The sink and
+ * clock are injectable for tests. Diagnostics never throw.
+ */
+export declare function createDebug(enabled: boolean, log?: (record: unknown) => void, now?: () => number): DebugFn;

package/dist/collect/config.js

@@ -0,0 +1,53 @@
+// Tag configuration (design/04): the script tag is the only per-site
+// configuration surface. Unknown attributes are ignored.
+const PRESETS = new Set([
+    "c15t",
+    "onetrust",
+    "cookiebot",
+    "trustarc",
+    "manual",
+]);
+function attribute(script, name) {
+    const value = script?.getAttribute?.(name);
+    if (value == null)
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed === "" ? undefined : trimmed;
+}
+/**
+ * readTagConfig parses the data-aci-* attributes off the SDK's own script
+ * element (document.currentScript). Missing or unrecognized values fall back
+ * to safe defaults; unknown attributes are tolerated.
+ */
+export function readTagConfig(script) {
+    const rawPreset = attribute(script, "data-aci-consent")?.toLowerCase();
+    const preset = rawPreset !== undefined && PRESETS.has(rawPreset)
+        ? rawPreset
+        : "manual";
+    return {
+        site: attribute(script, "data-aci-site"),
+        preset,
+        categories: attribute(script, "data-aci-consent-categories"),
+        debug: attribute(script, "data-aci-debug") === "1",
+    };
+}
+/**
+ * createDebug returns the structured debug emitter: {t, kind, detail}
+ * records via console.debug when enabled, a no-op otherwise. The sink and
+ * clock are injectable for tests. Diagnostics never throw.
+ */
+export function createDebug(enabled, log, now) {
+    if (!enabled) {
+        return () => { };
+    }
+    const emit = log ?? ((record) => console.debug("[aci]", record));
+    const clock = now ?? Date.now;
+    return (kind, detail) => {
+        try {
+            emit({ t: clock(), kind, detail });
+        }
+        catch {
+            // Diagnostics must never affect the page.
+        }
+    };
+}

package/dist/collect/consent/adapters/c15t.d.ts

@@ -0,0 +1,2 @@
+import { type AdapterDeps } from "../mapping.js";
+export declare function start(deps: AdapterDeps): void;

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

@@ -0,0 +1,43 @@
+// c15t adapter (P0, dogfood): a thin subscription over the shared mapping
+// core. Reads window.c15t's consents record (category -> boolean, modeled on
+// @c15t/nextjs's ConsentState) once on discovery, then follows
+// onConsentChange payloads (wrapped {consents} or a bare record).
+import { guard, handleCmpState, pollForGlobal, } from "../mapping.js";
+const PRESET = "c15t";
+function normalizeConsents(record) {
+    if (typeof record !== "object" || record === null)
+        return undefined;
+    const categories = {};
+    for (const [key, value] of Object.entries(record)) {
+        if (typeof value === "boolean")
+            categories[key.toLowerCase()] = value;
+    }
+    return { categories };
+}
+function payloadConsents(payload, c15t) {
+    if (typeof payload === "object" && payload !== null) {
+        if ("consents" in payload) {
+            return payload.consents;
+        }
+        return payload; // bare consents record
+    }
+    return c15t.consents; // unknown payload shape: re-read the global
+}
+export function start(deps) {
+    pollForGlobal(() => {
+        const c15t = deps.window.c15t;
+        return typeof c15t === "object" && c15t !== null
+            ? c15t
+            : undefined;
+    }, (c15t) => {
+        guard(deps.debug, () => {
+            const handle = (record) => {
+                const state = normalizeConsents(record);
+                if (state)
+                    handleCmpState(state, PRESET, deps);
+            };
+            handle(c15t.consents); // read the current state once
+            c15t.onConsentChange?.((payload) => guard(deps.debug, () => handle(payloadConsents(payload, c15t))));
+        });
+    }, deps);
+}

package/dist/collect/consent/adapters/cookiebot.d.ts

@@ -0,0 +1,2 @@
+import { type AdapterDeps } from "../mapping.js";
+export declare function start(deps: AdapterDeps): void;

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

@@ -0,0 +1,48 @@
+// Cookiebot adapter: reads window.Cookiebot.consent (a category -> boolean
+// record: preferences/statistics/marketing) and follows the documented
+// window events CookiebotOnConsentReady / CookiebotOnAccept /
+// CookiebotOnDecline. Before the visitor has responded
+// (Cookiebot.hasResponse !== true) the state is not a decision — the
+// adapter writes nothing (fail closed).
+import { guard, handleCmpState, pollForGlobal, } from "../mapping.js";
+const PRESET = "cookiebot";
+const CONSENT_EVENTS = [
+    "CookiebotOnConsentReady",
+    "CookiebotOnAccept",
+    "CookiebotOnDecline",
+];
+function readGlobal(w) {
+    const cookiebot = w.Cookiebot;
+    return typeof cookiebot === "object" && cookiebot !== null
+        ? cookiebot
+        : undefined;
+}
+function normalizeConsent(record) {
+    if (typeof record !== "object" || record === null)
+        return undefined;
+    const categories = {};
+    for (const [key, value] of Object.entries(record)) {
+        if (typeof value === "boolean")
+            categories[key.toLowerCase()] = value;
+    }
+    return { categories };
+}
+export function start(deps) {
+    const readAndHandle = () => {
+        const cookiebot = readGlobal(deps.window);
+        if (!cookiebot)
+            return;
+        if (cookiebot.hasResponse !== true)
+            return; // no decision yet: fail closed
+        const state = normalizeConsent(cookiebot.consent);
+        if (state)
+            handleCmpState(state, PRESET, deps);
+    };
+    const target = deps.window;
+    if (typeof target.addEventListener === "function") {
+        for (const name of CONSENT_EVENTS) {
+            target.addEventListener(name, () => guard(deps.debug, readAndHandle));
+        }
+    }
+    pollForGlobal(() => readGlobal(deps.window), () => guard(deps.debug, readAndHandle), deps);
+}

package/dist/collect/consent/adapters/onetrust.d.ts

@@ -0,0 +1,2 @@
+import { type AdapterDeps } from "../mapping.js";
+export declare function start(deps: AdapterDeps): void;

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

@@ -0,0 +1,54 @@
+// OneTrust adapter: reads the window.OnetrustActiveGroups string (the
+// active-group list, e.g. ",C0001,C0002,") and chains OptanonWrapper —
+// OneTrust invokes it on load and on every consent change.
+//
+// The active-groups surface only enumerates GRANTED groups, so denial is
+// inferred: a configured category shaped like a standard group id (C0002,
+// C0004, ...) that is absent from the list reads as recognized-but-denied,
+// which lets a genuine revoke propagate. Custom-named categories that never
+// appear stay unrecognized and write nothing (fail closed).
+import { guard, handleCmpState, pollForGlobal, resolveCategories, } from "../mapping.js";
+const PRESET = "onetrust";
+const STANDARD_GROUP_ID = /^c\d{4}$/;
+function normalizeGroups(groups, configured) {
+    const categories = {};
+    for (const token of groups.split(",")) {
+        const group = token.trim().toLowerCase();
+        if (group !== "")
+            categories[group] = true;
+    }
+    for (const category of configured ?? []) {
+        if (!(category in categories) && STANDARD_GROUP_ID.test(category)) {
+            categories[category] = false;
+        }
+    }
+    return { categories };
+}
+export function start(deps) {
+    const w = deps.window;
+    const readAndHandle = () => {
+        const groups = w.OnetrustActiveGroups;
+        if (typeof groups !== "string")
+            return;
+        const configured = resolveCategories(PRESET, deps.categories);
+        handleCmpState(normalizeGroups(groups, configured), PRESET, deps);
+    };
+    // Chain the wrapper immediately so consent changes reach us even when
+    // OneTrust loads (or the visitor decides) after this adapter starts.
+    const previous = w.OptanonWrapper;
+    w.OptanonWrapper = () => {
+        if (typeof previous === "function") {
+            try {
+                previous();
+            }
+            catch {
+                // The site's own wrapper is third-party code; never let it stop us.
+            }
+        }
+        guard(deps.debug, readAndHandle);
+    };
+    pollForGlobal(() => {
+        const groups = w.OnetrustActiveGroups;
+        return typeof groups === "string" ? groups : undefined;
+    }, () => guard(deps.debug, readAndHandle), deps);
+}

package/dist/collect/consent/adapters/trustarc.d.ts

@@ -0,0 +1,2 @@
+import { type AdapterDeps } from "../mapping.js";
+export declare function start(deps: AdapterDeps): void;