@drakkar.software/sunglasses-react 0.2.0

package/dist/index.d.mts

@@ -0,0 +1,122 @@
+import React from 'react';
+import { ISunglassesClient, ScreenTrackingOptions, ConsentStatus } from '@drakkar.software/sunglasses-core';
+export { ConsentStatus, ISunglassesClient, ScreenTrackingOptions, SunglassesConfig, SunglassesCore, SunglassesEvent } from '@drakkar.software/sunglasses-core';
+
+interface SunglassesProviderProps {
+    /** An initialized ISunglassesClient (from SunglassesCore.create()). */
+    client: ISunglassesClient;
+    /** Optional screen tracking configuration. */
+    screenTracking?: ScreenTrackingOptions;
+    children: React.ReactNode;
+}
+/**
+ * Provides a SunGlasses client to the React component tree.
+ *
+ * Place this at the root of your application, wrapping all components that
+ * need access to event tracking.
+ *
+ * @example
+ * ```tsx
+ * const client = await SunglassesCore.create({ ... });
+ *
+ * function App() {
+ *   return (
+ *     <SunglassesProvider client={client} screenTracking={{ useHistoryApi: true }}>
+ *       <Router />
+ *     </SunglassesProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function SunglassesProvider({ client, screenTracking, children, }: SunglassesProviderProps): React.ReactElement;
+
+/**
+ * Read UTM attribution parameters from the current URL and register them as
+ * super properties on the client.
+ *
+ * Call this once at app startup, immediately after `SunglassesCore.create()`.
+ * The registered properties are automatically merged into every subsequent event
+ * until `client.unregister()` or `client.reset()` is called.
+ *
+ * Captured properties (when present):
+ * - `utm_source`         — traffic source (e.g. "google", "newsletter")
+ * - `utm_medium`         — marketing channel (e.g. "cpc", "email")
+ * - `utm_campaign`       — campaign name (e.g. "spring_sale")
+ * - `utm_content`        — ad variant (e.g. "banner_v2")
+ * - `utm_term`           — paid search keyword
+ * - `$referrer`          — full URL of the referring page
+ * - `$referring_domain`  — hostname of the referring page
+ *
+ * @example
+ * ```ts
+ * const client = await SunglassesCore.create({ ... });
+ * captureUtmParams(client); // call once on initial load
+ * ```
+ */
+declare function captureUtmParams(client: ISunglassesClient): void;
+
+/**
+ * Access the SunGlasses client from React context.
+ * Throws if called outside of a SunglassesProvider.
+ */
+declare function useSunglasses(): ISunglassesClient;
+
+/**
+ * Web screen tracking via the History API.
+ *
+ * Monkey-patches history.pushState and history.replaceState, and listens to
+ * the popstate event. Fires client.screen() on every navigation.
+ *
+ * Must be called inside a component that has access to the SunGlasses client,
+ * typically inside SunglassesProvider. Only one instance of this hook should
+ * be active at a time — mounting it in multiple components simultaneously will
+ * result in the second instance being a no-op until the first unmounts.
+ */
+declare function useScreenTracking(client: ISunglassesClient, options?: ScreenTrackingOptions): void;
+
+/**
+ * Returns a bound `capture` function for the current SunGlasses client.
+ *
+ * Shorthand for `useSunglasses().capture` — avoids holding a reference to the
+ * entire client when you only need to fire events from a component.
+ *
+ * The returned function is stable across renders (same reference) as long as
+ * the client itself does not change.
+ *
+ * @example
+ * ```tsx
+ * function SubmitButton() {
+ *   const capture = useCapture();
+ *   return (
+ *     <button onClick={() => capture('form_submitted', { formId: 'signup' })}>
+ *       Submit
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare function useCapture(): (eventName: string, properties?: Record<string, unknown>) => void;
+
+/**
+ * Returns the current consent status as a snapshot.
+ *
+ * This is a convenience hook over `useSunglasses().getConsentStatus()`.
+ *
+ * **Important:** this hook returns a snapshot at render time and does not
+ * subscribe to future changes. Re-renders are not triggered automatically
+ * when `optIn()` or `optOut()` are called. If you need the UI to react to
+ * consent changes, lift the consent call into a parent component that also
+ * manages re-render state, or call `useSunglasses()` directly.
+ *
+ * @example
+ * ```tsx
+ * function ConsentBanner() {
+ *   const status = useConsentStatus();
+ *   if (status !== 'unknown') return null;
+ *   return <Banner />;
+ * }
+ * ```
+ */
+declare function useConsentStatus(): ConsentStatus;
+
+export { SunglassesProvider, type SunglassesProviderProps, captureUtmParams, useCapture, useConsentStatus, useScreenTracking, useSunglasses };

