@xray-analytics/analytics-react 0.0.2

package/dist/index.d.mts

@@ -0,0 +1,84 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { PropsWithChildren } from 'react';
+
+type Transport = 'auto' | 'bff' | 'direct';
+type AnalyticsEnvironment = 'local' | 'dev' | 'production';
+type TrackProps = Record<string, unknown>;
+type TrackTags = string[];
+type TrackEventName = 'page_view' | 'click_link' | 'redirect' | 'click_button' | 'scroll' | 'element_view' | (string & {});
+type TrackCatalogEntry = {
+    trackName: string;
+    validateOn?: 'props' | 'event';
+    version?: number;
+    description?: string;
+    tags?: string[];
+    deprecated?: boolean;
+    schema?: Record<string, unknown>;
+};
+type AnalyticsTrackMetadataConfig = {
+    enabled?: boolean;
+    includeIp?: boolean;
+    includeUserAgent?: boolean;
+    includeDevice?: boolean;
+    includeLanguage?: boolean;
+    includeScreen?: boolean;
+    staticIp?: string;
+    resolveIp?: () => Promise<string | undefined>;
+};
+type AnalyticsTrackClientMetadata = {
+    ip?: string;
+    userAgent?: string;
+    isMobile?: boolean;
+    os?: 'android' | 'ios' | 'macos' | 'windows' | 'linux' | 'unknown';
+    platform?: string;
+    language?: string;
+    screen?: {
+        width: number;
+        height: number;
+    };
+};
+type TrackOptions = {
+    metadata?: boolean | AnalyticsTrackMetadataConfig;
+};
+type AnalyticsProviderProps = PropsWithChildren<{
+    appId: string;
+    transport?: Transport;
+    bffEndpoint?: string;
+    directEndpoint?: string;
+    writeKey?: string;
+    environment?: AnalyticsEnvironment | string;
+    autoPageViews?: boolean;
+    debug?: boolean;
+    preferSendBeacon?: boolean;
+    metadata?: boolean | AnalyticsTrackMetadataConfig;
+    catalog?: TrackCatalogEntry[];
+    catalogEndpoint?: string;
+    strictCatalog?: boolean;
+}>;
+type SendTrack = (name: TrackEventName, props?: TrackProps, tags?: TrackTags, options?: TrackOptions) => void;
+type AnalyticsContextValue = {
+    track: SendTrack;
+    sendTrack: SendTrack;
+    trackPageView: (props?: TrackProps, tags?: TrackTags) => void;
+    trackClickLink: (props?: TrackProps, tags?: TrackTags) => void;
+    trackRedirect: (props?: TrackProps, tags?: TrackTags) => void;
+    trackClickButton: (props?: TrackProps, tags?: TrackTags) => void;
+    trackScroll: (props?: TrackProps, tags?: TrackTags) => void;
+    trackElementView: (props?: TrackProps, tags?: TrackTags) => void;
+};
+type TrackPageViewProps = {
+    props?: TrackProps;
+    trackOnPopState?: boolean;
+};
+
+declare function AnalyticsProvider({ children, appId, transport, bffEndpoint, directEndpoint, writeKey, environment, autoPageViews, debug, preferSendBeacon, metadata, catalog, catalogEndpoint, strictCatalog, }: AnalyticsProviderProps): react_jsx_runtime.JSX.Element;
+
+declare function useTrackPageView(props?: TrackProps, trackOnPopState?: boolean): void;
+declare function TrackPageView({ props, trackOnPopState }: TrackPageViewProps): null;
+
+type UseAnalyticsOptions = {
+    metadata?: boolean | AnalyticsTrackMetadataConfig;
+};
+declare function useAnalytics(options?: UseAnalyticsOptions): AnalyticsContextValue;
+
+export { type AnalyticsEnvironment, AnalyticsProvider, type AnalyticsProviderProps, type AnalyticsTrackClientMetadata, type AnalyticsTrackMetadataConfig, type SendTrack, type TrackCatalogEntry, type TrackEventName, type TrackOptions, TrackPageView, type TrackPageViewProps, type TrackProps, type Transport, useAnalytics, useTrackPageView };

