@kywi-software/core 0.14.0 → 0.15.1

package/dist/audiences/collectors/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../../src/audiences/collectors/session.ts"],"names":[],"mappings":"AACA,OAAO,EAA8C,KAAK,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAGnG;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,IAAI,GAAE,kBAAkB,GAAG;IAAE,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAO,GAC/D,cAAc,CAMhB;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAYjE"}

package/dist/audiences/collectors/session.js

@@ -0,0 +1,50 @@
+import { COOKIE_NAMES } from '../cookies.js';
+import { cookieAllowed, readConsentFromCookieHeader } from '../consent.js';
+import { entryPagePath } from '../entry-page.js';
+/**
+ * Resolve the visitor's entry page: the `kywi_entry` cookie recorded on the
+ * first request of the session, falling back to THIS request's path + query.
+ *
+ * The cookie is a `personalization` cookie, so it is treated as absent unless
+ * the visitor consents (kywi-cms#91) — a stored entry page from an earlier
+ * "accept" must stop resolving a visitor who has since rejected.
+ *
+ * The fallback is not a degraded mode, it is the mechanism: a `Set-Cookie` only
+ * takes effect on the NEXT request, so the landing request — the one carrying
+ * `?from=marketer` — has no cookie to read and must evaluate against its own
+ * path. That is what lets a campaign link personalize the page it links to
+ * without a reload, consent or no consent.
+ */
+export function collectSession(req, cookies, gate = {}) {
+    const consent = readConsentFromCookieHeader(gate.cookieHeader ?? req.headers.get('cookie'));
+    const stored = cookieAllowed(COOKIE_NAMES.ENTRY, consent, gate)
+        ? cookies.get(COOKIE_NAMES.ENTRY)
+        : undefined;
+    return { entryPage: stored || entryPagePath(req.url) || '/' };
+}
+/**
+ * Every query parameter on this request, as the `query.<param>` signal family
+ * (kywi-cms#196) — so a campaign link like `/developers?from=marketer` is a
+ * one-line audience rule (`query.from equals marketer`) instead of a substring
+ * match against the entry page.
+ *
+ * Never gated: like the URL's own `utm_*` params, these are the content of the
+ * request being served, not tracking carried into it from an earlier visit.
+ * Repeated params keep the FIRST value, matching `URLSearchParams.get`.
+ */
+export function collectQuery(req) {
+    const out = {};
+    let params;
+    try {
+        params = new URL(req.url).searchParams;
+    }
+    catch {
+        return out;
+    }
+    for (const [key, value] of params) {
+        if (key !== '' && !(key in out))
+            out[key] = value;
+    }
+    return out;
+}
+//# sourceMappingURL=session.js.map

package/dist/audiences/collectors/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../../src/audiences/collectors/session.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,EAAE,aAAa,EAAE,2BAA2B,EAA2B,MAAM,eAAe,CAAA;AACnG,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAchD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,cAAc,CAC5B,GAAY,EACZ,OAA4B,EAC5B,OAA8D,EAAE;IAEhE,MAAM,OAAO,GAAG,2BAA2B,CAAC,IAAI,CAAC,YAAY,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAA;IAC3F,MAAM,MAAM,GAAG,aAAa,CAAC,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC;QAC7D,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,KAAK,CAAC;QACjC,CAAC,CAAC,SAAS,CAAA;IACb,OAAO,EAAE,SAAS,EAAE,MAAM,IAAI,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,GAAG,EAAE,CAAA;AAC/D,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAAC,GAAY;IACvC,MAAM,GAAG,GAA2B,EAAE,CAAA;IACtC,IAAI,MAAuB,CAAA;IAC3B,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,YAAY,CAAA;IACxC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,GAAG,CAAA;IACZ,CAAC;IACD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,EAAE,CAAC;QAClC,IAAI,GAAG,KAAK,EAAE,IAAI,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC;YAAE,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAA;IACnD,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC"}

package/dist/audiences/collectors/utm.d.ts

