@intlayer/analytics 9.4.0-canary.0 → 9.4.0

package/README.md

@@ -214,6 +214,7 @@ Explore our comprehensive documentation to get started with Intlayer and learn h
   <li><a href="https://intlayer.org/doc/environment/vite-and-vue" rel=''>Vite + Vue</a></li>
   <li><a href="https://intlayer.org/doc/environment/nuxt-and-vue" rel=''>Vite + Nuxt</a></li>
   <li><a href="https://intlayer.org/doc/environment/vite-and-solid" rel=''>Vite + Solid</a></li>
+  <li><a href="https://intlayer.org/doc/environment/solid-start" rel=''>Solid Start</a></li>
   <li><a href="https://intlayer.org/doc/environment/angular" rel=''>Angular</a></li>
   <li>
      <a href="https://intlayer.org/doc/environment/express" rel=''>Backend</a>
@@ -223,7 +224,9 @@ Explore our comprehensive documentation to get started with Intlayer and learn h
       <li><a href="https://intlayer.org/doc/environment/fastify" rel=''>Fastify</a></li>
       <li><a href="https://intlayer.org/doc/environment/adonisjs" rel=''>AdonisJS</a></li>
       <li><a href="https://intlayer.org/doc/environment/hono" rel=''>Hono</a></li>
+      <li><a href="https://intlayer.org/doc/environment/elysia" rel=''>Elysia</a></li>
     </ul>
+
   </li>
 </ul>
 </details>

package/dist/cjs/core/AnalyticsClient.cjs

@@ -1,7 +1,9 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_utils_isBot = require('../utils/isBot.cjs');
 const require_utils_idle = require('../utils/idle.cjs');
 const require_core_abTesting = require('./abTesting.cjs');
 const require_core_eventBuffer = require('./eventBuffer.cjs');
+const require_core_publicToken = require('./publicToken.cjs');
 const require_core_sampling = require('./sampling.cjs');
 const require_core_session = require('./session.cjs');
 const require_core_transport = require('./transport.cjs');
