@intlayer/analytics 9.0.0-canary.16

package/dist/esm/events/contentExposure.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"contentExposure.mjs","names":[],"sources":["../../../src/events/contentExposure.ts"],"sourcesContent":["import type { KeyPath } from '@intlayer/types/keyPath';\nimport type { ContentExposureEvent, TrackableEvent } from '../core/types';\n\n/**\n * Serializes a `KeyPath[]` into a compact, stable string used both as the\n * coalescing key in the buffer and as the stored `keyPath` on the wire.\n *\n * Only the `key` of each segment is kept (types are implied by the dictionary\n * shape), producing paths like `\"faq.items.2.answer\"`.\n *\n * @param keyPath - The interpreter key path locating a node.\n * @returns A dot-joined, stable path string.\n *\n * @example\n * serializeKeyPath([{ type: 'object', key: 'faq' }, { type: 'array', key: 2 }]);\n * // \"faq.2\"\n */\nexport const serializeKeyPath = (keyPath: KeyPath[]): string =>\n  keyPath\n    .map((segment) => (segment.key === undefined ? '*' : String(segment.key)))\n    .join('.');\n\n/**\n * Builds a content-exposure payload from interpreter node metadata. Shared by\n * every framework binding's analytics node plugin so the wire shape stays\n * identical across React, Vue, Svelte, Angular, etc.\n *\n * @param params - Node metadata available on `NodeProps`.\n * @returns A trackable content-exposure event (minus buffer-stamped fields).\n */\nexport const buildContentExposure = (params: {\n  dictionaryKey: string;\n  keyPath: KeyPath[];\n  locale?: string;\n  nodeType?: string;\n  experimentKey?: string;\n  variant?: string;\n}): Omit<TrackableEvent<ContentExposureEvent>, 'type'> => ({\n  dictionaryKey: params.dictionaryKey,\n  keyPath: serializeKeyPath(params.keyPath),\n  // Left undefined when unknown so the client stamps its ambient locale.\n  locale: params.locale,\n  nodeType: params.nodeType,\n  experimentKey: params.experimentKey,\n  variant: params.variant,\n});\n"],"mappings":";;;;;;;;;;;;;;;AAiBA,MAAa,oBAAoB,YAC/B,QACG,KAAK,YAAa,QAAQ,QAAQ,SAAY,MAAM,OAAO,QAAQ,IAAI,CAAE,CACzE,KAAK,IAAI;;;;;;;;;AAUd,MAAa,wBAAwB,YAOsB;CACzD,eAAe,OAAO;CACtB,SAAS,iBAAiB,OAAO,QAAQ;CAEzC,QAAQ,OAAO;CACf,UAAU,OAAO;CACjB,eAAe,OAAO;CACtB,SAAS,OAAO;CACjB"}

package/dist/esm/index.mjs

@@ -0,0 +1,11 @@
+import { assignVariant } from "./core/abTesting.mjs";
+import { createEventBuffer } from "./core/eventBuffer.mjs";
+import { isSampledIn } from "./core/sampling.mjs";
+import { getSessionId } from "./core/session.mjs";
+import { sendEvents } from "./core/transport.mjs";
+import { DEFAULT_FLUSH_INTERVAL, DEFAULT_MAX_BUFFER_SIZE, DEFAULT_SAMPLE_RATE, MAX_EVENTS_PER_SEND, createAnalyticsClient } from "./core/AnalyticsClient.mjs";
+import { decrementAnalyticsClientRefCount, getGlobalAnalyticsClient, incrementAnalyticsClientRefCount, setGlobalAnalyticsClient } from "./core/globalManager.mjs";
+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 };

package/dist/esm/isEnabled.mjs

@@ -0,0 +1,28 @@
+import { analytics, editor } from "@intlayer/config/built";
+
+//#region src/isEnabled.ts
+/**
+* Compile-time kill switch. Bundlers replace `process.env.INTLAYER_ANALYTICS_ENABLED`
+* (set to `'false'` by `@intlayer/config` unless `analytics.enabled` is `true`
+* AND an `editor.clientId` is configured) so the whole analytics integration is
+* dead-code-eliminated for apps that don't opt in.
+*/
+const TREE_SHAKE_ANALYTICS = process.env.INTLAYER_ANALYTICS_ENABLED === "false";
+/**
+* Runtime guard mirroring `@intlayer/editor`'s `isEnabled`, but inverted with
+* respect to the iframe: analytics runs for real end users on the **top**
+* window and stays off inside the editor/CMS preview iframe so editor sessions
+* are never counted as traffic.
+*
+* Enabled when:
+* - the bundler did not tree-shake analytics away, and
+* - the user opted in (`analytics.enabled === true`), 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).
+*/
+const isEnabled = !TREE_SHAKE_ANALYTICS && analytics?.enabled === true && Boolean(editor?.clientId) && typeof window !== "undefined" && window.self === window.top;
+
+//#endregion
+export { isEnabled };
+//# sourceMappingURL=isEnabled.mjs.map