package/dist/index.d.ts

@@ -0,0 +1,122 @@
+import React from 'react';
+import { ISunglassesClient, ScreenTrackingOptions, ConsentStatus } from '@drakkar.software/sunglasses-core';
+export { ConsentStatus, ISunglassesClient, ScreenTrackingOptions, SunglassesConfig, SunglassesCore, SunglassesEvent } from '@drakkar.software/sunglasses-core';
+
+interface SunglassesProviderProps {
+    /** An initialized ISunglassesClient (from SunglassesCore.create()). */
+    client: ISunglassesClient;
+    /** Optional screen tracking configuration. */
+    screenTracking?: ScreenTrackingOptions;
+    children: React.ReactNode;
+}
+/**
+ * Provides a SunGlasses client to the React component tree.
+ *
+ * Place this at the root of your application, wrapping all components that
+ * need access to event tracking.
+ *
+ * @example
+ * ```tsx
+ * const client = await SunglassesCore.create({ ... });
+ *
+ * function App() {
+ *   return (
+ *     <SunglassesProvider client={client} screenTracking={{ useHistoryApi: true }}>
+ *       <Router />
+ *     </SunglassesProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function SunglassesProvider({ client, screenTracking, children, }: SunglassesProviderProps): React.ReactElement;
+
+/**
+ * Read UTM attribution parameters from the current URL and register them as
+ * super properties on the client.
+ *
+ * Call this once at app startup, immediately after `SunglassesCore.create()`.
+ * The registered properties are automatically merged into every subsequent event
+ * until `client.unregister()` or `client.reset()` is called.
+ *
+ * Captured properties (when present):
+ * - `utm_source`         — traffic source (e.g. "google", "newsletter")
+ * - `utm_medium`         — marketing channel (e.g. "cpc", "email")
+ * - `utm_campaign`       — campaign name (e.g. "spring_sale")
+ * - `utm_content`        — ad variant (e.g. "banner_v2")
+ * - `utm_term`           — paid search keyword
+ * - `$referrer`          — full URL of the referring page
+ * - `$referring_domain`  — hostname of the referring page
+ *
+ * @example
+ * ```ts
+ * const client = await SunglassesCore.create({ ... });
+ * captureUtmParams(client); // call once on initial load
+ * ```
+ */
+declare function captureUtmParams(client: ISunglassesClient): void;
+
+/**
+ * Access the SunGlasses client from React context.
+ * Throws if called outside of a SunglassesProvider.
+ */
+declare function useSunglasses(): ISunglassesClient;
+
+/**
+ * Web screen tracking via the History API.
+ *
+ * Monkey-patches history.pushState and history.replaceState, and listens to
+ * the popstate event. Fires client.screen() on every navigation.
+ *
+ * Must be called inside a component that has access to the SunGlasses client,
+ * typically inside SunglassesProvider. Only one instance of this hook should
+ * be active at a time — mounting it in multiple components simultaneously will
+ * result in the second instance being a no-op until the first unmounts.
+ */
+declare function useScreenTracking(client: ISunglassesClient, options?: ScreenTrackingOptions): void;
+
+/**
+ * Returns a bound `capture` function for the current SunGlasses client.
+ *
+ * Shorthand for `useSunglasses().capture` — avoids holding a reference to the
+ * entire client when you only need to fire events from a component.
+ *
+ * The returned function is stable across renders (same reference) as long as
+ * the client itself does not change.
+ *
+ * @example
+ * ```tsx
+ * function SubmitButton() {
+ *   const capture = useCapture();
+ *   return (
+ *     <button onClick={() => capture('form_submitted', { formId: 'signup' })}>
+ *       Submit
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare function useCapture(): (eventName: string, properties?: Record<string, unknown>) => void;
+
+/**
+ * Returns the current consent status as a snapshot.
+ *
+ * This is a convenience hook over `useSunglasses().getConsentStatus()`.
+ *
+ * **Important:** this hook returns a snapshot at render time and does not
+ * subscribe to future changes. Re-renders are not triggered automatically
+ * when `optIn()` or `optOut()` are called. If you need the UI to react to
+ * consent changes, lift the consent call into a parent component that also
+ * manages re-render state, or call `useSunglasses()` directly.
+ *
+ * @example
+ * ```tsx
+ * function ConsentBanner() {
+ *   const status = useConsentStatus();
+ *   if (status !== 'unknown') return null;
+ *   return <Banner />;
+ * }
+ * ```
+ */
+declare function useConsentStatus(): ConsentStatus;
+
+export { SunglassesProvider, type SunglassesProviderProps, captureUtmParams, useCapture, useConsentStatus, useScreenTracking, useSunglasses };

