@snovasys/usage-analytics-sdk 1.0.0

package/dist/index.cjs

@@ -0,0 +1,729 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  flush: () => flush,
+  identify: () => identify,
+  init: () => init,
+  isInitialized: () => isInitialized,
+  reset: () => reset,
+  track: () => track
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/buffer/pre-init-buffer.ts
+var PreInitBuffer = class {
+  constructor(options) {
+    this.queue = [];
+    this.options = options;
+    this.isBrowser = options.isBrowserOverride !== void 0 ? options.isBrowserOverride : typeof window !== "undefined";
+  }
+  /**
+   * Push a track call. No-op if mode is drop or not browser (SSR).
+   */
+  pushTrack(name, properties, timestamp) {
+    if (this.options.mode === "drop" || !this.isBrowser) return;
+    const item = {
+      type: "track",
+      name,
+      properties,
+      timestamp,
+      createdAt: Date.now()
+    };
+    this.push(item);
+  }
+  /**
+   * Push an identify call. No-op if mode is drop or not browser (SSR).
+   */
+  pushIdentify(userId, traits) {
+    if (this.options.mode === "drop" || !this.isBrowser) return;
+    const item = {
+      type: "identify",
+      userId,
+      traits,
+      createdAt: Date.now()
+    };
+    this.push(item);
+  }
+  push(item) {
+    while (this.queue.length >= this.options.maxSize && this.queue.length > 0) {
+      this.queue.shift();
+    }
+    this.queue.push(item);
+  }
+  /**
+   * Replay queued items: all identify first (order), then all track (order).
+   * Items older than ttlMs are dropped. Then clear the queue.
+   */
+  flush(onTrack, onIdentify) {
+    if (!this.isBrowser || this.queue.length === 0) {
+      this.queue.length = 0;
+      return;
+    }
+    const now = Date.now();
+    const cutoff = now - this.options.ttlMs;
+    const identifyItems = this.queue.filter(
+      (item) => item.type === "identify" && item.createdAt >= cutoff
+    );
+    const trackItems = this.queue.filter(
+      (item) => item.type === "track" && item.createdAt >= cutoff
+    );
+    for (const item of identifyItems) {
+      onIdentify(item.userId, item.traits);
+    }
+    for (const item of trackItems) {
+      onTrack({
+        name: item.name,
+        properties: item.properties,
+        timestamp: item.timestamp
+      });
+    }
+    this.queue.length = 0;
+  }
+  /** Number of items currently queued (for tests). */
+  get length() {
+    return this.queue.length;
+  }
+};
+
+// src/dispatcher/registry.ts
+var ListenerRegistry = class {
+  constructor() {
+    this.listeners = [];
+  }
+  add(id, listener) {
+    this.listeners.push({ id, listener });
+  }
+  getAll() {
+    return [...this.listeners];
+  }
+  clear() {
+    this.listeners.length = 0;
+  }
+};
+
+// src/enricher/session.ts
+var STORAGE_KEY_PREFIX = "snovasys_usage_analytics_session_";
+function generateId() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  return fallbackUuidV4();
+}
+function fallbackUuidV4() {
+  const hex = "0123456789abcdef";
+  let result = "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx";
+  result = result.replace(/[xy]/g, (c) => {
+    const r = Math.random() * 16 | 0;
+    const v = c === "x" ? r : r & 3 | 8;
+    return hex[v];
+  });
+  return result;
+}
+function getOrCreateSessionId(appId, providedSessionId) {
+  if (providedSessionId) return providedSessionId;
+  const key = `${STORAGE_KEY_PREFIX}${appId}`;
+  if (typeof window !== "undefined" && typeof sessionStorage !== "undefined") {
+    try {
+      const existing = sessionStorage.getItem(key);
+      if (existing) return existing;
+      const newId = generateId();
+      sessionStorage.setItem(key, newId);
+      return newId;
+    } catch {
+      return generateId();
+    }
+  }
+  return generateId();
+}
+
+// src/enricher/enricher.ts
+var ENVELOPE_VERSION = 1;
+function createEnricherState(appId, environment, sdkVersion, sessionId) {
+  const resolvedSessionId = getOrCreateSessionId(appId, sessionId);
+  return {
+    appId,
+    environment,
+    sdkVersion,
+    sessionId,
+    resolvedSessionId
+  };
+}
+function enrich(payload, state) {
+  const timestamp = payload.timestamp ?? (/* @__PURE__ */ new Date()).toISOString();
+  const envelope = {
+    name: payload.name,
+    timestamp,
+    eventId: generateId(),
+    appId: state.appId,
+    environment: state.environment,
+    sdkVersion: state.sdkVersion,
+    version: ENVELOPE_VERSION
+  };
+  if (payload.properties != null) envelope.properties = payload.properties;
+  if (state.resolvedSessionId) envelope.sessionId = state.resolvedSessionId;
+  if (state.userId) envelope.userId = state.userId;
+  return envelope;
+}
+function setUserId(state, userId) {
+  state.userId = userId;
+}
+function clearUserId(state) {
+  state.userId = void 0;
+}
+
+// src/dispatcher/dispatcher.ts
+function dispatchTrack(deps, payload) {
+  const state = deps.getEnricherState();
+  const envelope = enrich(payload, state);
+  dispatchEnvelope(deps, envelope, "track");
+}
+function dispatchEnvelope(deps, envelope, kind) {
+  const { registry: registry2, onError: onError2 } = deps;
+  for (const { id, listener } of registry2.getAll()) {
+    try {
+      listener.track(envelope);
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      onError2?.(error, { listenerId: id });
+    }
+  }
+}
+function dispatchIdentify(deps, userId, traits) {
+  const { registry: registry2, onError: onError2 } = deps;
+  for (const { id, listener } of registry2.getAll()) {
+    if (typeof listener.identify !== "function") continue;
+    try {
+      listener.identify(userId, traits);
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      onError2?.(error, { listenerId: id });
+    }
+  }
+}
+
+// src/listeners/noop.ts
+function createNoopListener() {
+  return {
+    init(_config) {
+    },
+    track(_envelope) {
+    }
+  };
+}
+var noopListener = createNoopListener();
+
+// src/listeners/clarity.ts
+var CLARITY_SCRIPT_BASE = "https://www.clarity.ms/tag/";
+function isBrowser() {
+  return typeof window !== "undefined";
+}
+function loadClarityScript(projectId) {
+  return new Promise((resolve) => {
+    if (!isBrowser()) {
+      resolve();
+      return;
+    }
+    if (typeof window.clarity === "function") {
+      resolve();
+      return;
+    }
+    const script = document.createElement("script");
+    script.async = true;
+    script.src = `${CLARITY_SCRIPT_BASE}${encodeURIComponent(projectId)}`;
+    script.onload = () => resolve();
+    script.onerror = () => resolve();
+    document.head.appendChild(script);
+  });
+}
+function createClarityListener(config) {
+  const projectId = config.projectId;
+  let ready = false;
+  return {
+    async init(cfg) {
+      try {
+        const c = cfg ?? config;
+        const id = c.projectId;
+        if (!id || !isBrowser()) return;
+        await loadClarityScript(id);
+        ready = true;
+      } catch {
+      }
+    },
+    track(envelope) {
+      try {
+        if (!isBrowser() || !ready || typeof window.clarity !== "function") return;
+        window.clarity("event", envelope.name);
+        if (envelope.properties && typeof window.clarity === "function") {
+          for (const [key, value] of Object.entries(envelope.properties)) {
+            if (typeof value === "string" || Array.isArray(value)) {
+              window.clarity("set", key, value);
+            }
+          }
+        }
+      } catch {
+      }
+    },
+    identify(userId, _traits) {
+      try {
+        if (!isBrowser() || !ready || typeof window.clarity !== "function") return;
+        window.clarity("identify", userId, void 0, void 0, void 0);
+      } catch {
+      }
+    }
+  };
+}
+
+// src/listeners/ga.ts
+var GTAG_SCRIPT_URL = "https://www.googletagmanager.com/gtag/js";
+function isBrowser2() {
+  return typeof window !== "undefined";
+}
+function loadGtagScript(measurementId) {
+  return new Promise((resolve) => {
+    if (!isBrowser2()) {
+      resolve();
+      return;
+    }
+    if (window.gtag) {
+      window.gtag("config", measurementId);
+      resolve();
+      return;
+    }
+    window.dataLayer = window.dataLayer ?? [];
+    const gtag = (...args) => {
+      window.dataLayer.push(args);
+    };
+    window.gtag = gtag;
+    gtag("js", /* @__PURE__ */ new Date());
+    const script = document.createElement("script");
+    script.async = true;
+    script.src = `${GTAG_SCRIPT_URL}?id=${encodeURIComponent(measurementId)}`;
+    script.onload = () => {
+      gtag("config", measurementId);
+      resolve();
+    };
+    script.onerror = () => resolve();
+    document.head.appendChild(script);
+  });
+}
+function createGAListener(config) {
+  const measurementId = config.measurementId;
+  let ready = false;
+  return {
+    async init(cfg) {
+      try {
+        const c = cfg ?? config;
+        const id = c.measurementId;
+        if (!id || !isBrowser2()) return;
+        await loadGtagScript(id);
+        ready = true;
+      } catch {
+      }
+    },
+    track(envelope) {
+      try {
+        if (!isBrowser2() || !ready || typeof window.gtag !== "function") return;
+        const params = envelope.properties ?? {};
+        if (envelope.userId) params["user_id"] = envelope.userId;
+        window.gtag("event", envelope.name, params);
+      } catch {
+      }
+    },
+    identify(userId, traits) {
+      try {
+        if (!isBrowser2() || typeof window.gtag !== "function") return;
+        window.gtag("set", "user_properties", { user_id: userId, ...traits });
+      } catch {
+      }
+    }
+  };
+}
+
+// src/listeners/custom-api.ts
+var DEFAULT_BATCH_SIZE = 1;
+var DEFAULT_FLUSH_INTERVAL_MS = 5e3;
+function createCustomApiListener(config) {
+  const endpoint = config.endpoint;
+  const apiKey = config.apiKey;
+  const batchSize = config.batchSize ?? DEFAULT_BATCH_SIZE;
+  const flushIntervalMs = config.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS;
+  let batch = [];
+  let flushTimer = null;
+  function scheduleFlush() {
+    if (flushTimer != null) return;
+    flushTimer = setTimeout(() => {
+      flushTimer = null;
+      sendBatch();
+    }, flushIntervalMs);
+  }
+  function sendBatch() {
+    if (batch.length === 0) return;
+    const toSend = [...batch];
+    batch = [];
+    const body = JSON.stringify(toSend.length === 1 ? toSend[0] : { events: toSend });
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (apiKey) headers["Authorization"] = `Bearer ${apiKey}`;
+    if (typeof fetch !== "undefined") {
+      fetch(endpoint, {
+        method: "POST",
+        headers,
+        body,
+        keepalive: true
+      }).catch(() => {
+      });
+    }
+  }
+  return {
+    init(_config) {
+    },
+    track(envelope) {
+      try {
+        batch.push(envelope);
+        if (batch.length >= batchSize) {
+          sendBatch();
+        } else if (flushIntervalMs > 0) {
+          scheduleFlush();
+        }
+      } catch {
+      }
+    },
+    flush() {
+      if (flushTimer != null) {
+        clearTimeout(flushTimer);
+        flushTimer = null;
+      }
+      sendBatch();
+      return Promise.resolve();
+    },
+    teardown() {
+      if (flushTimer != null) {
+        clearTimeout(flushTimer);
+        flushTimer = null;
+      }
+      batch.length = 0;
+    }
+  };
+}
+
+// src/listeners/registry.ts
+var BUILT_IN_FACTORIES = {
+  noop: () => createNoopListener(),
+  clarity: (config) => createClarityListener(config),
+  ga: (config) => createGAListener(config),
+  "custom-api": (config) => createCustomApiListener(config)
+};
+function buildListenersFromRemoteConfig(remote, options) {
+  const factories = options?.factories ?? BUILT_IN_FACTORIES;
+  const onError2 = options?.onError;
+  const entries = [];
+  if (!Array.isArray(remote.listeners)) {
+    return entries;
+  }
+  for (const entry of remote.listeners) {
+    if (entry.enabled === false) continue;
+    const id = entry.id;
+    if (id == null || typeof id !== "string") continue;
+    const factory = factories[id];
+    if (factory == null) {
+      onError2?.(new Error(`Unknown listener id: ${id}`), { listenerId: id });
+      continue;
+    }
+    let listener;
+    try {
+      listener = factory(entry.config);
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      onError2?.(error, { listenerId: id });
+      continue;
+    }
+    entries.push({
+      id,
+      enabled: entry.enabled,
+      listener,
+      config: entry.config
+    });
+  }
+  return entries;
+}
+
+// src/validate-config.ts
+var VALID_PRE_INIT_BEHAVIORS = ["drop", "queue"];
+function isRemoteListenerEntry(entry) {
+  if (entry == null || typeof entry !== "object") return false;
+  const o = entry;
+  return typeof o.id === "string" && o.id.trim() !== "" && "config" in o && !("listener" in o && o.listener != null);
+}
+function validateConfig(options) {
+  const useRemoteConfig = Boolean(options.configUrl ?? options.getConfig);
+  if (typeof options.appId !== "string" || options.appId.trim() === "") {
+    throw new Error("Analytics init failed: appId is required and must be a non-empty string (e.g. from environment variables).");
+  }
+  if (options.listeners != null && !Array.isArray(options.listeners)) {
+    throw new Error("Analytics init failed: listeners must be an array.");
+  }
+  const behavior = options.preInitBehavior ?? "drop";
+  if (!VALID_PRE_INIT_BEHAVIORS.includes(behavior)) {
+    throw new Error(
+      `Analytics init failed: preInitBehavior must be 'queue' or 'drop', got '${behavior}'.`
+    );
+  }
+  if (behavior === "queue") {
+    const maxSize = options.queueMaxSize ?? 100;
+    const ttlMs = options.queueTtlMs ?? 5e3;
+    if (typeof maxSize !== "number" || maxSize <= 0) {
+      throw new Error("Analytics init failed: queueMaxSize must be a positive number.");
+    }
+    if (typeof ttlMs !== "number" || ttlMs <= 0) {
+      throw new Error("Analytics init failed: queueTtlMs must be a positive number.");
+    }
+  }
+  if (useRemoteConfig) {
+    return;
+  }
+  const listeners = options.listeners ?? [];
+  const isRemoteShape = listeners.length > 0 && listeners.every(isRemoteListenerEntry);
+  if (isRemoteShape) {
+    for (let i = 0; i < listeners.length; i++) {
+      const entry = listeners[i];
+      if (entry.enabled === false) continue;
+      if (typeof entry.id !== "string" || entry.id.trim() === "") {
+        throw new Error(`Analytics init failed: listeners[${i}].id is required and must be a non-empty string.`);
+      }
+    }
+    return;
+  }
+  for (let i = 0; i < listeners.length; i++) {
+    const entry = listeners[i];
+    if (entry.enabled === false) continue;
+    if (entry.listener == null || typeof entry.listener !== "object") {
+      throw new Error(`Analytics init failed: listeners[${i}].listener is required.`);
+    }
+    const listener = entry.listener;
+    if (typeof listener.track !== "function") {
+      throw new Error(`Analytics init failed: listeners[${i}].listener must have a track method.`);
+    }
+  }
+}
+
+// src/version.ts
+var SDK_VERSION = "1.0.0";
+
+// src/facade.ts
+var enricherState = null;
+var registry = null;
+var preInitBuffer = null;
+var onError;
+var initialized = false;
+function getOrCreatePreInitBuffer() {
+  if (preInitBuffer == null) {
+    preInitBuffer = new PreInitBuffer({
+      mode: "queue",
+      maxSize: 100,
+      ttlMs: 5e3
+    });
+  }
+  return preInitBuffer;
+}
+function getEnricherState() {
+  if (enricherState == null) {
+    throw new Error("Analytics not initialized.");
+  }
+  return enricherState;
+}
+async function fetchRemoteConfig(options) {
+  if (options.getConfig) {
+    return options.getConfig();
+  }
+  if (options.configUrl) {
+    const fetchFn = options.fetch ?? globalThis.fetch;
+    const res = await fetchFn(options.configUrl);
+    if (!res.ok) {
+      throw new Error(`Analytics config fetch failed: ${res.status} ${res.statusText}`);
+    }
+    const json = await res.json();
+    if (json == null || typeof json !== "object") {
+      throw new Error("Analytics config response must be a JSON object.");
+    }
+    return json;
+  }
+  return null;
+}
+function isInlineRemoteShape(listeners) {
+  if (!Array.isArray(listeners) || listeners.length === 0) return false;
+  return listeners.every(
+    (entry) => entry != null && typeof entry === "object" && typeof entry.id === "string" && "config" in entry && !("listener" in entry && entry.listener != null)
+  );
+}
+async function init(options) {
+  validateConfig(options);
+  let appId;
+  let environment;
+  let listeners;
+  const remote = await fetchRemoteConfig(options);
+  if (remote != null) {
+    appId = (options.appId ?? "").toString().trim();
+    environment = options.environment ?? "production";
+    if (!appId) {
+      throw new Error("Analytics init failed: appId is required (set in init options, e.g. from environment variables).");
+    }
+    listeners = buildListenersFromRemoteConfig(remote, {
+      factories: options.listenerFactories,
+      onError: options.onError
+    });
+  } else {
+    appId = options.appId.trim();
+    environment = options.environment ?? "production";
+    const rawListeners = options.listeners ?? [];
+    if (isInlineRemoteShape(rawListeners)) {
+      listeners = buildListenersFromRemoteConfig(
+        { listeners: rawListeners },
+        {
+          factories: options.listenerFactories,
+          onError: options.onError
+        }
+      );
+    } else {
+      listeners = rawListeners;
+    }
+  }
+  const preInitBehavior = options.preInitBehavior ?? "drop";
+  const queueMaxSize = options.queueMaxSize ?? 100;
+  const queueTtlMs = options.queueTtlMs ?? 5e3;
+  onError = options.onError;
+  const mode = preInitBehavior === "queue" ? "queue" : "drop";
+  preInitBuffer = new PreInitBuffer({ mode, maxSize: queueMaxSize, ttlMs: queueTtlMs });
+  enricherState = createEnricherState(appId, environment, SDK_VERSION, options.sessionId);
+  registry = new ListenerRegistry();
+  for (const entry of listeners) {
+    if (entry.enabled === false) continue;
+    try {
+      const initResult = entry.listener.init(entry.config);
+      if (initResult instanceof Promise) {
+        await initResult;
+      }
+      registry.add(entry.id, entry.listener);
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      onError?.(error, { listenerId: entry.id });
+    }
+  }
+  const deps = {
+    registry,
+    getEnricherState,
+    onError
+  };
+  if (preInitBuffer) {
+    if (preInitBehavior === "queue") {
+      preInitBuffer.flush(
+        (payload) => dispatchTrack(deps, payload),
+        (userId, traits) => {
+          setUserId(enricherState, userId);
+          dispatchIdentify(deps, userId, traits);
+        }
+      );
+    } else {
+      preInitBuffer.flush(() => {
+      }, () => {
+      });
+    }
+    preInitBuffer = null;
+  }
+  initialized = true;
+}
+function track(event) {
+  if (!initialized) {
+    getOrCreatePreInitBuffer().pushTrack(event.name, event.properties, event.timestamp);
+    return;
+  }
+  const deps = {
+    registry,
+    getEnricherState,
+    onError
+  };
+  dispatchTrack(deps, event);
+}
+function identify(userId, traits) {
+  if (!initialized) {
+    getOrCreatePreInitBuffer().pushIdentify(userId, traits);
+    return;
+  }
+  if (enricherState) setUserId(enricherState, userId);
+  const deps = {
+    registry,
+    getEnricherState,
+    onError
+  };
+  dispatchIdentify(deps, userId, traits);
+}
+async function flush() {
+  if (!initialized || registry == null) return;
+  const promises = [];
+  for (const { listener } of registry.getAll()) {
+    if (typeof listener.flush === "function") {
+      const result = listener.flush();
+      if (result instanceof Promise) promises.push(result);
+    }
+  }
+  await Promise.all(promises);
+}
+async function reset() {
+  if (preInitBuffer) {
+    preInitBuffer.flush(() => {
+    }, () => {
+    });
+  }
+  if (enricherState) clearUserId(enricherState);
+  if (registry) {
+    for (const { listener } of registry.getAll()) {
+      if (typeof listener.teardown === "function") {
+        try {
+          const result = listener.teardown();
+          if (result instanceof Promise) await result;
+        } catch (err) {
+          const error = err instanceof Error ? err : new Error(String(err));
+          onError?.(error, {});
+        }
+      }
+    }
+    registry.clear();
+  }
+  preInitBuffer = null;
+  enricherState = null;
+  registry = null;
+  onError = void 0;
+  initialized = false;
+}
+function isInitialized() {
+  return initialized;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  flush,
+  identify,
+  init,
+  isInitialized,
+  reset,
+  track
+});
+//# sourceMappingURL=index.cjs.map