package/dist/esm/isEnabled.mjs.map

@@ -0,0 +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 * AND an `editor.clientId` is configured) so the whole analytics integration is\n * dead-code-eliminated for apps that don't opt in.\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 opted in (`analytics.enabled === true`), 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":";;;;;;;;;AAQA,MAAM,uBAAuB,QAAQ,IAAI,+BAA+B;;;;;;;;;;;;;;AAexE,MAAa,YACX,CAAC,wBACD,WAAW,YAAY,QACvB,QAAQ,QAAQ,SAAS,IACzB,OAAO,WAAW,eAClB,OAAO,SAAS,OAAO"}

package/dist/esm/utils/hash.mjs

@@ -0,0 +1,24 @@
+//#region src/utils/hash.ts
+/**
+* FNV-1a 32-bit string hash. Small, fast, dependency-free, and stable across
+* runtimes — good enough for deterministic A/B bucketing and session seeding
+* (not for cryptographic use).
+*
+* @param input - The string to hash.
+* @returns An unsigned 32-bit integer hash.
+*
+* @example
+* hashString('session-1:homepage-hero'); // 3039336720
+*/
+const hashString = (input) => {
+	let hash = 2166136261;
+	for (let index = 0; index < input.length; index++) {
+		hash ^= input.charCodeAt(index);
+		hash = Math.imul(hash, 16777619);
+	}
+	return hash >>> 0;
+};
+
+//#endregion
+export { hashString };
+//# sourceMappingURL=hash.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hash.mjs","names":[],"sources":["../../../src/utils/hash.ts"],"sourcesContent":["/**\n * FNV-1a 32-bit string hash. Small, fast, dependency-free, and stable across\n * runtimes — good enough for deterministic A/B bucketing and session seeding\n * (not for cryptographic use).\n *\n * @param input - The string to hash.\n * @returns An unsigned 32-bit integer hash.\n *\n * @example\n * hashString('session-1:homepage-hero'); // 3039336720\n */\nexport const hashString = (input: string): number => {\n  let hash = 0x811c9dc5; // FNV offset basis\n\n  for (let index = 0; index < input.length; index++) {\n    hash ^= input.charCodeAt(index);\n    // 32-bit FNV prime multiplication via shifts to stay within Number safe range\n    hash = Math.imul(hash, 0x01000193);\n  }\n\n  // Coerce to unsigned 32-bit\n  return hash >>> 0;\n};\n"],"mappings":";;;;;;;;;;;;AAWA,MAAa,cAAc,UAA0B;CACnD,IAAI,OAAO;AAEX,MAAK,IAAI,QAAQ,GAAG,QAAQ,MAAM,QAAQ,SAAS;AACjD,UAAQ,MAAM,WAAW,MAAM;AAE/B,SAAO,KAAK,KAAK,MAAM,SAAW;;AAIpC,QAAO,SAAS"}

package/dist/esm/utils/idle.mjs

@@ -0,0 +1,24 @@
+//#region src/utils/idle.ts
+/**
+* Runs a callback when the browser is idle, without blocking first render.
+* Falls back to a short `setTimeout` where `requestIdleCallback` is unavailable
+* (Safari, React Native, Lynx).
+*
+* @param callback - Work to run once the main thread is free.
+*
+* @example
+* onIdle(() => attachVisibilityListeners());
+*/
+const onIdle = (callback) => {
+	if (typeof window === "undefined") return;
+	const requestIdle = window.requestIdleCallback;
+	if (typeof requestIdle === "function") {
+		requestIdle(() => callback());
+		return;
+	}
+	setTimeout(callback, 1);
+};
+
+//#endregion
+export { onIdle };
+//# sourceMappingURL=idle.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"idle.mjs","names":[],"sources":["../../../src/utils/idle.ts"],"sourcesContent":["/**\n * Runs a callback when the browser is idle, without blocking first render.\n * Falls back to a short `setTimeout` where `requestIdleCallback` is unavailable\n * (Safari, React Native, Lynx).\n *\n * @param callback - Work to run once the main thread is free.\n *\n * @example\n * onIdle(() => attachVisibilityListeners());\n */\nexport const onIdle = (callback: () => void): void => {\n  if (typeof window === 'undefined') return;\n\n  const requestIdle = (\n    window as Window & {\n      requestIdleCallback?: (cb: () => void) => number;\n    }\n  ).requestIdleCallback;\n\n  if (typeof requestIdle === 'function') {\n    requestIdle(() => callback());\n    return;\n  }\n\n  setTimeout(callback, 1);\n};\n"],"mappings":";;;;;;;;;;;AAUA,MAAa,UAAU,aAA+B;AACpD,KAAI,OAAO,WAAW,YAAa;CAEnC,MAAM,cACJ,OAGA;AAEF,KAAI,OAAO,gBAAgB,YAAY;AACrC,oBAAkB,UAAU,CAAC;AAC7B;;AAGF,YAAW,UAAU,EAAE"}

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