package/dist/index.js

@@ -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, {
+  SunglassesCore: () => import_sunglasses_core.SunglassesCore,
+  SunglassesProvider: () => SunglassesProvider,
+  captureUtmParams: () => captureUtmParams,
+  useCapture: () => useCapture,
+  useConsentStatus: () => useConsentStatus,
+  useScreenTracking: () => useScreenTracking,
+  useSunglasses: () => useSunglasses
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/SunglassesProvider.tsx
+var import_react3 = require("react");
+
+// src/context.ts
+var import_react = require("react");
+var SunglassesContext = (0, import_react.createContext)(null);
+function useSunglasses() {
+  const client = (0, import_react.useContext)(SunglassesContext);
+  if (client === null) {
+    throw new Error(
+      "[SunGlasses] useSunglasses() must be called inside a <SunglassesProvider>."
+    );
+  }
+  return client;
+}
+
+// src/useScreenTracking.ts
+var import_react2 = require("react");
+var historyPatched = false;
+var previousPath = null;
+function useScreenTracking(client, options = {}) {
+  const { useHistoryApi = true, screenNameMapper } = options;
+  const clientRef = (0, import_react2.useRef)(client);
+  clientRef.current = client;
+  const mapperRef = (0, import_react2.useRef)(screenNameMapper);
+  mapperRef.current = screenNameMapper;
+  (0, import_react2.useEffect)(() => {
+    if (!useHistoryApi || typeof window === "undefined") return;
+    if (historyPatched) {
+      console.warn(
+        "[SunGlasses] useScreenTracking: history is already patched by another instance \u2014 this instance will not track."
+      );
+      return;
+    }
+    historyPatched = true;
+    const handleRouteChange = (path) => {
+      const name = mapperRef.current ? mapperRef.current(path) : path;
+      const props = {
+        $path: path,
+        $url: window.location.href
+      };
+      if (document.title) props.$title = document.title;
+      if (previousPath !== null) {
+        props.$referrer = previousPath;
+      } else if (document.referrer) {
+        props.$referrer = document.referrer;
+      }
+      previousPath = path;
+      clientRef.current.screen(name, props);
+    };
+    handleRouteChange(window.location.pathname);
+    const originalPush = history.pushState.bind(history);
+    history.pushState = (...args) => {
+      originalPush(...args);
+      handleRouteChange(window.location.pathname);
+    };
+    const originalReplace = history.replaceState.bind(history);
+    history.replaceState = (...args) => {
+      originalReplace(...args);
+      handleRouteChange(window.location.pathname);
+    };
+    const onPopState = () => handleRouteChange(window.location.pathname);
+    window.addEventListener("popstate", onPopState);
+    return () => {
+      history.pushState = originalPush;
+      history.replaceState = originalReplace;
+      window.removeEventListener("popstate", onPopState);
+      historyPatched = false;
+      previousPath = null;
+    };
+  }, [useHistoryApi]);
+}
+
+// src/SunglassesProvider.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+function SunglassesProvider({
+  client,
+  screenTracking,
+  children
+}) {
+  (0, import_react3.useEffect)(() => {
+    return () => {
+      client.shutdown().catch(() => {
+      });
+    };
+  }, [client]);
+  (0, import_react3.useEffect)(() => {
+    if (typeof document === "undefined") return;
+    const handleVisibilityChange = () => {
+      if (document.visibilityState === "hidden") {
+        client.flush().catch(() => {
+        });
+      }
+    };
+    document.addEventListener("visibilitychange", handleVisibilityChange);
+    return () => document.removeEventListener("visibilitychange", handleVisibilityChange);
+  }, [client]);
+  useScreenTracking(client, screenTracking ?? { useHistoryApi: false });
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(SunglassesContext.Provider, { value: client, children });
+}
+
+// src/captureUtmParams.ts
+var UTM_PARAMS = [
+  "utm_source",
+  "utm_medium",
+  "utm_campaign",
+  "utm_content",
+  "utm_term"
+];
+function captureUtmParams(client) {
+  if (typeof window === "undefined") return;
+  const params = {};
+  const searchParams = new URLSearchParams(window.location.search);
+  for (const key of UTM_PARAMS) {
+    const value = searchParams.get(key);
+    if (value) params[key] = value;
+  }
+  if (document.referrer) {
+    params["$referrer"] = document.referrer;
+    try {
+      params["$referring_domain"] = new URL(document.referrer).hostname;
+    } catch {
+    }
+  }
+  if (Object.keys(params).length > 0) {
+    client.register(params);
+  }
+}
+
+// src/useCapture.ts
+var import_react4 = require("react");
+function useCapture() {
+  const client = useSunglasses();
+  return (0, import_react4.useCallback)(
+    (eventName, properties) => {
+      client.capture(eventName, properties);
+    },
+    [client]
+  );
+}
+
+// src/useConsentStatus.ts
+function useConsentStatus() {
+  const client = useSunglasses();
+  return client.getConsentStatus();
+}
+
+// src/index.ts
+var import_sunglasses_core = require("@drakkar.software/sunglasses-core");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SunglassesCore,
+  SunglassesProvider,
+  captureUtmParams,
+  useCapture,
+  useConsentStatus,
+  useScreenTracking,
+  useSunglasses
+});

