@kywi-software/js 0.14.0 → 0.15.1

package/dist/kywi.js

@@ -21,14 +21,24 @@ var Kywi = (() => {
   // src/index.ts
   var src_exports = {};
   __export(src_exports, {
+    AUDIENCE_PIN_COOKIE: () => AUDIENCE_PIN_COOKIE,
+    CONSENT_COOKIE: () => CONSENT_COOKIE,
+    COOKIE_CONSENT_CATEGORY: () => COOKIE_CONSENT_CATEGORY,
     Kywi: () => Kywi,
     NAV_BREAKPOINT: () => NAV_BREAKPOINT,
+    SWITCHER_PIN_PREFIX: () => SWITCHER_PIN_PREFIX,
     bootAudienceEngine: () => bootAudienceEngine,
     bootExperiments: () => bootExperiments,
+    clearDeniedCookies: () => clearDeniedCookies,
+    clearSelfId: () => clearSelfId,
     enhanceNav: () => enhanceNav,
+    getConsentState: () => getConsentState,
+    hasConsent: () => hasConsent,
     initNavMenus: () => initNavMenus,
     openTransparencyPanel: () => openTransparencyPanel,
-    renderTransparencyPanel: () => renderTransparencyPanel
+    renderTransparencyPanel: () => renderTransparencyPanel,
+    setConsent: () => setConsent,
+    setSelfId: () => setSelfId
   });
 
   // src/context.ts
@@ -569,6 +579,98 @@ var Kywi = (() => {
     return runtime;
   }
 
+  // src/audience/selfid-collector.ts
+  var SELFID_KEY = "kywi_selfid";
+  function collectSelfId() {
+    const raw = readStorage(SELFID_KEY);
+    if (!raw) return {};
+    try {
+      const parsed = JSON.parse(raw);
+      if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return {};
+      return parsed;
+    } catch {
+      return {};
+    }
+  }
+  function storeSelfId(responses) {
+    try {
+      localStorage.setItem(SELFID_KEY, JSON.stringify(responses));
+    } catch {
+    }
+  }
+  function clearStoredSelfId() {
+    try {
+      localStorage.removeItem(SELFID_KEY);
+    } catch {
+    }
+  }
+  function readStorage(key) {
+    try {
+      return localStorage.getItem(key);
+    } catch {
+      return null;
+    }
+  }
+
+  // src/audience/selfid-api.ts
+  var DEFAULT_API_BASE = "/api/v1";
+  function resolveApiBase(explicit) {
+    if (explicit) return explicit;
+    const basePath = globalThis.Kywi?.context?.basePath;
+    if (!basePath || basePath === "/") return DEFAULT_API_BASE;
+    return `${basePath}/api/v1`;
+  }
+  function resolveCsrfToken(explicit) {
+    if (explicit !== void 0) return explicit;
+    return globalThis.Kywi?.context?.csrfToken ?? null;
+  }
+  function reloadPage() {
+    try {
+      window.location.reload();
+    } catch {
+    }
+  }
+  async function setSelfId(fields, options = {}) {
+    const merged = { ...collectSelfId() };
+    for (const [key, value] of Object.entries(fields)) {
+      if (value === "") delete merged[key];
+      else merged[key] = value;
+    }
+    if (Object.keys(merged).length > 0) storeSelfId(merged);
+    else clearStoredSelfId();
+    const result = await submit(merged, options);
+    if (options.reload !== false && result !== null) reloadPage();
+    return result ?? { audience: null, persisted: false, fields: merged };
+  }
+  async function clearSelfId(options = {}) {
+    clearStoredSelfId();
+    const result = await submit({}, options);
+    if (options.reload !== false && result !== null) reloadPage();
+    return result ?? { audience: null, persisted: false, fields: {} };
+  }
+  async function submit(fields, options) {
+    const csrfToken = resolveCsrfToken(options.csrfToken);
+    try {
+      const res = await fetch(`${resolveApiBase(options.apiBase)}/kywi/self-id`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", ...csrfToken ? { "X-CSRF-Token": csrfToken } : {} },
+        body: JSON.stringify({
+          fields,
+          ...options.audienceId ? { audienceId: options.audienceId } : {}
+        })
+      });
+      if (!res.ok) return null;
+      const body = await res.json().catch(() => null);
+      return {
+        audience: body?.data?.audience ?? null,
+        persisted: body?.data?.persisted === true,
+        fields
+      };
+    } catch {
+      return null;
+    }
+  }
+
   // ../core/dist/audiences/types.js
   function createEmptySignals() {
     return {
@@ -576,6 +678,7 @@ var Kywi = (() => {
       referrer: { raw: null, domain: null, sourceType: "direct" },
       session: { pageViewCount: 0, totalPageViews: 0, sessionDuration: 0, entryPage: "/", pagesVisited: [] },
       behavioral: { categoryScores: {}, totalScore: 0 },
+      query: {},
       selfId: {},
       identity: { visitorId: "", isKnown: false, maLeadId: null },
       adapters: {},
@@ -636,6 +739,10 @@ var Kywi = (() => {
       return signals.session.entryPage;
     if (ref === "session.pagesVisited")
       return signals.session.pagesVisited.join(",");
+    if (ref.startsWith("query.")) {
+      const key = ref.slice(6);
+      return signals.query[key] ?? null;
+    }
     if (ref.startsWith("selfId.")) {
       const key = ref.slice(7);
       return signals.selfId[key] ?? null;
@@ -803,6 +910,121 @@ var Kywi = (() => {
     return { winningAudienceId: allMatchedIds[0] ?? null, allMatchedIds, traces };
   }
 
+  // src/audience/query-collector.ts
+  function collectQuery() {
+    const out = {};
+    if (typeof location === "undefined") return out;
+    new URLSearchParams(location.search).forEach((value, key) => {
+      if (key !== "" && !(key in out)) out[key] = value;
+    });
+    return out;
+  }
+  function entryPageFor(currentPath) {
+    if (currentPath.includes("?")) return currentPath;
+    const search = typeof location === "undefined" ? "" : location.search;
+    return search ? `${currentPath}${search}` : currentPath;
+  }
+
+  // src/cookies.ts
+  var COOKIE_NAMES = {
+    SIGNALS: "kywi_signals",
+    VISITOR: "kywi_visitor",
+    UTM: "kywi_utm",
+    AUDIENCE: "kywi_audience",
+    OPTOUT: "kywi_optout",
+    KNOWN: "kywi_known",
+    PREVIEW_INIT: "kywi_preview_init"
+  };
+  function readCookies() {
+    const map = /* @__PURE__ */ new Map();
+    if (typeof document === "undefined") return map;
+    for (const pair of document.cookie.split(";")) {
+      const trimmed = pair.trim();
+      const eqIdx = trimmed.indexOf("=");
+      if (eqIdx < 0) continue;
+      map.set(trimmed.slice(0, eqIdx), decodeURIComponent(trimmed.slice(eqIdx + 1)));
+    }
+    return map;
+  }
+  function setCookie(name, value, maxAge) {
+    let str = `${name}=${encodeURIComponent(value)}; Path=/; SameSite=Lax`;
+    if (maxAge !== void 0 && maxAge >= 0) str += `; Max-Age=${maxAge}`;
+    document.cookie = str;
+  }
+  function deleteCookie(name) {
+    document.cookie = `${name}=; Path=/; Max-Age=0`;
+  }
+
+  // src/consent.ts
+  var CONSENT_COOKIE = "kywi_consent";
+  var AUDIENCE_PIN_COOKIE = "kywi_audience";
+  var SWITCHER_PIN_PREFIX = "switcher:";
+  var 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"
+  };
+  function getConsentState() {
+    const cookies = readCookies();
+    const raw = cookies.get(CONSENT_COOKIE);
+    if (!raw) return null;
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } 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
+    };
+  }
+  function setConsent(prefs) {
+    const state = {
+      essential: true,
+      analytics: prefs.analytics ?? false,
+      marketing: prefs.marketing ?? false,
+      personalization: prefs.personalization ?? false
+    };
+    setCookie(CONSENT_COOKIE, JSON.stringify(state), 31536e3);
+    clearDeniedCookies(state);
+  }
+  function clearDeniedCookies(state) {
+    if (typeof document === "undefined") return [];
+    const cookies = readCookies();
+    const deleted = [];
+    for (const [name, category] of Object.entries(COOKIE_CONSENT_CATEGORY)) {
+      if (category === "essential") continue;
+      if (state && state[category] === true) continue;
+      if (isDeliberatePreference(name, cookies.get(name))) continue;
+      deleteCookie(name);
+      deleted.push(name);
+    }
+    return deleted;
+  }
+  function isDeliberatePreference(name, value) {
+    if (name !== AUDIENCE_PIN_COOKIE || value === void 0) return false;
+    return value.startsWith(SWITCHER_PIN_PREFIX) && value.length > SWITCHER_PIN_PREFIX.length;
+  }
+  function hasConsent(category, options = {}) {
+    if (options.requireConsent === false) return true;
+    if (category === "essential") return true;
+    const state = getConsentState();
+    if (!state) return false;
+    return state[category] === true;
+  }
+
   // src/audience/behavioral-collector.ts
   var SESSION_KEY = "kywi_session";
   var TOTAL_VIEWS_KEY = "kywi_total_views";
@@ -835,10 +1057,11 @@ var Kywi = (() => {
     }
     return {};
   }
-  function collectBehavioral(currentPath, category) {
+  function collectBehavioral(currentPath, category, gate = {}) {
     const session = getSession();
     session.pageViewCount += 1;
-    if (!session.entryPage) session.entryPage = currentPath;
+    const entryPage = session.entryPage || entryPageFor(currentPath);
+    if (!session.entryPage && hasConsent("personalization", gate)) session.entryPage = entryPage;
     session.pagesVisited.push(currentPath);
     sessionStorage.setItem(SESSION_KEY, JSON.stringify(session));
     const totalViews = (Number(localStorage.getItem(TOTAL_VIEWS_KEY)) || 0) + 1;
@@ -850,26 +1073,11 @@ var Kywi = (() => {
       localStorage.setItem(CATEGORY_SCORES_KEY, JSON.stringify(categoryScores));
     }
     return {
-      session: { pageViewCount: session.pageViewCount, totalPageViews: totalViews, sessionDuration: Math.floor((Date.now() - sessionStart) / 1e3), entryPage: session.entryPage, pagesVisited: session.pagesVisited },
+      session: { pageViewCount: session.pageViewCount, totalPageViews: totalViews, sessionDuration: Math.floor((Date.now() - sessionStart) / 1e3), entryPage, pagesVisited: session.pagesVisited },
       behavioral: { categoryScores, totalScore: 0 }
     };
   }
 
-  // src/audience/selfid-collector.ts
-  var SELFID_KEY = "kywi_selfid";
-  function collectSelfId() {
-    const raw = localStorage.getItem(SELFID_KEY);
-    if (!raw) return {};
-    try {
-      return JSON.parse(raw);
-    } catch {
-      return {};
-    }
-  }
-  function storeSelfId(responses) {
-    localStorage.setItem(SELFID_KEY, JSON.stringify(responses));
-  }
-
   // src/audience/evaluate.ts
   function merge(base, partial) {
     return {
@@ -877,17 +1085,18 @@ var Kywi = (() => {
       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 },
       meta: { ...base.meta, ...partial.meta }
     };
   }
-  function evaluateClientSide(audiences, serverSignals, currentPath, pageCategory) {
+  function evaluateClientSide(audiences, serverSignals, currentPath, pageCategory, gate = {}) {
     let signals = merge(createEmptySignals(), serverSignals);
-    const client = collectBehavioral(currentPath, pageCategory);
+    const client = collectBehavioral(currentPath, pageCategory, gate);
     const selfId = collectSelfId();
-    signals = merge(signals, { session: client.session, behavioral: client.behavioral, selfId, meta: { ...signals.meta, resolvedAt: "client" } });
+    signals = merge(signals, { session: client.session, behavioral: client.behavioral, query: collectQuery(), selfId, meta: { ...signals.meta, resolvedAt: "client" } });
     const { winningAudienceId, allMatchedIds } = resolveAudiences(audiences, signals);
     const isOptedOut2 = signals.meta.isOptedOut;
     return { winningAudienceId: isOptedOut2 ? null : winningAudienceId, allMatchedIds, signals, isOptedOut: isOptedOut2 };
@@ -904,7 +1113,9 @@ var Kywi = (() => {
       el.removeAttribute("aria-busy");
       const skeleton = el.querySelector(".kywi-variant-skeleton");
       if (skeleton) skeleton.remove();
-      const target = winningAudienceId ?? "default";
+      const requested = winningAudienceId ?? "default";
+      const hasMatch = arms.some((child) => child.getAttribute("data-kywi-variant") === requested);
+      const target = hasMatch ? requested : "default";
       el.setAttribute("data-variant", target);
       for (const child of arms) {
         const h = child;
@@ -913,36 +1124,6 @@ var Kywi = (() => {
     }
   }
 
-  // src/cookies.ts
-  var COOKIE_NAMES = {
-    SIGNALS: "kywi_signals",
-    VISITOR: "kywi_visitor",
-    UTM: "kywi_utm",
-    AUDIENCE: "kywi_audience",
-    OPTOUT: "kywi_optout",
-    KNOWN: "kywi_known",
-    PREVIEW_INIT: "kywi_preview_init"
-  };
-  function readCookies() {
-    const map = /* @__PURE__ */ new Map();
-    if (typeof document === "undefined") return map;
-    for (const pair of document.cookie.split(";")) {
-      const trimmed = pair.trim();
-      const eqIdx = trimmed.indexOf("=");
-      if (eqIdx < 0) continue;
-      map.set(trimmed.slice(0, eqIdx), decodeURIComponent(trimmed.slice(eqIdx + 1)));
-    }
-    return map;
-  }
-  function setCookie(name, value, maxAge) {
-    let str = `${name}=${encodeURIComponent(value)}; Path=/; SameSite=Lax`;
-    if (maxAge !== void 0 && maxAge >= 0) str += `; Max-Age=${maxAge}`;
-    document.cookie = str;
-  }
-  function deleteCookie(name) {
-    document.cookie = `${name}=; Path=/; Max-Age=0`;
-  }
-
   // src/audience/transparency.ts
   var COLLAPSED_KEY = "kywi_transparency_collapsed";
   var LEGACY_DISMISSED_KEY = "kywi_transparency_dismissed";
@@ -950,10 +1131,10 @@ var Kywi = (() => {
   var PANEL_ID = "kywi-transparency-panel";
   var TITLE_ID = "kywi-transparency-title";
   var SWITCHER_LABEL_ID = "kywi-transparency-switcher-label";
-  var DEFAULT_API_BASE = "/api/v1";
+  var DEFAULT_API_BASE2 = "/api/v1";
   var lastState = null;
   var forcedOpen = false;
-  function readStorage(key) {
+  function readStorage2(key) {
     try {
       return localStorage.getItem(key);
     } catch {
@@ -973,12 +1154,12 @@ var Kywi = (() => {
     }
   }
   function isCollapsed() {
-    if (readStorage(LEGACY_DISMISSED_KEY) === "1") {
+    if (readStorage2(LEGACY_DISMISSED_KEY) === "1") {
       removeStorage(LEGACY_DISMISSED_KEY);
       writeStorage(COLLAPSED_KEY, "1");
       return true;
     }
-    return readStorage(COLLAPSED_KEY) !== "0";
+    return readStorage2(COLLAPSED_KEY) !== "0";
   }
   function setCollapsed(collapsed) {
     writeStorage(COLLAPSED_KEY, collapsed ? "1" : "0");
@@ -997,16 +1178,28 @@ var Kywi = (() => {
     return readCookies().has(COOKIE_NAMES.AUDIENCE);
   }
   async function pinAudience(audienceId, opts = {}) {
-    const apiBase = opts.apiBase ?? DEFAULT_API_BASE;
+    const apiBase = opts.apiBase ?? DEFAULT_API_BASE2;
     try {
-      await fetch(`${apiBase}/kywi/audience`, {
+      const res = await fetch(`${apiBase}/kywi/audience`, {
         method: "POST",
         headers: { "Content-Type": "application/json", ...opts.csrfToken ? { "X-CSRF-Token": opts.csrfToken } : {} },
-        body: JSON.stringify({ audienceId })
+        body: JSON.stringify({ audienceId, source: "switcher" })
       });
+      if (!res.ok) return false;
+      const body = await res.json().catch(() => null);
+      return body?.data?.persisted !== false;
     } catch {
+      return false;
     }
   }
+  function showSwitcherError(group) {
+    group.parentElement?.querySelector(".kywi-transparency-switcher-error")?.remove();
+    const note = document.createElement("p");
+    note.className = "kywi-transparency-switcher-error";
+    note.setAttribute("role", "status");
+    note.textContent = "Couldn't save that choice. It won't be remembered on the next page.";
+    group.parentElement?.appendChild(note);
+  }
   function reload() {
     try {
       window.location.reload();
@@ -1111,7 +1304,12 @@ var Kywi = (() => {
         const isCurrent = option.id === state.audienceId;
         const optionBtn = button("kywi-transparency-option", option.name, () => {
           if (isCurrent) return;
-          void pinAudience(option.id, { apiBase: state.apiBase, csrfToken: state.csrfToken }).then(reload);
+          void pinAudience(option.id, { apiBase: state.apiBase, csrfToken: state.csrfToken }).then(
+            (persisted) => {
+              if (persisted) reload();
+              else showSwitcherError(group);
+            }
+          );
         });
         optionBtn.dataset.kywiAudienceId = option.id;
         optionBtn.setAttribute("aria-pressed", String(isCurrent));
@@ -1564,7 +1762,7 @@ var Kywi = (() => {
   }
 
   // src/audience/index.ts
-  function resolveApiBase(explicit) {
+  function resolveApiBase2(explicit) {
     if (explicit) return explicit;
     const basePath = Kywi.context?.basePath;
     if (!basePath || basePath === "/") return "/api/v1";
@@ -1572,7 +1770,7 @@ var Kywi = (() => {
   }
   async function bootAudienceEngine(config) {
     const { audiences, currentPath, pageCategory, serverSignals } = config;
-    const apiBase = resolveApiBase(config.apiBase);
+    const apiBase = resolveApiBase2(config.apiBase);
     checkPreviewInit();
     const serverMeta = readServerMeta();
     const previewId = getPreviewAudienceId();
@@ -1587,17 +1785,21 @@ var Kywi = (() => {
       return;
     }
     const cookies = readCookies();
+    const consentGate = config.requireConsent === void 0 ? {} : { requireConsent: config.requireConsent };
+    const mayPersonalize = hasConsent("personalization", consentGate);
+    const storedVisitorId = mayPersonalize ? cookies.get(COOKIE_NAMES.VISITOR) : void 0;
     let merged = {
       ...serverSignals,
-      identity: { visitorId: serverMeta.visitorId || cookies.get(COOKIE_NAMES.VISITOR) || "", isKnown: cookies.has(COOKIE_NAMES.KNOWN), maLeadId: null },
+      identity: { visitorId: serverMeta.visitorId || storedVisitorId || "", isKnown: mayPersonalize && cookies.has(COOKIE_NAMES.KNOWN), maLeadId: null },
       meta: { isOptedOut: cookies.has(COOKIE_NAMES.OPTOUT), isPreview: false, previewAudienceId: null, resolvedAt: "server" }
     };
     if (config.adapters && config.adapters.length > 0) {
       const adapterResults = await runClientAdapters(config.adapters, merged, apiBase);
       merged.adapters = { ...merged.adapters, ...adapterResults };
     }
-    const result = evaluateClientSide(audiences, merged, currentPath, pageCategory);
-    const pinnedId = cookies.get(COOKIE_NAMES.AUDIENCE) ?? null;
+    const result = evaluateClientSide(audiences, merged, currentPath, pageCategory, consentGate);
+    const rawPin = cookies.get(COOKIE_NAMES.AUDIENCE) ?? null;
+    const pinnedId = rawPin?.startsWith("switcher:") ? rawPin.slice("switcher:".length) || null : rawPin;
     const isPinned = !result.isOptedOut && pinnedId !== null && activeAudiences.some((a) => a.id === pinnedId);
     const effectiveAudienceId = isPinned ? pinnedId : result.winningAudienceId;
     patchVariantContainers(effectiveAudienceId);
@@ -1614,11 +1816,14 @@ var Kywi = (() => {
     renderPersonalizationBadge({ audienceName: nameOf(effectiveAudienceId) });
     populateDataLayer({ visitorId: result.signals.identity.visitorId, audienceId: effectiveAudienceId, experimentId: serverMeta.experimentId, variantId: serverMeta.variantId, isPreview: false, isOptedOut: result.isOptedOut });
     fireKywiReady();
-    if (!isPinned && result.winningAudienceId && result.winningAudienceId !== serverMeta.audienceId) {
+    if (!isPinned && mayPersonalize && result.winningAudienceId && result.winningAudienceId !== serverMeta.audienceId) {
       fetch(`${apiBase}/kywi/audience`, {
         method: "POST",
         headers: { "Content-Type": "application/json", ...Kywi.context?.csrfToken ? { "X-CSRF-Token": Kywi.context.csrfToken } : {} },
-        body: JSON.stringify({ audienceId: result.winningAudienceId })
+        // Explicitly the AUTOMATIC write, so the server applies the
+        // personalization gate to it (kywi-cms#91). The transparency panel's
+        // hand-operated switcher sends source:'switcher' and is exempt.
+        body: JSON.stringify({ audienceId: result.winningAudienceId, source: "boot" })
       }).catch(() => {
       });
     }
@@ -1696,6 +1901,19 @@ var Kywi = (() => {
         }
       }
     },
+    /**
+     * Record who the visitor says they are, and resolve their audience
+     * (kywi-cms#200). Writes the browser-side answers, posts them to the
+     * consent-gated runtime endpoint, and reloads so the SERVER can re-render
+     * with the resolved audience pinned — which is the only way to reach a
+     * variant arm, since every losing arm is pruned server-side (#167).
+     *
+     * On the global because a site's own "What brings you here?" control needs
+     * it: the built-in widget's write path is module-private.
+     */
+    setSelfId,
+    /** Forget the visitor's self-identification and un-pin their audience. */
+    clearSelfId,
     getEntity: null,
     getFeed: null,
     renderFeed: null,