@kywi-software/js 0.14.0 → 0.15.1

package/dist/kywi.esm.js

@@ -536,6 +536,98 @@ function bootExperiments(config = {}) {
   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 {
@@ -543,6 +635,7 @@ function createEmptySignals() {
     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: {},
@@ -603,6 +696,10 @@ function resolveSignalValue(signals, ref) {
     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;
@@ -770,6 +867,121 @@ function resolveAudiences(audiences, signals) {
   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";
@@ -802,10 +1014,11 @@ function getCategoryScores() {
   }
   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;
@@ -817,26 +1030,11 @@ function collectBehavioral(currentPath, category) {
     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 {
@@ -844,17 +1042,18 @@ function merge(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 },
     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 };
@@ -871,7 +1070,9 @@ function patchVariantContainers(winningAudienceId) {
     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;
@@ -880,36 +1081,6 @@ function patchVariantContainers(winningAudienceId) {
   }
 }
 
-// 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";
@@ -917,10 +1088,10 @@ var ROOT_ID = "kywi-transparency";
 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 {
@@ -940,12 +1111,12 @@ function removeStorage(key) {
   }
 }
 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");
@@ -964,16 +1135,28 @@ function hasPin() {
   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();
@@ -1078,7 +1261,12 @@ function renderTransparencyPanel(state) {
       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));
@@ -1531,7 +1719,7 @@ function renderPersonalizationBadge(info = {}) {
 }
 
 // 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";
@@ -1539,7 +1727,7 @@ function resolveApiBase(explicit) {
 }
 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();
@@ -1554,17 +1742,21 @@ async function bootAudienceEngine(config) {
     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);
@@ -1581,11 +1773,14 @@ async function bootAudienceEngine(config) {
   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(() => {
     });
   }
@@ -1663,6 +1858,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,
@@ -1694,13 +1902,23 @@ if (typeof document !== "undefined") {
   }
 }
 export {
+  AUDIENCE_PIN_COOKIE,
+  CONSENT_COOKIE,
+  COOKIE_CONSENT_CATEGORY,
   Kywi,
   NAV_BREAKPOINT,
+  SWITCHER_PIN_PREFIX,
   bootAudienceEngine,
   bootExperiments,
+  clearDeniedCookies,
+  clearSelfId,
   enhanceNav,
+  getConsentState,
+  hasConsent,
   initNavMenus,
   openTransparencyPanel,
-  renderTransparencyPanel
+  renderTransparencyPanel,
+  setConsent,
+  setSelfId
 };
 //# sourceMappingURL=kywi.esm.js.map