package/dist/index.mjs

@@ -0,0 +1,158 @@
+// src/SunglassesProvider.tsx
+import { useEffect as useEffect2 } from "react";
+
+// src/context.ts
+import { createContext, useContext } from "react";
+var SunglassesContext = createContext(null);
+function useSunglasses() {
+  const client = useContext(SunglassesContext);
+  if (client === null) {
+    throw new Error(
+      "[SunGlasses] useSunglasses() must be called inside a <SunglassesProvider>."
+    );
+  }
+  return client;
+}
+
+// src/useScreenTracking.ts
+import { useEffect, useRef } from "react";
+var historyPatched = false;
+var previousPath = null;
+function useScreenTracking(client, options = {}) {
+  const { useHistoryApi = true, screenNameMapper } = options;
+  const clientRef = useRef(client);
+  clientRef.current = client;
+  const mapperRef = useRef(screenNameMapper);
+  mapperRef.current = screenNameMapper;
+  useEffect(() => {
+    if (!useHistoryApi || typeof window === "undefined") return;
+    if (historyPatched) {
+      console.warn(
+        "[SunGlasses] useScreenTracking: history is already patched by another instance \u2014 this instance will not track."
+      );
+      return;
+    }
+    historyPatched = true;
+    const handleRouteChange = (path) => {
+      const name = mapperRef.current ? mapperRef.current(path) : path;
+      const props = {
+        $path: path,
+        $url: window.location.href
+      };
+      if (document.title) props.$title = document.title;
+      if (previousPath !== null) {
+        props.$referrer = previousPath;
+      } else if (document.referrer) {
+        props.$referrer = document.referrer;
+      }
+      previousPath = path;
+      clientRef.current.screen(name, props);
+    };
+    handleRouteChange(window.location.pathname);
+    const originalPush = history.pushState.bind(history);
+    history.pushState = (...args) => {
+      originalPush(...args);
+      handleRouteChange(window.location.pathname);
+    };
+    const originalReplace = history.replaceState.bind(history);
+    history.replaceState = (...args) => {
+      originalReplace(...args);
+      handleRouteChange(window.location.pathname);
+    };
+    const onPopState = () => handleRouteChange(window.location.pathname);
+    window.addEventListener("popstate", onPopState);
+    return () => {
+      history.pushState = originalPush;
+      history.replaceState = originalReplace;
+      window.removeEventListener("popstate", onPopState);
+      historyPatched = false;
+      previousPath = null;
+    };
+  }, [useHistoryApi]);
+}
+
+// src/SunglassesProvider.tsx
+import { jsx } from "react/jsx-runtime";
+function SunglassesProvider({
+  client,
+  screenTracking,
+  children
+}) {
+  useEffect2(() => {
+    return () => {
+      client.shutdown().catch(() => {
+      });
+    };
+  }, [client]);
+  useEffect2(() => {
+    if (typeof document === "undefined") return;
+    const handleVisibilityChange = () => {
+      if (document.visibilityState === "hidden") {
+        client.flush().catch(() => {
+        });
+      }
+    };
+    document.addEventListener("visibilitychange", handleVisibilityChange);
+    return () => document.removeEventListener("visibilitychange", handleVisibilityChange);
+  }, [client]);
+  useScreenTracking(client, screenTracking ?? { useHistoryApi: false });
+  return /* @__PURE__ */ jsx(SunglassesContext.Provider, { value: client, children });
+}
+
+// src/captureUtmParams.ts
+var UTM_PARAMS = [
+  "utm_source",
+  "utm_medium",
+  "utm_campaign",
+  "utm_content",
+  "utm_term"
+];
+function captureUtmParams(client) {
+  if (typeof window === "undefined") return;
+  const params = {};
+  const searchParams = new URLSearchParams(window.location.search);
+  for (const key of UTM_PARAMS) {
+    const value = searchParams.get(key);
+    if (value) params[key] = value;
+  }
+  if (document.referrer) {
+    params["$referrer"] = document.referrer;
+    try {
+      params["$referring_domain"] = new URL(document.referrer).hostname;
+    } catch {
+    }
+  }
+  if (Object.keys(params).length > 0) {
+    client.register(params);
+  }
+}
+
+// src/useCapture.ts
+import { useCallback } from "react";
+function useCapture() {
+  const client = useSunglasses();
+  return useCallback(
+    (eventName, properties) => {
+      client.capture(eventName, properties);
+    },
+    [client]
+  );
+}
+
+// src/useConsentStatus.ts
+function useConsentStatus() {
+  const client = useSunglasses();
+  return client.getConsentStatus();
+}
+
+// src/index.ts
+import { SunglassesCore } from "@drakkar.software/sunglasses-core";
+export {
+  SunglassesCore,
+  SunglassesProvider,
+  captureUtmParams,
+  useCapture,
+  useConsentStatus,
+  useScreenTracking,
+  useSunglasses
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@drakkar.software/sunglasses-react",
+  "version": "0.2.0",
+  "description": "React (web) provider and hooks for SunGlasses event tracking",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@drakkar.software/sunglasses-core": "0.2.0"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.12",
+    "happy-dom": "^15.11.7",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8",
+    "@drakkar.software/sunglasses-tsconfig": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/",
+    "test": "vitest run",
+    "clean": "rm -rf dist .tsbuildinfo"
+  }
+}