@@ -0,0 +1,51 @@
+import { AnalyticsClientConfig, ContentExposureEvent, ConversionEvent, PageViewEvent, TrackableEvent } from "./types.js";
+
+//#region src/core/AnalyticsClient.d.ts
+/**
+ * Caller-supplied fields for a page view. Everything is optional — the client
+ * fills `url`, `locale`, viewport, and referrer from the environment when omitted.
+ */
+type PageViewInput = {
+  /** Explicit pathname / screen name (native runtimes have no `location`). */url?: string; /** Explicit locale; falls back to the client's ambient locale. */
+  locale?: string; /** Referrer host override. */
+  ref?: string; /** Viewport width override. */
+  vw?: number; /** Viewport height override. */
+  vh?: number; /** Why the view was recorded. */
+  reason?: PageViewEvent['reason'];
+};
+/** Default flush cadence — one network request per 20 seconds. */
+declare const DEFAULT_FLUSH_INTERVAL = 20000;
+/** Default cap on distinct buffered events before an early flush. */
+declare const DEFAULT_MAX_BUFFER_SIZE = 500;
+/** Default sampling — keep every session. */
+declare const DEFAULT_SAMPLE_RATE = 1;
+/**
+ * Maximum events per network request. `sendBeacon` and `fetch(keepalive)`
+ * reject bodies over ~64KB, so large batches are split into multiple sends.
+ */
+declare const MAX_EVENTS_PER_SEND = 200;
+/**
+ * The public surface of the analytics client singleton. Framework bindings hold
+ * a reference to this and forward provider/node/conversion signals into it.
+ */
+type AnalyticsClient = {
+  /** Sets the ambient locale stamped onto subsequent events. */setLocale: (locale: string) => void; /** Records a page/locale view (provider level). */
+  trackPageView: (event?: PageViewInput) => void; /** Records a content exposure (node level). Sampled + deduped per page view. */
+  trackContentExposure: (event: Omit<TrackableEvent<ContentExposureEvent>, 'type'>) => void; /** Records a conversion tied to an experiment variant. */
+  trackConversion: (event: Omit<TrackableEvent<ConversionEvent>, 'type'>) => void; /** Deterministically resolves this session's variant for an experiment. */
+  getVariant: (experimentKey: string, variants: string[], weights?: number[]) => string; /** Sends the buffered batch now. */
+  flush: (useBeacon?: boolean) => void; /** Starts the flush loop and lifecycle listeners (idempotent). */
+  start: () => void; /** Stops timers/listeners and flushes any remaining events. */
+  stop: () => void;
+};
+/**
+ * Creates an analytics client. Prefer {@link initAnalyticsClient} in application
+ * code — it manages a shared singleton so there is only ever one flush timer.
+ *
+ * @param config - Resolved client configuration.
+ * @returns A started-on-demand {@link AnalyticsClient}.
+ */
+declare const createAnalyticsClient: (config: AnalyticsClientConfig) => AnalyticsClient;
+//#endregion
+export { AnalyticsClient, DEFAULT_FLUSH_INTERVAL, DEFAULT_MAX_BUFFER_SIZE, DEFAULT_SAMPLE_RATE, MAX_EVENTS_PER_SEND, PageViewInput, createAnalyticsClient };
+//# sourceMappingURL=AnalyticsClient.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AnalyticsClient.d.ts","names":[],"sources":["../../../src/core/AnalyticsClient.ts"],"mappings":";;;;;AAmBA;;KAAY,aAAA;EAYY,4EAVtB,GAAA,WAEA;EAAA,MAAA,WAIA;EAFA,GAAA,WAMA;EAJA,EAAA,WAIsB;EAFtB,EAAA,WAMW;EAJX,MAAA,GAAS,aAAA;AAAA;;cAIE,sBAAA;AAEb;AAAA,cAAa,uBAAA;;cAEA,mBAAA;;AAAb;;;cAKa,mBAAA;;AAAb;;;KAQY,eAAA;EARoB,8DAU9B,SAAA,GAAY,MAAA,mBAFa;EAIzB,aAAA,GAAgB,KAAA,GAAQ,aAAA,WAAA;EAExB,oBAAA,GACE,KAAA,EAAO,IAAA,CAAK,cAAA,CAAe,oBAAA,qBAAf;EAGd,eAAA,GACE,KAAA,EAAO,IAAA,CAAK,cAAA,CAAe,eAAA,qBAAA;EAG7B,UAAA,GACE,aAAA,UACA,QAAA,YACA,OAAA,wBANO;EAST,KAAA,GAAQ,SAAA,qBATK;EAWb,KAAA,cApBY;EAsBZ,IAAA;AAAA;;;;;;;;cA+BW,qBAAA,GACX,MAAA,EAAQ,qBAAA,KACP,eAAA"}

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