package/dist/index.d.ts

@@ -0,0 +1,84 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { PropsWithChildren } from 'react';
+
+type Transport = 'auto' | 'bff' | 'direct';
+type AnalyticsEnvironment = 'local' | 'dev' | 'production';
+type TrackProps = Record<string, unknown>;
+type TrackTags = string[];
+type TrackEventName = 'page_view' | 'click_link' | 'redirect' | 'click_button' | 'scroll' | 'element_view' | (string & {});
+type TrackCatalogEntry = {
+    trackName: string;
+    validateOn?: 'props' | 'event';
+    version?: number;
+    description?: string;
+    tags?: string[];
+    deprecated?: boolean;
+    schema?: Record<string, unknown>;
+};
+type AnalyticsTrackMetadataConfig = {
+    enabled?: boolean;
+    includeIp?: boolean;
+    includeUserAgent?: boolean;
+    includeDevice?: boolean;
+    includeLanguage?: boolean;
+    includeScreen?: boolean;
+    staticIp?: string;
+    resolveIp?: () => Promise<string | undefined>;
+};
+type AnalyticsTrackClientMetadata = {
+    ip?: string;
+    userAgent?: string;
+    isMobile?: boolean;
+    os?: 'android' | 'ios' | 'macos' | 'windows' | 'linux' | 'unknown';
+    platform?: string;
+    language?: string;
+    screen?: {
+        width: number;
+        height: number;
+    };
+};
+type TrackOptions = {
+    metadata?: boolean | AnalyticsTrackMetadataConfig;
+};
+type AnalyticsProviderProps = PropsWithChildren<{
+    appId: string;
+    transport?: Transport;
+    bffEndpoint?: string;
+    directEndpoint?: string;
+    writeKey?: string;
+    environment?: AnalyticsEnvironment | string;
+    autoPageViews?: boolean;
+    debug?: boolean;
+    preferSendBeacon?: boolean;
+    metadata?: boolean | AnalyticsTrackMetadataConfig;
+    catalog?: TrackCatalogEntry[];
+    catalogEndpoint?: string;
+    strictCatalog?: boolean;
+}>;
+type SendTrack = (name: TrackEventName, props?: TrackProps, tags?: TrackTags, options?: TrackOptions) => void;
+type AnalyticsContextValue = {
+    track: SendTrack;
+    sendTrack: SendTrack;
+    trackPageView: (props?: TrackProps, tags?: TrackTags) => void;
+    trackClickLink: (props?: TrackProps, tags?: TrackTags) => void;
+    trackRedirect: (props?: TrackProps, tags?: TrackTags) => void;
+    trackClickButton: (props?: TrackProps, tags?: TrackTags) => void;
+    trackScroll: (props?: TrackProps, tags?: TrackTags) => void;
+    trackElementView: (props?: TrackProps, tags?: TrackTags) => void;
+};
+type TrackPageViewProps = {
+    props?: TrackProps;
+    trackOnPopState?: boolean;
+};
+
+declare function AnalyticsProvider({ children, appId, transport, bffEndpoint, directEndpoint, writeKey, environment, autoPageViews, debug, preferSendBeacon, metadata, catalog, catalogEndpoint, strictCatalog, }: AnalyticsProviderProps): react_jsx_runtime.JSX.Element;
+
+declare function useTrackPageView(props?: TrackProps, trackOnPopState?: boolean): void;
+declare function TrackPageView({ props, trackOnPopState }: TrackPageViewProps): null;
+
+type UseAnalyticsOptions = {
+    metadata?: boolean | AnalyticsTrackMetadataConfig;
+};
+declare function useAnalytics(options?: UseAnalyticsOptions): AnalyticsContextValue;
+
+export { type AnalyticsEnvironment, AnalyticsProvider, type AnalyticsProviderProps, type AnalyticsTrackClientMetadata, type AnalyticsTrackMetadataConfig, type SendTrack, type TrackCatalogEntry, type TrackEventName, type TrackOptions, TrackPageView, type TrackPageViewProps, type TrackProps, type Transport, useAnalytics, useTrackPageView };

package/dist/index.js

