@kywi-software/core 0.14.0 → 0.15.1

package/dist/audiences/consent.js

@@ -0,0 +1,335 @@
+/**
+ * Cookie consent — the category map, and the gate every optional cookie write
+ * passes through (kywi-cms#91).
+ *
+ * Before this module the `cookieConsent` layout module and the `kywi_consent`
+ * cookie were two halves of a feature that never met: the banner's buttons had
+ * no handlers, and no cookie-writing code path ever asked whether the visitor
+ * had consented. This file is the join. It owns three things:
+ *
+ *   1. `COOKIE_CONSENT_CATEGORY` — the SINGLE SOURCE OF TRUTH mapping every
+ *      cookie the engine writes to the consent category it needs. Nothing else
+ *      in the codebase may decide a cookie's category.
+ *   2. `cookieAllowed()` / `consentAllows()` — the gate. Every optional cookie
+ *      write calls one of these first.
+ *   3. The browser-side read/write of the `kywi_consent` cookie itself, used by
+ *      the `cookieConsent` layout module's buttons.
+ *
+ * ── Category decisions (owner-set) ──────────────────────────────────────────
+ *
+ *   necessary / `essential` — always allowed, never gated:
+ *     `kywi_consent`      the consent record itself
+ *     `kywi_optout`       the personalization opt-out flag: a *suppression*
+ *                         preference. Blocking a visitor from recording "stop
+ *                         personalizing me" until they consent to cookies would
+ *                         be perverse, so this is necessary by construction.
+ *     `kywi_preview_init` admin preview hand-off, not visitor tracking.
+ *
+ *   `personalization` — gated:
+ *     `kywi_visitor`   visitor id, incl. experiment bucketing / exposure
+ *     `kywi_signals`   the signed server-resolved audience signals
+ *     `kywi_utm`       campaign attribution carried across navigation
+ *     `kywi_audience`  the audience the RUNTIME resolved and remembered. A pin
+ *                      the visitor chose by hand in the transparency panel is
+ *                      `essential` instead — see the `source` discussion in
+ *                      `api/audience-runtime-routes.ts`
+ *     `kywi_known`     adapter-pushed known-identity flag
+ *     `kywi_entry`     the first page of the session (kywi-cms#196). Carried
+ *                      across navigation, so it is exactly the kind of stored
+ *                      signal the gate governs — the landing request's own path
+ *                      is read straight off the URL either way, so a campaign
+ *                      link still personalizes the page it points at.
+ *     `kywi_selfid`    the visitor's self-ID answers, kept server-readable so a
+ *                      server-pruned variant arm can be chosen from them
+ *                      (kywi-cms#200). The audience PIN that a self-ID submit
+ *                      produces is `essential` under the `switcher:` rule
+ *                      below — a control the visitor operated by hand — but the
+ *                      stored attribute bag itself is tracking and is gated.
+ *
+ *   Auth/session cookies (the admin's access + refresh cookies, CSRF) are
+ *   `essential` by definition and deliberately never routed through this gate —
+ *   they carry no tracking and the admin cannot function without them.
+ *
+ * ── Undecided means not consented ───────────────────────────────────────────
+ *
+ * A visitor who has not answered the banner has a null `ConsentState`, and
+ * `consentAllows(null, 'personalization')` is FALSE. This matches `hasConsent()`
+ * in `@kywi-software/js` and is the compliance-correct default. The consequence
+ * is deliberate: until a visitor accepts, personalization cookies are not
+ * written and pages degrade to their default (unpersonalized) content. Nothing
+ * fails — the request still resolves, the visitor id is still minted for the
+ * duration of that request, it just is not persisted.
+ *
+ * An unmapped cookie name is denied rather than allowed, so adding a new cookie
+ * without classifying it here fails closed. A core test asserts every name in
+ * `COOKIE_NAMES` appears in the map, so that failure surfaces at test time.
+ *
+ * ── The escape hatch: personalization.requireConsent ────────────────────────
+ *
+ * `theme.personalization.requireConsent` (kywi.config.ts) DEFAULTS TO TRUE — the
+ * compliant behaviour above. Setting it to `false` turns this gate off entirely:
+ * every category reads as allowed, decided or not, and the cookie writes behave
+ * as they did before kywi-cms#91. That is for a site whose consent is collected
+ * by external tooling (a third-party CMP) which suppresses cookies its own way;
+ * the site takes responsibility for compliance, and Kywi stops second-guessing
+ * it. It is NOT a way to opt out of consent — turning it off on a site with no
+ * other consent mechanism is the non-compliant configuration this issue existed
+ * to fix.
+ *
+ * Every gate function takes the flag through a `ConsentGateOptions` bag rather
+ * than reading config itself, because this module must stay dependency-free
+ * (see below). `personalizationRequiresConsent()` in `./consent-config.ts`
+ * resolves it from a `KywiConfig`; the edge middleware, which cannot import an
+ * app's config at all, mirrors it with `KYWI_REQUIRE_CONSENT=false`.
+ *
+ * EDGE-SAFE LEAF MODULE: this file imports nothing, so it can be pulled into
+ * Next.js edge middleware (where core's DB-backed code cannot run) and into
+ * `audiences/utm-persistence.ts`, which has the same constraint. It is
+ * published as its own export entry (`@kywi-software/core/audiences/consent`).
+ * Keep it dependency-free. The browser-only helpers guard on `document`, so
+ * importing this on the server or the edge is safe.
+ */
+/** The cookie the visitor's consent decision is stored in. */
+export const CONSENT_COOKIE = 'kywi_consent';
+/** 1 year, in seconds — how long a consent decision is remembered. */
+export const CONSENT_MAX_AGE = 365 * 24 * 3600;
+/** The cookie an audience pin lives in. */
+export const AUDIENCE_PIN_COOKIE = 'kywi_audience';
+/**
+ * The `kywi_audience` value prefix marking a pin the visitor chose BY HAND in
+ * the transparency panel, as opposed to one the runtime remembered on its own.
+ *
+ * Owned here, in the zero-import leaf, because both halves of the feature need
+ * it and neither can import the other: `collectors/pinned-audience.ts` encodes
+ * and decodes with it, and `clearDeniedCookies` below must recognise it to avoid
+ * sweeping away a preference it is supposed to honour.
+ */
+export const SWITCHER_PIN_PREFIX = 'switcher:';
+/**
+ * Every cookie the engine writes → the consent category it requires.
+ * The single source of truth; see the file header for the reasoning behind
+ * each classification.
+ */
+export const COOKIE_CONSENT_CATEGORY = {
+    kywi_consent: 'essential',
+    kywi_optout: 'essential',
+    kywi_preview_init: 'essential',
+    kywi_signals: 'personalization',
+    kywi_visitor: 'personalization',
+    kywi_utm: 'personalization',
+    kywi_audience: 'personalization',
+    kywi_known: 'personalization',
+    kywi_entry: 'personalization',
+    kywi_selfid: 'personalization',
+};
+/**
+ * The consent category `cookieName` requires, or `null` when the name is not
+ * classified. An unclassified cookie is denied by `cookieAllowed`.
+ */
+export function consentCategoryFor(cookieName) {
+    return COOKIE_CONSENT_CATEGORY[cookieName] ?? null;
+}
+/** Parse a raw `kywi_consent` cookie value. Returns null when absent/malformed. */
+export function parseConsentValue(raw) {
+    if (!raw)
+        return null;
+    let text = raw;
+    try {
+        text = decodeURIComponent(raw);
+    }
+    catch {
+        /* malformed escape — fall through with the raw value */
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return null;
+    const obj = parsed;
+    return {
+        essential: true,
+        analytics: obj.analytics === true,
+        marketing: obj.marketing === true,
+        personalization: obj.personalization === true,
+    };
+}
+/**
+ * Read the consent decision out of a request's `Cookie` header.
+ * Returns null when the header is absent or carries no usable decision.
+ *
+ * A header can legitimately carry the same cookie name twice — most often a
+ * `Path=/` cookie shadowed by a narrower one from an earlier deploy. Taking the
+ * first match and giving up if it will not parse would throw away a perfectly
+ * good decision sitting right behind a corrupt one, so keep looking.
+ */
+export function readConsentFromCookieHeader(header) {
+    if (!header)
+        return null;
+    for (const pair of header.split(';')) {
+        const trimmed = pair.trim();
+        const eqIdx = trimmed.indexOf('=');
+        if (eqIdx < 0)
+            continue;
+        if (trimmed.slice(0, eqIdx) !== CONSENT_COOKIE)
+            continue;
+        const state = parseConsentValue(trimmed.slice(eqIdx + 1));
+        if (state)
+            return state;
+    }
+    return null;
+}
+/**
+ * Is `category` granted by `state`? `essential` is always granted — necessary
+ * cookies need no consent. Every other category requires an explicit `true`,
+ * so an undecided visitor (null state) grants nothing.
+ */
+export function consentAllows(state, category, options = {}) {
+    if (options.requireConsent === false)
+        return true;
+    if (category === 'essential')
+        return true;
+    if (!state)
+        return false;
+    return state[category] === true;
+}
+/**
+ * The gate: may `cookieName` be written given `state`? Unclassified cookie
+ * names fail closed — unless the gate itself is off.
+ */
+export function cookieAllowed(cookieName, state, options = {}) {
+    // With the gate off there is nothing to classify against — the site's own
+    // tooling decides, including for a cookie this map has never heard of.
+    if (options.requireConsent === false)
+        return true;
+    const category = consentCategoryFor(cookieName);
+    if (category === null)
+        return false;
+    return consentAllows(state, category);
+}
+/** Convenience for request handlers: gate `cookieName` against a `Cookie` header. */
+export function cookieAllowedByHeader(cookieName, header, options = {}) {
+    return cookieAllowed(cookieName, readConsentFromCookieHeader(header), options);
+}
+/** Every cookie name classified into `category`. */
+export function cookiesInCategory(category) {
+    return Object.entries(COOKIE_CONSENT_CATEGORY)
+        .filter(([, c]) => c === category)
+        .map(([name]) => name);
+}
+/* ── browser side: the cookieConsent module's read/write ─────────────────── */
+/**
+ * Delete every cookie whose category `state` does not grant, and return the
+ * names deleted.
+ *
+ * Refusing to WRITE new cookies is only half of "Reject All" — a visitor who
+ * accepted last month and rejects today is still carrying a `kywi_visitor` id,
+ * and a gate that only blocks writes would keep reading it forever. So a
+ * decision revokes as well as denies (kywi-cms#91).
+ *
+ * `kywi_signals` is HttpOnly and cannot be removed from script; the attempt is
+ * harmless and the server stops writing it, after which it expires on its own
+ * 60-second horizon. The server-side read paths ALSO ignore personalization
+ * cookies whenever the gate denies, so a cookie script cannot clear is inert
+ * either way.
+ *
+ * No-op off the browser.
+ */
+export function clearDeniedCookies(state) {
+    if (typeof document === 'undefined')
+        return [];
+    const deleted = [];
+    for (const [name, category] of Object.entries(COOKIE_CONSENT_CATEGORY)) {
+        if (consentAllows(state, category))
+            continue;
+        if (isDeliberatePreference(name, rawCookie(name)))
+            continue;
+        document.cookie = `${name}=; Path=/; Max-Age=0`;
+        deleted.push(name);
+    }
+    return deleted;
+}
+/** The raw (decoded) value of one cookie, or undefined. Browser-only. */
+function rawCookie(name) {
+    if (typeof document === 'undefined')
+        return undefined;
+    for (const pair of document.cookie.split(';')) {
+        const trimmed = pair.trim();
+        const eqIdx = trimmed.indexOf('=');
+        if (eqIdx < 0 || trimmed.slice(0, eqIdx) !== name)
+            continue;
+        const raw = trimmed.slice(eqIdx + 1);
+        if (raw === '')
+            return undefined;
+        try {
+            return decodeURIComponent(raw);
+        }
+        catch {
+            return raw;
+        }
+    }
+    return undefined;
+}
+/**
+ * Does this cookie's CURRENT VALUE mark it as an explicit visitor preference
+ * that outranks its category?
+ *
+ * `kywi_audience` is the one cookie whose category depends on how it was
+ * written: automatic ("remember what I resolved") is `personalization`, but an
+ * audience the visitor picked by hand in the transparency panel is `essential`,
+ * on the same argument as `kywi_optout`. The category map is static and cannot
+ * express that, so the sweep asks the value.
+ *
+ * Without this, rejecting personalization would delete a choice the visitor made
+ * deliberately and which the server is under orders to keep honouring — the
+ * revocation would quietly undo the exemption.
+ */
+function isDeliberatePreference(name, value) {
+    if (name !== AUDIENCE_PIN_COOKIE || value === undefined)
+        return false;
+    // The prefix alone is not a pin — `switcher:` with no id decodes to nothing
+    // (parseAudiencePin rejects it), so exempting it would strand a cookie nobody
+    // will ever honour.
+    return value.startsWith(SWITCHER_PIN_PREFIX) && value.length > SWITCHER_PIN_PREFIX.length;
+}
+/** Read the visitor's consent decision from `document.cookie`, or null. */
+export function getConsentState() {
+    if (typeof document === 'undefined')
+        return null;
+    return readConsentFromCookieHeader(document.cookie);
+}
+/**
+ * Record a consent decision. `essential` is always forced true — the visitor
+ * cannot decline necessary cookies, and the banner renders that checkbox
+ * checked and disabled to say so. Returns the state written.
+ *
+ * Any category the decision denies is REVOKED at the same time: see
+ * `clearDeniedCookies`. Rejecting is not just "stop writing", it is "and delete
+ * what you already wrote".
+ */
+export function setConsent(prefs) {
+    const state = {
+        essential: true,
+        analytics: prefs.analytics === true,
+        marketing: prefs.marketing === true,
+        personalization: prefs.personalization === true,
+    };
+    if (typeof document !== 'undefined') {
+        document.cookie =
+            `${CONSENT_COOKIE}=${encodeURIComponent(JSON.stringify(state))}` +
+                `; Path=/; Max-Age=${CONSENT_MAX_AGE}; SameSite=Lax`;
+        // A decision REVOKES as well as denies: cookies from an earlier, more
+        // permissive answer are removed here rather than lingering until they
+        // expire. Written first so the consent record survives its own sweep.
+        clearDeniedCookies(state);
+    }
+    return state;
+}
+/** Has the visitor granted `category`? See `consentAllows` for the semantics. */
+export function hasConsent(category, options = {}) {
+    return consentAllows(getConsentState(), category, options);
+}
+//# sourceMappingURL=consent.js.map

package/dist/audiences/consent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consent.js","sourceRoot":"","sources":["../../src/audiences/consent.ts"],"names":[],"mappings":"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"}

package/dist/audiences/cookies.d.ts

@@ -6,6 +6,10 @@ export declare const COOKIE_NAMES: {
     readonly OPTOUT: "kywi_optout";
     readonly KNOWN: "kywi_known";
     readonly PREVIEW_INIT: "kywi_preview_init";
+    /** First page (path + query) of the visitor's session — kywi-cms#196. */
+    readonly ENTRY: "kywi_entry";
+    /** Server-readable copy of the visitor's self-ID answers — kywi-cms#200. */
+    readonly SELFID: "kywi_selfid";
 };
 export declare const COOKIE_MAX_AGE: {
     readonly SIGNALS: 60;
@@ -15,12 +19,29 @@ export declare const COOKIE_MAX_AGE: {
     readonly OPTOUT: number;
     readonly KNOWN: number;
     readonly PREVIEW_INIT: 30;
+    readonly ENTRY: -1;
+    /**
+     * Not a cookie of its own: the "until the browser closes" lifetime, for a
+     * write whose durability depends on consent. A self-ID pin from a visitor who
+     * has not consented is honoured for the session and then forgotten, rather
+     * than filed for 30 days (kywi-cms#200).
+     */
+    readonly SESSION: -1;
+    readonly SELFID: number;
 };
 export declare function signSignals(payload: unknown, secret: string): Promise<string>;
 export declare function verifySignals(token: string, secret: string): Promise<unknown | null>;
 export declare function parseCookies(cookieHeader: string): Map<string, string>;
+/**
+ * `options.secure` adds the `Secure` attribute, which callers pass when the
+ * request being answered is https. It is opt-in rather than always-on because
+ * a browser silently DISCARDS a `Secure` cookie over plain http, which would
+ * break local development and any http-only deployment — so the caller, which
+ * is the only thing that knows the scheme, decides. Omitted, nothing changes.
+ */
 export declare function buildSetCookieHeader(name: string, value: string, maxAge: number, options?: {
     httpOnly?: boolean;
     sameSite?: 'Strict' | 'Lax' | 'None';
+    secure?: boolean;
 }): string;
 //# sourceMappingURL=cookies.d.ts.map

package/dist/audiences/cookies.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cookies.d.ts","sourceRoot":"","sources":["../../src/audiences/cookies.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,YAAY;;;;;;;;CAQf,CAAA;AAEV,eAAO,MAAM,cAAc;;;;;;;;CAWjB,CAAA;AAEV,wBAAsB,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAMnF;AAED,wBAAsB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAQ1F;AAED,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAwBtE;AAED,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAA;CAAE,GACrE,MAAM,CAQR"}
+{"version":3,"file":"cookies.d.ts","sourceRoot":"","sources":["../../src/audiences/cookies.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,YAAY;;;;;;;;IAQvB,yEAAyE;;IAEzE,4EAA4E;;CAEpE,CAAA;AAEV,eAAO,MAAM,cAAc;;;;;;;;;IAczB;;;;;OAKG;;;CAKK,CAAA;AAEV,wBAAsB,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAMnF;AAED,wBAAsB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAQ1F;AAED,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAwBtE;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GACvF,MAAM,CASR"}

package/dist/audiences/cookies.js

@@ -7,6 +7,10 @@ export const COOKIE_NAMES = {
     OPTOUT: 'kywi_optout',
     KNOWN: 'kywi_known',
     PREVIEW_INIT: 'kywi_preview_init',
+    /** First page (path + query) of the visitor's session — kywi-cms#196. */
+    ENTRY: 'kywi_entry',
+    /** Server-readable copy of the visitor's self-ID answers — kywi-cms#200. */
+    SELFID: 'kywi_selfid',
 };
 export const COOKIE_MAX_AGE = {
     SIGNALS: 60,
@@ -19,6 +23,19 @@ export const COOKIE_MAX_AGE = {
     OPTOUT: 365 * 24 * 3600,
     KNOWN: 24 * 3600,
     PREVIEW_INIT: 30,
+    // A session cookie (negative = no Max-Age directive): a new visit is a new
+    // entry page, so this must not outlive the browser session.
+    ENTRY: -1,
+    /**
+     * Not a cookie of its own: the "until the browser closes" lifetime, for a
+     * write whose durability depends on consent. A self-ID pin from a visitor who
+     * has not consented is honoured for the session and then forgotten, rather
+     * than filed for 30 days (kywi-cms#200).
+     */
+    SESSION: -1,
+    // Self-ID answers persist on the same horizon as the audience they resolve to
+    // — long enough to be worth asking for, short enough to age out.
+    SELFID: 30 * 24 * 3600,
 };
 export async function signSignals(payload, secret) {
     const key = new TextEncoder().encode(secret);
@@ -65,6 +82,13 @@ export function parseCookies(cookieHeader) {
     }
     return map;
 }
+/**
+ * `options.secure` adds the `Secure` attribute, which callers pass when the
+ * request being answered is https. It is opt-in rather than always-on because
+ * a browser silently DISCARDS a `Secure` cookie over plain http, which would
+ * break local development and any http-only deployment — so the caller, which
+ * is the only thing that knows the scheme, decides. Omitted, nothing changes.
+ */
 export function buildSetCookieHeader(name, value, maxAge, options) {
     const parts = [`${name}=${encodeURIComponent(value)}`];
     if (maxAge >= 0)
@@ -74,6 +98,8 @@ export function buildSetCookieHeader(name, value, maxAge, options) {
     if (options?.httpOnly !== false)
         parts.push('HttpOnly');
     parts.push(`SameSite=${options?.sameSite ?? 'Lax'}`);
+    if (options?.secure)
+        parts.push('Secure');
     return parts.join('; ');
 }
 //# sourceMappingURL=cookies.js.map

package/dist/audiences/cookies.js.map

@@ -1 +1 @@
-{"version":3,"file":"cookies.js","sourceRoot":"","sources":["../../src/audiences/cookies.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cookies.js","sourceRoot":"","sources":["../../src/audiences/cookies.ts"],"names":[],"mappings":"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"}

package/dist/audiences/engine.d.ts

@@ -1,6 +1,13 @@
 import type { VisitorContext, AudienceResult, Audience } from './types.js';
 export interface AudienceEngineConfig {
     audiences: Audience[];
+    /**
+     * `theme.personalization.requireConsent` (kywi-cms#91). Defaults to true —
+     * personalization cookies are neither written nor READ for a visitor who has
+     * not consented, so a stale id from an earlier "accept" cannot keep resolving
+     * them after they reject.
+     */
+    requireConsent?: boolean;
 }
 export interface AudienceEngine {
     evaluate(context: VisitorContext): Promise<AudienceResult>;

package/dist/audiences/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/audiences/engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkB,cAAc,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAM1F,MAAM,WAAW,oBAAoB;IAAG,SAAS,EAAE,QAAQ,EAAE,CAAA;CAAE;AAC/D,MAAM,WAAW,cAAc;IAAG,QAAQ,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAAA;CAAE;AAe9F,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,oBAAoB,GAAG,cAAc,CA4BjF"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/audiences/engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkB,cAAc,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAM1F,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,QAAQ,EAAE,CAAA;IACrB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB;AACD,MAAM,WAAW,cAAc;IAAG,QAAQ,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAAA;CAAE;AAgB9F,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,oBAAoB,GAAG,cAAc,CAiCjF"}

package/dist/audiences/engine.js

@@ -8,6 +8,7 @@ function mergeSignals(base, partial) {
         referrer: partial.referrer ?? base.referrer,
         session: partial.session ?? base.session,
         behavioral: partial.behavioral ?? base.behavioral,
+        query: { ...base.query, ...partial.query },
         selfId: { ...base.selfId, ...partial.selfId },
         identity: partial.identity ?? base.identity,
         adapters: { ...base.adapters, ...partial.adapters },
@@ -17,7 +18,10 @@ function mergeSignals(base, partial) {
 export function createAudienceEngine(config) {
     return {
         async evaluate(context) {
-            const serverSignals = runServerCollectors(context.request);
+            // Built conditionally: under `exactOptionalPropertyTypes` an explicit
+            // `undefined` is not the same as an absent key.
+            const gate = config.requireConsent === undefined ? {} : { requireConsent: config.requireConsent };
+            const serverSignals = runServerCollectors(context.request, gate);
             let signals = mergeSignals(createEmptySignals(), serverSignals);
             if (context.partialSignals) {
                 signals = mergeSignals(signals, context.partialSignals);
@@ -29,7 +33,8 @@ export function createAudienceEngine(config) {
             // (behavioral / self-ID) into the server render. Opt-out still wins below,
             // and `allMatchedIds` stays signal-derived (the pin overrides the winner,
             // not the set of audiences the current signals matched).
-            const pinnedAudienceId = collectPinnedAudience(parseCookies(context.request.headers.get('cookie') ?? ''), config.audiences);
+            const cookieHeader = context.request.headers.get('cookie');
+            const pinnedAudienceId = collectPinnedAudience(parseCookies(cookieHeader ?? ''), config.audiences, { ...gate, cookieHeader });
             const resolvedWinner = pinnedAudienceId ?? winningAudienceId;
             return {
                 winningAudienceId: isOptedOut ? null : resolvedWinner,

package/dist/audiences/engine.js.map

@@ -1 +1 @@
-{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../src/audiences/engine.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAC/C,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAA;AAClF,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAA;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAK3C,SAAS,YAAY,CAAC,IAAoB,EAAE,OAAgC;IAC1E,OAAO;QACL,GAAG,EAAE,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG;QAC5B,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,IAAI,CAAC,QAAQ;QAC3C,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO;QACxC,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,IAAI,CAAC,UAAU;QACjD,MAAM,EAAE,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE;QAC7C,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,IAAI,CAAC,QAAQ;QAC3C,QAAQ,EAAE,EAAE,GAAG,IAAI,CAAC,QAAQ,EAAE,GAAG,OAAO,CAAC,QAAQ,EAAE;QACnD,IAAI,EAAE,EAAE,GAAG,IAAI,CAAC,IAAI,EAAE,GAAG,OAAO,CAAC,IAAI,EAAE;KACxC,CAAA;AACH,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,MAA4B;IAC/D,OAAO;QACL,KAAK,CAAC,QAAQ,CAAC,OAAuB;YACpC,MAAM,aAAa,GAAG,mBAAmB,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;YAC1D,IAAI,OAAO,GAAG,YAAY,CAAC,kBAAkB,EAAE,EAAE,aAAa,CAAC,CAAA;YAC/D,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;gBAC3B,OAAO,GAAG,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,cAAc,CAAC,CAAA;YACzD,CAAC;YACD,MAAM,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,UAAU,CAAA;YAC1C,MAAM,EAAE,iBAAiB,EAAE,aAAa,EAAE,GAAG,gBAAgB,CAAC,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,CAAA;YACxF,yEAAyE;YACzE,oEAAoE;YACpE,2EAA2E;YAC3E,0EAA0E;YAC1E,yDAAyD;YACzD,MAAM,gBAAgB,GAAG,qBAAqB,CAC5C,YAAY,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,EACzD,MAAM,CAAC,SAAS,CACjB,CAAA;YACD,MAAM,cAAc,GAAG,gBAAgB,IAAI,iBAAiB,CAAA;YAC5D,OAAO;gBACL,iBAAiB,EAAE,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,cAAc;gBACrD,aAAa;gBACb,OAAO;gBACP,UAAU;aACX,CAAA;QACH,CAAC;KACF,CAAA;AACH,CAAC"}
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../src/audiences/engine.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAC/C,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAA;AAClF,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAA;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAc3C,SAAS,YAAY,CAAC,IAAoB,EAAE,OAAgC;IAC1E,OAAO;QACL,GAAG,EAAE,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG;QAC5B,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,IAAI,CAAC,QAAQ;QAC3C,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO;QACxC,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,IAAI,CAAC,UAAU;QACjD,KAAK,EAAE,EAAE,GAAG,IAAI,CAAC,KAAK,EAAE,GAAG,OAAO,CAAC,KAAK,EAAE;QAC1C,MAAM,EAAE,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE;QAC7C,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,IAAI,CAAC,QAAQ;QAC3C,QAAQ,EAAE,EAAE,GAAG,IAAI,CAAC,QAAQ,EAAE,GAAG,OAAO,CAAC,QAAQ,EAAE;QACnD,IAAI,EAAE,EAAE,GAAG,IAAI,CAAC,IAAI,EAAE,GAAG,OAAO,CAAC,IAAI,EAAE;KACxC,CAAA;AACH,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,MAA4B;IAC/D,OAAO;QACL,KAAK,CAAC,QAAQ,CAAC,OAAuB;YACpC,sEAAsE;YACtE,gDAAgD;YAChD,MAAM,IAAI,GAAG,MAAM,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,MAAM,CAAC,cAAc,EAAE,CAAA;YACjG,MAAM,aAAa,GAAG,mBAAmB,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,CAAA;YAChE,IAAI,OAAO,GAAG,YAAY,CAAC,kBAAkB,EAAE,EAAE,aAAa,CAAC,CAAA;YAC/D,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;gBAC3B,OAAO,GAAG,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,cAAc,CAAC,CAAA;YACzD,CAAC;YACD,MAAM,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,UAAU,CAAA;YAC1C,MAAM,EAAE,iBAAiB,EAAE,aAAa,EAAE,GAAG,gBAAgB,CAAC,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,CAAA;YACxF,yEAAyE;YACzE,oEAAoE;YACpE,2EAA2E;YAC3E,0EAA0E;YAC1E,yDAAyD;YACzD,MAAM,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;YAC1D,MAAM,gBAAgB,GAAG,qBAAqB,CAC5C,YAAY,CAAC,YAAY,IAAI,EAAE,CAAC,EAChC,MAAM,CAAC,SAAS,EAChB,EAAE,GAAG,IAAI,EAAE,YAAY,EAAE,CAC1B,CAAA;YACD,MAAM,cAAc,GAAG,gBAAgB,IAAI,iBAAiB,CAAA;YAC5D,OAAO;gBACL,iBAAiB,EAAE,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,cAAc;gBACrD,aAAa;gBACb,OAAO;gBACP,UAAU;aACX,CAAA;QACH,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/audiences/entry-page.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Entry page — the *write* side of the `kywi_entry` cookie contract
+ * (kywi-cms#196).
+ *
+ * `session.entryPage` has been in the signal catalogue and in the admin rule
+ * tester since the audience engine shipped, but nothing in core ever wrote it:
+ * `runServerCollectors` fed UTM params, the referrer and the visitor cookies
+ * into signal collection and left `session` at its schema defaults, so
+ * `entryPage` stayed `'/'` forever. A rule like
+ * `session.entryPage contains 'from=marketer'` could not fire on a real request
+ * no matter what the visitor did.
+ *
+ * This module is the missing writer, living next to its reader
+ * (`collectors/session.ts`) so a scaffolded app, the reference app and the
+ * runtime routes all share one implementation. The contract:
+ *
+ *   • The value is `pathname + search` of the FIRST request of a session —
+ *     `/developers?from=marketer`, not the whole URL. Query is included on
+ *     purpose: a campaign link's own params are the interesting part.
+ *   • It is written ONCE. A request that already carries the cookie returns
+ *     `null` here, so "entry page" keeps meaning the page the visitor arrived
+ *     on rather than quietly becoming "current page".
+ *   • It is written only for a DOCUMENT request. If a subresource could record
+ *     it, the first request of a session that happens to be `/kywi.js`, a font
+ *     or an API call would name the entry page, and every rule downstream would
+ *     be matching against an asset URL. Callers pass `Sec-Fetch-Dest` (and
+ *     `Accept` for browsers that omit it); saying neither fails closed.
+ *   • It is a SESSION cookie (no Max-Age): a new visit is a new entry page.
+ *   • It is a `personalization` cookie in the category map, gated exactly like
+ *     `kywi_visitor` and `kywi_utm` (kywi-cms#91). Without consent nothing is
+ *     persisted — and the read side falls back to the CURRENT request's path,
+ *     so a rule on the entry page still fires on the landing request itself.
+ *     That fallback is also what makes `/developers?from=marketer` switch on
+ *     the very request that carries it, with no reload, for everyone: a
+ *     Set-Cookie only takes effect on the NEXT request.
+ *
+ * EDGE-SAFE LEAF MODULE: its only import is `./consent.js`, itself a zero-import
+ * leaf, because this is imported from Next.js edge middleware where core's
+ * DB-backed code cannot run. Keep it dependency-free beyond that. It is
+ * published as its own export entry (`@kywi-software/core/audiences/entry-page`)
+ * so importing it never drags in the DB-backed `audiences` barrel — the same
+ * arrangement as `utm-persistence.ts`.
+ */
+import { type ConsentGateOptions } from './consent.js';
+/**
+ * Cookie name the entry-page collector reads (mirrors `COOKIE_NAMES.ENTRY` in
+ * `audiences/cookies.ts`). Kept as a literal so this leaf imports nothing — the
+ * `cookies` module pulls in `jose`, which an edge writer does not need. A core
+ * test asserts this stays equal to `COOKIE_NAMES.ENTRY`, so the two cannot drift.
+ */
+export declare const ENTRY_COOKIE = "kywi_entry";
+/**
+ * The entry-page value for a URL: `pathname + search`, or `null` when the URL
+ * cannot be parsed. Exported because the READ side needs exactly the same
+ * derivation for its current-request fallback.
+ */
+export declare function entryPagePath(url: string): string | null;
+/**
+ * The value to write to `kywi_entry` for this request, or `null` to leave things
+ * alone. `null` when: the visitor has not consented to personalization, the
+ * cookie is already set (the session's entry page is already recorded), or the
+ * URL is unparseable.
+ *
+ * Callers write it as a SESSION cookie — `buildSetCookieHeader(ENTRY_COOKIE,
+ * value, -1, { httpOnly: false })`, or the framework equivalent with no
+ * `maxAge`.
+ */
+export declare function entryPageCookieValue(url: string, options?: {
+    cookieHeader?: string | null;
+    /** The request's `Sec-Fetch-Dest` header. */
+    secFetchDest?: string | null;
+    /** The request's `Accept` header — the fallback when `Sec-Fetch-Dest` is absent. */
+    accept?: string | null;
+} & ConsentGateOptions): string | null;
+/**
+ * Is this request the visitor navigating to a PAGE, rather than the page
+ * fetching something?
+ *
+ * `Sec-Fetch-Dest` is authoritative where it exists (every current browser
+ * sends it, and it is one of the headers a page cannot forge). Without it, an
+ * `Accept` naming `text/html` is the long-standing signal. Neither is a no:
+ * a caller that cannot say what kind of request this is does not get to name
+ * the visitor's entry page.
+ */
+export declare function isDocumentRequest(headers: {
+    secFetchDest?: string | null;
+    accept?: string | null;
+}): boolean;
+//# sourceMappingURL=entry-page.d.ts.map

package/dist/audiences/entry-page.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry-page.d.ts","sourceRoot":"","sources":["../../src/audiences/entry-page.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,OAAO,EAAyB,KAAK,kBAAkB,EAAE,MAAM,cAAc,CAAA;AAE7E;;;;;GAKG;AACH,eAAO,MAAM,YAAY,eAAe,CAAA;AAExC;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOxD;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE;IACP,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,6CAA6C;IAC7C,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,oFAAoF;IACpF,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB,GAAG,kBAAuB,GAC1B,MAAM,GAAG,IAAI,CAKf;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE;IACzC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB,GAAG,OAAO,CAGV"}