@@ -0,0 +1,23 @@
+//#region src/core/abTesting.d.ts
+/**
+ * Deterministically assigns a variant to a session for a given experiment.
+ *
+ * The assignment is a pure function of `sessionId` + `experimentKey`, so it is
+ * stable for the whole session and requires **no** server round-trip before the
+ * first render — avoiding layout shift / content flicker. Optional `weights`
+ * bias the split (e.g. `[0.9, 0.1]` for a 90/10 rollout).
+ *
+ * @param sessionId - The current anonymous session id.
+ * @param experimentKey - Unique key identifying the experiment.
+ * @param variants - The candidate variant names (at least one).
+ * @param weights - Optional relative weights, one per variant.
+ * @returns The variant assigned to this session.
+ *
+ * @example
+ * assignVariant('sid-1', 'homepage-hero', ['a', 'b']);          // stable 'a' | 'b'
+ * assignVariant('sid-1', 'homepage-hero', ['a', 'b'], [9, 1]);  // ~90% 'a'
+ */
+declare const assignVariant: (sessionId: string, experimentKey: string, variants: string[], weights?: number[]) => string;
+//#endregion
+export { assignVariant };
+//# sourceMappingURL=abTesting.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"abTesting.d.ts","names":[],"sources":["../../../src/core/abTesting.ts"],"mappings":";;AAoBA;;;;;;;;;;;;;;;;;cAAa,aAAA,GACX,SAAA,UACA,aAAA,UACA,QAAA,YACA,OAAA"}

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

@@ -0,0 +1,35 @@
+import { AnalyticsEvent } from "./types.js";
+
+//#region src/core/eventBuffer.d.ts
+/**
+ * A bounded, coalescing in-memory buffer for analytics events.
+ *
+ * - `page_view` and `conversion` events are appended verbatim (they are rare
+ *   and valuable — they are never evicted while exposures remain).
+ * - `content_exposure` events are deduplicated by page/node/locale/variant with
+ *   a running `count`, keeping the highest-volume signal cheap.
+ * - When the total number of stored events exceeds `max`, the **oldest
+ *   exposures** are evicted first (analytics is lossy by design; exposures are
+ *   the expendable signal). Discrete events are only dropped once no exposures
+ *   remain.
+ */
+type EventBuffer = {
+  /** Adds an event, coalescing content exposures. Returns the current size. */push: (event: AnalyticsEvent) => number; /** Removes and returns every buffered event. */
+  drain: () => AnalyticsEvent[]; /** Current number of distinct buffered events. */
+  size: () => number;
+};
+/**
+ * Creates an {@link EventBuffer}.
+ *
+ * @param options - Buffer options.
+ * @param options.max - Maximum number of distinct events to retain.
+ * @returns A new buffer instance.
+ */
+declare const createEventBuffer: ({
+  max
+}: {
+  max: number;
+}) => EventBuffer;
+//#endregion
+export { EventBuffer, createEventBuffer };
+//# sourceMappingURL=eventBuffer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"eventBuffer.d.ts","names":[],"sources":["../../../src/core/eventBuffer.ts"],"mappings":";;;;;AAgCA;;;;;;;;;;KAAY,WAAA;EAMN,6EAJJ,IAAA,GAAO,KAAA,EAAO,cAAA,aAiEf;EA/DC,KAAA,QAAa,cAAA,IA+Dd;EA7DC,IAAA;AAAA;;;;;;;;cAUW,iBAAA;EAAqB;AAAA;EAAW,GAAA;AAAA,MAAgB,WAAA"}

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

@@ -0,0 +1,28 @@
+import { AnalyticsClient } from "./AnalyticsClient.js";
+
+//#region src/core/globalManager.d.ts
+/**
+ * Returns the global analytics client, or `null` in SSR or before init.
+ */
+declare const getGlobalAnalyticsClient: () => AnalyticsClient | null;
+/**
+ * Sets (or clears) the global analytics client singleton.
+ *
+ * @param client - The client to store globally, or `null` to clear it.
+ */
+declare const setGlobalAnalyticsClient: (client: AnalyticsClient | null) => void;
+/**
+ * Increments the shared provider reference count.
+ *
+ * @returns The count after incrementing (`0` in SSR, where nothing is stored).
+ */
+declare const incrementAnalyticsClientRefCount: () => number;
+/**
+ * Decrements the shared provider reference count, clamping at zero.
+ *
+ * @returns The count after decrementing (`0` in SSR, where nothing is stored).
+ */
+declare const decrementAnalyticsClientRefCount: () => number;
+//#endregion
+export { decrementAnalyticsClientRefCount, getGlobalAnalyticsClient, incrementAnalyticsClientRefCount, setGlobalAnalyticsClient };
+//# sourceMappingURL=globalManager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"globalManager.d.ts","names":[],"sources":["../../../src/core/globalManager.ts"],"mappings":";;;;;AA2BA;cAAa,wBAAA,QAA+B,eAAA;;;;AAU5C;;cAAa,wBAAA,GACX,MAAA,EAAQ,eAAA;;;AAWV;;;cAAa,gCAAA;;AAYb;;;;cAAa,gCAAA"}

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