@@ -1,3 +1,4 @@
+import { type ConsentGateOptions } from '../consent.js';
 export interface UtmSignals {
     source: string | null;
     medium: string | null;
@@ -5,5 +6,18 @@ export interface UtmSignals {
     term: string | null;
     content: string | null;
 }
-export declare function collectUtm(req: Request, cookies: Map<string, string>): UtmSignals;
+/**
+ * Resolve the visitor's UTM attribution: this request's `utm_*` query params,
+ * falling back to the persisted `kywi_utm` cookie.
+ *
+ * The cookie fallback is IGNORED unless the visitor consents to personalization
+ * (kywi-cms#91). Blocking the write alone would not be enough — a visitor who
+ * accepted last month and rejects today still carries the cookie, and reading it
+ * would keep them in a campaign audience they just opted out of. The URL's own
+ * `utm_*` params are always honoured: they are this request's content, not
+ * stored tracking.
+ */
+export declare function collectUtm(req: Request, cookies: Map<string, string>, gate?: ConsentGateOptions & {
+    cookieHeader?: string | null;
+}): UtmSignals;
 //# sourceMappingURL=utm.d.ts.map

package/dist/audiences/collectors/utm.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utm.d.ts","sourceRoot":"","sources":["../../../src/audiences/collectors/utm.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,UAAU,CAcjF"}
+{"version":3,"file":"utm.d.ts","sourceRoot":"","sources":["../../../src/audiences/collectors/utm.ts"],"names":[],"mappings":"AACA,OAAO,EAAyB,KAAK,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAE9E,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CACxB,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,IAAI,GAAE,kBAAkB,GAAG;IAAE,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAO,GAC/D,UAAU,CAgBZ"}

package/dist/audiences/collectors/utm.js

@@ -1,8 +1,22 @@
 import { COOKIE_NAMES } from '../cookies.js';
-export function collectUtm(req, cookies) {
+import { cookieAllowedByHeader } from '../consent.js';
+/**
+ * Resolve the visitor's UTM attribution: this request's `utm_*` query params,
+ * falling back to the persisted `kywi_utm` cookie.
+ *
+ * The cookie fallback is IGNORED unless the visitor consents to personalization
+ * (kywi-cms#91). Blocking the write alone would not be enough — a visitor who
+ * accepted last month and rejects today still carries the cookie, and reading it
+ * would keep them in a campaign audience they just opted out of. The URL's own
+ * `utm_*` params are always honoured: they are this request's content, not
+ * stored tracking.
+ */
+export function collectUtm(req, cookies, gate = {}) {
     const url = new URL(req.url);
     let cookieUtm = {};
-    const raw = cookies.get(COOKIE_NAMES.UTM);
+    const raw = cookieAllowedByHeader(COOKIE_NAMES.UTM, gate.cookieHeader ?? req.headers.get('cookie'), gate)
+        ? cookies.get(COOKIE_NAMES.UTM)
+        : undefined;
     if (raw) {
         try {
             cookieUtm = JSON.parse(raw);

package/dist/audiences/collectors/utm.js.map

@@ -1 +1 @@
-{"version":3,"file":"utm.js","sourceRoot":"","sources":["../../../src/audiences/collectors/utm.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAU5C,MAAM,UAAU,UAAU,CAAC,GAAY,EAAE,OAA4B;IACnE,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IAC5B,IAAI,SAAS,GAAwB,EAAE,CAAA;IACvC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,CAAA;IACzC,IAAI,GAAG,EAAE,CAAC;QACR,IAAI,CAAC;YAAC,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAwB,CAAA;QAAC,CAAC;QAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;IACnF,CAAC;IACD,OAAO;QACL,MAAM,EAAE,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,SAAS,CAAC,MAAM,IAAI,IAAI;QACtE,MAAM,EAAE,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,SAAS,CAAC,MAAM,IAAI,IAAI;QACtE,QAAQ,EAAE,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,SAAS,CAAC,QAAQ,IAAI,IAAI;QAC5E,IAAI,EAAE,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,SAAS,CAAC,IAAI,IAAI,IAAI;QAChE,OAAO,EAAE,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,SAAS,CAAC,OAAO,IAAI,IAAI;KAC1E,CAAA;AACH,CAAC"}
+{"version":3,"file":"utm.js","sourceRoot":"","sources":["../../../src/audiences/collectors/utm.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,EAAE,qBAAqB,EAA2B,MAAM,eAAe,CAAA;AAU9E;;;;;;;;;;GAUG;AACH,MAAM,UAAU,UAAU,CACxB,GAAY,EACZ,OAA4B,EAC5B,OAA8D,EAAE;IAEhE,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IAC5B,IAAI,SAAS,GAAwB,EAAE,CAAA;IACvC,MAAM,GAAG,GAAG,qBAAqB,CAAC,YAAY,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC;QACvG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC;QAC/B,CAAC,CAAC,SAAS,CAAA;IACb,IAAI,GAAG,EAAE,CAAC;QACR,IAAI,CAAC;YAAC,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAwB,CAAA;QAAC,CAAC;QAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;IACnF,CAAC;IACD,OAAO;QACL,MAAM,EAAE,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,SAAS,CAAC,MAAM,IAAI,IAAI;QACtE,MAAM,EAAE,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,SAAS,CAAC,MAAM,IAAI,IAAI;QACtE,QAAQ,EAAE,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,SAAS,CAAC,QAAQ,IAAI,IAAI;QAC5E,IAAI,EAAE,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,SAAS,CAAC,IAAI,IAAI,IAAI;QAChE,OAAO,EAAE,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,SAAS,CAAC,OAAO,IAAI,IAAI;KAC1E,CAAA;AACH,CAAC"}

package/dist/audiences/consent-config.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Resolve `theme.personalization.requireConsent` from a `KywiConfig`
+ * (kywi-cms#91).
+ *
+ * Kept out of `./consent.ts` because that module must import nothing at all —
+ * it is pulled into Next.js edge middleware. This file's only import is a TYPE,
+ * which erases at compile time, but it lives next door rather than inside the
+ * gate so the edge entry stays obviously dependency-free.
+ */
+import type { KywiConfig } from '../config/types.js';
+/**
+ * Does this site require consent before personalization cookies are written?
+ *
+ * **True unless a theme explicitly opts out.** The flag lives on the theme, so
+ * it resolves the same way `clientRuntimeEnabled` / `transparencyNoticeEnabled`
+ * do in the reference app: the named site's theme, falling back to the first
+ * site's theme and then the first theme declared. A site with no theme at all
+ * requires consent — the safe answer is the default answer.
+ */
+export declare function personalizationRequiresConsent(config: KywiConfig, siteId?: string): boolean;
+//# sourceMappingURL=consent-config.d.ts.map

package/dist/audiences/consent-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consent-config.d.ts","sourceRoot":"","sources":["../../src/audiences/consent-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAEpD;;;;;;;;GAQG;AACH,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAI3F"}

package/dist/audiences/consent-config.js

@@ -0,0 +1,15 @@
+/**
+ * Does this site require consent before personalization cookies are written?
+ *
+ * **True unless a theme explicitly opts out.** The flag lives on the theme, so
+ * it resolves the same way `clientRuntimeEnabled` / `transparencyNoticeEnabled`
+ * do in the reference app: the named site's theme, falling back to the first
+ * site's theme and then the first theme declared. A site with no theme at all
+ * requires consent — the safe answer is the default answer.
+ */
+export function personalizationRequiresConsent(config, siteId) {
+    const site = (siteId ? config.sites.find((s) => s.id === siteId) : undefined) ?? config.sites[0];
+    const theme = config.themes.find((t) => t.name === site?.theme) ?? config.themes[0];
+    return theme?.personalization?.requireConsent !== false;
+}
+//# sourceMappingURL=consent-config.js.map

package/dist/audiences/consent-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consent-config.js","sourceRoot":"","sources":["../../src/audiences/consent-config.ts"],"names":[],"mappings":"AAWA;;;;;;;;GAQG;AACH,MAAM,UAAU,8BAA8B,CAAC,MAAkB,EAAE,MAAe;IAChF,MAAM,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;IAChG,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAA;IACnF,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,KAAK,KAAK,CAAA;AACzD,CAAC"}

package/dist/audiences/consent-startup.d.ts

@@ -0,0 +1,39 @@
+import type { KywiDb } from '../db/client.js';
+/** The env var mirroring `theme.personalization.requireConsent` for edge middleware. */
+export declare const REQUIRE_CONSENT_ENV = "KYWI_REQUIRE_CONSENT";
+/** How `middleware.ts` reads the mirror: anything but the literal "false" is true. */
+export declare function requireConsentFromEnv(env?: Record<string, string | undefined>): boolean;
+/**
+ * Fail startup when the config flag and its edge mirror disagree.
+ *
+ * Deliberately a throw and not a warning: the two halves of one setting pointing
+ * opposite ways is never intentional, and the resulting behaviour (cookies
+ * written by the edge that the API then declines to read, or vice versa) is
+ * exactly the kind of bug that survives to production because nothing is
+ * visibly broken.
+ */
+export declare function assertConsentEnvAgreement(requireConsentFromConfig: boolean, env?: Record<string, string | undefined>): void;
+/**
+ * Build the once-only "consent required, but nothing asks for it" check.
+ *
+ * Returns a function safe to call on every request: it runs at most once, never
+ * awaits (the first request does not pay for it), and swallows every error. A
+ * warning that could break a page, or add latency to the hot path, would not be
+ * worth having.
+ *
+ * The check is a `::text LIKE` prefilter — the same shape
+ * `checkAudienceDeletionSafety` uses — looking for anything that mentions the
+ * module type at all. Over-matching is fine here: a false negative (staying
+ * quiet) is the safe direction for an advisory warning.
+ *
+ * It reads BOTH places a module can be placed: `kywi_content.layout` and
+ * `kywi_section_templates.definition`. A banner composed from a blueprint is a
+ * banner, and scanning pages alone told a site that builds every page that way
+ * that consent could never be granted — while the banner was on screen.
+ */
+export declare function createConsentBannerCheck(deps: {
+    db: KywiDb;
+    requireConsent: boolean;
+    warn?: (message: string) => void;
+}): () => void;
+//# sourceMappingURL=consent-startup.d.ts.map

package/dist/audiences/consent-startup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consent-startup.d.ts","sourceRoot":"","sources":["../../src/audiences/consent-startup.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAE7C,wFAAwF;AACxF,eAAO,MAAM,mBAAmB,yBAAyB,CAAA;AAEzD,sFAAsF;AACtF,wBAAgB,qBAAqB,CAAC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GAAG,OAAO,CAEpG;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACvC,wBAAwB,EAAE,OAAO,EACjC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GACpD,IAAI,CAcN;AASD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE;IAC7C,EAAE,EAAE,MAAM,CAAA;IACV,cAAc,EAAE,OAAO,CAAA;IACvB,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CACjC,GAAG,MAAM,IAAI,CA8Bb"}

package/dist/audiences/consent-startup.js

@@ -0,0 +1,105 @@
+/**
+ * Startup checks for the cookie-consent gate (kywi-cms#91).
+ *
+ * Two failure modes are invisible at runtime and expensive to discover later:
+ *
+ *   1. The config flag and its edge mirror disagree. `middleware.ts` runs on the
+ *      edge and cannot read `kywi.config.ts`, so `requireConsent` is mirrored as
+ *      `KYWI_REQUIRE_CONSENT`. If the two drift, the middleware and the API
+ *      disagree about whether a visitor may be tracked — one writes
+ *      `kywi_visitor`, the other refuses to read it — and nothing anywhere says
+ *      so. That is a misconfiguration, and it fails the deploy.
+ *
+ *   2. Consent is required and no page offers a way to give it. Every
+ *      personalization cookie is then permanently suppressed: audiences,
+ *      experiments and UTM attribution quietly do nothing, and the site looks
+ *      broken rather than gated. That is a WARNING, not an error — a site may
+ *      legitimately have no personalization at all — but it must be said out
+ *      loud, once, rather than left for someone to debug.
+ */
+import { sql } from 'drizzle-orm';
+/** The env var mirroring `theme.personalization.requireConsent` for edge middleware. */
+export const REQUIRE_CONSENT_ENV = 'KYWI_REQUIRE_CONSENT';
+/** How `middleware.ts` reads the mirror: anything but the literal "false" is true. */
+export function requireConsentFromEnv(env = process.env) {
+    return env[REQUIRE_CONSENT_ENV] !== 'false';
+}
+/**
+ * Fail startup when the config flag and its edge mirror disagree.
+ *
+ * Deliberately a throw and not a warning: the two halves of one setting pointing
+ * opposite ways is never intentional, and the resulting behaviour (cookies
+ * written by the edge that the API then declines to read, or vice versa) is
+ * exactly the kind of bug that survives to production because nothing is
+ * visibly broken.
+ */
+export function assertConsentEnvAgreement(requireConsentFromConfig, env = process.env) {
+    const fromEnv = requireConsentFromEnv(env);
+    if (fromEnv === requireConsentFromConfig)
+        return;
+    const raw = env[REQUIRE_CONSENT_ENV];
+    throw new Error(`Cookie-consent misconfiguration: theme.personalization.requireConsent is ` +
+        `${requireConsentFromConfig} but ${REQUIRE_CONSENT_ENV} is ` +
+        `${raw === undefined ? 'unset (which means true)' : JSON.stringify(raw)}.\n` +
+        `  Next.js edge middleware cannot read kywi.config.ts, so it mirrors that flag ` +
+        `through ${REQUIRE_CONSENT_ENV}. While they disagree, the middleware and the API ` +
+        `disagree about whether a visitor may be tracked.\n` +
+        `  Set both, or neither: ${REQUIRE_CONSENT_ENV}=false alongside ` +
+        `personalization: { requireConsent: false }, or remove both.`);
+}
+const NO_BANNER_WARNING = '[kywi] Cookie consent is required (theme.personalization.requireConsent) but no ' +
+    'page or layout places the `cookieConsent` module, so no visitor can ever grant it. ' +
+    'Every personalization cookie stays suppressed: audiences, A/B bucketing and UTM ' +
+    'attribution will resolve to default content for everyone. Place the module, or set ' +
+    'personalization: { requireConsent: false } if consent is collected by external tooling.';
+/**
+ * Build the once-only "consent required, but nothing asks for it" check.
+ *
+ * Returns a function safe to call on every request: it runs at most once, never
+ * awaits (the first request does not pay for it), and swallows every error. A
+ * warning that could break a page, or add latency to the hot path, would not be
+ * worth having.
+ *
+ * The check is a `::text LIKE` prefilter — the same shape
+ * `checkAudienceDeletionSafety` uses — looking for anything that mentions the
+ * module type at all. Over-matching is fine here: a false negative (staying
+ * quiet) is the safe direction for an advisory warning.
+ *
+ * It reads BOTH places a module can be placed: `kywi_content.layout` and
+ * `kywi_section_templates.definition`. A banner composed from a blueprint is a
+ * banner, and scanning pages alone told a site that builds every page that way
+ * that consent could never be granted — while the banner was on screen.
+ */
+export function createConsentBannerCheck(deps) {
+    const warn = deps.warn ?? ((m) => console.warn(m));
+    let started = false;
+    return () => {
+        if (started || !deps.requireConsent)
+            return;
+        started = true;
+        void (async () => {
+            try {
+                const rows = await deps.db.execute(sql `
+            SELECT 1 AS found
+            FROM kywi_content
+            WHERE layout IS NOT NULL
+              AND layout::text LIKE ${'%"cookieConsent"%'}
+            UNION ALL
+            SELECT 1 AS found
+            FROM kywi_section_templates
+            WHERE definition IS NOT NULL
+              AND definition::text LIKE ${'%"cookieConsent"%'}
+            LIMIT 1
+          `);
+                if (rows.length === 0)
+                    warn(NO_BANNER_WARNING);
+            }
+            catch {
+                // No content table yet (a fresh install mid-migration), a dialect that
+                // cannot cast, a transient connection failure — none of that is worth
+                // failing or logging a request over. Silence is the safe direction.
+            }
+        })();
+    };
+}
+//# sourceMappingURL=consent-startup.js.map

package/dist/audiences/consent-startup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consent-startup.js","sourceRoot":"","sources":["../../src/audiences/consent-startup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAA;AAGjC,wFAAwF;AACxF,MAAM,CAAC,MAAM,mBAAmB,GAAG,sBAAsB,CAAA;AAEzD,sFAAsF;AACtF,MAAM,UAAU,qBAAqB,CAAC,MAA0C,OAAO,CAAC,GAAG;IACzF,OAAO,GAAG,CAAC,mBAAmB,CAAC,KAAK,OAAO,CAAA;AAC7C,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,yBAAyB,CACvC,wBAAiC,EACjC,MAA0C,OAAO,CAAC,GAAG;IAErD,MAAM,OAAO,GAAG,qBAAqB,CAAC,GAAG,CAAC,CAAA;IAC1C,IAAI,OAAO,KAAK,wBAAwB;QAAE,OAAM;IAChD,MAAM,GAAG,GAAG,GAAG,CAAC,mBAAmB,CAAC,CAAA;IACpC,MAAM,IAAI,KAAK,CACb,2EAA2E;QACzE,GAAG,wBAAwB,QAAQ,mBAAmB,MAAM;QAC5D,GAAG,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,0BAA0B,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK;QAC5E,gFAAgF;QAChF,WAAW,mBAAmB,oDAAoD;QAClF,oDAAoD;QACpD,2BAA2B,mBAAmB,mBAAmB;QACjE,6DAA6D,CAChE,CAAA;AACH,CAAC;AAED,MAAM,iBAAiB,GACrB,kFAAkF;IAClF,qFAAqF;IACrF,kFAAkF;IAClF,qFAAqF;IACrF,yFAAyF,CAAA;AAE3F;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,wBAAwB,CAAC,IAIxC;IACC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAA;IAC1D,IAAI,OAAO,GAAG,KAAK,CAAA;IACnB,OAAO,GAAG,EAAE;QACV,IAAI,OAAO,IAAI,CAAC,IAAI,CAAC,cAAc;YAAE,OAAM;QAC3C,OAAO,GAAG,IAAI,CAAA;QACd,KAAK,CAAC,KAAK,IAAI,EAAE;YACf,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,OAAO,CAChC,GAAG,CAAA;;;;sCAIyB,mBAAmB;;;;;0CAKf,mBAAmB;;WAElD,CACF,CAAA;gBACD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;oBAAE,IAAI,CAAC,iBAAiB,CAAC,CAAA;YAChD,CAAC;YAAC,MAAM,CAAC;gBACP,uEAAuE;gBACvE,sEAAsE;gBACtE,oEAAoE;YACtE,CAAC;QACH,CAAC,CAAC,EAAE,CAAA;IACN,CAAC,CAAA;AACH,CAAC"}

package/dist/audiences/consent.d.ts

@@ -0,0 +1,205 @@
+/**
+ * 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 declare const CONSENT_COOKIE = "kywi_consent";
+/** 1 year, in seconds — how long a consent decision is remembered. */
+export declare const CONSENT_MAX_AGE: number;
+/** The cookie an audience pin lives in. */
+export declare 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 declare const SWITCHER_PIN_PREFIX = "switcher:";
+export type ConsentCategory = 'essential' | 'analytics' | 'marketing' | 'personalization';
+/** Shared tail argument of every gate function. */
+export interface ConsentGateOptions {
+    /**
+     * `theme.personalization.requireConsent`. Defaults to true. When explicitly
+     * `false` the gate is off and every category reads as allowed — the
+     * external-CMP escape hatch described in the file header.
+     */
+    requireConsent?: boolean;
+}
+export interface ConsentState {
+    essential: boolean;
+    analytics: boolean;
+    marketing: boolean;
+    personalization: boolean;
+}
+/**
+ * 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 declare const COOKIE_CONSENT_CATEGORY: {
+    readonly kywi_consent: "essential";
+    readonly kywi_optout: "essential";
+    readonly kywi_preview_init: "essential";
+    readonly kywi_signals: "personalization";
+    readonly kywi_visitor: "personalization";
+    readonly kywi_utm: "personalization";
+    readonly kywi_audience: "personalization";
+    readonly kywi_known: "personalization";
+    readonly kywi_entry: "personalization";
+    readonly kywi_selfid: "personalization";
+};
+/**
+ * The consent category `cookieName` requires, or `null` when the name is not
+ * classified. An unclassified cookie is denied by `cookieAllowed`.
+ */
+export declare function consentCategoryFor(cookieName: string): ConsentCategory | null;
+/** Parse a raw `kywi_consent` cookie value. Returns null when absent/malformed. */
+export declare function parseConsentValue(raw: string | null | undefined): ConsentState | null;
+/**
+ * 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 declare function readConsentFromCookieHeader(header: string | null | undefined): ConsentState | 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 declare function consentAllows(state: ConsentState | null, category: ConsentCategory, options?: ConsentGateOptions): boolean;
+/**
+ * The gate: may `cookieName` be written given `state`? Unclassified cookie
+ * names fail closed — unless the gate itself is off.
+ */
+export declare function cookieAllowed(cookieName: string, state: ConsentState | null, options?: ConsentGateOptions): boolean;
+/** Convenience for request handlers: gate `cookieName` against a `Cookie` header. */
+export declare function cookieAllowedByHeader(cookieName: string, header: string | null | undefined, options?: ConsentGateOptions): boolean;
+/** Every cookie name classified into `category`. */
+export declare function cookiesInCategory(category: ConsentCategory): string[];
+/**
+ * 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 declare function clearDeniedCookies(state: ConsentState | null): string[];
+/** Read the visitor's consent decision from `document.cookie`, or null. */
+export declare function getConsentState(): ConsentState | null;
+/**
+ * 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 declare function setConsent(prefs: Partial<Omit<ConsentState, 'essential'>>): ConsentState;
+/** Has the visitor granted `category`? See `consentAllows` for the semantics. */
+export declare function hasConsent(category: ConsentCategory, options?: ConsentGateOptions): boolean;
+//# sourceMappingURL=consent.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"consent.d.ts","sourceRoot":"","sources":["../../src/audiences/consent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0FG;AAEH,8DAA8D;AAC9D,eAAO,MAAM,cAAc,iBAAiB,CAAA;AAE5C,sEAAsE;AACtE,eAAO,MAAM,eAAe,QAAkB,CAAA;AAE9C,2CAA2C;AAC3C,eAAO,MAAM,mBAAmB,kBAAkB,CAAA;AAElD;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,cAAc,CAAA;AAE9C,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,iBAAiB,CAAA;AAEzF,mDAAmD;AACnD,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,OAAO,CAAA;IAClB,SAAS,EAAE,OAAO,CAAA;IAClB,SAAS,EAAE,OAAO,CAAA;IAClB,eAAe,EAAE,OAAO,CAAA;CACzB;AAED;;;;GAIG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;CAWgB,CAAA;AAEpD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAE7E;AAED,mFAAmF;AACnF,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,YAAY,GAAG,IAAI,CAsBrF;AAED;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,YAAY,GAAG,IAAI,CAWlG;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,YAAY,GAAG,IAAI,EAC1B,QAAQ,EAAE,eAAe,EACzB,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAKT;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,YAAY,GAAG,IAAI,EAC1B,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAOT;AAED,qFAAqF;AACrF,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACjC,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAET;AAED,oDAAoD;AACpD,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,EAAE,CAIrE;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,GAAG,MAAM,EAAE,CAUvE;AAsCD,2EAA2E;AAC3E,wBAAgB,eAAe,IAAI,YAAY,GAAG,IAAI,CAGrD;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,WAAW,CAAC,CAAC,GAAG,YAAY,CAiBxF;AAED,iFAAiF;AACjF,wBAAgB,UAAU,CAAC,QAAQ,EAAE,eAAe,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAE/F"}