@@ -48,22 +50,33 @@ const referrerHost = () => {
 */
 const createAnalyticsClient = (config) => {
 	const sessionId = require_core_session.getSessionId();
-	const sampledIn = require_core_sampling.isSampledIn(sessionId, config.sampleRate);
+	const isBotSession = require_utils_isBot.isBotEnvironment();
+	const sampledIn = !isBotSession && require_core_sampling.isSampledIn(sessionId, config.sampleRate);
 	const buffer = require_core_eventBuffer.createEventBuffer({ max: config.maxBufferSize });
 	const endpoint = `${config.backendURL.replace(/\/$/, "")}/api/analytics/events`;
+	const publicToken = require_core_publicToken.createPublicTokenManager({
+		backendURL: config.backendURL,
+		clientId: config.clientId
+	});
 	let ambientLocale = "";
 	let flushTimer = null;
 	let started = false;
 	let detachListeners = null;
+	let lastPageViewUrl = null;
 	let seenExposureKeys = /* @__PURE__ */ new Set();
 	const flush = (useBeacon = false) => {
 		const events = buffer.drain();
+		const token = publicToken.getToken();
 		for (let start = 0; start < events.length; start += 200) require_core_transport.sendEvents(endpoint, {
-			clientId: config.clientId,
+			token,
+			clientId: token ? void 0 : config.clientId,
 			sessionId,
 			sdkVersion: SDK_VERSION,
 			events: events.slice(start, start + 200)
-		}, { useBeacon });
+		}, {
+			useBeacon,
+			token
+		});
 	};
 	/** Pushes an event and triggers an early flush if the buffer is full. */
 	const enqueue = (event) => {
@@ -74,16 +87,20 @@ const createAnalyticsClient = (config) => {
 	};
 	const trackPageView = (event = {}) => {
 		if (!sampledIn) return;
+		const url = event.url ?? currentUrl();
+		const reason = event.reason ?? "initial";
+		if (reason === "route_change" && url === lastPageViewUrl) return;
+		lastPageViewUrl = url;
 		seenExposureKeys = /* @__PURE__ */ new Set();
 		enqueue({
 			type: "page_view",
 			t: Date.now(),
-			url: event.url ?? currentUrl(),
+			url,
 			locale: event.locale ?? ambientLocale,
 			ref: event.ref ?? referrerHost(),
 			vw: event.vw ?? (typeof window !== "undefined" ? window.innerWidth : void 0),
 			vh: event.vh ?? (typeof window !== "undefined" ? window.innerHeight : void 0),
-			reason: event.reason ?? "initial"
+			reason
 		});
 	};
 	const trackContentExposure = (event) => {
@@ -107,6 +124,7 @@ const createAnalyticsClient = (config) => {
 		});
 	};
 	const trackConversion = (event) => {
+		if (isBotSession) return;
 		enqueue({
 			...event,
 			type: "conversion",
@@ -144,8 +162,9 @@ const createAnalyticsClient = (config) => {
 		};
 	};
 	const start = () => {
-		if (started) return;
+		if (started || isBotSession) return;
 		started = true;
+		publicToken.prime();
 		flushTimer = setInterval(flush, config.flushInterval);
 		flushTimer?.unref?.();
 		require_utils_idle.onIdle(attachListeners);

package/dist/cjs/core/AnalyticsClient.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"AnalyticsClient.cjs","names":["getSessionId","isSampledIn","createEventBuffer","assignVariant"],"sources":["../../../src/core/AnalyticsClient.ts"],"sourcesContent":["import { onIdle } from '../utils/idle';\nimport { assignVariant } from './abTesting';\nimport { createEventBuffer, type EventBuffer } from './eventBuffer';\nimport { isSampledIn } from './sampling';\nimport { getSessionId } from './session';\nimport { sendEvents } from './transport';\nimport type {\n  AnalyticsClientConfig,\n  AnalyticsEvent,\n  ContentExposureEvent,\n  ConversionEvent,\n  PageViewEvent,\n  TrackableEvent,\n} from './types';\n\n/**\n * Caller-supplied fields for a page view. Everything is optional — the client\n * fills `url`, `locale`, viewport, and referrer from the environment when omitted.\n */\nexport type PageViewInput = {\n  /** Explicit pathname / screen name (native runtimes have no `location`). */\n  url?: string;\n  /** Explicit locale; falls back to the client's ambient locale. */\n  locale?: string;\n  /** Referrer host override. */\n  ref?: string;\n  /** Viewport width override. */\n  vw?: number;\n  /** Viewport height override. */\n  vh?: number;\n  /** Why the view was recorded. */\n  reason?: PageViewEvent['reason'];\n};\n\n/** Default flush cadence — one network request per 20 seconds. */\nexport const DEFAULT_FLUSH_INTERVAL = 20_000;\n/** Default cap on distinct buffered events before an early flush. */\nexport const DEFAULT_MAX_BUFFER_SIZE = 500;\n/** Default sampling — keep every session. */\nexport const DEFAULT_SAMPLE_RATE = 1;\n/**\n * Maximum events per network request. `sendBeacon` and `fetch(keepalive)`\n * reject bodies over ~64KB, so large batches are split into multiple sends.\n */\nexport const MAX_EVENTS_PER_SEND = 200;\n/** Identifies the producing SDK in the ingest envelope. */\nconst SDK_VERSION = 'intlayer-analytics/1';\n\n/**\n * The public surface of the analytics client singleton. Framework bindings hold\n * a reference to this and forward provider/node/conversion signals into it.\n */\nexport type AnalyticsClient = {\n  /** Sets the ambient locale stamped onto subsequent events. */\n  setLocale: (locale: string) => void;\n  /** Records a page/locale view (provider level). */\n  trackPageView: (event?: PageViewInput) => void;\n  /** Records a content exposure (node level). Sampled + deduped per page view. */\n  trackContentExposure: (\n    event: Omit<TrackableEvent<ContentExposureEvent>, 'type'>\n  ) => void;\n  /** Records a conversion tied to an experiment variant. */\n  trackConversion: (\n    event: Omit<TrackableEvent<ConversionEvent>, 'type'>\n  ) => void;\n  /** Deterministically resolves this session's variant for an experiment. */\n  getVariant: (\n    experimentKey: string,\n    variants: string[],\n    weights?: number[]\n  ) => string;\n  /** Sends the buffered batch now. */\n  flush: (useBeacon?: boolean) => void;\n  /** Starts the flush loop and lifecycle listeners (idempotent). */\n  start: () => void;\n  /** Stops timers/listeners and flushes any remaining events. */\n  stop: () => void;\n};\n\n/**\n * Reads the current page pathname. Search params are intentionally excluded to\n * avoid capturing anything sensitive.\n */\nconst currentUrl = (): string => {\n  if (typeof window === 'undefined' || !window.location) return '';\n  return window.location.pathname;\n};\n\n/**\n * Reduces the referrer to its host — never the full URL — for privacy.\n */\nconst referrerHost = (): string | undefined => {\n  if (typeof document === 'undefined' || !document.referrer) return undefined;\n  try {\n    return new URL(document.referrer).host;\n  } catch {\n    return undefined;\n  }\n};\n\n/**\n * Creates an analytics client. Prefer {@link initAnalyticsClient} in application\n * code — it manages a shared singleton so there is only ever one flush timer.\n *\n * @param config - Resolved client configuration.\n * @returns A started-on-demand {@link AnalyticsClient}.\n */\nexport const createAnalyticsClient = (\n  config: AnalyticsClientConfig\n): AnalyticsClient => {\n  const sessionId = getSessionId();\n  const sampledIn = isSampledIn(sessionId, config.sampleRate);\n  const buffer: EventBuffer = createEventBuffer({ max: config.maxBufferSize });\n  const endpoint = `${config.backendURL.replace(/\\/$/, '')}/api/analytics/events`;\n\n  let ambientLocale = '';\n  let flushTimer: ReturnType<typeof setInterval> | null = null;\n  let started = false;\n  let detachListeners: (() => void) | null = null;\n\n  // Exposure keys already recorded for the current page view. React (and other\n  // frameworks) resolve content nodes on every re-render; without this gate a\n  // component re-rendering 60×/s would count 60 exposures per second. The set\n  // is cleared on each page view so the recorded semantic is \"shown at least\n  // once during this page view\".\n  let seenExposureKeys = new Set<string>();\n\n  const flush = (useBeacon = false): void => {\n    const events = buffer.drain();\n\n    // Split into bounded chunks so no single request exceeds transport limits.\n    for (let start = 0; start < events.length; start += MAX_EVENTS_PER_SEND) {\n      sendEvents(\n        endpoint,\n        {\n          clientId: config.clientId,\n          sessionId,\n          sdkVersion: SDK_VERSION,\n          events: events.slice(start, start + MAX_EVENTS_PER_SEND),\n        },\n        { useBeacon }\n      );\n    }\n  };\n\n  /** Pushes an event and triggers an early flush if the buffer is full. */\n  const enqueue = (event: AnalyticsEvent): void => {\n    const size = buffer.push(event);\n    if (size >= config.maxBufferSize) flush();\n  };\n\n  const setLocale = (locale: string): void => {\n    ambientLocale = locale;\n  };\n\n  const trackPageView: AnalyticsClient['trackPageView'] = (event = {}) => {\n    if (!sampledIn) return;\n\n    // A new page view starts a fresh exposure window.\n    seenExposureKeys = new Set<string>();\n\n    enqueue({\n      type: 'page_view',\n      t: Date.now(),\n      url: event.url ?? currentUrl(),\n      locale: event.locale ?? ambientLocale,\n      ref: event.ref ?? referrerHost(),\n      vw:\n        event.vw ??\n        (typeof window !== 'undefined' ? window.innerWidth : undefined),\n      vh:\n        event.vh ??\n        (typeof window !== 'undefined' ? window.innerHeight : undefined),\n      reason: event.reason ?? 'initial',\n    });\n  };\n\n  const trackContentExposure: AnalyticsClient['trackContentExposure'] = (\n    event\n  ) => {\n    if (!sampledIn) return;\n\n    const locale = event.locale ?? ambientLocale;\n    // Joined with \\x01 (never present in content keys) so parts cannot collide.\n    const exposureKey = [\n      event.dictionaryKey,\n      event.keyPath,\n      locale,\n      event.experimentKey ?? '',\n      event.variant ?? '',\n    ].join('\u0001');\n\n    // Deduplicate within the current page view (see `seenExposureKeys`).\n    if (seenExposureKeys.has(exposureKey)) return;\n    seenExposureKeys.add(exposureKey);\n\n    enqueue({\n      ...event,\n      type: 'content_exposure',\n      t: Date.now(),\n      url: currentUrl(),\n      locale,\n    });\n  };\n\n  const trackConversion: AnalyticsClient['trackConversion'] = (event) => {\n    // Conversions are never sampled out — they are rare and decisive for A/B.\n    enqueue({\n      ...event,\n      type: 'conversion',\n      t: Date.now(),\n      url: currentUrl(),\n      locale: event.locale ?? ambientLocale,\n    });\n    // Flush conversions promptly so they are not lost on immediate navigation.\n    flush();\n  };\n\n  const getVariant: AnalyticsClient['getVariant'] = (\n    experimentKey,\n    variants,\n    weights\n  ) => assignVariant(sessionId, experimentKey, variants, weights);\n\n  /** Attaches lifecycle + SPA-navigation listeners without blocking render. */\n  const attachListeners = (): void => {\n    if (typeof window === 'undefined') return;\n\n    const onHidden = (): void => {\n      if (document.visibilityState === 'hidden') flush(true);\n    };\n    const onPageHide = (): void => flush(true);\n    const onPopState = (): void => trackPageView({ reason: 'route_change' });\n\n    document.addEventListener('visibilitychange', onHidden);\n    window.addEventListener('pagehide', onPageHide, { capture: true });\n    window.addEventListener('popstate', onPopState);\n\n    // Patch history.pushState so client-side route changes emit a page view.\n    // `replaceState` is intentionally left untouched: routers use it for\n    // same-page URL sync (scroll, params), which is not a navigation.\n    const history = window.history;\n    const originalPush = history.pushState;\n\n    const patchedPushState = function patchedPush(\n      this: History,\n      ...args: Parameters<History['pushState']>\n    ) {\n      const result = originalPush.apply(this, args);\n      trackPageView({ reason: 'route_change' });\n      return result;\n    };\n    history.pushState = patchedPushState;\n\n    detachListeners = (): void => {\n      document.removeEventListener('visibilitychange', onHidden);\n      window.removeEventListener('pagehide', onPageHide, { capture: true });\n      window.removeEventListener('popstate', onPopState);\n      // Only restore if nothing else re-patched pushState after us; restoring\n      // blindly would clobber another library's wrapper.\n      if (history.pushState === patchedPushState) {\n        history.pushState = originalPush;\n      }\n    };\n  };\n\n  const start = (): void => {\n    if (started) return;\n    started = true;\n\n    flushTimer = setInterval(flush, config.flushInterval);\n    // Some runtimes (Node during SSR) keep the process alive on timers.\n    (flushTimer as { unref?: () => void })?.unref?.();\n\n    onIdle(attachListeners);\n  };\n\n  const stop = (): void => {\n    if (!started) return;\n    started = false;\n\n    if (flushTimer) {\n      clearInterval(flushTimer);\n      flushTimer = null;\n    }\n    detachListeners?.();\n    detachListeners = null;\n    flush(true);\n  };\n\n  return {\n    setLocale,\n    trackPageView,\n    trackContentExposure,\n    trackConversion,\n    getVariant,\n    flush,\n    start,\n    stop,\n  };\n};\n"],"mappings":"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"}
+{"version":3,"file":"AnalyticsClient.cjs","names":["getSessionId","isBotEnvironment","isSampledIn","createEventBuffer","createPublicTokenManager","assignVariant"],"sources":["../../../src/core/AnalyticsClient.ts"],"sourcesContent":["import { onIdle } from '../utils/idle';\nimport { isBotEnvironment } from '../utils/isBot';\nimport { assignVariant } from './abTesting';\nimport { createEventBuffer, type EventBuffer } from './eventBuffer';\nimport { createPublicTokenManager } from './publicToken';\nimport { isSampledIn } from './sampling';\nimport { getSessionId } from './session';\nimport { sendEvents } from './transport';\nimport type {\n  AnalyticsClientConfig,\n  AnalyticsEvent,\n  ContentExposureEvent,\n  ConversionEvent,\n  PageViewEvent,\n  TrackableEvent,\n} from './types';\n\n/**\n * Caller-supplied fields for a page view. Everything is optional — the client\n * fills `url`, `locale`, viewport, and referrer from the environment when omitted.\n */\nexport type PageViewInput = {\n  /** Explicit pathname / screen name (native runtimes have no `location`). */\n  url?: string;\n  /** Explicit locale; falls back to the client's ambient locale. */\n  locale?: string;\n  /** Referrer host override. */\n  ref?: string;\n  /** Viewport width override. */\n  vw?: number;\n  /** Viewport height override. */\n  vh?: number;\n  /** Why the view was recorded. */\n  reason?: PageViewEvent['reason'];\n};\n\n/** Default flush cadence — one network request per 20 seconds. */\nexport const DEFAULT_FLUSH_INTERVAL = 20_000;\n/** Default cap on distinct buffered events before an early flush. */\nexport const DEFAULT_MAX_BUFFER_SIZE = 500;\n/** Default sampling — keep every session. */\nexport const DEFAULT_SAMPLE_RATE = 1;\n/**\n * Maximum events per network request. `sendBeacon` and `fetch(keepalive)`\n * reject bodies over ~64KB, so large batches are split into multiple sends.\n */\nexport const MAX_EVENTS_PER_SEND = 200;\n/** Identifies the producing SDK in the ingest envelope. */\nconst SDK_VERSION = 'intlayer-analytics/1';\n\n/**\n * The public surface of the analytics client singleton. Framework bindings hold\n * a reference to this and forward provider/node/conversion signals into it.\n */\nexport type AnalyticsClient = {\n  /** Sets the ambient locale stamped onto subsequent events. */\n  setLocale: (locale: string) => void;\n  /** Records a page/locale view (provider level). */\n  trackPageView: (event?: PageViewInput) => void;\n  /** Records a content exposure (node level). Sampled + deduped per page view. */\n  trackContentExposure: (\n    event: Omit<TrackableEvent<ContentExposureEvent>, 'type'>\n  ) => void;\n  /** Records a conversion tied to an experiment variant. */\n  trackConversion: (\n    event: Omit<TrackableEvent<ConversionEvent>, 'type'>\n  ) => void;\n  /** Deterministically resolves this session's variant for an experiment. */\n  getVariant: (\n    experimentKey: string,\n    variants: string[],\n    weights?: number[]\n  ) => string;\n  /** Sends the buffered batch now. */\n  flush: (useBeacon?: boolean) => void;\n  /** Starts the flush loop and lifecycle listeners (idempotent). */\n  start: () => void;\n  /** Stops timers/listeners and flushes any remaining events. */\n  stop: () => void;\n};\n\n/**\n * Reads the current page pathname. Search params are intentionally excluded to\n * avoid capturing anything sensitive.\n */\nconst currentUrl = (): string => {\n  if (typeof window === 'undefined' || !window.location) return '';\n  return window.location.pathname;\n};\n\n/**\n * Reduces the referrer to its host — never the full URL — for privacy.\n */\nconst referrerHost = (): string | undefined => {\n  if (typeof document === 'undefined' || !document.referrer) return undefined;\n  try {\n    return new URL(document.referrer).host;\n  } catch {\n    return undefined;\n  }\n};\n\n/**\n * Creates an analytics client. Prefer {@link initAnalyticsClient} in application\n * code — it manages a shared singleton so there is only ever one flush timer.\n *\n * @param config - Resolved client configuration.\n * @returns A started-on-demand {@link AnalyticsClient}.\n */\nexport const createAnalyticsClient = (\n  config: AnalyticsClientConfig\n): AnalyticsClient => {\n  const sessionId = getSessionId();\n  // Crawlers, link-preview fetchers and headless runtimes execute JavaScript,\n  // so they reach this point like any visitor. Detected once at creation: the\n  // client then buffers nothing, sends nothing and never starts its timers.\n  const isBotSession = isBotEnvironment();\n  const sampledIn = !isBotSession && isSampledIn(sessionId, config.sampleRate);\n  const buffer: EventBuffer = createEventBuffer({ max: config.maxBufferSize });\n  const endpoint = `${config.backendURL.replace(/\\/$/, '')}/api/analytics/events`;\n  const publicToken = createPublicTokenManager({\n    backendURL: config.backendURL,\n    clientId: config.clientId,\n  });\n\n  let ambientLocale = '';\n  let flushTimer: ReturnType<typeof setInterval> | null = null;\n  let started = false;\n  let detachListeners: (() => void) | null = null;\n\n  // Path of the most recent page view, so an automatic route-change signal for\n  // a page already recorded is ignored. Routers call `pushState` for\n  // query-only and hash-only updates (filters, tabs, modals, scroll sync),\n  // each of which would otherwise land as another view of the same page.\n  let lastPageViewUrl: string | null = null;\n\n  // Exposure keys already recorded for the current page view. React (and other\n  // frameworks) resolve content nodes on every re-render; without this gate a\n  // component re-rendering 60×/s would count 60 exposures per second. The set\n  // is cleared on each page view so the recorded semantic is \"shown at least\n  // once during this page view\".\n  let seenExposureKeys = new Set<string>();\n\n  const flush = (useBeacon = false): void => {\n    const events = buffer.drain();\n\n    // Read synchronously: the flush-on-hide path runs during `pagehide` and\n    // cannot await the exchange. Until it resolves, the public `clientId` is\n    // sent instead so the first batch of a visit is still attributed.\n    const token = publicToken.getToken();\n\n    // Split into bounded chunks so no single request exceeds transport limits.\n    for (let start = 0; start < events.length; start += MAX_EVENTS_PER_SEND) {\n      sendEvents(\n        endpoint,\n        {\n          token,\n          clientId: token ? undefined : config.clientId,\n          sessionId,\n          sdkVersion: SDK_VERSION,\n          events: events.slice(start, start + MAX_EVENTS_PER_SEND),\n        },\n        { useBeacon, token }\n      );\n    }\n  };\n\n  /** Pushes an event and triggers an early flush if the buffer is full. */\n  const enqueue = (event: AnalyticsEvent): void => {\n    const size = buffer.push(event);\n    if (size >= config.maxBufferSize) flush();\n  };\n\n  const setLocale = (locale: string): void => {\n    ambientLocale = locale;\n  };\n\n  const trackPageView: AnalyticsClient['trackPageView'] = (event = {}) => {\n    if (!sampledIn) return;\n\n    const url = event.url ?? currentUrl();\n    const reason = event.reason ?? 'initial';\n\n    // Only the automatic navigation signal is deduplicated: a provider asking\n    // for an `initial` or `locale_change` view is reporting something the\n    // pathname alone cannot express.\n    if (reason === 'route_change' && url === lastPageViewUrl) return;\n    lastPageViewUrl = url;\n\n    // A new page view starts a fresh exposure window.\n    seenExposureKeys = new Set<string>();\n\n    enqueue({\n      type: 'page_view',\n      t: Date.now(),\n      url,\n      locale: event.locale ?? ambientLocale,\n      ref: event.ref ?? referrerHost(),\n      vw:\n        event.vw ??\n        (typeof window !== 'undefined' ? window.innerWidth : undefined),\n      vh:\n        event.vh ??\n        (typeof window !== 'undefined' ? window.innerHeight : undefined),\n      reason,\n    });\n  };\n\n  const trackContentExposure: AnalyticsClient['trackContentExposure'] = (\n    event\n  ) => {\n    if (!sampledIn) return;\n\n    const locale = event.locale ?? ambientLocale;\n    // Joined with \\x01 (never present in content keys) so parts cannot collide.\n    const exposureKey = [\n      event.dictionaryKey,\n      event.keyPath,\n      locale,\n      event.experimentKey ?? '',\n      event.variant ?? '',\n    ].join('\u0001');\n\n    // Deduplicate within the current page view (see `seenExposureKeys`).\n    if (seenExposureKeys.has(exposureKey)) return;\n    seenExposureKeys.add(exposureKey);\n\n    enqueue({\n      ...event,\n      type: 'content_exposure',\n      t: Date.now(),\n      url: currentUrl(),\n      locale,\n    });\n  };\n\n  const trackConversion: AnalyticsClient['trackConversion'] = (event) => {\n    // Conversions are never sampled out — they are rare and decisive for A/B —\n    // but bot traffic is still excluded, or it would skew every variant rate.\n    if (isBotSession) return;\n\n    enqueue({\n      ...event,\n      type: 'conversion',\n      t: Date.now(),\n      url: currentUrl(),\n      locale: event.locale ?? ambientLocale,\n    });\n    // Flush conversions promptly so they are not lost on immediate navigation.\n    flush();\n  };\n\n  const getVariant: AnalyticsClient['getVariant'] = (\n    experimentKey,\n    variants,\n    weights\n  ) => assignVariant(sessionId, experimentKey, variants, weights);\n\n  /** Attaches lifecycle + SPA-navigation listeners without blocking render. */\n  const attachListeners = (): void => {\n    if (typeof window === 'undefined') return;\n\n    const onHidden = (): void => {\n      if (document.visibilityState === 'hidden') flush(true);\n    };\n    const onPageHide = (): void => flush(true);\n    const onPopState = (): void => trackPageView({ reason: 'route_change' });\n\n    document.addEventListener('visibilitychange', onHidden);\n    window.addEventListener('pagehide', onPageHide, { capture: true });\n    window.addEventListener('popstate', onPopState);\n\n    // Patch history.pushState so client-side route changes emit a page view.\n    // `replaceState` is intentionally left untouched: routers use it for\n    // same-page URL sync (scroll, params), which is not a navigation.\n    const history = window.history;\n    const originalPush = history.pushState;\n\n    const patchedPushState = function patchedPush(\n      this: History,\n      ...args: Parameters<History['pushState']>\n    ) {\n      const result = originalPush.apply(this, args);\n      trackPageView({ reason: 'route_change' });\n      return result;\n    };\n    history.pushState = patchedPushState;\n\n    detachListeners = (): void => {\n      document.removeEventListener('visibilitychange', onHidden);\n      window.removeEventListener('pagehide', onPageHide, { capture: true });\n      window.removeEventListener('popstate', onPopState);\n      // Only restore if nothing else re-patched pushState after us; restoring\n      // blindly would clobber another library's wrapper.\n      if (history.pushState === patchedPushState) {\n        history.pushState = originalPush;\n      }\n    };\n  };\n\n  const start = (): void => {\n    if (started || isBotSession) return;\n    started = true;\n\n    // Exchanged ahead of the first flush so a token is already cached by the\n    // time a batch — including one sent during `pagehide` — goes out.\n    publicToken.prime();\n\n    flushTimer = setInterval(flush, config.flushInterval);\n    // Some runtimes (Node during SSR) keep the process alive on timers.\n    (flushTimer as { unref?: () => void })?.unref?.();\n\n    onIdle(attachListeners);\n  };\n\n  const stop = (): void => {\n    if (!started) return;\n    started = false;\n\n    if (flushTimer) {\n      clearInterval(flushTimer);\n      flushTimer = null;\n    }\n    detachListeners?.();\n    detachListeners = null;\n    flush(true);\n  };\n\n  return {\n    setLocale,\n    trackPageView,\n    trackContentExposure,\n    trackConversion,\n    getVariant,\n    flush,\n    start,\n    stop,\n  };\n};\n"],"mappings":"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"}

package/dist/cjs/core/publicToken.cjs

@@ -0,0 +1,104 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+//#region src/core/publicToken.ts
+/**
+* Short-lived ingest token used to authorise analytics batches.
+*
+* The SDK runs in the browser, where no confidential credential can be kept, so
+* it exchanges the project's **public** `clientId` for a token scoped to
+* analytics ingestion and nothing else. The backend authorises the exchange by
+* the request's `Origin`, which the page cannot forge.
+*
+* The token is read synchronously at flush time — the flush-on-hide path runs
+* during `pagehide` and cannot await anything — so it is fetched ahead of time
+* and cached, both in memory and in `sessionStorage` so a multi-page visit
+* exchanges once per tab rather than once per navigation.
+*/
+/** `sessionStorage` key holding the cached token for this tab. */
+const TOKEN_STORAGE_KEY = "__intlayer_public_token__";
+/**
+* Refresh margin: a token within this window of expiry is treated as expired,
+* so a batch is never sent with a token that dies in flight.
+*/
+const EXPIRY_MARGIN_MS = 6e4;
+/** Reads the cached token for this tab, ignoring an unusable cache. */
+const readStoredToken = () => {
+	try {
+		const raw = window.sessionStorage?.getItem(TOKEN_STORAGE_KEY);
+		if (!raw) return null;
+		const parsed = JSON.parse(raw);
+		if (typeof parsed?.token !== "string") return null;
+		if (typeof parsed?.expiresAt !== "number") return null;
+		return parsed;
+	} catch {
+		return null;
+	}
+};
+/** Persists the token for this tab. Best-effort: storage may be unavailable. */
+const writeStoredToken = (cached) => {
+	try {
+		window.sessionStorage?.setItem(TOKEN_STORAGE_KEY, JSON.stringify(cached));
+	} catch {}
+};
+/**
+* Creates the ingest token manager for a project.
+*
+* Every failure path is silent: analytics must never break, slow, or log noise
+* into the host application. Without a token the client falls back to sending
+* its public `clientId`, which the backend still accepts.
+*
+* @param options - Backend URL and the public project key.
+* @returns A manager exposing a synchronous {@link PublicTokenManager.getToken}.
+*/
+const createPublicTokenManager = ({ backendURL, clientId }) => {
+	const endpoint = `${backendURL.replace(/\/$/, "")}/api/public/token`;
+	let cached = null;
+	let pendingExchange = null;
+	const isUsable = (candidate) => candidate !== null && candidate.expiresAt - EXPIRY_MARGIN_MS > Date.now();
+	const getToken = () => {
+		if (isUsable(cached)) return cached.token;
+		if (typeof window !== "undefined") {
+			const stored = readStoredToken();
+			if (isUsable(stored)) {
+				cached = stored;
+				return stored.token;
+			}
+		}
+	};
+	const exchange = async () => {
+		try {
+			const response = await fetch(endpoint, {
+				method: "POST",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify({ clientId }),
+				credentials: "omit",
+				mode: "cors"
+			});
+			if (!response.ok) return;
+			const payload = await response.json();
+			const token = payload?.data?.token;
+			const expiresIn = payload?.data?.expiresIn ?? 0;
+			if (!token || expiresIn <= 0) return;
+			cached = {
+				token,
+				expiresAt: Date.now() + expiresIn * 1e3
+			};
+			if (typeof window !== "undefined") writeStoredToken(cached);
+		} catch {} finally {
+			pendingExchange = null;
+		}
+	};
+	const prime = () => {
+		if (!clientId || typeof fetch !== "function") return;
+		if (getToken()) return;
+		if (pendingExchange) return;
+		pendingExchange = exchange();
+	};
+	return {
+		getToken,
+		prime
+	};
+};
+
+//#endregion
+exports.createPublicTokenManager = createPublicTokenManager;
+//# sourceMappingURL=publicToken.cjs.map

package/dist/cjs/core/publicToken.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"publicToken.cjs","names":[],"sources":["../../../src/core/publicToken.ts"],"sourcesContent":["/**\n * Short-lived ingest token used to authorise analytics batches.\n *\n * The SDK runs in the browser, where no confidential credential can be kept, so\n * it exchanges the project's **public** `clientId` for a token scoped to\n * analytics ingestion and nothing else. The backend authorises the exchange by\n * the request's `Origin`, which the page cannot forge.\n *\n * The token is read synchronously at flush time — the flush-on-hide path runs\n * during `pagehide` and cannot await anything — so it is fetched ahead of time\n * and cached, both in memory and in `sessionStorage` so a multi-page visit\n * exchanges once per tab rather than once per navigation.\n */\n\n/** `sessionStorage` key holding the cached token for this tab. */\nconst TOKEN_STORAGE_KEY = '__intlayer_public_token__';\n\n/**\n * Refresh margin: a token within this window of expiry is treated as expired,\n * so a batch is never sent with a token that dies in flight.\n */\nconst EXPIRY_MARGIN_MS = 60 * 1000;\n\ntype CachedToken = {\n  token: string;\n  /** Epoch milliseconds. */\n  expiresAt: number;\n};\n\n/** Reads the cached token for this tab, ignoring an unusable cache. */\nconst readStoredToken = (): CachedToken | null => {\n  try {\n    const raw = window.sessionStorage?.getItem(TOKEN_STORAGE_KEY);\n    if (!raw) return null;\n\n    const parsed = JSON.parse(raw) as CachedToken;\n\n    if (typeof parsed?.token !== 'string') return null;\n    if (typeof parsed?.expiresAt !== 'number') return null;\n\n    return parsed;\n  } catch {\n    // Private mode, disabled storage, or corrupted entry — start fresh.\n    return null;\n  }\n};\n\n/** Persists the token for this tab. Best-effort: storage may be unavailable. */\nconst writeStoredToken = (cached: CachedToken): void => {\n  try {\n    window.sessionStorage?.setItem(TOKEN_STORAGE_KEY, JSON.stringify(cached));\n  } catch {\n    /* ignore — the in-memory cache still applies for this page */\n  }\n};\n\n/** Options accepted by {@link createPublicTokenManager}. */\nexport type PublicTokenManagerOptions = {\n  /** Backend base URL, without a trailing slash. */\n  backendURL: string;\n  /** The project's public key (`editor.clientId`). */\n  clientId?: string;\n};\n\n/** Synchronous accessor + background refresher for the ingest token. */\nexport type PublicTokenManager = {\n  /**\n   * The currently valid token, or `undefined` when none has been obtained yet.\n   * Never blocks and never triggers a request.\n   */\n  getToken: () => string | undefined;\n  /**\n   * Ensures a valid token is being fetched. Safe to call repeatedly:\n   * concurrent calls share a single in-flight exchange.\n   */\n  prime: () => void;\n};\n\n/**\n * Creates the ingest token manager for a project.\n *\n * Every failure path is silent: analytics must never break, slow, or log noise\n * into the host application. Without a token the client falls back to sending\n * its public `clientId`, which the backend still accepts.\n *\n * @param options - Backend URL and the public project key.\n * @returns A manager exposing a synchronous {@link PublicTokenManager.getToken}.\n */\nexport const createPublicTokenManager = ({\n  backendURL,\n  clientId,\n}: PublicTokenManagerOptions): PublicTokenManager => {\n  const endpoint = `${backendURL.replace(/\\/$/, '')}/api/public/token`;\n\n  let cached: CachedToken | null = null;\n  let pendingExchange: Promise<void> | null = null;\n\n  const isUsable = (candidate: CachedToken | null): candidate is CachedToken =>\n    candidate !== null && candidate.expiresAt - EXPIRY_MARGIN_MS > Date.now();\n\n  const getToken = (): string | undefined => {\n    if (isUsable(cached)) return cached.token;\n\n    if (typeof window !== 'undefined') {\n      const stored = readStoredToken();\n      if (isUsable(stored)) {\n        cached = stored;\n        return stored.token;\n      }\n    }\n\n    return undefined;\n  };\n\n  const exchange = async (): Promise<void> => {\n    try {\n      const response = await fetch(endpoint, {\n        method: 'POST',\n        headers: { 'Content-Type': 'application/json' },\n        body: JSON.stringify({ clientId }),\n        // The exchange is authorised by `Origin`, never by cookies.\n        credentials: 'omit',\n        mode: 'cors',\n      });\n\n      if (!response.ok) return;\n\n      const payload = (await response.json()) as {\n        data?: { token?: string | null; expiresIn?: number };\n      };\n\n      const token = payload?.data?.token;\n      const expiresIn = payload?.data?.expiresIn ?? 0;\n\n      // A `null` token means the key is unknown or the origin is not allowed.\n      if (!token || expiresIn <= 0) return;\n\n      cached = { token, expiresAt: Date.now() + expiresIn * 1000 };\n\n      if (typeof window !== 'undefined') writeStoredToken(cached);\n    } catch {\n      /* swallow — best-effort, the `clientId` fallback still reports */\n    } finally {\n      pendingExchange = null;\n    }\n  };\n\n  const prime = (): void => {\n    if (!clientId || typeof fetch !== 'function') return;\n    if (getToken()) return;\n    if (pendingExchange) return;\n\n    pendingExchange = exchange();\n  };\n\n  return { getToken, prime };\n};\n"],"mappings":";;;;;;;;;;;;;;;;AAeA,MAAM,oBAAoB;;;;;AAM1B,MAAM,mBAAmB;;AASzB,MAAM,wBAA4C;CAChD,IAAI;EACF,MAAM,MAAM,OAAO,gBAAgB,QAAQ,iBAAiB;EAC5D,IAAI,CAAC,KAAK,OAAO;EAEjB,MAAM,SAAS,KAAK,MAAM,GAAG;EAE7B,IAAI,OAAO,QAAQ,UAAU,UAAU,OAAO;EAC9C,IAAI,OAAO,QAAQ,cAAc,UAAU,OAAO;EAElD,OAAO;CACT,QAAQ;EAEN,OAAO;CACT;AACF;;AAGA,MAAM,oBAAoB,WAA8B;CACtD,IAAI;EACF,OAAO,gBAAgB,QAAQ,mBAAmB,KAAK,UAAU,MAAM,CAAC;CAC1E,QAAQ,CAER;AACF;;;;;;;;;;;AAkCA,MAAa,4BAA4B,EACvC,YACA,eACmD;CACnD,MAAM,WAAW,GAAG,WAAW,QAAQ,OAAO,EAAE,EAAE;CAElD,IAAI,SAA6B;CACjC,IAAI,kBAAwC;CAE5C,MAAM,YAAY,cAChB,cAAc,QAAQ,UAAU,YAAY,mBAAmB,KAAK,IAAI;CAE1E,MAAM,iBAAqC;EACzC,IAAI,SAAS,MAAM,GAAG,OAAO,OAAO;EAEpC,IAAI,OAAO,WAAW,aAAa;GACjC,MAAM,SAAS,gBAAgB;GAC/B,IAAI,SAAS,MAAM,GAAG;IACpB,SAAS;IACT,OAAO,OAAO;GAChB;EACF;CAGF;CAEA,MAAM,WAAW,YAA2B;EAC1C,IAAI;GACF,MAAM,WAAW,MAAM,MAAM,UAAU;IACrC,QAAQ;IACR,SAAS,EAAE,gBAAgB,mBAAmB;IAC9C,MAAM,KAAK,UAAU,EAAE,SAAS,CAAC;IAEjC,aAAa;IACb,MAAM;GACR,CAAC;GAED,IAAI,CAAC,SAAS,IAAI;GAElB,MAAM,UAAW,MAAM,SAAS,KAAK;GAIrC,MAAM,QAAQ,SAAS,MAAM;GAC7B,MAAM,YAAY,SAAS,MAAM,aAAa;GAG9C,IAAI,CAAC,SAAS,aAAa,GAAG;GAE9B,SAAS;IAAE;IAAO,WAAW,KAAK,IAAI,IAAI,YAAY;GAAK;GAE3D,IAAI,OAAO,WAAW,aAAa,iBAAiB,MAAM;EAC5D,QAAQ,CAER,UAAU;GACR,kBAAkB;EACpB;CACF;CAEA,MAAM,cAAoB;EACxB,IAAI,CAAC,YAAY,OAAO,UAAU,YAAY;EAC9C,IAAI,SAAS,GAAG;EAChB,IAAI,iBAAiB;EAErB,kBAAkB,SAAS;CAC7B;CAEA,OAAO;EAAE;EAAU;CAAM;AAC3B"}

package/dist/cjs/core/transport.cjs

@@ -18,16 +18,22 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 * @param body - The batched payload.
 * @param options - Transport options.
 * @param options.useBeacon - Prefer `sendBeacon` (used when the page is hiding).
+* @param options.token - Ingest token, sent as a bearer on the `fetch` path.
+*   `sendBeacon` cannot set headers, which is why the token is also carried in
+*   the body.
 * @returns `true` when a send was dispatched, `false` otherwise.
 */
-const sendEvents = (endpoint, body, { useBeacon = false } = {}) => {
+const sendEvents = (endpoint, body, { useBeacon = false, token } = {}) => {
 	try {
 		const payload = JSON.stringify(body);
 		if (useBeacon && typeof navigator !== "undefined" && typeof navigator.sendBeacon === "function") return navigator.sendBeacon(endpoint, payload);
 		if (typeof fetch === "function") {
 			fetch(endpoint, {
 				method: "POST",
-				headers: { "Content-Type": "application/json" },
+				headers: {
+					"Content-Type": "application/json",
+					...token ? { Authorization: `Bearer ${token}` } : {}
+				},
 				body: payload,
 				keepalive: true,
 				credentials: "omit",

package/dist/cjs/core/transport.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"transport.cjs","names":[],"sources":["../../../src/core/transport.ts"],"sourcesContent":["import type { AnalyticsIngestBody } from './types';\n\n/**\n * Sends a batch of events to the backend. Every path is non-blocking and\n * no-throw — analytics must never break, slow, or delay the host application.\n *\n * Strategy:\n * 1. `navigator.sendBeacon` for the flush-on-hide path — survives page unload\n *    and never blocks navigation. The payload is sent as `text/plain` (a\n *    CORS-safelisted content type): a JSON `Blob` would require a CORS\n *    preflight that browsers handle inconsistently during unload, silently\n *    dropping the beacon. The backend parses `text/plain` bodies as JSON.\n * 2. `fetch(..., { keepalive: true })` for interval flushes — survives short\n *    navigations without holding the main thread.\n * 3. Plain `fetch` fallback for runtimes without `keepalive` (older RN/Lynx).\n *\n * @param endpoint - Fully-qualified ingestion URL.\n * @param body - The batched payload.\n * @param options - Transport options.\n * @param options.useBeacon - Prefer `sendBeacon` (used when the page is hiding).\n * @returns `true` when a send was dispatched, `false` otherwise.\n */\nexport const sendEvents = (\n  endpoint: string,\n  body: AnalyticsIngestBody,\n  { useBeacon = false }: { useBeacon?: boolean } = {}\n): boolean => {\n  try {\n    const payload = JSON.stringify(body);\n\n    if (\n      useBeacon &&\n      typeof navigator !== 'undefined' &&\n      typeof navigator.sendBeacon === 'function'\n    ) {\n      // Note: unlike the fetch path below, sendBeacon always includes\n      // credentials; the ingest endpoint ignores them.\n      return navigator.sendBeacon(endpoint, payload);\n    }\n\n    if (typeof fetch === 'function') {\n      // keepalive lets the request outlive a same-tab navigation.\n      void fetch(endpoint, {\n        method: 'POST',\n        headers: { 'Content-Type': 'application/json' },\n        body: payload,\n        keepalive: true,\n        // Analytics is best-effort; never send credentials.\n        credentials: 'omit',\n        mode: 'cors',\n      }).catch(() => {\n        /* swallow — best-effort delivery */\n      });\n      return true;\n    }\n\n    return false;\n  } catch {\n    // JSON serialization failed — drop the batch silently.\n    return false;\n  }\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAsBA,MAAa,cACX,UACA,MACA,EAAE,YAAY,UAAmC,CAAC,MACtC;CACZ,IAAI;EACF,MAAM,UAAU,KAAK,UAAU,IAAI;EAEnC,IACE,aACA,OAAO,cAAc,eACrB,OAAO,UAAU,eAAe,YAIhC,OAAO,UAAU,WAAW,UAAU,OAAO;EAG/C,IAAI,OAAO,UAAU,YAAY;GAE/B,AAAK,MAAM,UAAU;IACnB,QAAQ;IACR,SAAS,EAAE,gBAAgB,mBAAmB;IAC9C,MAAM;IACN,WAAW;IAEX,aAAa;IACb,MAAM;GACR,CAAC,CAAC,CAAC,YAAY,CAEf,CAAC;GACD,OAAO;EACT;EAEA,OAAO;CACT,QAAQ;EAEN,OAAO;CACT;AACF"}
+{"version":3,"file":"transport.cjs","names":[],"sources":["../../../src/core/transport.ts"],"sourcesContent":["import type { AnalyticsIngestBody } from './types';\n\n/**\n * Sends a batch of events to the backend. Every path is non-blocking and\n * no-throw — analytics must never break, slow, or delay the host application.\n *\n * Strategy:\n * 1. `navigator.sendBeacon` for the flush-on-hide path — survives page unload\n *    and never blocks navigation. The payload is sent as `text/plain` (a\n *    CORS-safelisted content type): a JSON `Blob` would require a CORS\n *    preflight that browsers handle inconsistently during unload, silently\n *    dropping the beacon. The backend parses `text/plain` bodies as JSON.\n * 2. `fetch(..., { keepalive: true })` for interval flushes — survives short\n *    navigations without holding the main thread.\n * 3. Plain `fetch` fallback for runtimes without `keepalive` (older RN/Lynx).\n *\n * @param endpoint - Fully-qualified ingestion URL.\n * @param body - The batched payload.\n * @param options - Transport options.\n * @param options.useBeacon - Prefer `sendBeacon` (used when the page is hiding).\n * @param options.token - Ingest token, sent as a bearer on the `fetch` path.\n *   `sendBeacon` cannot set headers, which is why the token is also carried in\n *   the body.\n * @returns `true` when a send was dispatched, `false` otherwise.\n */\nexport const sendEvents = (\n  endpoint: string,\n  body: AnalyticsIngestBody,\n  { useBeacon = false, token }: { useBeacon?: boolean; token?: string } = {}\n): boolean => {\n  try {\n    const payload = JSON.stringify(body);\n\n    if (\n      useBeacon &&\n      typeof navigator !== 'undefined' &&\n      typeof navigator.sendBeacon === 'function'\n    ) {\n      // Note: unlike the fetch path below, sendBeacon always includes\n      // credentials; the ingest endpoint ignores them.\n      return navigator.sendBeacon(endpoint, payload);\n    }\n\n    if (typeof fetch === 'function') {\n      // keepalive lets the request outlive a same-tab navigation.\n      void fetch(endpoint, {\n        method: 'POST',\n        headers: {\n          'Content-Type': 'application/json',\n          ...(token ? { Authorization: `Bearer ${token}` } : {}),\n        },\n        body: payload,\n        keepalive: true,\n        // Analytics is best-effort; never send credentials.\n        credentials: 'omit',\n        mode: 'cors',\n      }).catch(() => {\n        /* swallow — best-effort delivery */\n      });\n      return true;\n    }\n\n    return false;\n  } catch {\n    // JSON serialization failed — drop the batch silently.\n    return false;\n  }\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,MAAa,cACX,UACA,MACA,EAAE,YAAY,OAAO,UAAmD,CAAC,MAC7D;CACZ,IAAI;EACF,MAAM,UAAU,KAAK,UAAU,IAAI;EAEnC,IACE,aACA,OAAO,cAAc,eACrB,OAAO,UAAU,eAAe,YAIhC,OAAO,UAAU,WAAW,UAAU,OAAO;EAG/C,IAAI,OAAO,UAAU,YAAY;GAE/B,AAAK,MAAM,UAAU;IACnB,QAAQ;IACR,SAAS;KACP,gBAAgB;KAChB,GAAI,QAAQ,EAAE,eAAe,UAAU,QAAQ,IAAI,CAAC;IACtD;IACA,MAAM;IACN,WAAW;IAEX,aAAa;IACb,MAAM;GACR,CAAC,CAAC,CAAC,YAAY,CAEf,CAAC;GACD,OAAO;EACT;EAEA,OAAO;CACT,QAAQ;EAEN,OAAO;CACT;AACF"}

package/dist/cjs/index.cjs

@@ -1,4 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_utils_isBot = require('./utils/isBot.cjs');
 const require_core_abTesting = require('./core/abTesting.cjs');
 const require_core_eventBuffer = require('./core/eventBuffer.cjs');
 const require_core_sampling = require('./core/sampling.cjs');
@@ -9,6 +10,7 @@ const require_core_globalManager = require('./core/globalManager.cjs');
 const require_core_initAnalyticsClient = require('./core/initAnalyticsClient.cjs');
 const require_events_contentExposure = require('./events/contentExposure.cjs');
 
+exports.BOT_USER_AGENT_PATTERN = require_utils_isBot.BOT_USER_AGENT_PATTERN;
 exports.DEFAULT_FLUSH_INTERVAL = require_core_AnalyticsClient.DEFAULT_FLUSH_INTERVAL;
 exports.DEFAULT_MAX_BUFFER_SIZE = require_core_AnalyticsClient.DEFAULT_MAX_BUFFER_SIZE;
 exports.DEFAULT_SAMPLE_RATE = require_core_AnalyticsClient.DEFAULT_SAMPLE_RATE;
@@ -22,6 +24,8 @@ exports.getGlobalAnalyticsClient = require_core_globalManager.getGlobalAnalytics
 exports.getSessionId = require_core_session.getSessionId;
 exports.incrementAnalyticsClientRefCount = require_core_globalManager.incrementAnalyticsClientRefCount;
 exports.initAnalyticsClient = require_core_initAnalyticsClient.initAnalyticsClient;
+exports.isBotEnvironment = require_utils_isBot.isBotEnvironment;
+exports.isBotUserAgent = require_utils_isBot.isBotUserAgent;
 exports.isSampledIn = require_core_sampling.isSampledIn;
 exports.sendEvents = require_core_transport.sendEvents;
 exports.serializeKeyPath = require_events_contentExposure.serializeKeyPath;

package/dist/cjs/isEnabled.cjs

@@ -1,4 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_utils_isBot = require('./utils/isBot.cjs');
 let _intlayer_config_built = require("@intlayer/config/built");
 
 //#region src/isEnabled.ts
@@ -21,9 +22,10 @@ const TREE_SHAKE_ANALYTICS = process.env.INTLAYER_ANALYTICS_ENABLED === "false";
 * - the user did not opt out (`analytics.enabled === true`, the default), and
 * - a project key is configured (`editor.clientId`), and
 * - we are on the client, and
-* - we are the top window (not embedded in the editor).
+* - we are the top window (not embedded in the editor), and
+* - the visitor is not a bot, crawler or automation runtime.
 */
-const isEnabled = !TREE_SHAKE_ANALYTICS && _intlayer_config_built.analytics?.enabled === true && Boolean(_intlayer_config_built.editor?.clientId) && typeof window !== "undefined" && window.self === window.top;
+const isEnabled = !TREE_SHAKE_ANALYTICS && _intlayer_config_built.analytics?.enabled === true && Boolean(_intlayer_config_built.editor?.clientId) && typeof window !== "undefined" && window.self === window.top && !require_utils_isBot.isBotEnvironment();
 
 //#endregion
 exports.isEnabled = isEnabled;

package/dist/cjs/isEnabled.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"isEnabled.cjs","names":["analytics","editor"],"sources":["../../src/isEnabled.ts"],"sourcesContent":["import { analytics, editor } from '@intlayer/config/built';\n\n/**\n * Compile-time kill switch. Bundlers replace `process.env.INTLAYER_ANALYTICS_ENABLED`\n * (set to `'false'` by `@intlayer/config` unless `analytics.enabled` is `true`\n * — the default once this package is installed — AND an `editor.clientId` is\n * configured) so the whole analytics integration is dead-code-eliminated for\n * apps that opted out.\n */\nconst TREE_SHAKE_ANALYTICS = process.env.INTLAYER_ANALYTICS_ENABLED === 'false';\n\n/**\n * Runtime guard mirroring `@intlayer/editor`'s `isEnabled`, but inverted with\n * respect to the iframe: analytics runs for real end users on the **top**\n * window and stays off inside the editor/CMS preview iframe so editor sessions\n * are never counted as traffic.\n *\n * Enabled when:\n * - the bundler did not tree-shake analytics away, and\n * - the user did not opt out (`analytics.enabled === true`, the default), and\n * - a project key is configured (`editor.clientId`), and\n * - we are on the client, and\n * - we are the top window (not embedded in the editor).\n */\nexport const isEnabled =\n  !TREE_SHAKE_ANALYTICS &&\n  analytics?.enabled === true &&\n  Boolean(editor?.clientId) &&\n  typeof window !== 'undefined' &&\n  window.self === window.top;\n"],"mappings":";;;;;;;;;;;AASA,MAAM,uBAAuB,QAAQ,IAAI,+BAA+B;;;;;;;;;;;;;;AAexE,MAAa,YACX,CAAC,wBACDA,kCAAW,YAAY,QACvB,QAAQC,+BAAQ,QAAQ,KACxB,OAAO,WAAW,eAClB,OAAO,SAAS,OAAO"}
+{"version":3,"file":"isEnabled.cjs","names":["analytics","editor","isBotEnvironment"],"sources":["../../src/isEnabled.ts"],"sourcesContent":["import { analytics, editor } from '@intlayer/config/built';\nimport { isBotEnvironment } from './utils/isBot';\n\n/**\n * Compile-time kill switch. Bundlers replace `process.env.INTLAYER_ANALYTICS_ENABLED`\n * (set to `'false'` by `@intlayer/config` unless `analytics.enabled` is `true`\n * — the default once this package is installed — AND an `editor.clientId` is\n * configured) so the whole analytics integration is dead-code-eliminated for\n * apps that opted out.\n */\nconst TREE_SHAKE_ANALYTICS = process.env.INTLAYER_ANALYTICS_ENABLED === 'false';\n\n/**\n * Runtime guard mirroring `@intlayer/editor`'s `isEnabled`, but inverted with\n * respect to the iframe: analytics runs for real end users on the **top**\n * window and stays off inside the editor/CMS preview iframe so editor sessions\n * are never counted as traffic.\n *\n * Enabled when:\n * - the bundler did not tree-shake analytics away, and\n * - the user did not opt out (`analytics.enabled === true`, the default), and\n * - a project key is configured (`editor.clientId`), and\n * - we are on the client, and\n * - we are the top window (not embedded in the editor), and\n * - the visitor is not a bot, crawler or automation runtime.\n */\nexport const isEnabled =\n  !TREE_SHAKE_ANALYTICS &&\n  analytics?.enabled === true &&\n  Boolean(editor?.clientId) &&\n  typeof window !== 'undefined' &&\n  window.self === window.top &&\n  !isBotEnvironment();\n"],"mappings":";;;;;;;;;;;;AAUA,MAAM,uBAAuB,QAAQ,IAAI,+BAA+B;;;;;;;;;;;;;;;AAgBxE,MAAa,YACX,CAAC,wBACDA,kCAAW,YAAY,QACvB,QAAQC,+BAAQ,QAAQ,KACxB,OAAO,WAAW,eAClB,OAAO,SAAS,OAAO,OACvB,CAACC,qCAAiB"}

package/dist/cjs/utils/isBot.cjs

@@ -0,0 +1,89 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+//#region src/utils/isBot.ts
+/**
+* Bot / automation detection.
+*
+* Analytics must describe real people. Crawlers, link-preview fetchers, uptime
+* monitors, AI agents and CI browsers (Lighthouse, Playwright, Puppeteer) all
+* execute JavaScript nowadays, so they would otherwise be counted as visitors
+* and inflate page views, content exposures and A/B conversion rates.
+*
+* Everything here is a pure string/environment check — no network, no storage.
+*/
+/**
+* User agents that look like a bot but belong to real user devices, checked
+* before {@link BOT_USER_AGENT_PATTERN}. `CUBOT` is an Android phone brand
+* whose model strings (`CUBOT_X19`) contain the `bot` token.
+*/
+const HUMAN_USER_AGENT_EXCEPTION_PATTERN = /cubot/i;
+/**
+* Matches known non-human user agents. Grouped by family so the list stays
+* reviewable:
+* - generic tokens (`…bot`, `crawler`, `spider`, `scraper`)
+* - HTTP clients used by scripts (curl, wget, requests, axios…)
+* - headless / automation runtimes (Playwright, Puppeteer, Lighthouse…)
+* - search-engine and SEO crawlers
+* - social link-preview fetchers
+* - AI / LLM crawlers and agents
+*/
+const BOT_USER_AGENT_PATTERN = /bot\b|bot[/\-\s]|crawler|crawling|spider|scraper|slurp|archiver|feedfetcher|validator|curl\/|wget\/|python-requests|python-urllib|okhttp|axios\/|node-fetch|got \(|go-http-client|java\/|libwww|httpunit|http_request|apache-httpclient|headless|phantomjs|puppeteer|playwright|selenium|webdriver|cypress|lighthouse|pagespeed|gtmetrix|prerender|pingdom|uptime|statuscake|site24x7|bingpreview|yandex|baiduspider|sogou|exabot|semrush|ahrefs|mj12|dotbot|petalbot|applebot|amazonbot|bytespider|facebookexternalhit|meta-externalagent|embedly|outbrain|quora link preview|skypeuripreview|vkshare|w3c_validator|apis-google|mediapartners|adsbot|storebot-google|google-inspectiontool|google-read-aloud|google-extended|duplexweb-google|gptbot|oai-searchbot|chatgpt-user|perplexity|claudebot|claude-web|anthropic-ai|cohere-ai|ccbot|diffbot|imagesift|omgili|timpi|youbot/i;
+/**
+* Tells whether a user agent string identifies a bot, crawler or automation
+* runtime rather than a human visitor.
+*
+* A missing or empty user agent is treated as a bot: every real browser sends
+* one, so its absence means a script or a forged request.
+*
+* @param userAgent - The raw `User-Agent` string (header or `navigator.userAgent`).
+* @returns `true` when the traffic must not be recorded.
+*
+* @example
+* isBotUserAgent('Mozilla/5.0 (compatible; Googlebot/2.1)'); // true
+* isBotUserAgent('Mozilla/5.0 (Macintosh) Chrome/120'); // false
+*/
+const isBotUserAgent = (userAgent) => {
+	if (!userAgent) return true;
+	if (HUMAN_USER_AGENT_EXCEPTION_PATTERN.test(userAgent)) return false;
+	return BOT_USER_AGENT_PATTERN.test(userAgent);
+};
+/**
+* Globals injected by automation runtimes. Their mere presence means the page
+* is driven by a script, whatever the user agent claims.
+*/
+const AUTOMATION_GLOBAL_KEYS = [
+	"_phantom",
+	"__nightmare",
+	"callPhantom",
+	"__selenium_unwrapped",
+	"__webdriver_evaluate",
+	"__driver_evaluate",
+	"domAutomation",
+	"Cypress"
+];
+/**
+* Tells whether the current browser environment is automated, combining the
+* user agent with automation fingerprints (`navigator.webdriver`, runtime
+* globals) that headless browsers spoofing a normal user agent still expose.
+*
+* Always `false` outside a browser (SSR): there is nothing to collect there,
+* and the server must not disable a client that has not run yet.
+*
+* @returns `true` when analytics must stay off for this environment.
+*
+* @example
+* if (isBotEnvironment()) return; // never start the client for a crawler
+*/
+const isBotEnvironment = () => {
+	if (typeof navigator === "undefined") return false;
+	if (navigator.webdriver === true) return true;
+	const automationGlobals = globalThis;
+	if (AUTOMATION_GLOBAL_KEYS.some((key) => key in automationGlobals)) return true;
+	if (!navigator.userAgent) return false;
+	return isBotUserAgent(navigator.userAgent);
+};
+
+//#endregion
+exports.BOT_USER_AGENT_PATTERN = BOT_USER_AGENT_PATTERN;
+exports.isBotEnvironment = isBotEnvironment;
+exports.isBotUserAgent = isBotUserAgent;
+//# sourceMappingURL=isBot.cjs.map

package/dist/cjs/utils/isBot.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"isBot.cjs","names":[],"sources":["../../../src/utils/isBot.ts"],"sourcesContent":["/**\n * Bot / automation detection.\n *\n * Analytics must describe real people. Crawlers, link-preview fetchers, uptime\n * monitors, AI agents and CI browsers (Lighthouse, Playwright, Puppeteer) all\n * execute JavaScript nowadays, so they would otherwise be counted as visitors\n * and inflate page views, content exposures and A/B conversion rates.\n *\n * Everything here is a pure string/environment check — no network, no storage.\n */\n\n/**\n * User agents that look like a bot but belong to real user devices, checked\n * before {@link BOT_USER_AGENT_PATTERN}. `CUBOT` is an Android phone brand\n * whose model strings (`CUBOT_X19`) contain the `bot` token.\n */\nconst HUMAN_USER_AGENT_EXCEPTION_PATTERN = /cubot/i;\n\n/**\n * Matches known non-human user agents. Grouped by family so the list stays\n * reviewable:\n * - generic tokens (`…bot`, `crawler`, `spider`, `scraper`)\n * - HTTP clients used by scripts (curl, wget, requests, axios…)\n * - headless / automation runtimes (Playwright, Puppeteer, Lighthouse…)\n * - search-engine and SEO crawlers\n * - social link-preview fetchers\n * - AI / LLM crawlers and agents\n */\nexport const BOT_USER_AGENT_PATTERN =\n  /bot\\b|bot[/\\-\\s]|crawler|crawling|spider|scraper|slurp|archiver|feedfetcher|validator|curl\\/|wget\\/|python-requests|python-urllib|okhttp|axios\\/|node-fetch|got \\(|go-http-client|java\\/|libwww|httpunit|http_request|apache-httpclient|headless|phantomjs|puppeteer|playwright|selenium|webdriver|cypress|lighthouse|pagespeed|gtmetrix|prerender|pingdom|uptime|statuscake|site24x7|bingpreview|yandex|baiduspider|sogou|exabot|semrush|ahrefs|mj12|dotbot|petalbot|applebot|amazonbot|bytespider|facebookexternalhit|meta-externalagent|embedly|outbrain|quora link preview|skypeuripreview|vkshare|w3c_validator|apis-google|mediapartners|adsbot|storebot-google|google-inspectiontool|google-read-aloud|google-extended|duplexweb-google|gptbot|oai-searchbot|chatgpt-user|perplexity|claudebot|claude-web|anthropic-ai|cohere-ai|ccbot|diffbot|imagesift|omgili|timpi|youbot/i;\n\n/**\n * Tells whether a user agent string identifies a bot, crawler or automation\n * runtime rather than a human visitor.\n *\n * A missing or empty user agent is treated as a bot: every real browser sends\n * one, so its absence means a script or a forged request.\n *\n * @param userAgent - The raw `User-Agent` string (header or `navigator.userAgent`).\n * @returns `true` when the traffic must not be recorded.\n *\n * @example\n * isBotUserAgent('Mozilla/5.0 (compatible; Googlebot/2.1)'); // true\n * isBotUserAgent('Mozilla/5.0 (Macintosh) Chrome/120'); // false\n */\nexport const isBotUserAgent = (userAgent?: string | null): boolean => {\n  if (!userAgent) return true;\n  if (HUMAN_USER_AGENT_EXCEPTION_PATTERN.test(userAgent)) return false;\n\n  return BOT_USER_AGENT_PATTERN.test(userAgent);\n};\n\n/**\n * Globals injected by automation runtimes. Their mere presence means the page\n * is driven by a script, whatever the user agent claims.\n */\nconst AUTOMATION_GLOBAL_KEYS = [\n  '_phantom',\n  '__nightmare',\n  'callPhantom',\n  '__selenium_unwrapped',\n  '__webdriver_evaluate',\n  '__driver_evaluate',\n  'domAutomation',\n  'Cypress',\n] as const;\n\n/**\n * Tells whether the current browser environment is automated, combining the\n * user agent with automation fingerprints (`navigator.webdriver`, runtime\n * globals) that headless browsers spoofing a normal user agent still expose.\n *\n * Always `false` outside a browser (SSR): there is nothing to collect there,\n * and the server must not disable a client that has not run yet.\n *\n * @returns `true` when analytics must stay off for this environment.\n *\n * @example\n * if (isBotEnvironment()) return; // never start the client for a crawler\n */\nexport const isBotEnvironment = (): boolean => {\n  if (typeof navigator === 'undefined') return false;\n\n  if (navigator.webdriver === true) return true;\n\n  const automationGlobals = globalThis as unknown as Record<string, unknown>;\n  if (AUTOMATION_GLOBAL_KEYS.some((key) => key in automationGlobals)) {\n    return true;\n  }\n\n  // Unlike a server reading the `User-Agent` header, an absent user agent here\n  // means a non-browser runtime (React Native, Lynx) — a real app, not a bot.\n  if (!navigator.userAgent) return false;\n\n  return isBotUserAgent(navigator.userAgent);\n};\n"],"mappings":";;;;;;;;;;;;;;;;;AAgBA,MAAM,qCAAqC;;;;;;;;;;;AAY3C,MAAa,yBACX;;;;;;;;;;;;;;;AAgBF,MAAa,kBAAkB,cAAuC;CACpE,IAAI,CAAC,WAAW,OAAO;CACvB,IAAI,mCAAmC,KAAK,SAAS,GAAG,OAAO;CAE/D,OAAO,uBAAuB,KAAK,SAAS;AAC9C;;;;;AAMA,MAAM,yBAAyB;CAC7B;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF;;;;;;;;;;;;;;AAeA,MAAa,yBAAkC;CAC7C,IAAI,OAAO,cAAc,aAAa,OAAO;CAE7C,IAAI,UAAU,cAAc,MAAM,OAAO;CAEzC,MAAM,oBAAoB;CAC1B,IAAI,uBAAuB,MAAM,QAAQ,OAAO,iBAAiB,GAC/D,OAAO;CAKT,IAAI,CAAC,UAAU,WAAW,OAAO;CAEjC,OAAO,eAAe,UAAU,SAAS;AAC3C"}

package/dist/esm/core/AnalyticsClient.mjs

@@ -1,6 +1,8 @@
+import { isBotEnvironment } from "../utils/isBot.mjs";
 import { onIdle } from "../utils/idle.mjs";
 import { assignVariant } from "./abTesting.mjs";
 import { createEventBuffer } from "./eventBuffer.mjs";
+import { createPublicTokenManager } from "./publicToken.mjs";
 import { isSampledIn } from "./sampling.mjs";
 import { getSessionId } from "./session.mjs";
 import { sendEvents } from "./transport.mjs";
@@ -47,22 +49,33 @@ const referrerHost = () => {
 */
 const createAnalyticsClient = (config) => {
 	const sessionId = getSessionId();
-	const sampledIn = isSampledIn(sessionId, config.sampleRate);
+	const isBotSession = isBotEnvironment();
+	const sampledIn = !isBotSession && isSampledIn(sessionId, config.sampleRate);
 	const buffer = createEventBuffer({ max: config.maxBufferSize });
 	const endpoint = `${config.backendURL.replace(/\/$/, "")}/api/analytics/events`;
+	const publicToken = createPublicTokenManager({
+		backendURL: config.backendURL,
+		clientId: config.clientId
+	});
 	let ambientLocale = "";
 	let flushTimer = null;
 	let started = false;
 	let detachListeners = null;
+	let lastPageViewUrl = null;
 	let seenExposureKeys = /* @__PURE__ */ new Set();
 	const flush = (useBeacon = false) => {
 		const events = buffer.drain();
+		const token = publicToken.getToken();
 		for (let start = 0; start < events.length; start += 200) sendEvents(endpoint, {
-			clientId: config.clientId,
+			token,
+			clientId: token ? void 0 : config.clientId,
 			sessionId,
 			sdkVersion: SDK_VERSION,
 			events: events.slice(start, start + 200)
-		}, { useBeacon });
+		}, {
+			useBeacon,
+			token
+		});
 	};
 	/** Pushes an event and triggers an early flush if the buffer is full. */
 	const enqueue = (event) => {
@@ -73,16 +86,20 @@ const createAnalyticsClient = (config) => {
 	};
 	const trackPageView = (event = {}) => {
 		if (!sampledIn) return;
+		const url = event.url ?? currentUrl();
+		const reason = event.reason ?? "initial";
+		if (reason === "route_change" && url === lastPageViewUrl) return;
+		lastPageViewUrl = url;
 		seenExposureKeys = /* @__PURE__ */ new Set();
 		enqueue({
 			type: "page_view",
 			t: Date.now(),
-			url: event.url ?? currentUrl(),
+			url,
 			locale: event.locale ?? ambientLocale,
 			ref: event.ref ?? referrerHost(),
 			vw: event.vw ?? (typeof window !== "undefined" ? window.innerWidth : void 0),
 			vh: event.vh ?? (typeof window !== "undefined" ? window.innerHeight : void 0),
-			reason: event.reason ?? "initial"
+			reason
 		});
 	};
 	const trackContentExposure = (event) => {
@@ -106,6 +123,7 @@ const createAnalyticsClient = (config) => {
 		});
 	};
 	const trackConversion = (event) => {
+		if (isBotSession) return;
 		enqueue({
 			...event,
 			type: "conversion",
@@ -143,8 +161,9 @@ const createAnalyticsClient = (config) => {
 		};
 	};
 	const start = () => {
-		if (started) return;
+		if (started || isBotSession) return;
 		started = true;
+		publicToken.prime();
 		flushTimer = setInterval(flush, config.flushInterval);
 		flushTimer?.unref?.();
 		onIdle(attachListeners);

package/dist/esm/core/AnalyticsClient.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"AnalyticsClient.mjs","names":[],"sources":["../../../src/core/AnalyticsClient.ts"],"sourcesContent":["import { onIdle } from '../utils/idle';\nimport { assignVariant } from './abTesting';\nimport { createEventBuffer, type EventBuffer } from './eventBuffer';\nimport { isSampledIn } from './sampling';\nimport { getSessionId } from './session';\nimport { sendEvents } from './transport';\nimport type {\n  AnalyticsClientConfig,\n  AnalyticsEvent,\n  ContentExposureEvent,\n  ConversionEvent,\n  PageViewEvent,\n  TrackableEvent,\n} from './types';\n\n/**\n * Caller-supplied fields for a page view. Everything is optional — the client\n * fills `url`, `locale`, viewport, and referrer from the environment when omitted.\n */\nexport type PageViewInput = {\n  /** Explicit pathname / screen name (native runtimes have no `location`). */\n  url?: string;\n  /** Explicit locale; falls back to the client's ambient locale. */\n  locale?: string;\n  /** Referrer host override. */\n  ref?: string;\n  /** Viewport width override. */\n  vw?: number;\n  /** Viewport height override. */\n  vh?: number;\n  /** Why the view was recorded. */\n  reason?: PageViewEvent['reason'];\n};\n\n/** Default flush cadence — one network request per 20 seconds. */\nexport const DEFAULT_FLUSH_INTERVAL = 20_000;\n/** Default cap on distinct buffered events before an early flush. */\nexport const DEFAULT_MAX_BUFFER_SIZE = 500;\n/** Default sampling — keep every session. */\nexport const DEFAULT_SAMPLE_RATE = 1;\n/**\n * Maximum events per network request. `sendBeacon` and `fetch(keepalive)`\n * reject bodies over ~64KB, so large batches are split into multiple sends.\n */\nexport const MAX_EVENTS_PER_SEND = 200;\n/** Identifies the producing SDK in the ingest envelope. */\nconst SDK_VERSION = 'intlayer-analytics/1';\n\n/**\n * The public surface of the analytics client singleton. Framework bindings hold\n * a reference to this and forward provider/node/conversion signals into it.\n */\nexport type AnalyticsClient = {\n  /** Sets the ambient locale stamped onto subsequent events. */\n  setLocale: (locale: string) => void;\n  /** Records a page/locale view (provider level). */\n  trackPageView: (event?: PageViewInput) => void;\n  /** Records a content exposure (node level). Sampled + deduped per page view. */\n  trackContentExposure: (\n    event: Omit<TrackableEvent<ContentExposureEvent>, 'type'>\n  ) => void;\n  /** Records a conversion tied to an experiment variant. */\n  trackConversion: (\n    event: Omit<TrackableEvent<ConversionEvent>, 'type'>\n  ) => void;\n  /** Deterministically resolves this session's variant for an experiment. */\n  getVariant: (\n    experimentKey: string,\n    variants: string[],\n    weights?: number[]\n  ) => string;\n  /** Sends the buffered batch now. */\n  flush: (useBeacon?: boolean) => void;\n  /** Starts the flush loop and lifecycle listeners (idempotent). */\n  start: () => void;\n  /** Stops timers/listeners and flushes any remaining events. */\n  stop: () => void;\n};\n\n/**\n * Reads the current page pathname. Search params are intentionally excluded to\n * avoid capturing anything sensitive.\n */\nconst currentUrl = (): string => {\n  if (typeof window === 'undefined' || !window.location) return '';\n  return window.location.pathname;\n};\n\n/**\n * Reduces the referrer to its host — never the full URL — for privacy.\n */\nconst referrerHost = (): string | undefined => {\n  if (typeof document === 'undefined' || !document.referrer) return undefined;\n  try {\n    return new URL(document.referrer).host;\n  } catch {\n    return undefined;\n  }\n};\n\n/**\n * Creates an analytics client. Prefer {@link initAnalyticsClient} in application\n * code — it manages a shared singleton so there is only ever one flush timer.\n *\n * @param config - Resolved client configuration.\n * @returns A started-on-demand {@link AnalyticsClient}.\n */\nexport const createAnalyticsClient = (\n  config: AnalyticsClientConfig\n): AnalyticsClient => {\n  const sessionId = getSessionId();\n  const sampledIn = isSampledIn(sessionId, config.sampleRate);\n  const buffer: EventBuffer = createEventBuffer({ max: config.maxBufferSize });\n  const endpoint = `${config.backendURL.replace(/\\/$/, '')}/api/analytics/events`;\n\n  let ambientLocale = '';\n  let flushTimer: ReturnType<typeof setInterval> | null = null;\n  let started = false;\n  let detachListeners: (() => void) | null = null;\n\n  // Exposure keys already recorded for the current page view. React (and other\n  // frameworks) resolve content nodes on every re-render; without this gate a\n  // component re-rendering 60×/s would count 60 exposures per second. The set\n  // is cleared on each page view so the recorded semantic is \"shown at least\n  // once during this page view\".\n  let seenExposureKeys = new Set<string>();\n\n  const flush = (useBeacon = false): void => {\n    const events = buffer.drain();\n\n    // Split into bounded chunks so no single request exceeds transport limits.\n    for (let start = 0; start < events.length; start += MAX_EVENTS_PER_SEND) {\n      sendEvents(\n        endpoint,\n        {\n          clientId: config.clientId,\n          sessionId,\n          sdkVersion: SDK_VERSION,\n          events: events.slice(start, start + MAX_EVENTS_PER_SEND),\n        },\n        { useBeacon }\n      );\n    }\n  };\n\n  /** Pushes an event and triggers an early flush if the buffer is full. */\n  const enqueue = (event: AnalyticsEvent): void => {\n    const size = buffer.push(event);\n    if (size >= config.maxBufferSize) flush();\n  };\n\n  const setLocale = (locale: string): void => {\n    ambientLocale = locale;\n  };\n\n  const trackPageView: AnalyticsClient['trackPageView'] = (event = {}) => {\n    if (!sampledIn) return;\n\n    // A new page view starts a fresh exposure window.\n    seenExposureKeys = new Set<string>();\n\n    enqueue({\n      type: 'page_view',\n      t: Date.now(),\n      url: event.url ?? currentUrl(),\n      locale: event.locale ?? ambientLocale,\n      ref: event.ref ?? referrerHost(),\n      vw:\n        event.vw ??\n        (typeof window !== 'undefined' ? window.innerWidth : undefined),\n      vh:\n        event.vh ??\n        (typeof window !== 'undefined' ? window.innerHeight : undefined),\n      reason: event.reason ?? 'initial',\n    });\n  };\n\n  const trackContentExposure: AnalyticsClient['trackContentExposure'] = (\n    event\n  ) => {\n    if (!sampledIn) return;\n\n    const locale = event.locale ?? ambientLocale;\n    // Joined with \\x01 (never present in content keys) so parts cannot collide.\n    const exposureKey = [\n      event.dictionaryKey,\n      event.keyPath,\n      locale,\n      event.experimentKey ?? '',\n      event.variant ?? '',\n    ].join('\u0001');\n\n    // Deduplicate within the current page view (see `seenExposureKeys`).\n    if (seenExposureKeys.has(exposureKey)) return;\n    seenExposureKeys.add(exposureKey);\n\n    enqueue({\n      ...event,\n      type: 'content_exposure',\n      t: Date.now(),\n      url: currentUrl(),\n      locale,\n    });\n  };\n\n  const trackConversion: AnalyticsClient['trackConversion'] = (event) => {\n    // Conversions are never sampled out — they are rare and decisive for A/B.\n    enqueue({\n      ...event,\n      type: 'conversion',\n      t: Date.now(),\n      url: currentUrl(),\n      locale: event.locale ?? ambientLocale,\n    });\n    // Flush conversions promptly so they are not lost on immediate navigation.\n    flush();\n  };\n\n  const getVariant: AnalyticsClient['getVariant'] = (\n    experimentKey,\n    variants,\n    weights\n  ) => assignVariant(sessionId, experimentKey, variants, weights);\n\n  /** Attaches lifecycle + SPA-navigation listeners without blocking render. */\n  const attachListeners = (): void => {\n    if (typeof window === 'undefined') return;\n\n    const onHidden = (): void => {\n      if (document.visibilityState === 'hidden') flush(true);\n    };\n    const onPageHide = (): void => flush(true);\n    const onPopState = (): void => trackPageView({ reason: 'route_change' });\n\n    document.addEventListener('visibilitychange', onHidden);\n    window.addEventListener('pagehide', onPageHide, { capture: true });\n    window.addEventListener('popstate', onPopState);\n\n    // Patch history.pushState so client-side route changes emit a page view.\n    // `replaceState` is intentionally left untouched: routers use it for\n    // same-page URL sync (scroll, params), which is not a navigation.\n    const history = window.history;\n    const originalPush = history.pushState;\n\n    const patchedPushState = function patchedPush(\n      this: History,\n      ...args: Parameters<History['pushState']>\n    ) {\n      const result = originalPush.apply(this, args);\n      trackPageView({ reason: 'route_change' });\n      return result;\n    };\n    history.pushState = patchedPushState;\n\n    detachListeners = (): void => {\n      document.removeEventListener('visibilitychange', onHidden);\n      window.removeEventListener('pagehide', onPageHide, { capture: true });\n      window.removeEventListener('popstate', onPopState);\n      // Only restore if nothing else re-patched pushState after us; restoring\n      // blindly would clobber another library's wrapper.\n      if (history.pushState === patchedPushState) {\n        history.pushState = originalPush;\n      }\n    };\n  };\n\n  const start = (): void => {\n    if (started) return;\n    started = true;\n\n    flushTimer = setInterval(flush, config.flushInterval);\n    // Some runtimes (Node during SSR) keep the process alive on timers.\n    (flushTimer as { unref?: () => void })?.unref?.();\n\n    onIdle(attachListeners);\n  };\n\n  const stop = (): void => {\n    if (!started) return;\n    started = false;\n\n    if (flushTimer) {\n      clearInterval(flushTimer);\n      flushTimer = null;\n    }\n    detachListeners?.();\n    detachListeners = null;\n    flush(true);\n  };\n\n  return {\n    setLocale,\n    trackPageView,\n    trackContentExposure,\n    trackConversion,\n    getVariant,\n    flush,\n    start,\n    stop,\n  };\n};\n"],"mappings":"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"}
+{"version":3,"file":"AnalyticsClient.mjs","names":[],"sources":["../../../src/core/AnalyticsClient.ts"],"sourcesContent":["import { onIdle } from '../utils/idle';\nimport { isBotEnvironment } from '../utils/isBot';\nimport { assignVariant } from './abTesting';\nimport { createEventBuffer, type EventBuffer } from './eventBuffer';\nimport { createPublicTokenManager } from './publicToken';\nimport { isSampledIn } from './sampling';\nimport { getSessionId } from './session';\nimport { sendEvents } from './transport';\nimport type {\n  AnalyticsClientConfig,\n  AnalyticsEvent,\n  ContentExposureEvent,\n  ConversionEvent,\n  PageViewEvent,\n  TrackableEvent,\n} from './types';\n\n/**\n * Caller-supplied fields for a page view. Everything is optional — the client\n * fills `url`, `locale`, viewport, and referrer from the environment when omitted.\n */\nexport type PageViewInput = {\n  /** Explicit pathname / screen name (native runtimes have no `location`). */\n  url?: string;\n  /** Explicit locale; falls back to the client's ambient locale. */\n  locale?: string;\n  /** Referrer host override. */\n  ref?: string;\n  /** Viewport width override. */\n  vw?: number;\n  /** Viewport height override. */\n  vh?: number;\n  /** Why the view was recorded. */\n  reason?: PageViewEvent['reason'];\n};\n\n/** Default flush cadence — one network request per 20 seconds. */\nexport const DEFAULT_FLUSH_INTERVAL = 20_000;\n/** Default cap on distinct buffered events before an early flush. */\nexport const DEFAULT_MAX_BUFFER_SIZE = 500;\n/** Default sampling — keep every session. */\nexport const DEFAULT_SAMPLE_RATE = 1;\n/**\n * Maximum events per network request. `sendBeacon` and `fetch(keepalive)`\n * reject bodies over ~64KB, so large batches are split into multiple sends.\n */\nexport const MAX_EVENTS_PER_SEND = 200;\n/** Identifies the producing SDK in the ingest envelope. */\nconst SDK_VERSION = 'intlayer-analytics/1';\n\n/**\n * The public surface of the analytics client singleton. Framework bindings hold\n * a reference to this and forward provider/node/conversion signals into it.\n */\nexport type AnalyticsClient = {\n  /** Sets the ambient locale stamped onto subsequent events. */\n  setLocale: (locale: string) => void;\n  /** Records a page/locale view (provider level). */\n  trackPageView: (event?: PageViewInput) => void;\n  /** Records a content exposure (node level). Sampled + deduped per page view. */\n  trackContentExposure: (\n    event: Omit<TrackableEvent<ContentExposureEvent>, 'type'>\n  ) => void;\n  /** Records a conversion tied to an experiment variant. */\n  trackConversion: (\n    event: Omit<TrackableEvent<ConversionEvent>, 'type'>\n  ) => void;\n  /** Deterministically resolves this session's variant for an experiment. */\n  getVariant: (\n    experimentKey: string,\n    variants: string[],\n    weights?: number[]\n  ) => string;\n  /** Sends the buffered batch now. */\n  flush: (useBeacon?: boolean) => void;\n  /** Starts the flush loop and lifecycle listeners (idempotent). */\n  start: () => void;\n  /** Stops timers/listeners and flushes any remaining events. */\n  stop: () => void;\n};\n\n/**\n * Reads the current page pathname. Search params are intentionally excluded to\n * avoid capturing anything sensitive.\n */\nconst currentUrl = (): string => {\n  if (typeof window === 'undefined' || !window.location) return '';\n  return window.location.pathname;\n};\n\n/**\n * Reduces the referrer to its host — never the full URL — for privacy.\n */\nconst referrerHost = (): string | undefined => {\n  if (typeof document === 'undefined' || !document.referrer) return undefined;\n  try {\n    return new URL(document.referrer).host;\n  } catch {\n    return undefined;\n  }\n};\n\n/**\n * Creates an analytics client. Prefer {@link initAnalyticsClient} in application\n * code — it manages a shared singleton so there is only ever one flush timer.\n *\n * @param config - Resolved client configuration.\n * @returns A started-on-demand {@link AnalyticsClient}.\n */\nexport const createAnalyticsClient = (\n  config: AnalyticsClientConfig\n): AnalyticsClient => {\n  const sessionId = getSessionId();\n  // Crawlers, link-preview fetchers and headless runtimes execute JavaScript,\n  // so they reach this point like any visitor. Detected once at creation: the\n  // client then buffers nothing, sends nothing and never starts its timers.\n  const isBotSession = isBotEnvironment();\n  const sampledIn = !isBotSession && isSampledIn(sessionId, config.sampleRate);\n  const buffer: EventBuffer = createEventBuffer({ max: config.maxBufferSize });\n  const endpoint = `${config.backendURL.replace(/\\/$/, '')}/api/analytics/events`;\n  const publicToken = createPublicTokenManager({\n    backendURL: config.backendURL,\n    clientId: config.clientId,\n  });\n\n  let ambientLocale = '';\n  let flushTimer: ReturnType<typeof setInterval> | null = null;\n  let started = false;\n  let detachListeners: (() => void) | null = null;\n\n  // Path of the most recent page view, so an automatic route-change signal for\n  // a page already recorded is ignored. Routers call `pushState` for\n  // query-only and hash-only updates (filters, tabs, modals, scroll sync),\n  // each of which would otherwise land as another view of the same page.\n  let lastPageViewUrl: string | null = null;\n\n  // Exposure keys already recorded for the current page view. React (and other\n  // frameworks) resolve content nodes on every re-render; without this gate a\n  // component re-rendering 60×/s would count 60 exposures per second. The set\n  // is cleared on each page view so the recorded semantic is \"shown at least\n  // once during this page view\".\n  let seenExposureKeys = new Set<string>();\n\n  const flush = (useBeacon = false): void => {\n    const events = buffer.drain();\n\n    // Read synchronously: the flush-on-hide path runs during `pagehide` and\n    // cannot await the exchange. Until it resolves, the public `clientId` is\n    // sent instead so the first batch of a visit is still attributed.\n    const token = publicToken.getToken();\n\n    // Split into bounded chunks so no single request exceeds transport limits.\n    for (let start = 0; start < events.length; start += MAX_EVENTS_PER_SEND) {\n      sendEvents(\n        endpoint,\n        {\n          token,\n          clientId: token ? undefined : config.clientId,\n          sessionId,\n          sdkVersion: SDK_VERSION,\n          events: events.slice(start, start + MAX_EVENTS_PER_SEND),\n        },\n        { useBeacon, token }\n      );\n    }\n  };\n\n  /** Pushes an event and triggers an early flush if the buffer is full. */\n  const enqueue = (event: AnalyticsEvent): void => {\n    const size = buffer.push(event);\n    if (size >= config.maxBufferSize) flush();\n  };\n\n  const setLocale = (locale: string): void => {\n    ambientLocale = locale;\n  };\n\n  const trackPageView: AnalyticsClient['trackPageView'] = (event = {}) => {\n    if (!sampledIn) return;\n\n    const url = event.url ?? currentUrl();\n    const reason = event.reason ?? 'initial';\n\n    // Only the automatic navigation signal is deduplicated: a provider asking\n    // for an `initial` or `locale_change` view is reporting something the\n    // pathname alone cannot express.\n    if (reason === 'route_change' && url === lastPageViewUrl) return;\n    lastPageViewUrl = url;\n\n    // A new page view starts a fresh exposure window.\n    seenExposureKeys = new Set<string>();\n\n    enqueue({\n      type: 'page_view',\n      t: Date.now(),\n      url,\n      locale: event.locale ?? ambientLocale,\n      ref: event.ref ?? referrerHost(),\n      vw:\n        event.vw ??\n        (typeof window !== 'undefined' ? window.innerWidth : undefined),\n      vh:\n        event.vh ??\n        (typeof window !== 'undefined' ? window.innerHeight : undefined),\n      reason,\n    });\n  };\n\n  const trackContentExposure: AnalyticsClient['trackContentExposure'] = (\n    event\n  ) => {\n    if (!sampledIn) return;\n\n    const locale = event.locale ?? ambientLocale;\n    // Joined with \\x01 (never present in content keys) so parts cannot collide.\n    const exposureKey = [\n      event.dictionaryKey,\n      event.keyPath,\n      locale,\n      event.experimentKey ?? '',\n      event.variant ?? '',\n    ].join('\u0001');\n\n    // Deduplicate within the current page view (see `seenExposureKeys`).\n    if (seenExposureKeys.has(exposureKey)) return;\n    seenExposureKeys.add(exposureKey);\n\n    enqueue({\n      ...event,\n      type: 'content_exposure',\n      t: Date.now(),\n      url: currentUrl(),\n      locale,\n    });\n  };\n\n  const trackConversion: AnalyticsClient['trackConversion'] = (event) => {\n    // Conversions are never sampled out — they are rare and decisive for A/B —\n    // but bot traffic is still excluded, or it would skew every variant rate.\n    if (isBotSession) return;\n\n    enqueue({\n      ...event,\n      type: 'conversion',\n      t: Date.now(),\n      url: currentUrl(),\n      locale: event.locale ?? ambientLocale,\n    });\n    // Flush conversions promptly so they are not lost on immediate navigation.\n    flush();\n  };\n\n  const getVariant: AnalyticsClient['getVariant'] = (\n    experimentKey,\n    variants,\n    weights\n  ) => assignVariant(sessionId, experimentKey, variants, weights);\n\n  /** Attaches lifecycle + SPA-navigation listeners without blocking render. */\n  const attachListeners = (): void => {\n    if (typeof window === 'undefined') return;\n\n    const onHidden = (): void => {\n      if (document.visibilityState === 'hidden') flush(true);\n    };\n    const onPageHide = (): void => flush(true);\n    const onPopState = (): void => trackPageView({ reason: 'route_change' });\n\n    document.addEventListener('visibilitychange', onHidden);\n    window.addEventListener('pagehide', onPageHide, { capture: true });\n    window.addEventListener('popstate', onPopState);\n\n    // Patch history.pushState so client-side route changes emit a page view.\n    // `replaceState` is intentionally left untouched: routers use it for\n    // same-page URL sync (scroll, params), which is not a navigation.\n    const history = window.history;\n    const originalPush = history.pushState;\n\n    const patchedPushState = function patchedPush(\n      this: History,\n      ...args: Parameters<History['pushState']>\n    ) {\n      const result = originalPush.apply(this, args);\n      trackPageView({ reason: 'route_change' });\n      return result;\n    };\n    history.pushState = patchedPushState;\n\n    detachListeners = (): void => {\n      document.removeEventListener('visibilitychange', onHidden);\n      window.removeEventListener('pagehide', onPageHide, { capture: true });\n      window.removeEventListener('popstate', onPopState);\n      // Only restore if nothing else re-patched pushState after us; restoring\n      // blindly would clobber another library's wrapper.\n      if (history.pushState === patchedPushState) {\n        history.pushState = originalPush;\n      }\n    };\n  };\n\n  const start = (): void => {\n    if (started || isBotSession) return;\n    started = true;\n\n    // Exchanged ahead of the first flush so a token is already cached by the\n    // time a batch — including one sent during `pagehide` — goes out.\n    publicToken.prime();\n\n    flushTimer = setInterval(flush, config.flushInterval);\n    // Some runtimes (Node during SSR) keep the process alive on timers.\n    (flushTimer as { unref?: () => void })?.unref?.();\n\n    onIdle(attachListeners);\n  };\n\n  const stop = (): void => {\n    if (!started) return;\n    started = false;\n\n    if (flushTimer) {\n      clearInterval(flushTimer);\n      flushTimer = null;\n    }\n    detachListeners?.();\n    detachListeners = null;\n    flush(true);\n  };\n\n  return {\n    setLocale,\n    trackPageView,\n    trackContentExposure,\n    trackConversion,\n    getVariant,\n    flush,\n    start,\n    stop,\n  };\n};\n"],"mappings":"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"}

package/dist/esm/core/publicToken.mjs

@@ -0,0 +1,103 @@
+//#region src/core/publicToken.ts
+/**
+* Short-lived ingest token used to authorise analytics batches.
+*
+* The SDK runs in the browser, where no confidential credential can be kept, so
+* it exchanges the project's **public** `clientId` for a token scoped to
+* analytics ingestion and nothing else. The backend authorises the exchange by
+* the request's `Origin`, which the page cannot forge.
+*
+* The token is read synchronously at flush time — the flush-on-hide path runs
+* during `pagehide` and cannot await anything — so it is fetched ahead of time
+* and cached, both in memory and in `sessionStorage` so a multi-page visit
+* exchanges once per tab rather than once per navigation.
+*/
+/** `sessionStorage` key holding the cached token for this tab. */
+const TOKEN_STORAGE_KEY = "__intlayer_public_token__";
+/**
+* Refresh margin: a token within this window of expiry is treated as expired,
+* so a batch is never sent with a token that dies in flight.
+*/
+const EXPIRY_MARGIN_MS = 6e4;
+/** Reads the cached token for this tab, ignoring an unusable cache. */
+const readStoredToken = () => {
+	try {
+		const raw = window.sessionStorage?.getItem(TOKEN_STORAGE_KEY);
+		if (!raw) return null;
+		const parsed = JSON.parse(raw);
+		if (typeof parsed?.token !== "string") return null;
+		if (typeof parsed?.expiresAt !== "number") return null;
+		return parsed;
+	} catch {
+		return null;
+	}
+};
+/** Persists the token for this tab. Best-effort: storage may be unavailable. */
+const writeStoredToken = (cached) => {
+	try {
+		window.sessionStorage?.setItem(TOKEN_STORAGE_KEY, JSON.stringify(cached));
+	} catch {}
+};
+/**
+* Creates the ingest token manager for a project.
+*
+* Every failure path is silent: analytics must never break, slow, or log noise
+* into the host application. Without a token the client falls back to sending
+* its public `clientId`, which the backend still accepts.
+*
+* @param options - Backend URL and the public project key.
+* @returns A manager exposing a synchronous {@link PublicTokenManager.getToken}.
+*/
+const createPublicTokenManager = ({ backendURL, clientId }) => {
+	const endpoint = `${backendURL.replace(/\/$/, "")}/api/public/token`;
+	let cached = null;
+	let pendingExchange = null;
+	const isUsable = (candidate) => candidate !== null && candidate.expiresAt - EXPIRY_MARGIN_MS > Date.now();
+	const getToken = () => {
+		if (isUsable(cached)) return cached.token;
+		if (typeof window !== "undefined") {
+			const stored = readStoredToken();
+			if (isUsable(stored)) {
+				cached = stored;
+				return stored.token;
+			}
+		}
+	};
+	const exchange = async () => {
+		try {
+			const response = await fetch(endpoint, {
+				method: "POST",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify({ clientId }),
+				credentials: "omit",
+				mode: "cors"
+			});
+			if (!response.ok) return;
+			const payload = await response.json();
+			const token = payload?.data?.token;
+			const expiresIn = payload?.data?.expiresIn ?? 0;
+			if (!token || expiresIn <= 0) return;
+			cached = {
+				token,
+				expiresAt: Date.now() + expiresIn * 1e3
+			};
+			if (typeof window !== "undefined") writeStoredToken(cached);
+		} catch {} finally {
+			pendingExchange = null;
+		}
+	};
+	const prime = () => {
+		if (!clientId || typeof fetch !== "function") return;
+		if (getToken()) return;
+		if (pendingExchange) return;
+		pendingExchange = exchange();
+	};
+	return {
+		getToken,
+		prime
+	};
+};
+
+//#endregion
+export { createPublicTokenManager };
+//# sourceMappingURL=publicToken.mjs.map

package/dist/esm/core/publicToken.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"publicToken.mjs","names":[],"sources":["../../../src/core/publicToken.ts"],"sourcesContent":["/**\n * Short-lived ingest token used to authorise analytics batches.\n *\n * The SDK runs in the browser, where no confidential credential can be kept, so\n * it exchanges the project's **public** `clientId` for a token scoped to\n * analytics ingestion and nothing else. The backend authorises the exchange by\n * the request's `Origin`, which the page cannot forge.\n *\n * The token is read synchronously at flush time — the flush-on-hide path runs\n * during `pagehide` and cannot await anything — so it is fetched ahead of time\n * and cached, both in memory and in `sessionStorage` so a multi-page visit\n * exchanges once per tab rather than once per navigation.\n */\n\n/** `sessionStorage` key holding the cached token for this tab. */\nconst TOKEN_STORAGE_KEY = '__intlayer_public_token__';\n\n/**\n * Refresh margin: a token within this window of expiry is treated as expired,\n * so a batch is never sent with a token that dies in flight.\n */\nconst EXPIRY_MARGIN_MS = 60 * 1000;\n\ntype CachedToken = {\n  token: string;\n  /** Epoch milliseconds. */\n  expiresAt: number;\n};\n\n/** Reads the cached token for this tab, ignoring an unusable cache. */\nconst readStoredToken = (): CachedToken | null => {\n  try {\n    const raw = window.sessionStorage?.getItem(TOKEN_STORAGE_KEY);\n    if (!raw) return null;\n\n    const parsed = JSON.parse(raw) as CachedToken;\n\n    if (typeof parsed?.token !== 'string') return null;\n    if (typeof parsed?.expiresAt !== 'number') return null;\n\n    return parsed;\n  } catch {\n    // Private mode, disabled storage, or corrupted entry — start fresh.\n    return null;\n  }\n};\n\n/** Persists the token for this tab. Best-effort: storage may be unavailable. */\nconst writeStoredToken = (cached: CachedToken): void => {\n  try {\n    window.sessionStorage?.setItem(TOKEN_STORAGE_KEY, JSON.stringify(cached));\n  } catch {\n    /* ignore — the in-memory cache still applies for this page */\n  }\n};\n\n/** Options accepted by {@link createPublicTokenManager}. */\nexport type PublicTokenManagerOptions = {\n  /** Backend base URL, without a trailing slash. */\n  backendURL: string;\n  /** The project's public key (`editor.clientId`). */\n  clientId?: string;\n};\n\n/** Synchronous accessor + background refresher for the ingest token. */\nexport type PublicTokenManager = {\n  /**\n   * The currently valid token, or `undefined` when none has been obtained yet.\n   * Never blocks and never triggers a request.\n   */\n  getToken: () => string | undefined;\n  /**\n   * Ensures a valid token is being fetched. Safe to call repeatedly:\n   * concurrent calls share a single in-flight exchange.\n   */\n  prime: () => void;\n};\n\n/**\n * Creates the ingest token manager for a project.\n *\n * Every failure path is silent: analytics must never break, slow, or log noise\n * into the host application. Without a token the client falls back to sending\n * its public `clientId`, which the backend still accepts.\n *\n * @param options - Backend URL and the public project key.\n * @returns A manager exposing a synchronous {@link PublicTokenManager.getToken}.\n */\nexport const createPublicTokenManager = ({\n  backendURL,\n  clientId,\n}: PublicTokenManagerOptions): PublicTokenManager => {\n  const endpoint = `${backendURL.replace(/\\/$/, '')}/api/public/token`;\n\n  let cached: CachedToken | null = null;\n  let pendingExchange: Promise<void> | null = null;\n\n  const isUsable = (candidate: CachedToken | null): candidate is CachedToken =>\n    candidate !== null && candidate.expiresAt - EXPIRY_MARGIN_MS > Date.now();\n\n  const getToken = (): string | undefined => {\n    if (isUsable(cached)) return cached.token;\n\n    if (typeof window !== 'undefined') {\n      const stored = readStoredToken();\n      if (isUsable(stored)) {\n        cached = stored;\n        return stored.token;\n      }\n    }\n\n    return undefined;\n  };\n\n  const exchange = async (): Promise<void> => {\n    try {\n      const response = await fetch(endpoint, {\n        method: 'POST',\n        headers: { 'Content-Type': 'application/json' },\n        body: JSON.stringify({ clientId }),\n        // The exchange is authorised by `Origin`, never by cookies.\n        credentials: 'omit',\n        mode: 'cors',\n      });\n\n      if (!response.ok) return;\n\n      const payload = (await response.json()) as {\n        data?: { token?: string | null; expiresIn?: number };\n      };\n\n      const token = payload?.data?.token;\n      const expiresIn = payload?.data?.expiresIn ?? 0;\n\n      // A `null` token means the key is unknown or the origin is not allowed.\n      if (!token || expiresIn <= 0) return;\n\n      cached = { token, expiresAt: Date.now() + expiresIn * 1000 };\n\n      if (typeof window !== 'undefined') writeStoredToken(cached);\n    } catch {\n      /* swallow — best-effort, the `clientId` fallback still reports */\n    } finally {\n      pendingExchange = null;\n    }\n  };\n\n  const prime = (): void => {\n    if (!clientId || typeof fetch !== 'function') return;\n    if (getToken()) return;\n    if (pendingExchange) return;\n\n    pendingExchange = exchange();\n  };\n\n  return { getToken, prime };\n};\n"],"mappings":";;;;;;;;;;;;;;;AAeA,MAAM,oBAAoB;;;;;AAM1B,MAAM,mBAAmB;;AASzB,MAAM,wBAA4C;CAChD,IAAI;EACF,MAAM,MAAM,OAAO,gBAAgB,QAAQ,iBAAiB;EAC5D,IAAI,CAAC,KAAK,OAAO;EAEjB,MAAM,SAAS,KAAK,MAAM,GAAG;EAE7B,IAAI,OAAO,QAAQ,UAAU,UAAU,OAAO;EAC9C,IAAI,OAAO,QAAQ,cAAc,UAAU,OAAO;EAElD,OAAO;CACT,QAAQ;EAEN,OAAO;CACT;AACF;;AAGA,MAAM,oBAAoB,WAA8B;CACtD,IAAI;EACF,OAAO,gBAAgB,QAAQ,mBAAmB,KAAK,UAAU,MAAM,CAAC;CAC1E,QAAQ,CAER;AACF;;;;;;;;;;;AAkCA,MAAa,4BAA4B,EACvC,YACA,eACmD;CACnD,MAAM,WAAW,GAAG,WAAW,QAAQ,OAAO,EAAE,EAAE;CAElD,IAAI,SAA6B;CACjC,IAAI,kBAAwC;CAE5C,MAAM,YAAY,cAChB,cAAc,QAAQ,UAAU,YAAY,mBAAmB,KAAK,IAAI;CAE1E,MAAM,iBAAqC;EACzC,IAAI,SAAS,MAAM,GAAG,OAAO,OAAO;EAEpC,IAAI,OAAO,WAAW,aAAa;GACjC,MAAM,SAAS,gBAAgB;GAC/B,IAAI,SAAS,MAAM,GAAG;IACpB,SAAS;IACT,OAAO,OAAO;GAChB;EACF;CAGF;CAEA,MAAM,WAAW,YAA2B;EAC1C,IAAI;GACF,MAAM,WAAW,MAAM,MAAM,UAAU;IACrC,QAAQ;IACR,SAAS,EAAE,gBAAgB,mBAAmB;IAC9C,MAAM,KAAK,UAAU,EAAE,SAAS,CAAC;IAEjC,aAAa;IACb,MAAM;GACR,CAAC;GAED,IAAI,CAAC,SAAS,IAAI;GAElB,MAAM,UAAW,MAAM,SAAS,KAAK;GAIrC,MAAM,QAAQ,SAAS,MAAM;GAC7B,MAAM,YAAY,SAAS,MAAM,aAAa;GAG9C,IAAI,CAAC,SAAS,aAAa,GAAG;GAE9B,SAAS;IAAE;IAAO,WAAW,KAAK,IAAI,IAAI,YAAY;GAAK;GAE3D,IAAI,OAAO,WAAW,aAAa,iBAAiB,MAAM;EAC5D,QAAQ,CAER,UAAU;GACR,kBAAkB;EACpB;CACF;CAEA,MAAM,cAAoB;EACxB,IAAI,CAAC,YAAY,OAAO,UAAU,YAAY;EAC9C,IAAI,SAAS,GAAG;EAChB,IAAI,iBAAiB;EAErB,kBAAkB,SAAS;CAC7B;CAEA,OAAO;EAAE;EAAU;CAAM;AAC3B"}

package/dist/esm/core/transport.mjs

@@ -17,16 +17,22 @@
 * @param body - The batched payload.
 * @param options - Transport options.
 * @param options.useBeacon - Prefer `sendBeacon` (used when the page is hiding).
+* @param options.token - Ingest token, sent as a bearer on the `fetch` path.
+*   `sendBeacon` cannot set headers, which is why the token is also carried in
+*   the body.
 * @returns `true` when a send was dispatched, `false` otherwise.
 */
-const sendEvents = (endpoint, body, { useBeacon = false } = {}) => {
+const sendEvents = (endpoint, body, { useBeacon = false, token } = {}) => {
 	try {
 		const payload = JSON.stringify(body);
 		if (useBeacon && typeof navigator !== "undefined" && typeof navigator.sendBeacon === "function") return navigator.sendBeacon(endpoint, payload);
 		if (typeof fetch === "function") {
 			fetch(endpoint, {
 				method: "POST",
-				headers: { "Content-Type": "application/json" },
+				headers: {
+					"Content-Type": "application/json",
+					...token ? { Authorization: `Bearer ${token}` } : {}
+				},
 				body: payload,
 				keepalive: true,
 				credentials: "omit",

package/dist/esm/core/transport.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"transport.mjs","names":[],"sources":["../../../src/core/transport.ts"],"sourcesContent":["import type { AnalyticsIngestBody } from './types';\n\n/**\n * Sends a batch of events to the backend. Every path is non-blocking and\n * no-throw — analytics must never break, slow, or delay the host application.\n *\n * Strategy:\n * 1. `navigator.sendBeacon` for the flush-on-hide path — survives page unload\n *    and never blocks navigation. The payload is sent as `text/plain` (a\n *    CORS-safelisted content type): a JSON `Blob` would require a CORS\n *    preflight that browsers handle inconsistently during unload, silently\n *    dropping the beacon. The backend parses `text/plain` bodies as JSON.\n * 2. `fetch(..., { keepalive: true })` for interval flushes — survives short\n *    navigations without holding the main thread.\n * 3. Plain `fetch` fallback for runtimes without `keepalive` (older RN/Lynx).\n *\n * @param endpoint - Fully-qualified ingestion URL.\n * @param body - The batched payload.\n * @param options - Transport options.\n * @param options.useBeacon - Prefer `sendBeacon` (used when the page is hiding).\n * @returns `true` when a send was dispatched, `false` otherwise.\n */\nexport const sendEvents = (\n  endpoint: string,\n  body: AnalyticsIngestBody,\n  { useBeacon = false }: { useBeacon?: boolean } = {}\n): boolean => {\n  try {\n    const payload = JSON.stringify(body);\n\n    if (\n      useBeacon &&\n      typeof navigator !== 'undefined' &&\n      typeof navigator.sendBeacon === 'function'\n    ) {\n      // Note: unlike the fetch path below, sendBeacon always includes\n      // credentials; the ingest endpoint ignores them.\n      return navigator.sendBeacon(endpoint, payload);\n    }\n\n    if (typeof fetch === 'function') {\n      // keepalive lets the request outlive a same-tab navigation.\n      void fetch(endpoint, {\n        method: 'POST',\n        headers: { 'Content-Type': 'application/json' },\n        body: payload,\n        keepalive: true,\n        // Analytics is best-effort; never send credentials.\n        credentials: 'omit',\n        mode: 'cors',\n      }).catch(() => {\n        /* swallow — best-effort delivery */\n      });\n      return true;\n    }\n\n    return false;\n  } catch {\n    // JSON serialization failed — drop the batch silently.\n    return false;\n  }\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAsBA,MAAa,cACX,UACA,MACA,EAAE,YAAY,UAAmC,CAAC,MACtC;CACZ,IAAI;EACF,MAAM,UAAU,KAAK,UAAU,IAAI;EAEnC,IACE,aACA,OAAO,cAAc,eACrB,OAAO,UAAU,eAAe,YAIhC,OAAO,UAAU,WAAW,UAAU,OAAO;EAG/C,IAAI,OAAO,UAAU,YAAY;GAE/B,AAAK,MAAM,UAAU;IACnB,QAAQ;IACR,SAAS,EAAE,gBAAgB,mBAAmB;IAC9C,MAAM;IACN,WAAW;IAEX,aAAa;IACb,MAAM;GACR,CAAC,CAAC,CAAC,YAAY,CAEf,CAAC;GACD,OAAO;EACT;EAEA,OAAO;CACT,QAAQ;EAEN,OAAO;CACT;AACF"}
+{"version":3,"file":"transport.mjs","names":[],"sources":["../../../src/core/transport.ts"],"sourcesContent":["import type { AnalyticsIngestBody } from './types';\n\n/**\n * Sends a batch of events to the backend. Every path is non-blocking and\n * no-throw — analytics must never break, slow, or delay the host application.\n *\n * Strategy:\n * 1. `navigator.sendBeacon` for the flush-on-hide path — survives page unload\n *    and never blocks navigation. The payload is sent as `text/plain` (a\n *    CORS-safelisted content type): a JSON `Blob` would require a CORS\n *    preflight that browsers handle inconsistently during unload, silently\n *    dropping the beacon. The backend parses `text/plain` bodies as JSON.\n * 2. `fetch(..., { keepalive: true })` for interval flushes — survives short\n *    navigations without holding the main thread.\n * 3. Plain `fetch` fallback for runtimes without `keepalive` (older RN/Lynx).\n *\n * @param endpoint - Fully-qualified ingestion URL.\n * @param body - The batched payload.\n * @param options - Transport options.\n * @param options.useBeacon - Prefer `sendBeacon` (used when the page is hiding).\n * @param options.token - Ingest token, sent as a bearer on the `fetch` path.\n *   `sendBeacon` cannot set headers, which is why the token is also carried in\n *   the body.\n * @returns `true` when a send was dispatched, `false` otherwise.\n */\nexport const sendEvents = (\n  endpoint: string,\n  body: AnalyticsIngestBody,\n  { useBeacon = false, token }: { useBeacon?: boolean; token?: string } = {}\n): boolean => {\n  try {\n    const payload = JSON.stringify(body);\n\n    if (\n      useBeacon &&\n      typeof navigator !== 'undefined' &&\n      typeof navigator.sendBeacon === 'function'\n    ) {\n      // Note: unlike the fetch path below, sendBeacon always includes\n      // credentials; the ingest endpoint ignores them.\n      return navigator.sendBeacon(endpoint, payload);\n    }\n\n    if (typeof fetch === 'function') {\n      // keepalive lets the request outlive a same-tab navigation.\n      void fetch(endpoint, {\n        method: 'POST',\n        headers: {\n          'Content-Type': 'application/json',\n          ...(token ? { Authorization: `Bearer ${token}` } : {}),\n        },\n        body: payload,\n        keepalive: true,\n        // Analytics is best-effort; never send credentials.\n        credentials: 'omit',\n        mode: 'cors',\n      }).catch(() => {\n        /* swallow — best-effort delivery */\n      });\n      return true;\n    }\n\n    return false;\n  } catch {\n    // JSON serialization failed — drop the batch silently.\n    return false;\n  }\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAyBA,MAAa,cACX,UACA,MACA,EAAE,YAAY,OAAO,UAAmD,CAAC,MAC7D;CACZ,IAAI;EACF,MAAM,UAAU,KAAK,UAAU,IAAI;EAEnC,IACE,aACA,OAAO,cAAc,eACrB,OAAO,UAAU,eAAe,YAIhC,OAAO,UAAU,WAAW,UAAU,OAAO;EAG/C,IAAI,OAAO,UAAU,YAAY;GAE/B,AAAK,MAAM,UAAU;IACnB,QAAQ;IACR,SAAS;KACP,gBAAgB;KAChB,GAAI,QAAQ,EAAE,eAAe,UAAU,QAAQ,IAAI,CAAC;IACtD;IACA,MAAM;IACN,WAAW;IAEX,aAAa;IACb,MAAM;GACR,CAAC,CAAC,CAAC,YAAY,CAEf,CAAC;GACD,OAAO;EACT;EAEA,OAAO;CACT,QAAQ;EAEN,OAAO;CACT;AACF"}

package/dist/esm/index.mjs

@@ -1,3 +1,4 @@
+import { BOT_USER_AGENT_PATTERN, isBotEnvironment, isBotUserAgent } from "./utils/isBot.mjs";
 import { assignVariant } from "./core/abTesting.mjs";
 import { createEventBuffer } from "./core/eventBuffer.mjs";
 import { isSampledIn } from "./core/sampling.mjs";
@@ -8,4 +9,4 @@ import { decrementAnalyticsClientRefCount, getGlobalAnalyticsClient, incrementAn
 import { initAnalyticsClient, stopAnalyticsClient } from "./core/initAnalyticsClient.mjs";
 import { buildContentExposure, serializeKeyPath } from "./events/contentExposure.mjs";
 
-export { DEFAULT_FLUSH_INTERVAL, DEFAULT_MAX_BUFFER_SIZE, DEFAULT_SAMPLE_RATE, MAX_EVENTS_PER_SEND, assignVariant, buildContentExposure, createAnalyticsClient, createEventBuffer, decrementAnalyticsClientRefCount, getGlobalAnalyticsClient, getSessionId, incrementAnalyticsClientRefCount, initAnalyticsClient, isSampledIn, sendEvents, serializeKeyPath, setGlobalAnalyticsClient, stopAnalyticsClient };
+export { BOT_USER_AGENT_PATTERN, DEFAULT_FLUSH_INTERVAL, DEFAULT_MAX_BUFFER_SIZE, DEFAULT_SAMPLE_RATE, MAX_EVENTS_PER_SEND, assignVariant, buildContentExposure, createAnalyticsClient, createEventBuffer, decrementAnalyticsClientRefCount, getGlobalAnalyticsClient, getSessionId, incrementAnalyticsClientRefCount, initAnalyticsClient, isBotEnvironment, isBotUserAgent, isSampledIn, sendEvents, serializeKeyPath, setGlobalAnalyticsClient, stopAnalyticsClient };

package/dist/esm/isEnabled.mjs

@@ -1,3 +1,4 @@
+import { isBotEnvironment } from "./utils/isBot.mjs";
 import { analytics, editor } from "@intlayer/config/built";
 
 //#region src/isEnabled.ts
@@ -20,9 +21,10 @@ const TREE_SHAKE_ANALYTICS = process.env.INTLAYER_ANALYTICS_ENABLED === "false";
 * - the user did not opt out (`analytics.enabled === true`, the default), and
 * - a project key is configured (`editor.clientId`), and
 * - we are on the client, and
-* - we are the top window (not embedded in the editor).
+* - we are the top window (not embedded in the editor), and
+* - the visitor is not a bot, crawler or automation runtime.
 */
-const isEnabled = !TREE_SHAKE_ANALYTICS && analytics?.enabled === true && Boolean(editor?.clientId) && typeof window !== "undefined" && window.self === window.top;
+const isEnabled = !TREE_SHAKE_ANALYTICS && analytics?.enabled === true && Boolean(editor?.clientId) && typeof window !== "undefined" && window.self === window.top && !isBotEnvironment();
 
 //#endregion
 export { isEnabled };

package/dist/esm/isEnabled.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"isEnabled.mjs","names":[],"sources":["../../src/isEnabled.ts"],"sourcesContent":["import { analytics, editor } from '@intlayer/config/built';\n\n/**\n * Compile-time kill switch. Bundlers replace `process.env.INTLAYER_ANALYTICS_ENABLED`\n * (set to `'false'` by `@intlayer/config` unless `analytics.enabled` is `true`\n * — the default once this package is installed — AND an `editor.clientId` is\n * configured) so the whole analytics integration is dead-code-eliminated for\n * apps that opted out.\n */\nconst TREE_SHAKE_ANALYTICS = process.env.INTLAYER_ANALYTICS_ENABLED === 'false';\n\n/**\n * Runtime guard mirroring `@intlayer/editor`'s `isEnabled`, but inverted with\n * respect to the iframe: analytics runs for real end users on the **top**\n * window and stays off inside the editor/CMS preview iframe so editor sessions\n * are never counted as traffic.\n *\n * Enabled when:\n * - the bundler did not tree-shake analytics away, and\n * - the user did not opt out (`analytics.enabled === true`, the default), and\n * - a project key is configured (`editor.clientId`), and\n * - we are on the client, and\n * - we are the top window (not embedded in the editor).\n */\nexport const isEnabled =\n  !TREE_SHAKE_ANALYTICS &&\n  analytics?.enabled === true &&\n  Boolean(editor?.clientId) &&\n  typeof window !== 'undefined' &&\n  window.self === window.top;\n"],"mappings":";;;;;;;;;;AASA,MAAM,uBAAuB,QAAQ,IAAI,+BAA+B;;;;;;;;;;;;;;AAexE,MAAa,YACX,CAAC,wBACD,WAAW,YAAY,QACvB,QAAQ,QAAQ,QAAQ,KACxB,OAAO,WAAW,eAClB,OAAO,SAAS,OAAO"}
+{"version":3,"file":"isEnabled.mjs","names":[],"sources":["../../src/isEnabled.ts"],"sourcesContent":["import { analytics, editor } from '@intlayer/config/built';\nimport { isBotEnvironment } from './utils/isBot';\n\n/**\n * Compile-time kill switch. Bundlers replace `process.env.INTLAYER_ANALYTICS_ENABLED`\n * (set to `'false'` by `@intlayer/config` unless `analytics.enabled` is `true`\n * — the default once this package is installed — AND an `editor.clientId` is\n * configured) so the whole analytics integration is dead-code-eliminated for\n * apps that opted out.\n */\nconst TREE_SHAKE_ANALYTICS = process.env.INTLAYER_ANALYTICS_ENABLED === 'false';\n\n/**\n * Runtime guard mirroring `@intlayer/editor`'s `isEnabled`, but inverted with\n * respect to the iframe: analytics runs for real end users on the **top**\n * window and stays off inside the editor/CMS preview iframe so editor sessions\n * are never counted as traffic.\n *\n * Enabled when:\n * - the bundler did not tree-shake analytics away, and\n * - the user did not opt out (`analytics.enabled === true`, the default), and\n * - a project key is configured (`editor.clientId`), and\n * - we are on the client, and\n * - we are the top window (not embedded in the editor), and\n * - the visitor is not a bot, crawler or automation runtime.\n */\nexport const isEnabled =\n  !TREE_SHAKE_ANALYTICS &&\n  analytics?.enabled === true &&\n  Boolean(editor?.clientId) &&\n  typeof window !== 'undefined' &&\n  window.self === window.top &&\n  !isBotEnvironment();\n"],"mappings":";;;;;;;;;;;AAUA,MAAM,uBAAuB,QAAQ,IAAI,+BAA+B;;;;;;;;;;;;;;;AAgBxE,MAAa,YACX,CAAC,wBACD,WAAW,YAAY,QACvB,QAAQ,QAAQ,QAAQ,KACxB,OAAO,WAAW,eAClB,OAAO,SAAS,OAAO,OACvB,CAAC,iBAAiB"}

package/dist/esm/utils/isBot.mjs

@@ -0,0 +1,86 @@
+//#region src/utils/isBot.ts
+/**
+* Bot / automation detection.
+*
+* Analytics must describe real people. Crawlers, link-preview fetchers, uptime
+* monitors, AI agents and CI browsers (Lighthouse, Playwright, Puppeteer) all
+* execute JavaScript nowadays, so they would otherwise be counted as visitors
+* and inflate page views, content exposures and A/B conversion rates.
+*
+* Everything here is a pure string/environment check — no network, no storage.
+*/
+/**
+* User agents that look like a bot but belong to real user devices, checked
+* before {@link BOT_USER_AGENT_PATTERN}. `CUBOT` is an Android phone brand
+* whose model strings (`CUBOT_X19`) contain the `bot` token.
+*/
+const HUMAN_USER_AGENT_EXCEPTION_PATTERN = /cubot/i;
+/**
+* Matches known non-human user agents. Grouped by family so the list stays
+* reviewable:
+* - generic tokens (`…bot`, `crawler`, `spider`, `scraper`)
+* - HTTP clients used by scripts (curl, wget, requests, axios…)
+* - headless / automation runtimes (Playwright, Puppeteer, Lighthouse…)
+* - search-engine and SEO crawlers
+* - social link-preview fetchers
+* - AI / LLM crawlers and agents
+*/
+const BOT_USER_AGENT_PATTERN = /bot\b|bot[/\-\s]|crawler|crawling|spider|scraper|slurp|archiver|feedfetcher|validator|curl\/|wget\/|python-requests|python-urllib|okhttp|axios\/|node-fetch|got \(|go-http-client|java\/|libwww|httpunit|http_request|apache-httpclient|headless|phantomjs|puppeteer|playwright|selenium|webdriver|cypress|lighthouse|pagespeed|gtmetrix|prerender|pingdom|uptime|statuscake|site24x7|bingpreview|yandex|baiduspider|sogou|exabot|semrush|ahrefs|mj12|dotbot|petalbot|applebot|amazonbot|bytespider|facebookexternalhit|meta-externalagent|embedly|outbrain|quora link preview|skypeuripreview|vkshare|w3c_validator|apis-google|mediapartners|adsbot|storebot-google|google-inspectiontool|google-read-aloud|google-extended|duplexweb-google|gptbot|oai-searchbot|chatgpt-user|perplexity|claudebot|claude-web|anthropic-ai|cohere-ai|ccbot|diffbot|imagesift|omgili|timpi|youbot/i;
+/**
+* Tells whether a user agent string identifies a bot, crawler or automation
+* runtime rather than a human visitor.
+*
+* A missing or empty user agent is treated as a bot: every real browser sends
+* one, so its absence means a script or a forged request.
+*
+* @param userAgent - The raw `User-Agent` string (header or `navigator.userAgent`).
+* @returns `true` when the traffic must not be recorded.
+*
+* @example
+* isBotUserAgent('Mozilla/5.0 (compatible; Googlebot/2.1)'); // true
+* isBotUserAgent('Mozilla/5.0 (Macintosh) Chrome/120'); // false
+*/
+const isBotUserAgent = (userAgent) => {
+	if (!userAgent) return true;
+	if (HUMAN_USER_AGENT_EXCEPTION_PATTERN.test(userAgent)) return false;
+	return BOT_USER_AGENT_PATTERN.test(userAgent);
+};
+/**
+* Globals injected by automation runtimes. Their mere presence means the page
+* is driven by a script, whatever the user agent claims.
+*/
+const AUTOMATION_GLOBAL_KEYS = [
+	"_phantom",
+	"__nightmare",
+	"callPhantom",
+	"__selenium_unwrapped",
+	"__webdriver_evaluate",
+	"__driver_evaluate",
+	"domAutomation",
+	"Cypress"
+];
+/**
+* Tells whether the current browser environment is automated, combining the
+* user agent with automation fingerprints (`navigator.webdriver`, runtime
+* globals) that headless browsers spoofing a normal user agent still expose.
+*
+* Always `false` outside a browser (SSR): there is nothing to collect there,
+* and the server must not disable a client that has not run yet.
+*
+* @returns `true` when analytics must stay off for this environment.
+*
+* @example
+* if (isBotEnvironment()) return; // never start the client for a crawler
+*/
+const isBotEnvironment = () => {
+	if (typeof navigator === "undefined") return false;
+	if (navigator.webdriver === true) return true;
+	const automationGlobals = globalThis;
+	if (AUTOMATION_GLOBAL_KEYS.some((key) => key in automationGlobals)) return true;
+	if (!navigator.userAgent) return false;
+	return isBotUserAgent(navigator.userAgent);
+};
+
+//#endregion
+export { BOT_USER_AGENT_PATTERN, isBotEnvironment, isBotUserAgent };
+//# sourceMappingURL=isBot.mjs.map

package/dist/esm/utils/isBot.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"isBot.mjs","names":[],"sources":["../../../src/utils/isBot.ts"],"sourcesContent":["/**\n * Bot / automation detection.\n *\n * Analytics must describe real people. Crawlers, link-preview fetchers, uptime\n * monitors, AI agents and CI browsers (Lighthouse, Playwright, Puppeteer) all\n * execute JavaScript nowadays, so they would otherwise be counted as visitors\n * and inflate page views, content exposures and A/B conversion rates.\n *\n * Everything here is a pure string/environment check — no network, no storage.\n */\n\n/**\n * User agents that look like a bot but belong to real user devices, checked\n * before {@link BOT_USER_AGENT_PATTERN}. `CUBOT` is an Android phone brand\n * whose model strings (`CUBOT_X19`) contain the `bot` token.\n */\nconst HUMAN_USER_AGENT_EXCEPTION_PATTERN = /cubot/i;\n\n/**\n * Matches known non-human user agents. Grouped by family so the list stays\n * reviewable:\n * - generic tokens (`…bot`, `crawler`, `spider`, `scraper`)\n * - HTTP clients used by scripts (curl, wget, requests, axios…)\n * - headless / automation runtimes (Playwright, Puppeteer, Lighthouse…)\n * - search-engine and SEO crawlers\n * - social link-preview fetchers\n * - AI / LLM crawlers and agents\n */\nexport const BOT_USER_AGENT_PATTERN =\n  /bot\\b|bot[/\\-\\s]|crawler|crawling|spider|scraper|slurp|archiver|feedfetcher|validator|curl\\/|wget\\/|python-requests|python-urllib|okhttp|axios\\/|node-fetch|got \\(|go-http-client|java\\/|libwww|httpunit|http_request|apache-httpclient|headless|phantomjs|puppeteer|playwright|selenium|webdriver|cypress|lighthouse|pagespeed|gtmetrix|prerender|pingdom|uptime|statuscake|site24x7|bingpreview|yandex|baiduspider|sogou|exabot|semrush|ahrefs|mj12|dotbot|petalbot|applebot|amazonbot|bytespider|facebookexternalhit|meta-externalagent|embedly|outbrain|quora link preview|skypeuripreview|vkshare|w3c_validator|apis-google|mediapartners|adsbot|storebot-google|google-inspectiontool|google-read-aloud|google-extended|duplexweb-google|gptbot|oai-searchbot|chatgpt-user|perplexity|claudebot|claude-web|anthropic-ai|cohere-ai|ccbot|diffbot|imagesift|omgili|timpi|youbot/i;\n\n/**\n * Tells whether a user agent string identifies a bot, crawler or automation\n * runtime rather than a human visitor.\n *\n * A missing or empty user agent is treated as a bot: every real browser sends\n * one, so its absence means a script or a forged request.\n *\n * @param userAgent - The raw `User-Agent` string (header or `navigator.userAgent`).\n * @returns `true` when the traffic must not be recorded.\n *\n * @example\n * isBotUserAgent('Mozilla/5.0 (compatible; Googlebot/2.1)'); // true\n * isBotUserAgent('Mozilla/5.0 (Macintosh) Chrome/120'); // false\n */\nexport const isBotUserAgent = (userAgent?: string | null): boolean => {\n  if (!userAgent) return true;\n  if (HUMAN_USER_AGENT_EXCEPTION_PATTERN.test(userAgent)) return false;\n\n  return BOT_USER_AGENT_PATTERN.test(userAgent);\n};\n\n/**\n * Globals injected by automation runtimes. Their mere presence means the page\n * is driven by a script, whatever the user agent claims.\n */\nconst AUTOMATION_GLOBAL_KEYS = [\n  '_phantom',\n  '__nightmare',\n  'callPhantom',\n  '__selenium_unwrapped',\n  '__webdriver_evaluate',\n  '__driver_evaluate',\n  'domAutomation',\n  'Cypress',\n] as const;\n\n/**\n * Tells whether the current browser environment is automated, combining the\n * user agent with automation fingerprints (`navigator.webdriver`, runtime\n * globals) that headless browsers spoofing a normal user agent still expose.\n *\n * Always `false` outside a browser (SSR): there is nothing to collect there,\n * and the server must not disable a client that has not run yet.\n *\n * @returns `true` when analytics must stay off for this environment.\n *\n * @example\n * if (isBotEnvironment()) return; // never start the client for a crawler\n */\nexport const isBotEnvironment = (): boolean => {\n  if (typeof navigator === 'undefined') return false;\n\n  if (navigator.webdriver === true) return true;\n\n  const automationGlobals = globalThis as unknown as Record<string, unknown>;\n  if (AUTOMATION_GLOBAL_KEYS.some((key) => key in automationGlobals)) {\n    return true;\n  }\n\n  // Unlike a server reading the `User-Agent` header, an absent user agent here\n  // means a non-browser runtime (React Native, Lynx) — a real app, not a bot.\n  if (!navigator.userAgent) return false;\n\n  return isBotUserAgent(navigator.userAgent);\n};\n"],"mappings":";;;;;;;;;;;;;;;;AAgBA,MAAM,qCAAqC;;;;;;;;;;;AAY3C,MAAa,yBACX;;;;;;;;;;;;;;;AAgBF,MAAa,kBAAkB,cAAuC;CACpE,IAAI,CAAC,WAAW,OAAO;CACvB,IAAI,mCAAmC,KAAK,SAAS,GAAG,OAAO;CAE/D,OAAO,uBAAuB,KAAK,SAAS;AAC9C;;;;;AAMA,MAAM,yBAAyB;CAC7B;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF;;;;;;;;;;;;;;AAeA,MAAa,yBAAkC;CAC7C,IAAI,OAAO,cAAc,aAAa,OAAO;CAE7C,IAAI,UAAU,cAAc,MAAM,OAAO;CAEzC,MAAM,oBAAoB;CAC1B,IAAI,uBAAuB,MAAM,QAAQ,OAAO,iBAAiB,GAC/D,OAAO;CAKT,IAAI,CAAC,UAAU,WAAW,OAAO;CAEjC,OAAO,eAAe,UAAU,SAAS;AAC3C"}

package/dist/types/core/AnalyticsClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AnalyticsClient.d.ts","names":[],"sources":["../../../src/core/AnalyticsClient.ts"],"mappings":";;;;;;KAmBY;;EAEV;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA,SAAS;;;cAIE;;cAEA;;cAEA;;;;;cAKA;;;;;KAQD;;EAEV,YAAY;;EAEZ,gBAAgB,QAAQ;;EAExB,uBACE,OAAO,KAAK,eAAe;;EAG7B,kBACE,OAAO,KAAK,eAAe;;EAG7B,aACE,uBACA,oBACA;;EAGF,QAAQ;;EAER;;EAEA;;;;;;;;;cA+BW,wBAAqB,QACxB,0BACP"}
+{"version":3,"file":"AnalyticsClient.d.ts","names":[],"sources":["../../../src/core/AnalyticsClient.ts"],"mappings":";;;;;;KAqBY;;EAEV;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA,SAAS;;;cAIE;;cAEA;;cAEA;;;;;cAKA;;;;;KAQD;;EAEV,YAAY;;EAEZ,gBAAgB,QAAQ;;EAExB,uBACE,OAAO,KAAK,eAAe;;EAG7B,kBACE,OAAO,KAAK,eAAe;;EAG7B,aACE,uBACA,oBACA;;EAGF,QAAQ;;EAER;;EAEA;;;;;;;;;cA+BW,wBAAqB,QACxB,0BACP"}

package/dist/types/core/publicToken.d.ts

@@ -0,0 +1,48 @@
+//#region src/core/publicToken.d.ts
+/**
+ * Short-lived ingest token used to authorise analytics batches.
+ *
+ * The SDK runs in the browser, where no confidential credential can be kept, so
+ * it exchanges the project's **public** `clientId` for a token scoped to
+ * analytics ingestion and nothing else. The backend authorises the exchange by
+ * the request's `Origin`, which the page cannot forge.
+ *
+ * The token is read synchronously at flush time — the flush-on-hide path runs
+ * during `pagehide` and cannot await anything — so it is fetched ahead of time
+ * and cached, both in memory and in `sessionStorage` so a multi-page visit
+ * exchanges once per tab rather than once per navigation.
+ */
+/** Options accepted by {@link createPublicTokenManager}. */
+type PublicTokenManagerOptions = {
+  /** Backend base URL, without a trailing slash. */
+  backendURL: string;
+  /** The project's public key (`editor.clientId`). */
+  clientId?: string;
+};
+/** Synchronous accessor + background refresher for the ingest token. */
+type PublicTokenManager = {
+  /**
+   * The currently valid token, or `undefined` when none has been obtained yet.
+   * Never blocks and never triggers a request.
+   */
+  getToken: () => string | undefined;
+  /**
+   * Ensures a valid token is being fetched. Safe to call repeatedly:
+   * concurrent calls share a single in-flight exchange.
+   */
+  prime: () => void;
+};
+/**
+ * Creates the ingest token manager for a project.
+ *
+ * Every failure path is silent: analytics must never break, slow, or log noise
+ * into the host application. Without a token the client falls back to sending
+ * its public `clientId`, which the backend still accepts.
+ *
+ * @param options - Backend URL and the public project key.
+ * @returns A manager exposing a synchronous {@link PublicTokenManager.getToken}.
+ */
+declare const createPublicTokenManager: ({ backendURL, clientId }: PublicTokenManagerOptions) => PublicTokenManager;
+//#endregion
+export { PublicTokenManager, PublicTokenManagerOptions, createPublicTokenManager };
+//# sourceMappingURL=publicToken.d.ts.map

package/dist/types/core/publicToken.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publicToken.d.ts","names":[],"sources":["../../../src/core/publicToken.ts"],"mappings":";;;;;;;;;;;;;;;KAyDY;;EAEV;;EAEA;;;KAIU;;;;;EAKV;;;;;EAKA;;;;;;;;;;;;cAaW,6BAAwB,YAAA,YAGlC,8BAA4B"}

package/dist/types/core/transport.d.ts

@@ -18,10 +18,14 @@ import { AnalyticsIngestBody } from "./types.js";
  * @param body - The batched payload.
  * @param options - Transport options.
  * @param options.useBeacon - Prefer `sendBeacon` (used when the page is hiding).
+ * @param options.token - Ingest token, sent as a bearer on the `fetch` path.
+ *   `sendBeacon` cannot set headers, which is why the token is also carried in
+ *   the body.
  * @returns `true` when a send was dispatched, `false` otherwise.
  */
-declare const sendEvents: (endpoint: string, body: AnalyticsIngestBody, { useBeacon }?: {
+declare const sendEvents: (endpoint: string, body: AnalyticsIngestBody, { useBeacon, token }?: {
   useBeacon?: boolean;
+  token?: string;
 }) => boolean;
 //#endregion
 export { sendEvents };

package/dist/types/core/transport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transport.d.ts","names":[],"sources":["../../../src/core/transport.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;cAsBa,aAAU,kBACL,MACV,uBAAmB;EACA"}
+{"version":3,"file":"transport.d.ts","names":[],"sources":["../../../src/core/transport.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;cAyBa,aAAU,kBACL,MACV,uBAAmB,WAAA;EACO;EAAqB"}

package/dist/types/core/types.d.ts

@@ -84,7 +84,18 @@ type TrackableEvent<E extends AnalyticsEvent = AnalyticsEvent> = Omit<E, 't' | '
  * The batched request body sent to `POST /api/analytics/events`.
  */
 type AnalyticsIngestBody = {
-  /** Public project key — reused from `editor.clientId`. */
+  /**
+   * Short-lived, ingest-scoped token obtained by exchanging the public
+   * `clientId`. Sent in the body rather than an `Authorization` header because
+   * the flush-on-hide path uses `navigator.sendBeacon`, which cannot set
+   * headers; the `fetch` path sends it both ways.
+   */
+  token?: string;
+  /**
+   * Public project key — reused from `editor.clientId`. Sent only until the
+   * token exchange resolves, so a batch collected on the very first page view
+   * is still attributed.
+   */
   clientId?: string;
   /** Anonymous per-tab session identifier (new tab ⇒ new id; never durable). */
   sessionId: string;

package/dist/types/core/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/core/types.ts"],"mappings":";;;;;;;;;KASY;;;;KAQA;;EAEV;;EAEA;;EAEA;;;;;;KAOU,gBAAgB;EAC1B;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;KAQU,uBAAuB;EACjC;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;;;;KAMU,kBAAkB;EAC5B;;EAEA;;EAEA;;EAEA;;EAEA;;;;;KAMU,iBACR,gBACA,uBACA;;;;;KAMQ,eAAe,UAAU,iBAAiB,kBAAkB,KACtE;;EAIA;;;;;KAMU;;EAEV;;EAEA;;EAEA;;EAEA,QAAQ;;;;;;KAOE;;EAEV;;EAEA;;EAEA;;EAEA;;EAEA"}
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/core/types.ts"],"mappings":";;;;;;;;;KASY;;;;KAQA;;EAEV;;EAEA;;EAEA;;;;;;KAOU,gBAAgB;EAC1B;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;KAQU,uBAAuB;EACjC;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;;;;KAMU,kBAAkB;EAC5B;;EAEA;;EAEA;;EAEA;;EAEA;;;;;KAMU,iBACR,gBACA,uBACA;;;;;KAMQ,eAAe,UAAU,iBAAiB,kBAAkB,KACtE;;EAIA;;;;;KAMU;;;;;;;EAOV;;;;;;EAMA;;EAEA;;EAEA;;EAEA,QAAQ;;;;;;KAOE;;EAEV;;EAEA;;EAEA;;EAEA;;EAEA"}

package/dist/types/index.d.ts

@@ -8,4 +8,5 @@ import { isSampledIn } from "./core/sampling.js";
 import { getSessionId } from "./core/session.js";
 import { sendEvents } from "./core/transport.js";
 import { buildContentExposure, serializeKeyPath } from "./events/contentExposure.js";
-export { AnalyticsClient, AnalyticsClientConfig, AnalyticsEvent, AnalyticsEventType, AnalyticsIngestBody, BaseAnalyticsEvent, ContentExposureEvent, ConversionEvent, DEFAULT_FLUSH_INTERVAL, DEFAULT_MAX_BUFFER_SIZE, DEFAULT_SAMPLE_RATE, EventBuffer, MAX_EVENTS_PER_SEND, PageViewEvent, PageViewInput, TrackableEvent, assignVariant, buildContentExposure, createAnalyticsClient, createEventBuffer, decrementAnalyticsClientRefCount, getGlobalAnalyticsClient, getSessionId, incrementAnalyticsClientRefCount, initAnalyticsClient, isSampledIn, sendEvents, serializeKeyPath, setGlobalAnalyticsClient, stopAnalyticsClient };
+import { BOT_USER_AGENT_PATTERN, isBotEnvironment, isBotUserAgent } from "./utils/isBot.js";
+export { AnalyticsClient, AnalyticsClientConfig, AnalyticsEvent, AnalyticsEventType, AnalyticsIngestBody, BOT_USER_AGENT_PATTERN, BaseAnalyticsEvent, ContentExposureEvent, ConversionEvent, DEFAULT_FLUSH_INTERVAL, DEFAULT_MAX_BUFFER_SIZE, DEFAULT_SAMPLE_RATE, EventBuffer, MAX_EVENTS_PER_SEND, PageViewEvent, PageViewInput, TrackableEvent, assignVariant, buildContentExposure, createAnalyticsClient, createEventBuffer, decrementAnalyticsClientRefCount, getGlobalAnalyticsClient, getSessionId, incrementAnalyticsClientRefCount, initAnalyticsClient, isBotEnvironment, isBotUserAgent, isSampledIn, sendEvents, serializeKeyPath, setGlobalAnalyticsClient, stopAnalyticsClient };

package/dist/types/isEnabled.d.ts

@@ -10,7 +10,8 @@
  * - the user did not opt out (`analytics.enabled === true`, the default), and
  * - a project key is configured (`editor.clientId`), and
  * - we are on the client, and
- * - we are the top window (not embedded in the editor).
+ * - we are the top window (not embedded in the editor), and
+ * - the visitor is not a bot, crawler or automation runtime.
  */
 declare const isEnabled: boolean;
 //#endregion

package/dist/types/isEnabled.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"isEnabled.d.ts","names":[],"sources":["../../src/isEnabled.ts"],"mappings":";;;;;;;;;;;;;;cAwBa"}
+{"version":3,"file":"isEnabled.d.ts","names":[],"sources":["../../src/isEnabled.ts"],"mappings":";;;;;;;;;;;;;;;cA0Ba"}

package/dist/types/utils/isBot.d.ts

@@ -0,0 +1,54 @@
+//#region src/utils/isBot.d.ts
+/**
+ * Bot / automation detection.
+ *
+ * Analytics must describe real people. Crawlers, link-preview fetchers, uptime
+ * monitors, AI agents and CI browsers (Lighthouse, Playwright, Puppeteer) all
+ * execute JavaScript nowadays, so they would otherwise be counted as visitors
+ * and inflate page views, content exposures and A/B conversion rates.
+ *
+ * Everything here is a pure string/environment check — no network, no storage.
+ */
+/**
+ * Matches known non-human user agents. Grouped by family so the list stays
+ * reviewable:
+ * - generic tokens (`…bot`, `crawler`, `spider`, `scraper`)
+ * - HTTP clients used by scripts (curl, wget, requests, axios…)
+ * - headless / automation runtimes (Playwright, Puppeteer, Lighthouse…)
+ * - search-engine and SEO crawlers
+ * - social link-preview fetchers
+ * - AI / LLM crawlers and agents
+ */
+declare const BOT_USER_AGENT_PATTERN: RegExp;
+/**
+ * Tells whether a user agent string identifies a bot, crawler or automation
+ * runtime rather than a human visitor.
+ *
+ * A missing or empty user agent is treated as a bot: every real browser sends
+ * one, so its absence means a script or a forged request.
+ *
+ * @param userAgent - The raw `User-Agent` string (header or `navigator.userAgent`).
+ * @returns `true` when the traffic must not be recorded.
+ *
+ * @example
+ * isBotUserAgent('Mozilla/5.0 (compatible; Googlebot/2.1)'); // true
+ * isBotUserAgent('Mozilla/5.0 (Macintosh) Chrome/120'); // false
+ */
+declare const isBotUserAgent: (userAgent?: string | null) => boolean;
+/**
+ * Tells whether the current browser environment is automated, combining the
+ * user agent with automation fingerprints (`navigator.webdriver`, runtime
+ * globals) that headless browsers spoofing a normal user agent still expose.
+ *
+ * Always `false` outside a browser (SSR): there is nothing to collect there,
+ * and the server must not disable a client that has not run yet.
+ *
+ * @returns `true` when analytics must stay off for this environment.
+ *
+ * @example
+ * if (isBotEnvironment()) return; // never start the client for a crawler
+ */
+declare const isBotEnvironment: () => boolean;
+//#endregion
+export { BOT_USER_AGENT_PATTERN, isBotEnvironment, isBotUserAgent };
+//# sourceMappingURL=isBot.d.ts.map

package/dist/types/utils/isBot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"isBot.d.ts","names":[],"sources":["../../../src/utils/isBot.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;cA4Ba,wBAAsB;;;;;;;;;;;;;;;cAiBtB,iBAAc;;;;;;;;;;;;;;cAmCd"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intlayer/analytics",
-  "version": "9.4.0-canary.0",
+  "version": "9.4.0",
   "private": false,
   "description": "Collects which Intlayer content is shown (page/locale + node-level) and powers content A/B testing. Optional, lazily-imported companion to @intlayer/editor.",
   "keywords": [
@@ -41,6 +41,11 @@
       "require": "./dist/cjs/isEnabled.cjs",
       "import": "./dist/esm/isEnabled.mjs"
     },
+    "./bot": {
+      "types": "./dist/types/utils/isBot.d.ts",
+      "require": "./dist/cjs/utils/isBot.cjs",
+      "import": "./dist/esm/utils/isBot.mjs"
+    },
     "./client": {
       "types": "./dist/types/core/index.d.ts",
       "require": "./dist/cjs/core/index.cjs",
@@ -82,10 +87,10 @@
   "dependencies": {
     "@intlayer/config": "9.4.0-canary.0",
     "@intlayer/core": "9.4.0-canary.0",
-    "@intlayer/types": "9.4.0-canary.0"
+    "@intlayer/types": "9.4.0"
   },
   "devDependencies": {
-    "@types/node": "26.2.0",
+    "@types/node": "26.3.0",
     "@utils/ts-config": "1.0.4",
     "@utils/ts-config-types": "1.0.4",
     "@utils/tsdown-config": "1.0.4",