@@ -0,0 +1,10 @@
+import { AnalyticsClientConfig, AnalyticsEvent, AnalyticsEventType, AnalyticsIngestBody, BaseAnalyticsEvent, ContentExposureEvent, ConversionEvent, PageViewEvent, TrackableEvent } from "./types.js";
+import { AnalyticsClient, DEFAULT_FLUSH_INTERVAL, DEFAULT_MAX_BUFFER_SIZE, DEFAULT_SAMPLE_RATE, MAX_EVENTS_PER_SEND, PageViewInput, createAnalyticsClient } from "./AnalyticsClient.js";
+import { assignVariant } from "./abTesting.js";
+import { EventBuffer, createEventBuffer } from "./eventBuffer.js";
+import { decrementAnalyticsClientRefCount, getGlobalAnalyticsClient, incrementAnalyticsClientRefCount, setGlobalAnalyticsClient } from "./globalManager.js";
+import { initAnalyticsClient, stopAnalyticsClient } from "./initAnalyticsClient.js";
+import { isSampledIn } from "./sampling.js";
+import { getSessionId } from "./session.js";
+import { sendEvents } from "./transport.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, createAnalyticsClient, createEventBuffer, decrementAnalyticsClientRefCount, getGlobalAnalyticsClient, getSessionId, incrementAnalyticsClientRefCount, initAnalyticsClient, isSampledIn, sendEvents, setGlobalAnalyticsClient, stopAnalyticsClient };

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

@@ -0,0 +1,28 @@
+import { AnalyticsClient } from "./AnalyticsClient.js";
+
+//#region src/core/initAnalyticsClient.d.ts
+/**
+ * Initializes the Intlayer analytics client singleton.
+ *
+ * Behavior comes from the `analytics` config block (`flushInterval`,
+ * `sampleRate`); attribution reuses the existing `editor` config
+ * (`editor.backendURL` for the endpoint, `editor.clientId` for the project).
+ *
+ * Safe to call multiple times: returns the existing client and increments a
+ * `window`-shared reference count so nested providers (or duplicated module
+ * instances) don't stop the client prematurely.
+ *
+ * @returns The started analytics client singleton.
+ */
+declare const initAnalyticsClient: () => AnalyticsClient;
+/**
+ * Decrements the shared reference count and stops the global analytics client
+ * only when the last provider unmounts (flushing any remaining events).
+ *
+ * Callers must pair each `stopAnalyticsClient` with a prior
+ * `initAnalyticsClient` — never call it when init was skipped or cancelled.
+ */
+declare const stopAnalyticsClient: () => void;
+//#endregion
+export { initAnalyticsClient, stopAnalyticsClient };
+//# sourceMappingURL=initAnalyticsClient.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"initAnalyticsClient.d.ts","names":[],"sources":["../../../src/core/initAnalyticsClient.ts"],"mappings":";;;;;AA4BA;;;;;AA2BA;;;;;;cA3Ba,mBAAA,QAA0B,eAAA;;;;;;;;cA2B1B,mBAAA"}

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

@@ -0,0 +1,20 @@
+//#region src/core/sampling.d.ts
+/**
+ * Deterministic per-session sampling gate. Using the session id (rather than a
+ * fresh random draw per event) means a sampled-in session reports *all* of its
+ * content exposures, keeping per-session funnels consistent instead of leaving
+ * holes.
+ *
+ * @param sessionId - The current anonymous session id.
+ * @param sampleRate - Fraction of sessions to keep, from 0 (none) to 1 (all).
+ * @returns `true` when this session's events should be recorded.
+ *
+ * @example
+ * isSampledIn('abc', 1);   // always true
+ * isSampledIn('abc', 0);   // always false
+ * isSampledIn('abc', 0.5); // stable per session
+ */
+declare const isSampledIn: (sessionId: string, sampleRate: number) => boolean;
+//#endregion
+export { isSampledIn };
+//# sourceMappingURL=sampling.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sampling.d.ts","names":[],"sources":["../../../src/core/sampling.ts"],"mappings":";;AAiBA;;;;;;;;;;;;;;cAAa,WAAA,GAAe,SAAA,UAAmB,UAAA"}

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

