@jmp-technologies/analytics 0.1.0

package/README.md

@@ -0,0 +1,7 @@
+# `@jmp-technologies/analytics`
+
+Browser client for **`POST {baseUrl}/api/events`**. Full API, CORS, and examples: **[docs/tracking-integration.md](../../docs/tracking-integration.md)**.
+
+**Build:** `npm run build` in this package (or root `prepare` after `npm install`).
+
+**Publish to npm (org `jmp-technologies`):** `npm publish` from this directory after `npm run build` (package sets `publishConfig.access` to `public`).

package/dist/index.cjs

@@ -0,0 +1,191 @@
+"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 index_exports = {};
+__export(index_exports, {
+  createJmpAnalytics: () => createJmpAnalytics
+});
+module.exports = __toCommonJS(index_exports);
+var DEFAULT_SOURCE = "direct";
+var SESSION_STORAGE_KEY = "jmp_analytics_sid";
+function normalizeBaseUrl(baseUrl) {
+  return baseUrl.replace(/\/$/, "");
+}
+function inferDevice() {
+  if (typeof window === "undefined") {
+    return "unknown";
+  }
+  return window.innerWidth < 768 ? "mobile" : "desktop";
+}
+function getOrCreateSessionId() {
+  if (typeof window === "undefined" || !globalThis.crypto?.randomUUID) {
+    return void 0;
+  }
+  try {
+    let id = sessionStorage.getItem(SESSION_STORAGE_KEY);
+    if (!id) {
+      id = crypto.randomUUID();
+      sessionStorage.setItem(SESSION_STORAGE_KEY, id);
+    }
+    return id;
+  } catch {
+    return void 0;
+  }
+}
+function createJmpAnalytics(config) {
+  const baseUrl = normalizeBaseUrl(config.baseUrl);
+  const resolvedFetch = config.fetchImpl ?? (typeof globalThis !== "undefined" && globalThis.fetch ? globalThis.fetch.bind(globalThis) : void 0);
+  if (!resolvedFetch) {
+    throw new Error(
+      "createJmpAnalytics: fetch is not available; pass fetchImpl in config"
+    );
+  }
+  const fetchFn = resolvedFetch;
+  let lastDedupePath = "";
+  let lastDedupeAt = 0;
+  async function send(body) {
+    const url = `${baseUrl}/api/events`;
+    const headers = {
+      "Content-Type": "application/json",
+      "X-JMP-Tracking-Key": config.trackingKey
+    };
+    const sid = getOrCreateSessionId();
+    const payload = { ...body, ...sid ? { sessionId: sid } : {} };
+    if (config.debug) {
+      console.debug("[@jmp-technologies/analytics]", "POST", url, payload);
+    }
+    const res = await fetchFn(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(payload),
+      keepalive: true
+    });
+    if (!res.ok) {
+      let detail = "";
+      try {
+        const err = await res.json();
+        detail = err.error ?? await res.text();
+      } catch {
+        detail = await res.text();
+      }
+      throw new Error(`JMP Analytics HTTP ${res.status}: ${detail}`);
+    }
+  }
+  function shouldDedupePageView(path) {
+    const ms = config.pageViewDedupeMs ?? 0;
+    if (ms <= 0 || typeof window === "undefined") {
+      return false;
+    }
+    const now = Date.now();
+    if (path === lastDedupePath && now - lastDedupeAt < ms) {
+      return true;
+    }
+    lastDedupePath = path;
+    lastDedupeAt = now;
+    return false;
+  }
+  function trackPageView(options) {
+    const path = options?.path ?? (typeof window !== "undefined" ? window.location.pathname : "/");
+    if (shouldDedupePageView(path)) {
+      return Promise.resolve();
+    }
+    return send({
+      type: "page_view",
+      path: path || "/",
+      source: options?.source ?? DEFAULT_SOURCE,
+      device: options?.device ?? inferDevice(),
+      country: options?.country,
+      metadata: options?.metadata && typeof options.metadata === "object" ? options.metadata : {}
+    });
+  }
+  function trackFormSubmit(path, metadata) {
+    return send({
+      type: "form_submit",
+      path: path || "/",
+      metadata: metadata ?? {}
+    });
+  }
+  function trackCallClick(path, metadata) {
+    return send({
+      type: "call_click",
+      path: path || "/",
+      metadata: metadata ?? {}
+    });
+  }
+  function track(type, payload) {
+    if (type === "page_view") {
+      return trackPageView({
+        path: payload.path,
+        source: payload.source,
+        device: payload.device,
+        country: payload.country,
+        metadata: payload.metadata
+      });
+    }
+    if (type === "form_submit") {
+      return trackFormSubmit(payload.path, payload.metadata);
+    }
+    return trackCallClick(payload.path, payload.metadata);
+  }
+  function subscribeToSpaNavigation() {
+    if (typeof window === "undefined") {
+      return () => {
+      };
+    }
+    let lastPath = window.location.pathname;
+    const run = () => {
+      const path = window.location.pathname;
+      if (path !== lastPath) {
+        lastPath = path;
+        void trackPageView({ path });
+      }
+    };
+    window.addEventListener("popstate", run);
+    const push = history.pushState.bind(history);
+    const replace = history.replaceState.bind(history);
+    history.pushState = (...args) => {
+      const r = push(...args);
+      queueMicrotask(run);
+      return r;
+    };
+    history.replaceState = (...args) => {
+      const r = replace(...args);
+      queueMicrotask(run);
+      return r;
+    };
+    return () => {
+      window.removeEventListener("popstate", run);
+      history.pushState = push;
+      history.replaceState = replace;
+    };
+  }
+  return {
+    track,
+    trackPageView,
+    trackFormSubmit,
+    trackCallClick,
+    subscribeToSpaNavigation
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createJmpAnalytics
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export type JmpEventType = \"page_view\" | \"form_submit\" | \"call_click\"\n\nexport type JmpAnalyticsConfig = {\n  /** Dashboard origin, e.g. https://analytics.example.com (no trailing slash) */\n  baseUrl: string\n  /** Per-website key from JMP admin */\n  trackingKey: string\n  /** Log requests to console */\n  debug?: boolean\n  /** Override fetch (tests, React Native) */\n  fetchImpl?: typeof fetch\n  /**\n   * Suppress duplicate `page_view` for the same path within this window (ms).\n   * Helps with React Strict Mode double-mount; typical: 500–1000.\n   */\n  pageViewDedupeMs?: number\n}\n\nexport type TrackPageViewOptions = {\n  path?: string\n  source?: string\n  device?: string\n  country?: string\n  metadata?: Record<string, unknown>\n}\n\nconst DEFAULT_SOURCE = \"direct\"\nconst SESSION_STORAGE_KEY = \"jmp_analytics_sid\"\n\nfunction normalizeBaseUrl(baseUrl: string) {\n  return baseUrl.replace(/\\/$/, \"\")\n}\n\nfunction inferDevice(): string {\n  if (typeof window === \"undefined\") {\n    return \"unknown\"\n  }\n  return window.innerWidth < 768 ? \"mobile\" : \"desktop\"\n}\n\n/** Stable per-tab session id for bounce and unique session metrics (server-stored). */\nfunction getOrCreateSessionId(): string | undefined {\n  if (typeof window === \"undefined\" || !globalThis.crypto?.randomUUID) {\n    return undefined\n  }\n  try {\n    let id = sessionStorage.getItem(SESSION_STORAGE_KEY)\n    if (!id) {\n      id = crypto.randomUUID()\n      sessionStorage.setItem(SESSION_STORAGE_KEY, id)\n    }\n    return id\n  } catch {\n    return undefined\n  }\n}\n\n/**\n * Create a tracker instance. Safe to call once per app and reuse.\n */\nexport function createJmpAnalytics(config: JmpAnalyticsConfig) {\n  const baseUrl = normalizeBaseUrl(config.baseUrl)\n  const resolvedFetch =\n    config.fetchImpl ??\n    (typeof globalThis !== \"undefined\" && globalThis.fetch\n      ? globalThis.fetch.bind(globalThis)\n      : undefined)\n\n  if (!resolvedFetch) {\n    throw new Error(\n      \"createJmpAnalytics: fetch is not available; pass fetchImpl in config\"\n    )\n  }\n\n  const fetchFn: typeof fetch = resolvedFetch\n\n  let lastDedupePath = \"\"\n  let lastDedupeAt = 0\n\n  async function send(body: Record<string, unknown>) {\n    const url = `${baseUrl}/api/events`\n    const headers: Record<string, string> = {\n      \"Content-Type\": \"application/json\",\n      \"X-JMP-Tracking-Key\": config.trackingKey,\n    }\n\n    const sid = getOrCreateSessionId()\n    const payload = { ...body, ...(sid ? { sessionId: sid } : {}) }\n\n    if (config.debug) {\n      console.debug(\"[@jmp-technologies/analytics]\", \"POST\", url, payload)\n    }\n\n    const res = await fetchFn(url, {\n      method: \"POST\",\n      headers,\n      body: JSON.stringify(payload),\n      keepalive: true,\n    })\n\n    if (!res.ok) {\n      let detail = \"\"\n      try {\n        const err = (await res.json()) as { error?: string }\n        detail = err.error ?? (await res.text())\n      } catch {\n        detail = await res.text()\n      }\n      throw new Error(`JMP Analytics HTTP ${res.status}: ${detail}`)\n    }\n  }\n\n  function shouldDedupePageView(path: string): boolean {\n    const ms = config.pageViewDedupeMs ?? 0\n    if (ms <= 0 || typeof window === \"undefined\") {\n      return false\n    }\n    const now = Date.now()\n    if (path === lastDedupePath && now - lastDedupeAt < ms) {\n      return true\n    }\n    lastDedupePath = path\n    lastDedupeAt = now\n    return false\n  }\n\n  function trackPageView(options?: TrackPageViewOptions) {\n    const path =\n      options?.path ??\n      (typeof window !== \"undefined\" ? window.location.pathname : \"/\")\n\n    if (shouldDedupePageView(path)) {\n      return Promise.resolve()\n    }\n\n    return send({\n      type: \"page_view\",\n      path: path || \"/\",\n      source: options?.source ?? DEFAULT_SOURCE,\n      device: options?.device ?? inferDevice(),\n      country: options?.country,\n      metadata:\n        options?.metadata && typeof options.metadata === \"object\"\n          ? options.metadata\n          : {},\n    })\n  }\n\n  function trackFormSubmit(\n    path: string,\n    metadata?: Record<string, unknown>\n  ) {\n    return send({\n      type: \"form_submit\",\n      path: path || \"/\",\n      metadata: metadata ?? {},\n    })\n  }\n\n  function trackCallClick(\n    path: string,\n    metadata?: Record<string, unknown>\n  ) {\n    return send({\n      type: \"call_click\",\n      path: path || \"/\",\n      metadata: metadata ?? {},\n    })\n  }\n\n  function track(\n    type: JmpEventType,\n    payload: {\n      path: string\n      metadata?: Record<string, unknown>\n      source?: string\n      device?: string\n      country?: string\n    }\n  ) {\n    if (type === \"page_view\") {\n      return trackPageView({\n        path: payload.path,\n        source: payload.source,\n        device: payload.device,\n        country: payload.country,\n        metadata: payload.metadata,\n      })\n    }\n    if (type === \"form_submit\") {\n      return trackFormSubmit(payload.path, payload.metadata)\n    }\n    return trackCallClick(payload.path, payload.metadata)\n  }\n\n  /**\n   * Fire `page_view` on browser back/forward and when `history.pushState` /\n   * `replaceState` are used (many SPAs). Call once after creating the tracker.\n   * Returns an unsubscribe function.\n   */\n  function subscribeToSpaNavigation(): () => void {\n    if (typeof window === \"undefined\") {\n      return () => {}\n    }\n\n    let lastPath = window.location.pathname\n\n    const run = () => {\n      const path = window.location.pathname\n      if (path !== lastPath) {\n        lastPath = path\n        void trackPageView({ path })\n      }\n    }\n\n    window.addEventListener(\"popstate\", run)\n\n    const push = history.pushState.bind(history)\n    const replace = history.replaceState.bind(history)\n\n    history.pushState = (...args: Parameters<History[\"pushState\"]>) => {\n      const r = push(...args)\n      queueMicrotask(run)\n      return r\n    }\n    history.replaceState = (...args: Parameters<History[\"replaceState\"]>) => {\n      const r = replace(...args)\n      queueMicrotask(run)\n      return r\n    }\n\n    return () => {\n      window.removeEventListener(\"popstate\", run)\n      history.pushState = push\n      history.replaceState = replace\n    }\n  }\n\n  return {\n    track,\n    trackPageView,\n    trackFormSubmit,\n    trackCallClick,\n    subscribeToSpaNavigation,\n  }\n}\n\nexport type JmpAnalytics = ReturnType<typeof createJmpAnalytics>\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,42 @@
+type JmpEventType = "page_view" | "form_submit" | "call_click";
+type JmpAnalyticsConfig = {
+    /** Dashboard origin, e.g. https://analytics.example.com (no trailing slash) */
+    baseUrl: string;
+    /** Per-website key from JMP admin */
+    trackingKey: string;
+    /** Log requests to console */
+    debug?: boolean;
+    /** Override fetch (tests, React Native) */
+    fetchImpl?: typeof fetch;
+    /**
+     * Suppress duplicate `page_view` for the same path within this window (ms).
+     * Helps with React Strict Mode double-mount; typical: 500–1000.
+     */
+    pageViewDedupeMs?: number;
+};
+type TrackPageViewOptions = {
+    path?: string;
+    source?: string;
+    device?: string;
+    country?: string;
+    metadata?: Record<string, unknown>;
+};
+/**
+ * Create a tracker instance. Safe to call once per app and reuse.
+ */
+declare function createJmpAnalytics(config: JmpAnalyticsConfig): {
+    track: (type: JmpEventType, payload: {
+        path: string;
+        metadata?: Record<string, unknown>;
+        source?: string;
+        device?: string;
+        country?: string;
+    }) => Promise<void>;
+    trackPageView: (options?: TrackPageViewOptions) => Promise<void>;
+    trackFormSubmit: (path: string, metadata?: Record<string, unknown>) => Promise<void>;
+    trackCallClick: (path: string, metadata?: Record<string, unknown>) => Promise<void>;
+    subscribeToSpaNavigation: () => () => void;
+};
+type JmpAnalytics = ReturnType<typeof createJmpAnalytics>;
+
+export { type JmpAnalytics, type JmpAnalyticsConfig, type JmpEventType, type TrackPageViewOptions, createJmpAnalytics };

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+type JmpEventType = "page_view" | "form_submit" | "call_click";
+type JmpAnalyticsConfig = {
+    /** Dashboard origin, e.g. https://analytics.example.com (no trailing slash) */
+    baseUrl: string;
+    /** Per-website key from JMP admin */
+    trackingKey: string;
+    /** Log requests to console */
+    debug?: boolean;
+    /** Override fetch (tests, React Native) */
+    fetchImpl?: typeof fetch;
+    /**
+     * Suppress duplicate `page_view` for the same path within this window (ms).
+     * Helps with React Strict Mode double-mount; typical: 500–1000.
+     */
+    pageViewDedupeMs?: number;
+};
+type TrackPageViewOptions = {
+    path?: string;
+    source?: string;
+    device?: string;
+    country?: string;
+    metadata?: Record<string, unknown>;
+};
+/**
+ * Create a tracker instance. Safe to call once per app and reuse.
+ */
+declare function createJmpAnalytics(config: JmpAnalyticsConfig): {
+    track: (type: JmpEventType, payload: {
+        path: string;
+        metadata?: Record<string, unknown>;
+        source?: string;
+        device?: string;
+        country?: string;
+    }) => Promise<void>;
+    trackPageView: (options?: TrackPageViewOptions) => Promise<void>;
+    trackFormSubmit: (path: string, metadata?: Record<string, unknown>) => Promise<void>;
+    trackCallClick: (path: string, metadata?: Record<string, unknown>) => Promise<void>;
+    subscribeToSpaNavigation: () => () => void;
+};
+type JmpAnalytics = ReturnType<typeof createJmpAnalytics>;
+
+export { type JmpAnalytics, type JmpAnalyticsConfig, type JmpEventType, type TrackPageViewOptions, createJmpAnalytics };

package/dist/index.js

@@ -0,0 +1,166 @@
+// src/index.ts
+var DEFAULT_SOURCE = "direct";
+var SESSION_STORAGE_KEY = "jmp_analytics_sid";
+function normalizeBaseUrl(baseUrl) {
+  return baseUrl.replace(/\/$/, "");
+}
+function inferDevice() {
+  if (typeof window === "undefined") {
+    return "unknown";
+  }
+  return window.innerWidth < 768 ? "mobile" : "desktop";
+}
+function getOrCreateSessionId() {
+  if (typeof window === "undefined" || !globalThis.crypto?.randomUUID) {
+    return void 0;
+  }
+  try {
+    let id = sessionStorage.getItem(SESSION_STORAGE_KEY);
+    if (!id) {
+      id = crypto.randomUUID();
+      sessionStorage.setItem(SESSION_STORAGE_KEY, id);
+    }
+    return id;
+  } catch {
+    return void 0;
+  }
+}
+function createJmpAnalytics(config) {
+  const baseUrl = normalizeBaseUrl(config.baseUrl);
+  const resolvedFetch = config.fetchImpl ?? (typeof globalThis !== "undefined" && globalThis.fetch ? globalThis.fetch.bind(globalThis) : void 0);
+  if (!resolvedFetch) {
+    throw new Error(
+      "createJmpAnalytics: fetch is not available; pass fetchImpl in config"
+    );
+  }
+  const fetchFn = resolvedFetch;
+  let lastDedupePath = "";
+  let lastDedupeAt = 0;
+  async function send(body) {
+    const url = `${baseUrl}/api/events`;
+    const headers = {
+      "Content-Type": "application/json",
+      "X-JMP-Tracking-Key": config.trackingKey
+    };
+    const sid = getOrCreateSessionId();
+    const payload = { ...body, ...sid ? { sessionId: sid } : {} };
+    if (config.debug) {
+      console.debug("[@jmp-technologies/analytics]", "POST", url, payload);
+    }
+    const res = await fetchFn(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(payload),
+      keepalive: true
+    });
+    if (!res.ok) {
+      let detail = "";
+      try {
+        const err = await res.json();
+        detail = err.error ?? await res.text();
+      } catch {
+        detail = await res.text();
+      }
+      throw new Error(`JMP Analytics HTTP ${res.status}: ${detail}`);
+    }
+  }
+  function shouldDedupePageView(path) {
+    const ms = config.pageViewDedupeMs ?? 0;
+    if (ms <= 0 || typeof window === "undefined") {
+      return false;
+    }
+    const now = Date.now();
+    if (path === lastDedupePath && now - lastDedupeAt < ms) {
+      return true;
+    }
+    lastDedupePath = path;
+    lastDedupeAt = now;
+    return false;
+  }
+  function trackPageView(options) {
+    const path = options?.path ?? (typeof window !== "undefined" ? window.location.pathname : "/");
+    if (shouldDedupePageView(path)) {
+      return Promise.resolve();
+    }
+    return send({
+      type: "page_view",
+      path: path || "/",
+      source: options?.source ?? DEFAULT_SOURCE,
+      device: options?.device ?? inferDevice(),
+      country: options?.country,
+      metadata: options?.metadata && typeof options.metadata === "object" ? options.metadata : {}
+    });
+  }
+  function trackFormSubmit(path, metadata) {
+    return send({
+      type: "form_submit",
+      path: path || "/",
+      metadata: metadata ?? {}
+    });
+  }
+  function trackCallClick(path, metadata) {
+    return send({
+      type: "call_click",
+      path: path || "/",
+      metadata: metadata ?? {}
+    });
+  }
+  function track(type, payload) {
+    if (type === "page_view") {
+      return trackPageView({
+        path: payload.path,
+        source: payload.source,
+        device: payload.device,
+        country: payload.country,
+        metadata: payload.metadata
+      });
+    }
+    if (type === "form_submit") {
+      return trackFormSubmit(payload.path, payload.metadata);
+    }
+    return trackCallClick(payload.path, payload.metadata);
+  }
+  function subscribeToSpaNavigation() {
+    if (typeof window === "undefined") {
+      return () => {
+      };
+    }
+    let lastPath = window.location.pathname;
+    const run = () => {
+      const path = window.location.pathname;
+      if (path !== lastPath) {
+        lastPath = path;
+        void trackPageView({ path });
+      }
+    };
+    window.addEventListener("popstate", run);
+    const push = history.pushState.bind(history);
+    const replace = history.replaceState.bind(history);
+    history.pushState = (...args) => {
+      const r = push(...args);
+      queueMicrotask(run);
+      return r;
+    };
+    history.replaceState = (...args) => {
+      const r = replace(...args);
+      queueMicrotask(run);
+      return r;
+    };
+    return () => {
+      window.removeEventListener("popstate", run);
+      history.pushState = push;
+      history.replaceState = replace;
+    };
+  }
+  return {
+    track,
+    trackPageView,
+    trackFormSubmit,
+    trackCallClick,
+    subscribeToSpaNavigation
+  };
+}
+export {
+  createJmpAnalytics
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export type JmpEventType = \"page_view\" | \"form_submit\" | \"call_click\"\n\nexport type JmpAnalyticsConfig = {\n  /** Dashboard origin, e.g. https://analytics.example.com (no trailing slash) */\n  baseUrl: string\n  /** Per-website key from JMP admin */\n  trackingKey: string\n  /** Log requests to console */\n  debug?: boolean\n  /** Override fetch (tests, React Native) */\n  fetchImpl?: typeof fetch\n  /**\n   * Suppress duplicate `page_view` for the same path within this window (ms).\n   * Helps with React Strict Mode double-mount; typical: 500–1000.\n   */\n  pageViewDedupeMs?: number\n}\n\nexport type TrackPageViewOptions = {\n  path?: string\n  source?: string\n  device?: string\n  country?: string\n  metadata?: Record<string, unknown>\n}\n\nconst DEFAULT_SOURCE = \"direct\"\nconst SESSION_STORAGE_KEY = \"jmp_analytics_sid\"\n\nfunction normalizeBaseUrl(baseUrl: string) {\n  return baseUrl.replace(/\\/$/, \"\")\n}\n\nfunction inferDevice(): string {\n  if (typeof window === \"undefined\") {\n    return \"unknown\"\n  }\n  return window.innerWidth < 768 ? \"mobile\" : \"desktop\"\n}\n\n/** Stable per-tab session id for bounce and unique session metrics (server-stored). */\nfunction getOrCreateSessionId(): string | undefined {\n  if (typeof window === \"undefined\" || !globalThis.crypto?.randomUUID) {\n    return undefined\n  }\n  try {\n    let id = sessionStorage.getItem(SESSION_STORAGE_KEY)\n    if (!id) {\n      id = crypto.randomUUID()\n      sessionStorage.setItem(SESSION_STORAGE_KEY, id)\n    }\n    return id\n  } catch {\n    return undefined\n  }\n}\n\n/**\n * Create a tracker instance. Safe to call once per app and reuse.\n */\nexport function createJmpAnalytics(config: JmpAnalyticsConfig) {\n  const baseUrl = normalizeBaseUrl(config.baseUrl)\n  const resolvedFetch =\n    config.fetchImpl ??\n    (typeof globalThis !== \"undefined\" && globalThis.fetch\n      ? globalThis.fetch.bind(globalThis)\n      : undefined)\n\n  if (!resolvedFetch) {\n    throw new Error(\n      \"createJmpAnalytics: fetch is not available; pass fetchImpl in config\"\n    )\n  }\n\n  const fetchFn: typeof fetch = resolvedFetch\n\n  let lastDedupePath = \"\"\n  let lastDedupeAt = 0\n\n  async function send(body: Record<string, unknown>) {\n    const url = `${baseUrl}/api/events`\n    const headers: Record<string, string> = {\n      \"Content-Type\": \"application/json\",\n      \"X-JMP-Tracking-Key\": config.trackingKey,\n    }\n\n    const sid = getOrCreateSessionId()\n    const payload = { ...body, ...(sid ? { sessionId: sid } : {}) }\n\n    if (config.debug) {\n      console.debug(\"[@jmp-technologies/analytics]\", \"POST\", url, payload)\n    }\n\n    const res = await fetchFn(url, {\n      method: \"POST\",\n      headers,\n      body: JSON.stringify(payload),\n      keepalive: true,\n    })\n\n    if (!res.ok) {\n      let detail = \"\"\n      try {\n        const err = (await res.json()) as { error?: string }\n        detail = err.error ?? (await res.text())\n      } catch {\n        detail = await res.text()\n      }\n      throw new Error(`JMP Analytics HTTP ${res.status}: ${detail}`)\n    }\n  }\n\n  function shouldDedupePageView(path: string): boolean {\n    const ms = config.pageViewDedupeMs ?? 0\n    if (ms <= 0 || typeof window === \"undefined\") {\n      return false\n    }\n    const now = Date.now()\n    if (path === lastDedupePath && now - lastDedupeAt < ms) {\n      return true\n    }\n    lastDedupePath = path\n    lastDedupeAt = now\n    return false\n  }\n\n  function trackPageView(options?: TrackPageViewOptions) {\n    const path =\n      options?.path ??\n      (typeof window !== \"undefined\" ? window.location.pathname : \"/\")\n\n    if (shouldDedupePageView(path)) {\n      return Promise.resolve()\n    }\n\n    return send({\n      type: \"page_view\",\n      path: path || \"/\",\n      source: options?.source ?? DEFAULT_SOURCE,\n      device: options?.device ?? inferDevice(),\n      country: options?.country,\n      metadata:\n        options?.metadata && typeof options.metadata === \"object\"\n          ? options.metadata\n          : {},\n    })\n  }\n\n  function trackFormSubmit(\n    path: string,\n    metadata?: Record<string, unknown>\n  ) {\n    return send({\n      type: \"form_submit\",\n      path: path || \"/\",\n      metadata: metadata ?? {},\n    })\n  }\n\n  function trackCallClick(\n    path: string,\n    metadata?: Record<string, unknown>\n  ) {\n    return send({\n      type: \"call_click\",\n      path: path || \"/\",\n      metadata: metadata ?? {},\n    })\n  }\n\n  function track(\n    type: JmpEventType,\n    payload: {\n      path: string\n      metadata?: Record<string, unknown>\n      source?: string\n      device?: string\n      country?: string\n    }\n  ) {\n    if (type === \"page_view\") {\n      return trackPageView({\n        path: payload.path,\n        source: payload.source,\n        device: payload.device,\n        country: payload.country,\n        metadata: payload.metadata,\n      })\n    }\n    if (type === \"form_submit\") {\n      return trackFormSubmit(payload.path, payload.metadata)\n    }\n    return trackCallClick(payload.path, payload.metadata)\n  }\n\n  /**\n   * Fire `page_view` on browser back/forward and when `history.pushState` /\n   * `replaceState` are used (many SPAs). Call once after creating the tracker.\n   * Returns an unsubscribe function.\n   */\n  function subscribeToSpaNavigation(): () => void {\n    if (typeof window === \"undefined\") {\n      return () => {}\n    }\n\n    let lastPath = window.location.pathname\n\n    const run = () => {\n      const path = window.location.pathname\n      if (path !== lastPath) {\n        lastPath = path\n        void trackPageView({ path })\n      }\n    }\n\n    window.addEventListener(\"popstate\", run)\n\n    const push = history.pushState.bind(history)\n    const replace = history.replaceState.bind(history)\n\n    history.pushState = (...args: Parameters<History[\"pushState\"]>) => {\n      const r = push(...args)\n      queueMicrotask(run)\n      return r\n    }\n    history.replaceState = (...args: Parameters<History[\"replaceState\"]>) => {\n      const r = replace(...args)\n      queueMicrotask(run)\n      return r\n    }\n\n    return () => {\n      window.removeEventListener(\"popstate\", run)\n      history.pushState = push\n      history.replaceState = replace\n    }\n  }\n\n  return {\n    track,\n    trackPageView,\n    trackFormSubmit,\n    trackCallClick,\n    subscribeToSpaNavigation,\n  }\n}\n\nexport type JmpAnalytics = ReturnType<typeof createJmpAnalytics>\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@jmp-technologies/analytics",
+  "version": "0.1.0",
+  "description": "Browser client for JMP Analytics event ingestion",
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": ["dist"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean --sourcemap"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  }
+}