@@ -0,0 +1,360 @@
+"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.tsx
+var index_exports = {};
+__export(index_exports, {
+  AnalyticsProvider: () => AnalyticsProvider,
+  TrackPageView: () => TrackPageView,
+  useAnalytics: () => useAnalytics,
+  useTrackPageView: () => useTrackPageView
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/core/provider.tsx
+var import_react2 = require("react");
+
+// src/core/context.ts
+var import_react = require("react");
+var AnalyticsContext = (0, import_react.createContext)(null);
+
+// src/runtime/catalog.ts
+function createCatalogMap(catalog) {
+  return new Map(catalog.map((entry) => [entry.trackName, entry]));
+}
+async function fetchCatalog(endpoint) {
+  const response = await fetch(endpoint, { method: "GET", cache: "no-store" });
+  if (!response.ok) {
+    throw new Error(`Failed to fetch track catalog (${response.status})`);
+  }
+  const payload = await response.json();
+  if (!payload.ok || !payload.data?.tracks) {
+    throw new Error("Invalid track catalog response");
+  }
+  return payload.data.tracks;
+}
+
+// src/runtime/environment.ts
+function normalizeEnvironment(environment) {
+  if (!environment) return "production";
+  const env = environment.toLowerCase();
+  if (env === "production" || env === "prod") return "production";
+  if (env === "development" || env === "dev") return "dev";
+  return "local";
+}
+
+// src/runtime/metadata.ts
+function detectOs(userAgent) {
+  const ua = userAgent.toLowerCase();
+  if (/android/.test(ua)) return "android";
+  if (/iphone|ipad|ipod/.test(ua)) return "ios";
+  if (/mac os x|macintosh/.test(ua)) return "macos";
+  if (/windows nt/.test(ua)) return "windows";
+  if (/linux/.test(ua)) return "linux";
+  return "unknown";
+}
+function normalizeMetadataConfig(metadata) {
+  if (!metadata) return null;
+  if (metadata === true) {
+    return {
+      enabled: true,
+      includeIp: true,
+      includeUserAgent: true,
+      includeDevice: true,
+      includeLanguage: true,
+      includeScreen: true
+    };
+  }
+  return {
+    enabled: metadata.enabled ?? true,
+    includeIp: metadata.includeIp ?? true,
+    includeUserAgent: metadata.includeUserAgent ?? true,
+    includeDevice: metadata.includeDevice ?? true,
+    includeLanguage: metadata.includeLanguage ?? true,
+    includeScreen: metadata.includeScreen ?? true,
+    staticIp: metadata.staticIp,
+    resolveIp: metadata.resolveIp
+  };
+}
+async function collectTrackClientMetadata(metadata) {
+  if (typeof window === "undefined" || typeof navigator === "undefined") return void 0;
+  const config = normalizeMetadataConfig(metadata);
+  if (!config || !config.enabled) return void 0;
+  const userAgent = navigator.userAgent;
+  const os = detectOs(userAgent);
+  const isMobile = /iphone|ipad|ipod|android|mobile/.test(userAgent.toLowerCase());
+  let ip;
+  if (config.includeIp) {
+    if (config.staticIp) {
+      ip = config.staticIp;
+    } else if (config.resolveIp) {
+      ip = await config.resolveIp().catch(() => void 0);
+    }
+  }
+  const metadataPayload = {
+    ip,
+    userAgent: config.includeUserAgent ? userAgent : void 0,
+    isMobile: config.includeDevice ? isMobile : void 0,
+    os: config.includeDevice ? os : void 0,
+    platform: config.includeDevice ? navigator.platform : void 0,
+    language: config.includeLanguage ? navigator.language : void 0,
+    screen: config.includeScreen && window.screen ? {
+      width: window.screen.width,
+      height: window.screen.height
+    } : void 0
+  };
+  const hasValue = Object.values(metadataPayload).some((value) => value !== void 0);
+  return hasValue ? metadataPayload : void 0;
+}
+
+// src/runtime/session.ts
+function getOrCreateSessionId() {
+  const key = "xray_session_id";
+  let id = localStorage.getItem(key);
+  if (!id) {
+    id = crypto.randomUUID();
+    localStorage.setItem(key, id);
+  }
+  return id;
+}
+
+// src/runtime/transport.ts
+async function sendBeaconFirst(url, payload, options) {
+  const preferBeacon = options?.preferBeacon ?? true;
+  if (preferBeacon && typeof navigator !== "undefined" && navigator.sendBeacon) {
+    try {
+      const ok = navigator.sendBeacon(url, new Blob([payload], { type: "application/json" }));
+      if (ok) return { ok: true, status: 204 };
+    } catch {
+    }
+  }
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: payload,
+      keepalive: true
+    });
+    return { ok: res.ok, status: res.status };
+  } catch {
+    return { ok: false, status: 0 };
+  }
+}
+
+// src/core/provider.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+function AnalyticsProvider({
+  children,
+  appId,
+  transport = "auto",
+  bffEndpoint = "/api/track",
+  directEndpoint,
+  writeKey,
+  environment = "production",
+  autoPageViews = true,
+  debug = false,
+  preferSendBeacon = true,
+  metadata,
+  catalog,
+  catalogEndpoint,
+  strictCatalog = false
+}) {
+  const sessionIdRef = (0, import_react2.useRef)(null);
+  const catalogMapRef = (0, import_react2.useRef)(
+    catalog ? createCatalogMap(catalog) : null
+  );
+  if (typeof window !== "undefined" && !sessionIdRef.current) {
+    sessionIdRef.current = getOrCreateSessionId();
+  }
+  (0, import_react2.useEffect)(() => {
+    if (!catalog) return;
+    catalogMapRef.current = createCatalogMap(catalog);
+  }, [catalog]);
+  (0, import_react2.useEffect)(() => {
+    if (!catalogEndpoint || typeof window === "undefined") return;
+    let cancelled = false;
+    fetchCatalog(catalogEndpoint).then((tracks) => {
+      if (cancelled) return;
+      catalogMapRef.current = createCatalogMap(tracks);
+    }).catch((error) => {
+      if (!debug) return;
+      console.warn(
+        "[xray] failed to load track catalog from endpoint",
+        error instanceof Error ? error.message : error
+      );
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [catalogEndpoint, debug]);
+  const base = (0, import_react2.useMemo)(
+    () => ({
+      appId,
+      sessionId: sessionIdRef.current ?? "unknown"
+    }),
+    [appId]
+  );
+  const sendTrack = (0, import_react2.useCallback)(
+    (name, props, tags, options) => {
+      if (typeof window === "undefined") return;
+      const resolvedEnvironment = normalizeEnvironment(environment);
+      const catalogMap = catalogMapRef.current;
+      if (catalogMap) {
+        const entry = catalogMap.get(name);
+        if (!entry) {
+          if (debug) {
+            console.warn(`[xray] track '${name}' does not exist in the loaded catalog`);
+          }
+          if (strictCatalog) return;
+        } else if (entry.deprecated && debug) {
+          console.warn(`[xray] track '${name}' is marked as deprecated in the catalog`);
+        }
+      }
+      (async () => {
+        const metadataConfig = (() => {
+          if (options?.metadata === void 0) return metadata;
+          if (options.metadata === true || options.metadata === false) return options.metadata;
+          const baseMetadataConfig = typeof metadata === "object" && metadata ? metadata : {};
+          return {
+            ...baseMetadataConfig,
+            ...options.metadata
+          };
+        })();
+        const clientMeta = await collectTrackClientMetadata(metadataConfig);
+        const event = {
+          name,
+          ts: Date.now(),
+          url: window.location.href,
+          path: window.location.pathname,
+          ref: document.referrer || void 0,
+          environment: resolvedEnvironment,
+          ...base,
+          props: props ?? void 0,
+          tags: tags ?? void 0,
+          clientMeta: clientMeta ?? void 0,
+          writeKey: writeKey ?? void 0
+        };
+        if (resolvedEnvironment !== "production") {
+          console.log("[xray][track]", event);
+          return;
+        }
+        const payload = JSON.stringify(event);
+        const sendWithTransport = (url) => preferSendBeacon ? sendBeaconFirst(url, payload) : sendBeaconFirst(url, payload, { preferBeacon: false });
+        if (transport === "bff") {
+          await sendWithTransport(bffEndpoint);
+          return;
+        }
+        if (transport === "direct") {
+          if (!directEndpoint) return;
+          await sendWithTransport(directEndpoint);
+          return;
+        }
+        const r1 = await sendWithTransport(bffEndpoint).catch(() => null);
+        if (r1?.ok) return;
+        if (directEndpoint) {
+          await sendWithTransport(directEndpoint).catch(() => null);
+        }
+      })().catch(() => {
+      });
+    },
+    [
+      base,
+      transport,
+      bffEndpoint,
+      directEndpoint,
+      writeKey,
+      debug,
+      environment,
+      strictCatalog,
+      preferSendBeacon,
+      metadata
+    ]
+  );
+  (0, import_react2.useEffect)(() => {
+    if (!autoPageViews || typeof window === "undefined") return;
+    sendTrack("page_view");
+    const notify = () => sendTrack("page_view");
+    window.addEventListener("popstate", notify);
+    return () => window.removeEventListener("popstate", notify);
+  }, [autoPageViews, sendTrack]);
+  const value = (0, import_react2.useMemo)(
+    () => ({
+      track: sendTrack,
+      sendTrack,
+      trackPageView: (props, tags) => sendTrack("page_view", props, tags),
+      trackClickLink: (props, tags) => sendTrack("click_link", props, tags),
+      trackRedirect: (props, tags) => sendTrack("redirect", props, tags),
+      trackClickButton: (props, tags) => sendTrack("click_button", props, tags),
+      trackScroll: (props, tags) => sendTrack("scroll", props, tags),
+      trackElementView: (props, tags) => sendTrack("element_view", props, tags)
+    }),
+    [sendTrack]
+  );
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(AnalyticsContext.Provider, { value, children });
+}
+
+// src/hooks/track-page-view.tsx
+var import_react4 = require("react");
+
+// src/hooks/use-analytics.ts
+var import_react3 = require("react");
+function useAnalytics(options) {
+  const ctx = (0, import_react3.useContext)(AnalyticsContext);
+  if (!ctx) throw new Error("useAnalytics must be used within AnalyticsProvider");
+  const metadataOption = options?.metadata;
+  const wrapped = (0, import_react3.useMemo)(
+    () => ({
+      ...ctx,
+      track: (name, props, tags) => ctx.track(name, props, tags, { metadata: metadataOption }),
+      sendTrack: (name, props, tags) => ctx.sendTrack(name, props, tags, { metadata: metadataOption }),
+      trackPageView: (props, tags) => ctx.track("page_view", props, tags, { metadata: metadataOption }),
+      trackClickLink: (props, tags) => ctx.track("click_link", props, tags, { metadata: metadataOption }),
+      trackRedirect: (props, tags) => ctx.track("redirect", props, tags, { metadata: metadataOption }),
+      trackClickButton: (props, tags) => ctx.track("click_button", props, tags, { metadata: metadataOption }),
+      trackScroll: (props, tags) => ctx.track("scroll", props, tags, { metadata: metadataOption }),
+      trackElementView: (props, tags) => ctx.track("element_view", props, tags, { metadata: metadataOption })
+    }),
+    [ctx, metadataOption]
+  );
+  return metadataOption ? wrapped : ctx;
+}
+
+// src/hooks/track-page-view.tsx
+function useTrackPageView(props, trackOnPopState = true) {
+  const { trackPageView } = useAnalytics();
+  (0, import_react4.useEffect)(() => {
+    if (typeof window === "undefined") return;
+    trackPageView(props);
+    if (!trackOnPopState) return;
+    const notify = () => trackPageView(props);
+    window.addEventListener("popstate", notify);
+    return () => window.removeEventListener("popstate", notify);
+  }, [trackPageView, props, trackOnPopState]);
+}
+function TrackPageView({ props, trackOnPopState = true }) {
+  useTrackPageView(props, trackOnPopState);
+  return null;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AnalyticsProvider,
+  TrackPageView,
+  useAnalytics,
+  useTrackPageView
+});

package/dist/index.mjs

@@ -0,0 +1,330 @@
+// src/core/provider.tsx
+import { useCallback, useEffect, useMemo, useRef } from "react";
+
+// src/core/context.ts
+import { createContext } from "react";
+var AnalyticsContext = createContext(null);
+
+// src/runtime/catalog.ts
+function createCatalogMap(catalog) {
+  return new Map(catalog.map((entry) => [entry.trackName, entry]));
+}
+async function fetchCatalog(endpoint) {
+  const response = await fetch(endpoint, { method: "GET", cache: "no-store" });
+  if (!response.ok) {
+    throw new Error(`Failed to fetch track catalog (${response.status})`);
+  }
+  const payload = await response.json();
+  if (!payload.ok || !payload.data?.tracks) {
+    throw new Error("Invalid track catalog response");
+  }
+  return payload.data.tracks;
+}
+
+// src/runtime/environment.ts
+function normalizeEnvironment(environment) {
+  if (!environment) return "production";
+  const env = environment.toLowerCase();
+  if (env === "production" || env === "prod") return "production";
+  if (env === "development" || env === "dev") return "dev";
+  return "local";
+}
+
+// src/runtime/metadata.ts
+function detectOs(userAgent) {
+  const ua = userAgent.toLowerCase();
+  if (/android/.test(ua)) return "android";
+  if (/iphone|ipad|ipod/.test(ua)) return "ios";
+  if (/mac os x|macintosh/.test(ua)) return "macos";
+  if (/windows nt/.test(ua)) return "windows";
+  if (/linux/.test(ua)) return "linux";
+  return "unknown";
+}
+function normalizeMetadataConfig(metadata) {
+  if (!metadata) return null;
+  if (metadata === true) {
+    return {
+      enabled: true,
+      includeIp: true,
+      includeUserAgent: true,
+      includeDevice: true,
+      includeLanguage: true,
+      includeScreen: true
+    };
+  }
+  return {
+    enabled: metadata.enabled ?? true,
+    includeIp: metadata.includeIp ?? true,
+    includeUserAgent: metadata.includeUserAgent ?? true,
+    includeDevice: metadata.includeDevice ?? true,
+    includeLanguage: metadata.includeLanguage ?? true,
+    includeScreen: metadata.includeScreen ?? true,
+    staticIp: metadata.staticIp,
+    resolveIp: metadata.resolveIp
+  };
+}
+async function collectTrackClientMetadata(metadata) {
+  if (typeof window === "undefined" || typeof navigator === "undefined") return void 0;
+  const config = normalizeMetadataConfig(metadata);
+  if (!config || !config.enabled) return void 0;
+  const userAgent = navigator.userAgent;
+  const os = detectOs(userAgent);
+  const isMobile = /iphone|ipad|ipod|android|mobile/.test(userAgent.toLowerCase());
+  let ip;
+  if (config.includeIp) {
+    if (config.staticIp) {
+      ip = config.staticIp;
+    } else if (config.resolveIp) {
+      ip = await config.resolveIp().catch(() => void 0);
+    }
+  }
+  const metadataPayload = {
+    ip,
+    userAgent: config.includeUserAgent ? userAgent : void 0,
+    isMobile: config.includeDevice ? isMobile : void 0,
+    os: config.includeDevice ? os : void 0,
+    platform: config.includeDevice ? navigator.platform : void 0,
+    language: config.includeLanguage ? navigator.language : void 0,
+    screen: config.includeScreen && window.screen ? {
+      width: window.screen.width,
+      height: window.screen.height
+    } : void 0
+  };
+  const hasValue = Object.values(metadataPayload).some((value) => value !== void 0);
+  return hasValue ? metadataPayload : void 0;
+}
+
+// src/runtime/session.ts
+function getOrCreateSessionId() {
+  const key = "xray_session_id";
+  let id = localStorage.getItem(key);
+  if (!id) {
+    id = crypto.randomUUID();
+    localStorage.setItem(key, id);
+  }
+  return id;
+}
+
+// src/runtime/transport.ts
+async function sendBeaconFirst(url, payload, options) {
+  const preferBeacon = options?.preferBeacon ?? true;
+  if (preferBeacon && typeof navigator !== "undefined" && navigator.sendBeacon) {
+    try {
+      const ok = navigator.sendBeacon(url, new Blob([payload], { type: "application/json" }));
+      if (ok) return { ok: true, status: 204 };
+    } catch {
+    }
+  }
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: payload,
+      keepalive: true
+    });
+    return { ok: res.ok, status: res.status };
+  } catch {
+    return { ok: false, status: 0 };
+  }
+}
+
+// src/core/provider.tsx
+import { jsx } from "react/jsx-runtime";
+function AnalyticsProvider({
+  children,
+  appId,
+  transport = "auto",
+  bffEndpoint = "/api/track",
+  directEndpoint,
+  writeKey,
+  environment = "production",
+  autoPageViews = true,
+  debug = false,
+  preferSendBeacon = true,
+  metadata,
+  catalog,
+  catalogEndpoint,
+  strictCatalog = false
+}) {
+  const sessionIdRef = useRef(null);
+  const catalogMapRef = useRef(
+    catalog ? createCatalogMap(catalog) : null
+  );
+  if (typeof window !== "undefined" && !sessionIdRef.current) {
+    sessionIdRef.current = getOrCreateSessionId();
+  }
+  useEffect(() => {
+    if (!catalog) return;
+    catalogMapRef.current = createCatalogMap(catalog);
+  }, [catalog]);
+  useEffect(() => {
+    if (!catalogEndpoint || typeof window === "undefined") return;
+    let cancelled = false;
+    fetchCatalog(catalogEndpoint).then((tracks) => {
+      if (cancelled) return;
+      catalogMapRef.current = createCatalogMap(tracks);
+    }).catch((error) => {
+      if (!debug) return;
+      console.warn(
+        "[xray] failed to load track catalog from endpoint",
+        error instanceof Error ? error.message : error
+      );
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [catalogEndpoint, debug]);
+  const base = useMemo(
+    () => ({
+      appId,
+      sessionId: sessionIdRef.current ?? "unknown"
+    }),
+    [appId]
+  );
+  const sendTrack = useCallback(
+    (name, props, tags, options) => {
+      if (typeof window === "undefined") return;
+      const resolvedEnvironment = normalizeEnvironment(environment);
+      const catalogMap = catalogMapRef.current;
+      if (catalogMap) {
+        const entry = catalogMap.get(name);
+        if (!entry) {
+          if (debug) {
+            console.warn(`[xray] track '${name}' does not exist in the loaded catalog`);
+          }
+          if (strictCatalog) return;
+        } else if (entry.deprecated && debug) {
+          console.warn(`[xray] track '${name}' is marked as deprecated in the catalog`);
+        }
+      }
+      (async () => {
+        const metadataConfig = (() => {
+          if (options?.metadata === void 0) return metadata;
+          if (options.metadata === true || options.metadata === false) return options.metadata;
+          const baseMetadataConfig = typeof metadata === "object" && metadata ? metadata : {};
+          return {
+            ...baseMetadataConfig,
+            ...options.metadata
+          };
+        })();
+        const clientMeta = await collectTrackClientMetadata(metadataConfig);
+        const event = {
+          name,
+          ts: Date.now(),
+          url: window.location.href,
+          path: window.location.pathname,
+          ref: document.referrer || void 0,
+          environment: resolvedEnvironment,
+          ...base,
+          props: props ?? void 0,
+          tags: tags ?? void 0,
+          clientMeta: clientMeta ?? void 0,
+          writeKey: writeKey ?? void 0
+        };
+        if (resolvedEnvironment !== "production") {
+          console.log("[xray][track]", event);
+          return;
+        }
+        const payload = JSON.stringify(event);
+        const sendWithTransport = (url) => preferSendBeacon ? sendBeaconFirst(url, payload) : sendBeaconFirst(url, payload, { preferBeacon: false });
+        if (transport === "bff") {
+          await sendWithTransport(bffEndpoint);
+          return;
+        }
+        if (transport === "direct") {
+          if (!directEndpoint) return;
+          await sendWithTransport(directEndpoint);
+          return;
+        }
+        const r1 = await sendWithTransport(bffEndpoint).catch(() => null);
+        if (r1?.ok) return;
+        if (directEndpoint) {
+          await sendWithTransport(directEndpoint).catch(() => null);
+        }
+      })().catch(() => {
+      });
+    },
+    [
+      base,
+      transport,
+      bffEndpoint,
+      directEndpoint,
+      writeKey,
+      debug,
+      environment,
+      strictCatalog,
+      preferSendBeacon,
+      metadata
+    ]
+  );
+  useEffect(() => {
+    if (!autoPageViews || typeof window === "undefined") return;
+    sendTrack("page_view");
+    const notify = () => sendTrack("page_view");
+    window.addEventListener("popstate", notify);
+    return () => window.removeEventListener("popstate", notify);
+  }, [autoPageViews, sendTrack]);
+  const value = useMemo(
+    () => ({
+      track: sendTrack,
+      sendTrack,
+      trackPageView: (props, tags) => sendTrack("page_view", props, tags),
+      trackClickLink: (props, tags) => sendTrack("click_link", props, tags),
+      trackRedirect: (props, tags) => sendTrack("redirect", props, tags),
+      trackClickButton: (props, tags) => sendTrack("click_button", props, tags),
+      trackScroll: (props, tags) => sendTrack("scroll", props, tags),
+      trackElementView: (props, tags) => sendTrack("element_view", props, tags)
+    }),
+    [sendTrack]
+  );
+  return /* @__PURE__ */ jsx(AnalyticsContext.Provider, { value, children });
+}
+
+// src/hooks/track-page-view.tsx
+import { useEffect as useEffect2 } from "react";
+
+// src/hooks/use-analytics.ts
+import { useContext, useMemo as useMemo2 } from "react";
+function useAnalytics(options) {
+  const ctx = useContext(AnalyticsContext);
+  if (!ctx) throw new Error("useAnalytics must be used within AnalyticsProvider");
+  const metadataOption = options?.metadata;
+  const wrapped = useMemo2(
+    () => ({
+      ...ctx,
+      track: (name, props, tags) => ctx.track(name, props, tags, { metadata: metadataOption }),
+      sendTrack: (name, props, tags) => ctx.sendTrack(name, props, tags, { metadata: metadataOption }),
+      trackPageView: (props, tags) => ctx.track("page_view", props, tags, { metadata: metadataOption }),
+      trackClickLink: (props, tags) => ctx.track("click_link", props, tags, { metadata: metadataOption }),
+      trackRedirect: (props, tags) => ctx.track("redirect", props, tags, { metadata: metadataOption }),
+      trackClickButton: (props, tags) => ctx.track("click_button", props, tags, { metadata: metadataOption }),
+      trackScroll: (props, tags) => ctx.track("scroll", props, tags, { metadata: metadataOption }),
+      trackElementView: (props, tags) => ctx.track("element_view", props, tags, { metadata: metadataOption })
+    }),
+    [ctx, metadataOption]
+  );
+  return metadataOption ? wrapped : ctx;
+}
+
+// src/hooks/track-page-view.tsx
+function useTrackPageView(props, trackOnPopState = true) {
+  const { trackPageView } = useAnalytics();
+  useEffect2(() => {
+    if (typeof window === "undefined") return;
+    trackPageView(props);
+    if (!trackOnPopState) return;
+    const notify = () => trackPageView(props);
+    window.addEventListener("popstate", notify);
+    return () => window.removeEventListener("popstate", notify);
+  }, [trackPageView, props, trackOnPopState]);
+}
+function TrackPageView({ props, trackOnPopState = true }) {
+  useTrackPageView(props, trackOnPopState);
+  return null;
+}
+export {
+  AnalyticsProvider,
+  TrackPageView,
+  useAnalytics,
+  useTrackPageView
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@xray-analytics/analytics-react",
+  "version": "0.0.2",
+  "private": false,
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "react": ">=19 <20"
+  },
+  "scripts": {
+    "build": "tsup src/index.tsx --format cjs,esm --dts",
+    "lint": "eslint .",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "typecheck": "tsc -p tsconfig.json --noEmit",
+  "devDependencies": {
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "jsdom": "^28.0.0",
+    "react-dom": "^19.2.4"
+  }
+}