@@ -0,0 +1,17 @@
+//#region src/core/session.d.ts
+/**
+ * Anonymous, per-tab session identity. Stored in `sessionStorage` so it is
+ * cleared when the tab closes and is never shared across sites — no durable
+ * cookie, no cross-site tracking, no PII.
+ */
+/**
+ * Returns the current session id, creating and persisting one on first access.
+ * Degrades gracefully to an in-memory id when `sessionStorage` is unavailable
+ * (private mode, native runtimes).
+ *
+ * @returns The stable session id for the lifetime of the tab.
+ */
+declare const getSessionId: () => string;
+//#endregion
+export { getSessionId };
+//# sourceMappingURL=session.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","names":[],"sources":["../../../src/core/session.ts"],"mappings":";;AAkCA;;;;;;;;;;;cAAa,YAAA"}

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

@@ -0,0 +1,31 @@
+import { AnalyticsIngestBody } from "./types.js";
+
+//#region src/core/transport.d.ts
+/**
+ * Sends a batch of events to the backend. Every path is non-blocking and
+ * no-throw — analytics must never break, slow, or delay the host application.
+ *
+ * Strategy:
+ * 1. `navigator.sendBeacon` for the flush-on-hide path — survives page unload
+ *    and never blocks navigation. The payload is sent as `text/plain` (a
+ *    CORS-safelisted content type): a JSON `Blob` would require a CORS
+ *    preflight that browsers handle inconsistently during unload, silently
+ *    dropping the beacon. The backend parses `text/plain` bodies as JSON.
+ * 2. `fetch(..., { keepalive: true })` for interval flushes — survives short
+ *    navigations without holding the main thread.
+ * 3. Plain `fetch` fallback for runtimes without `keepalive` (older RN/Lynx).
+ *
+ * @param endpoint - Fully-qualified ingestion URL.
+ * @param body - The batched payload.
+ * @param options - Transport options.
+ * @param options.useBeacon - Prefer `sendBeacon` (used when the page is hiding).
+ * @returns `true` when a send was dispatched, `false` otherwise.
+ */
+declare const sendEvents: (endpoint: string, body: AnalyticsIngestBody, {
+  useBeacon
+}?: {
+  useBeacon?: boolean;
+}) => boolean;
+//#endregion
+export { sendEvents };
+//# sourceMappingURL=transport.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","names":[],"sources":["../../../src/core/transport.ts"],"mappings":";;;;;AAsBA;;;;;;;;;;;;;;;;;;cAAa,UAAA,GACX,QAAA,UACA,IAAA,EAAM,mBAAA;EACN;AAAA;EAAyB,SAAA;AAAA"}

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

