@gradial/aci 0.1.41 → 0.1.42

package/dist/content/personalization.d.ts

@@ -55,3 +55,38 @@ export declare function collectTagAttributes(siteConfig: PersonalizationSiteConf
  * when personalization is disabled.
  */
 export declare function collectScriptTagHTML(siteConfig: PersonalizationSiteConfig | null | undefined): string;
+/** Version of the data-aci-assignments tag body. */
+export declare const ASSIGNMENTS_TAG_VERSION = 1;
+/**
+ * One experiment assignment carried by a variant payload's `experiments`
+ * block (wire field names match the SDK event contract).
+ */
+export interface ExperimentAssignmentContext {
+    experimentId: string;
+    armId: string;
+    allocationVersion: string;
+}
+/**
+ * The minimal page-payload surface assignments tag emission reads: the
+ * top-level `experiments` block stamped at build time onto experiment
+ * variant payloads. `KernelPage` satisfies this structurally.
+ */
+export interface AssignmentsPayloadSource {
+    experiments?: ExperimentAssignmentContext[] | null;
+}
+/**
+ * assignmentsScriptJSON derives the HTML-safe JSON body of the
+ * data-aci-assignments tag ({"v":1,"experiments":[…]}) from the page
+ * payload, or "" when the payload carries no experiment assignments.
+ * `<` / `>` / `&` are \u-escaped so the JSON can never break out of the
+ * script element (standard JSON-in-script escaping; application/json tags
+ * are data, never executed).
+ */
+export declare function assignmentsScriptJSON(page: AssignmentsPayloadSource | null | undefined): string;
+/**
+ * assignmentsScriptTagHTML renders the contract tag
+ * (`<script type="application/json" data-aci-assignments>…</script>`,
+ * design/04) as an HTML snippet for emitters without a React element seam
+ * (the Astro slug page). Returns "" when the payload carries no assignments.
+ */
+export declare function assignmentsScriptTagHTML(page: AssignmentsPayloadSource | null | undefined): string;

package/dist/content/personalization.js

@@ -52,3 +52,60 @@ function escapeAttribute(value) {
         .replace(/</g, "&lt;")
         .replace(/>/g, "&gt;");
 }
+// ---------------------------------------------------------------------------
+// Assignments tag (personalization-reporting design/04, D-PR-6): experiment
+// variant payloads carry a build-time `experiments` block; the starters
+// render it as ONE page-level JSON script tag the collect SDK reads for
+// exposure emission and context stamping. Base payloads carry no block and
+// emit no tag. Like the collect tag, both framework emitters derive the tag
+// through this module so there is exactly one derivation code path.
+// ---------------------------------------------------------------------------
+/** Version of the data-aci-assignments tag body. */
+export const ASSIGNMENTS_TAG_VERSION = 1;
+function isAssignment(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const record = value;
+    return (typeof record.experimentId === "string" &&
+        record.experimentId !== "" &&
+        typeof record.armId === "string" &&
+        record.armId !== "" &&
+        typeof record.allocationVersion === "string");
+}
+/**
+ * assignmentsScriptJSON derives the HTML-safe JSON body of the
+ * data-aci-assignments tag ({"v":1,"experiments":[…]}) from the page
+ * payload, or "" when the payload carries no experiment assignments.
+ * `<` / `>` / `&` are \u-escaped so the JSON can never break out of the
+ * script element (standard JSON-in-script escaping; application/json tags
+ * are data, never executed).
+ */
+export function assignmentsScriptJSON(page) {
+    const experiments = (page?.experiments ?? []).filter(isAssignment);
+    if (experiments.length === 0)
+        return "";
+    const body = JSON.stringify({
+        v: ASSIGNMENTS_TAG_VERSION,
+        experiments: experiments.map(({ experimentId, armId, allocationVersion }) => ({
+            experimentId,
+            armId,
+            allocationVersion,
+        })),
+    });
+    return body
+        .replace(/</g, "\\u003c")
+        .replace(/>/g, "\\u003e")
+        .replace(/&/g, "\\u0026");
+}
+/**
+ * assignmentsScriptTagHTML renders the contract tag
+ * (`<script type="application/json" data-aci-assignments>…</script>`,
+ * design/04) as an HTML snippet for emitters without a React element seam
+ * (the Astro slug page). Returns "" when the payload carries no assignments.
+ */
+export function assignmentsScriptTagHTML(page) {
+    const json = assignmentsScriptJSON(page);
+    if (!json)
+        return "";
+    return `<script type="application/json" data-aci-assignments>${json}</script>`;
+}

package/dist/content/types.d.ts

@@ -1,4 +1,4 @@
-import type { SitePersonalizationConfig } from './personalization.js';
+import type { ExperimentAssignmentContext, SitePersonalizationConfig } from './personalization.js';
 export type ButtonVariant = 'primary' | 'secondary' | 'tertiary' | 'outline' | 'ghost';
 export interface KernelImage {
     src: string;
@@ -58,6 +58,12 @@ export interface KernelPage {
     layout: string;
     metadata: KernelPageSeo;
     regions: Record<string, KernelPageBlock[]>;
+    /**
+     * Build-time experiment assignment context (personalization-reporting
+     * design/04); present only on experiment variant payloads. The starters
+     * render it as the data-aci-assignments tag.
+     */
+    experiments?: ExperimentAssignmentContext[];
 }
 export interface KernelSiteConfig {
     id: string;

package/dist/edge/personalization-core.d.ts

@@ -0,0 +1,11 @@
+export function selectPersonalizationVariant(request: any, route: any, claims: any, experiments: any, identity: any): any;
+export function resolvePersonalizationDecision(request: any, route: any, claims: any, experiments: any, identity: any): {
+    variant: any;
+    experiment: {
+        experimentId: any;
+        armId: any;
+        allocationVersion: string;
+        variantKey: any;
+        bucket: number;
+    } | null;
+};

package/dist/edge/personalization-core.js

@@ -0,0 +1,265 @@
+// Runtime-neutral personalization selection. Vercel imports this module and
+// the CloudFront Terraform wrapper inlines the same source into its function.
+// Keep this file free of platform APIs and dependencies.
+export function selectPersonalizationVariant(request, route, claims, experiments, identity) {
+    return resolvePersonalizationDecision(request, route, claims, experiments, identity).variant;
+}
+export function resolvePersonalizationDecision(request, route, claims, experiments, identity) {
+    if (!route)
+        return { variant: null, experiment: null };
+    let variant = selectRuleVariant(request, route, claims);
+    let experiment = null;
+    if (identity && identity.usable && route.variants && experiments) {
+        const candidates = Object.values(experiments)
+            .filter((item) => (item.kind === 'ab' || item.kind === 'abn') && item.status === 'running')
+            .filter((item) => routeHasExperiment(route, item.id))
+            .sort((left, right) => (right.priority || 0) - (left.priority || 0)
+            || String(left.id || '').localeCompare(String(right.id || '')));
+        for (let index = 0; index < candidates.length; index++) {
+            const item = candidates[index];
+            const assignment = assignExperiment(item, identity);
+            const candidate = assignment && route.variants[assignment.variantKey];
+            if (!candidate)
+                continue;
+            if (!variant || betterVariant(candidate.priority || 0, candidate.variantKey, variant.priority || 0, variant.variantKey)) {
+                variant = candidate;
+                experiment = assignment;
+            }
+            break;
+        }
+    }
+    return { variant: variant || null, experiment };
+}
+function selectRuleVariant(request, route, claims) {
+    if (!route.variants)
+        return null;
+    const matches = [];
+    for (const key in route.variants) {
+        const variant = route.variants[key];
+        const values = variant.variantValues || variantValuesFromKey(key);
+        if (!requestDimensionsMatch(request, values))
+            continue;
+        const membershipMatch = (values.audience && claims && (claims.aud || []).includes(values.audience))
+            || (values.segment && claims && (claims.seg || []).includes(values.segment));
+        const ruleMatch = variant.rule ? evaluateRule(request, variant.rule) : false;
+        if (membershipMatch || ruleMatch)
+            matches.push(variant);
+    }
+    matches.sort((left, right) => (right.priority || 0) - (left.priority || 0)
+        || String(left.variantKey || '').localeCompare(String(right.variantKey || '')));
+    return matches[0] || null;
+}
+// CloudFront KVS values are capped at 1 KiB. The variant map key is the
+// canonical encoding of its dimensions, so compact route records omit the
+// duplicated variantValues object and recover it at the edge.
+function variantValuesFromKey(key) {
+    const values = {};
+    const parts = String(key || '').replace(/&/g, ';').split(';');
+    for (let index = 0; index < parts.length; index++) {
+        const separator = parts[index].indexOf('=');
+        if (separator > 0)
+            values[parts[index].slice(0, separator)] = parts[index].slice(separator + 1);
+    }
+    return values;
+}
+function routeHasExperiment(route, experimentID) {
+    for (const key in route.variants || {}) {
+        const values = route.variants[key].variantValues || variantValuesFromKey(key);
+        if (values.experiment === experimentID)
+            return true;
+    }
+    return false;
+}
+function assignExperiment(experiment, identity) {
+    const version = String(experiment.allocationVersion || '').trim();
+    const salt = String(experiment.salt || '').trim();
+    const siteID = String(identity.siteId || '').trim();
+    const identityKey = `${String(identity.namespace || '').trim()}:${String(identity.identityHash || '').trim()}`;
+    if (!version || !salt || !siteID || identityKey === ':')
+        return null;
+    const input = [siteID, String(experiment.id || ''), version, identityKey, salt].join('\0');
+    const bucket = sha256Bucket(input);
+    let cumulative = 0;
+    const arms = experiment.arms || [];
+    for (let index = 0; index < arms.length; index++) {
+        const arm = arms[index];
+        if ((arm.allocationBasisPoints || 0) <= 0)
+            continue;
+        cumulative += arm.allocationBasisPoints;
+        if (bucket < cumulative) {
+            return {
+                experimentId: experiment.id,
+                armId: arm.id,
+                allocationVersion: version,
+                variantKey: arm.variantKey,
+                bucket,
+            };
+        }
+    }
+    return null;
+}
+function betterVariant(candidatePriority, candidateKey, bestPriority, bestKey) {
+    if (candidatePriority !== bestPriority)
+        return candidatePriority > bestPriority;
+    return String(candidateKey || '').localeCompare(String(bestKey || '')) < 0;
+}
+function requestDimensionsMatch(request, values) {
+    for (const rawKey in values) {
+        const rawWant = values[rawKey];
+        const key = String(rawKey).trim();
+        const normalized = key.toLowerCase();
+        const want = String(rawWant).trim();
+        if (!key || !want || ['audience', 'segment', 'experiment', 'experimentarm'].includes(normalized))
+            continue;
+        const candidates = (request.query[key] || []).concat(request.query['aci_' + key] || [], request.headers['x-aci-' + normalized] || '', request.headers['x-gradial-' + normalized] || '', request.cookies[key] || '', request.cookies['aci_' + key] || '');
+        if (normalized === 'locale') {
+            const locales = String(request.headers['accept-language'] || '')
+                .split(',').map((part) => part.split(';')[0].trim()).filter(Boolean);
+            for (let localeIndex = 0; localeIndex < locales.length; localeIndex++)
+                candidates.push(locales[localeIndex]);
+        }
+        if (!candidates.some((candidate) => normalized === 'locale'
+            ? String(candidate).toLowerCase() === want.toLowerCase()
+            : String(candidate) === want))
+            return false;
+    }
+    return true;
+}
+function evaluateRule(request, rule) {
+    const all = rule.all || [];
+    const any = rule.any || [];
+    if (all.length + any.length === 0)
+        return false;
+    return all.every((condition) => evaluateCondition(request, condition))
+        && (any.length === 0 || any.some((condition) => evaluateCondition(request, condition)));
+}
+function evaluateCondition(request, condition) {
+    const values = signalValues(request, condition.field);
+    if (condition.operator === 'exists')
+        return values.length > 0;
+    if (values.length === 0 || !['string', 'number', 'boolean'].includes(typeof condition.value))
+        return false;
+    const expected = String(condition.value);
+    return values.some((value) => {
+        switch (condition.operator) {
+            case 'equals': return value === expected;
+            case 'contains': return value.includes(expected);
+            case 'startsWith': return value.startsWith(expected);
+            default: return false;
+        }
+    });
+}
+function signalValues(request, field) {
+    if (field.startsWith('query.'))
+        return request.query[field.slice(6)] || [];
+    if (field.startsWith('header.'))
+        return request.headers[field.slice(7).toLowerCase()] ? [request.headers[field.slice(7).toLowerCase()]] : [];
+    if (field.startsWith('cookie.'))
+        return request.cookies[field.slice(7)] ? [request.cookies[field.slice(7)]] : [];
+    if (field.startsWith('utm.'))
+        return request.query['utm_' + field.slice(4)] || [];
+    if (field.startsWith('geo.')) {
+        const geo = request.signals && request.signals.geo;
+        const value = geo && geo[field.slice(4).toLowerCase()];
+        return value ? [value] : [];
+    }
+    if (field === 'referrer') {
+        const value = request.headers.referer || request.headers.referrer;
+        return value ? [value] : [];
+    }
+    return [];
+}
+// SHA-256 mirrors experiment.assignment.go: the first eight digest bytes are
+// interpreted big-endian and reduced modulo 10,000 basis points.
+// CLOUDFRONT_STRIP_START — the build script removes this block for CloudFront
+// Functions (experiment bucketing moves to the hosting Lambda to stay under
+// the 10 KiB function size limit).
+function sha256Bucket(value) {
+    const bytes = utf8(value);
+    const words = new Uint32Array(64);
+    const bitLength = bytes.length * 8;
+    const paddedLength = ((bytes.length + 9 + 63) >> 6) << 6;
+    const data = new Uint8Array(paddedLength);
+    data.set(bytes);
+    data[bytes.length] = 128;
+    // The message length is a 64-bit big-endian integer across the final
+    // eight bytes. The previous code wrote a single truncated byte into each
+    // word's most significant position, corrupting every digest (caught by
+    // the assignment parity vectors, spec experiment-variant-caching REQ-9).
+    const bitsHigh = Math.floor(bitLength / 0x100000000);
+    const bitsLow = bitLength >>> 0;
+    data[paddedLength - 8] = (bitsHigh >>> 24) & 255;
+    data[paddedLength - 7] = (bitsHigh >>> 16) & 255;
+    data[paddedLength - 6] = (bitsHigh >>> 8) & 255;
+    data[paddedLength - 5] = bitsHigh & 255;
+    data[paddedLength - 4] = (bitsLow >>> 24) & 255;
+    data[paddedLength - 3] = (bitsLow >>> 16) & 255;
+    data[paddedLength - 2] = (bitsLow >>> 8) & 255;
+    data[paddedLength - 1] = bitsLow & 255;
+    let a = 0x6a09e667, b = 0xbb67ae85, c = 0x3c6ef372, d = 0xa54ff53a;
+    let e = 0x510e527f, f = 0x9b05688c, g = 0x1f83d9ab, h = 0x5be0cd19;
+    const k = [0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5, 0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174, 0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da, 0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967, 0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, 0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070, 0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3, 0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2];
+    for (let offset = 0; offset < paddedLength; offset += 64) {
+        for (let i = 0; i < 16; i++) {
+            const p = offset + i * 4;
+            words[i] = (data[p] << 24) | (data[p + 1] << 16) | (data[p + 2] << 8) | data[p + 3];
+        }
+        for (let i = 16; i < 64; i++) {
+            const x = words[i - 15], y = words[i - 2];
+            words[i] = (words[i - 16] + (rotr(x, 7) ^ rotr(x, 18) ^ (x >>> 3)) + words[i - 7] + (rotr(y, 17) ^ rotr(y, 19) ^ (y >>> 10))) >>> 0;
+        }
+        let aa = a, bb = b, cc = c, dd = d, ee = e, ff = f, gg = g, hh = h;
+        for (let i = 0; i < 64; i++) {
+            const s1 = rotr(ee, 6) ^ rotr(ee, 11) ^ rotr(ee, 25);
+            const ch = (ee & ff) ^ (~ee & gg);
+            const t1 = (hh + s1 + ch + k[i] + words[i]) >>> 0;
+            const s0 = rotr(aa, 2) ^ rotr(aa, 13) ^ rotr(aa, 22);
+            const maj = (aa & bb) ^ (aa & cc) ^ (bb & cc);
+            const t2 = (s0 + maj) >>> 0;
+            hh = gg;
+            gg = ff;
+            ff = ee;
+            ee = (dd + t1) >>> 0;
+            dd = cc;
+            cc = bb;
+            bb = aa;
+            aa = (t1 + t2) >>> 0;
+        }
+        a = (a + aa) >>> 0;
+        b = (b + bb) >>> 0;
+        c = (c + cc) >>> 0;
+        d = (d + dd) >>> 0;
+        e = (e + ee) >>> 0;
+        f = (f + ff) >>> 0;
+        g = (g + gg) >>> 0;
+        h = (h + hh) >>> 0;
+    }
+    // Reduce the 64-bit big-endian value modulo 10000 in 32-bit halves:
+    // (hi*2^32 + lo) % 10000 == ((hi%10000) * (2^32 % 10000) + lo%10000) % 10000,
+    // and 2^32 % 10000 = 7296. Multiplying hi by 2^32 directly exceeds
+    // Number.MAX_SAFE_INTEGER and rounds away the low bits — that float error
+    // made most JS buckets diverge from assignment.go (caught by the
+    // assignment parity vectors, spec experiment-variant-caching REQ-9).
+    return (((a >>> 0) % 10000) * 7296 + ((b >>> 0) % 10000)) % 10000;
+}
+function rotr(value, amount) { return (value >>> amount) | (value << (32 - amount)); }
+function utf8(value) {
+    const out = [];
+    for (let i = 0; i < value.length; i++) {
+        let code = value.charCodeAt(i);
+        if (code >= 0xd800 && code <= 0xdbff && i + 1 < value.length) {
+            const next = value.charCodeAt(++i);
+            code = 0x10000 + ((code - 0xd800) << 10) + (next - 0xdc00);
+        }
+        if (code < 0x80)
+            out.push(code);
+        else if (code < 0x800)
+            out.push(0xc0 | (code >> 6), 0x80 | (code & 63));
+        else if (code < 0x10000)
+            out.push(0xe0 | (code >> 12), 0x80 | ((code >> 6) & 63), 0x80 | (code & 63));
+        else
+            out.push(0xf0 | (code >> 18), 0x80 | ((code >> 12) & 63), 0x80 | ((code >> 6) & 63), 0x80 | (code & 63));
+    }
+    return new Uint8Array(out);
+}
+// CLOUDFRONT_STRIP_END

package/dist/index.d.ts

@@ -15,3 +15,4 @@ export { AssetSchema, isImage, isAsset, } from './types/media.js';
 export * from './audience-data-models.js';
 export * from './define-data-model.js';
 export * from './types/index.js';
+export { mountConsentBanner, hasConsentCookie, type ConsentBannerOptions, } from './consent-banner/index.js';

package/dist/index.js

@@ -9,6 +9,7 @@ export { AssetSchema, isImage, isAsset, } from './types/media.js';
 export * from './audience-data-models.js';
 export * from './define-data-model.js';
 export * from './types/index.js';
+export { mountConsentBanner, hasConsentCookie, } from './consent-banner/index.js';
 // Note: content/ is NOT re-exported here because it imports node:path,
 // making it incompatible with client-side bundlers. Import server-only
 // content utilities from '@gradial/aci/content' explicitly.

package/dist/next/assignments-script.d.ts

@@ -0,0 +1,14 @@
+import { type AssignmentsPayloadSource } from '../content/personalization.js';
+export interface AssignmentsScriptProps {
+    page: AssignmentsPayloadSource | null | undefined;
+}
+/**
+ * AssignmentsScript renders the page-level experiment assignment tag
+ * (`<script type="application/json" data-aci-assignments>` with a
+ * {"v":1,"experiments":[…]} body, personalization-reporting design/04) when
+ * the page payload carries a build-time `experiments` block, and nothing
+ * otherwise. createPage appends it to the page tree exactly once per page;
+ * sites composing their own pages can render it directly. The JSON body is
+ * HTML-safe (assignmentsScriptJSON \u-escapes angle brackets).
+ */
+export declare function AssignmentsScript({ page }: AssignmentsScriptProps): import("react").JSX.Element | null;

package/dist/next/assignments-script.js

@@ -0,0 +1,17 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { assignmentsScriptJSON, } from '../content/personalization.js';
+/**
+ * AssignmentsScript renders the page-level experiment assignment tag
+ * (`<script type="application/json" data-aci-assignments>` with a
+ * {"v":1,"experiments":[…]} body, personalization-reporting design/04) when
+ * the page payload carries a build-time `experiments` block, and nothing
+ * otherwise. createPage appends it to the page tree exactly once per page;
+ * sites composing their own pages can render it directly. The JSON body is
+ * HTML-safe (assignmentsScriptJSON \u-escapes angle brackets).
+ */
+export function AssignmentsScript({ page }) {
+    const json = assignmentsScriptJSON(page);
+    if (!json)
+        return null;
+    return (_jsx("script", { type: "application/json", "data-aci-assignments": "", dangerouslySetInnerHTML: { __html: json } }));
+}

package/dist/next/collect-route.d.ts

@@ -0,0 +1,19 @@
+import { type IdentitySigningKeys, type PersonalizationBlobStore } from './personalization-host.js';
+export interface PersonalizationCollectRouteConfig {
+    siteId: string;
+    store: PersonalizationBlobStore;
+    identityKeys: IdentitySigningKeys;
+    /**
+     * Claims verify keys (kid -> secret) for withdrawal EVIDENCE
+     * (anonymous-experiments REQ-6): suppression fires only when the request
+     * presents a signature-verified aci_claims cookie — presence alone is
+     * spoofable, and under universal minting an unverified trigger would
+     * suppress every reject-all visitor. Empty = evidence never verifies =
+     * suppression disabled (fails safe).
+     */
+    claimsKeys?: Record<string, string>;
+    retentionSeconds?: number;
+    secureCookies?: boolean;
+    now?: () => Date;
+}
+export declare function createPersonalizationCollectRoute(config: PersonalizationCollectRouteConfig): (request: Request) => Promise<Response>;