@@ -0,0 +1,87 @@
+//#region src/core/types.d.ts
+/**
+ * Wire contract shared between the analytics client, `@intlayer/api`, and the
+ * backend ingestion endpoint. Keys are intentionally short to keep the batched
+ * payload small on the network.
+ */
+/**
+ * The kind of signal an event carries.
+ */
+type AnalyticsEventType = 'page_view' | 'content_exposure' | 'conversion';
+/**
+ * Fields present on every event regardless of its type.
+ */
+type BaseAnalyticsEvent = {
+  /** Client timestamp in milliseconds since epoch. */t: number; /** Current locale being displayed when the event was captured. */
+  locale: string; /** Pathname of the page (search params excluded by default for privacy). */
+  url: string;
+};
+/**
+ * A page/locale level event, emitted at the provider level on first mount,
+ * on client-side navigation, and on locale change.
+ */
+type PageViewEvent = BaseAnalyticsEvent & {
+  type: 'page_view'; /** Referrer host only (never the full URL) — omitted when unavailable. */
+  ref?: string; /** Viewport width in CSS pixels. */
+  vw?: number; /** Viewport height in CSS pixels. */
+  vh?: number; /** Why the view was recorded (initial load vs. locale switch vs. route change). */
+  reason?: 'initial' | 'locale_change' | 'route_change';
+};
+/**
+ * A node level event, emitted when a specific piece of dictionary content is
+ * resolved for display. Coalesced by the buffer so repeated exposures of the
+ * same node within a flush window collapse into a single event with a `count`.
+ */
+type ContentExposureEvent = BaseAnalyticsEvent & {
+  type: 'content_exposure'; /** The dictionary the resolved node belongs to. */
+  dictionaryKey: string; /** Stable-serialized `KeyPath[]` locating the node inside the dictionary. */
+  keyPath: string; /** The interpreter node type (translation, enumeration, markdown, …). */
+  nodeType?: string; /** The experiment this exposure belongs to, when part of an experiment. */
+  experimentKey?: string; /** A/B variant that produced this exposure, when part of an experiment. */
+  variant?: string; /** Number of coalesced exposures represented by this event. */
+  count?: number;
+};
+/**
+ * A conversion event tying a goal to the A/B variant the session was exposed to.
+ */
+type ConversionEvent = BaseAnalyticsEvent & {
+  type: 'conversion'; /** The experiment this conversion is attributed to. */
+  experimentKey: string; /** The variant the session was assigned. */
+  variant: string; /** The goal that was reached (e.g. `"signup"`, `"cta_click"`). */
+  goal: string; /** Optional numeric value associated with the conversion (e.g. revenue). */
+  value?: number;
+};
+/**
+ * The union of every event the client can emit.
+ */
+type AnalyticsEvent = PageViewEvent | ContentExposureEvent | ConversionEvent;
+/**
+ * An event as it is handed to the client trackers, before the buffer stamps the
+ * shared `BaseAnalyticsEvent` fields (`t`, `url`, and the ambient `locale`).
+ */
+type TrackableEvent<E extends AnalyticsEvent = AnalyticsEvent> = Omit<E, 't' | 'url' | 'locale'> & {
+  /** Optional explicit locale; falls back to the client's ambient locale. */locale?: string;
+};
+/**
+ * The batched request body sent to `POST /api/analytics/events`.
+ */
+type AnalyticsIngestBody = {
+  /** Public project key — reused from `editor.clientId`. */clientId?: string; /** Anonymous per-tab session identifier (new tab ⇒ new id; never durable). */
+  sessionId: string; /** Version of the analytics SDK that produced the batch. */
+  sdkVersion: string; /** The events collected during the flush window. */
+  events: AnalyticsEvent[];
+};
+/**
+ * Resolved runtime options for the analytics client. All values have safe
+ * defaults so the client can run with only a `backendURL`.
+ */
+type AnalyticsClientConfig = {
+  /** Base URL of the Intlayer backend — reused from `editor.backendURL`. */backendURL: string; /** Public project key — reused from `editor.clientId`. */
+  clientId?: string; /** Milliseconds between automatic flushes. Defaults to 20000. */
+  flushInterval: number; /** Maximum number of buffered events before an early flush. Defaults to 500. */
+  maxBufferSize: number; /** Fraction of content-exposure events to keep, 0..1. Defaults to 1. */
+  sampleRate: number;
+};
+//#endregion
+export { AnalyticsClientConfig, AnalyticsEvent, AnalyticsEventType, AnalyticsIngestBody, BaseAnalyticsEvent, ContentExposureEvent, ConversionEvent, PageViewEvent, TrackableEvent };
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/core/types.ts"],"mappings":";;AASA;;;;;AAQA;;KARY,kBAAA;;;;KAQA,kBAAA;EAMP,oDAJH,CAAA,UAWU;EATV,MAAA;EAEA,GAAA;AAAA;;;;;KAOU,aAAA,GAAgB,kBAAA;EAC1B,IAAA,eAQM;EANN,GAAA,WAc8B;EAZ9B,EAAA,WAYmD;EAVnD,EAAA,WAWA;EATA,MAAA;AAAA;;;;;;KAQU,oBAAA,GAAuB,kBAAA;EACjC,IAAA,sBAkByB;EAhBzB,aAAA,UAgB8C;EAd9C,OAAA,UAeA;EAbA,QAAA,WAiBA;EAfA,aAAA,WAmBA;EAjBA,OAAA,WAiBK;EAfL,KAAA;AAAA;;;;KAMU,eAAA,GAAkB,kBAAA;EAC5B,IAAA,gBAiBiB;EAfjB,aAAA,UAcE;EAZF,OAAA,UAaiB;EAXjB,IAAA,UAiBU;EAfV,KAAA;AAAA;;;;KAMU,cAAA,GACR,aAAA,GACA,oBAAA,GACA,eAAA;;;;;KAMQ,cAAA,WAAyB,cAAA,GAAiB,cAAA,IAAkB,IAAA,CACtE,CAAA;EADsE,2EAKtE,MAAA;AAAA;;;AAMF;KAAY,mBAAA;4DAEV,QAAA;EAEA,SAAA,UAEA;EAAA,UAAA,UAEQ;EAAR,MAAA,EAAQ,cAAA;AAAA;AAOV;;;;AAAA,KAAY,qBAAA;EAIV,0EAFA,UAAA,UAMA;EAJA,QAAA,WAMU;EAJV,aAAA;EAEA,aAAA;EAEA,UAAA;AAAA"}

package/dist/types/events/contentExposure.d.ts

@@ -0,0 +1,38 @@
+import { ContentExposureEvent, TrackableEvent } from "../core/types.js";
+import { KeyPath } from "@intlayer/types/keyPath";
+
+//#region src/events/contentExposure.d.ts
+/**
+ * Serializes a `KeyPath[]` into a compact, stable string used both as the
+ * coalescing key in the buffer and as the stored `keyPath` on the wire.
+ *
+ * Only the `key` of each segment is kept (types are implied by the dictionary
+ * shape), producing paths like `"faq.items.2.answer"`.
+ *
+ * @param keyPath - The interpreter key path locating a node.
+ * @returns A dot-joined, stable path string.
+ *
+ * @example
+ * serializeKeyPath([{ type: 'object', key: 'faq' }, { type: 'array', key: 2 }]);
+ * // "faq.2"
+ */
+declare const serializeKeyPath: (keyPath: KeyPath[]) => string;
+/**
+ * Builds a content-exposure payload from interpreter node metadata. Shared by
+ * every framework binding's analytics node plugin so the wire shape stays
+ * identical across React, Vue, Svelte, Angular, etc.
+ *
+ * @param params - Node metadata available on `NodeProps`.
+ * @returns A trackable content-exposure event (minus buffer-stamped fields).
+ */
+declare const buildContentExposure: (params: {
+  dictionaryKey: string;
+  keyPath: KeyPath[];
+  locale?: string;
+  nodeType?: string;
+  experimentKey?: string;
+  variant?: string;
+}) => Omit<TrackableEvent<ContentExposureEvent>, "type">;
+//#endregion
+export { buildContentExposure, serializeKeyPath };
+//# sourceMappingURL=contentExposure.d.ts.map

package/dist/types/events/contentExposure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contentExposure.d.ts","names":[],"sources":["../../../src/events/contentExposure.ts"],"mappings":";;;;;;AAiBA;;;;;AAaA;;;;;;;cAba,gBAAA,GAAoB,OAAA,EAAS,OAAA;;;;;;;;;cAa7B,oBAAA,GAAwB,MAAA;EACnC,aAAA;EACA,OAAA,EAAS,OAAA;EACT,MAAA;EACA,QAAA;EACA,aAAA;EACA,OAAA;AAAA,MACE,IAAA,CAAK,cAAA,CAAe,oBAAA"}

package/dist/types/index.d.ts

@@ -0,0 +1,11 @@
+import { AnalyticsClientConfig, AnalyticsEvent, AnalyticsEventType, AnalyticsIngestBody, BaseAnalyticsEvent, ContentExposureEvent, ConversionEvent, PageViewEvent, TrackableEvent } from "./core/types.js";
+import { AnalyticsClient, DEFAULT_FLUSH_INTERVAL, DEFAULT_MAX_BUFFER_SIZE, DEFAULT_SAMPLE_RATE, MAX_EVENTS_PER_SEND, PageViewInput, createAnalyticsClient } from "./core/AnalyticsClient.js";
+import { assignVariant } from "./core/abTesting.js";
+import { EventBuffer, createEventBuffer } from "./core/eventBuffer.js";
+import { decrementAnalyticsClientRefCount, getGlobalAnalyticsClient, incrementAnalyticsClientRefCount, setGlobalAnalyticsClient } from "./core/globalManager.js";
+import { initAnalyticsClient, stopAnalyticsClient } from "./core/initAnalyticsClient.js";
+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 };

package/dist/types/isEnabled.d.ts

@@ -0,0 +1,18 @@
+//#region src/isEnabled.d.ts
+/**
+ * Runtime guard mirroring `@intlayer/editor`'s `isEnabled`, but inverted with
+ * respect to the iframe: analytics runs for real end users on the **top**
+ * window and stays off inside the editor/CMS preview iframe so editor sessions
+ * are never counted as traffic.
+ *
+ * Enabled when:
+ * - the bundler did not tree-shake analytics away, and
+ * - the user opted in (`analytics.enabled === true`), 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).
+ */
+declare const isEnabled: boolean;
+//#endregion
+export { isEnabled };
+//# sourceMappingURL=isEnabled.d.ts.map

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

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

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

@@ -0,0 +1,16 @@
+//#region src/utils/hash.d.ts
+/**
+ * FNV-1a 32-bit string hash. Small, fast, dependency-free, and stable across
+ * runtimes — good enough for deterministic A/B bucketing and session seeding
+ * (not for cryptographic use).
+ *
+ * @param input - The string to hash.
+ * @returns An unsigned 32-bit integer hash.
+ *
+ * @example
+ * hashString('session-1:homepage-hero'); // 3039336720
+ */
+declare const hashString: (input: string) => number;
+//#endregion
+export { hashString };
+//# sourceMappingURL=hash.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","names":[],"sources":["../../../src/utils/hash.ts"],"mappings":";;AAWA;;;;;;;;;;cAAa,UAAA,GAAc,KAAA"}

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

@@ -0,0 +1,15 @@
+//#region src/utils/idle.d.ts
+/**
+ * Runs a callback when the browser is idle, without blocking first render.
+ * Falls back to a short `setTimeout` where `requestIdleCallback` is unavailable
+ * (Safari, React Native, Lynx).
+ *
+ * @param callback - Work to run once the main thread is free.
+ *
+ * @example
+ * onIdle(() => attachVisibilityListeners());
+ */
+declare const onIdle: (callback: () => void) => void;
+//#endregion
+export { onIdle };
+//# sourceMappingURL=idle.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"idle.d.ts","names":[],"sources":["../../../src/utils/idle.ts"],"mappings":";;AAUA;;;;;;;;;cAAa,MAAA,GAAU,QAAA"}