@lavarage/telemetry 1.1.0 → 1.2.0

package/README.md

@@ -263,6 +263,22 @@ Track a system event (not tied to any wallet address). System events are display
 ```typescript
 // Track app startup
 telemetry.trackSystemEvent('app_start', 'Application initialized', 'info');
+```
+
+#### `trackStateChange(stateName: string, previousValue?: any, newValue?: any, action?: string, metadata?: object)`
+
+Track a React state change. Useful for debugging and understanding user interactions.
+
+```typescript
+// Track a state change manually
+telemetry.trackStateChange(
+  'userPreferences',
+  { theme: 'light' },
+  { theme: 'dark' },
+  'TOGGLE_THEME',
+  { source: 'settings-panel' }
+);
+```
 
 // Track feature usage
 telemetry.trackSystemEvent('feature_used', 'User enabled dark mode', 'info', {
@@ -333,6 +349,177 @@ Clean up the telemetry instance, restore original functions, and flush remaining
 telemetry.destroy();
 ```
 
+## React State Tracking
+
+The SDK provides React hooks for automatically tracking state changes in your React components.
+
+### Installation
+
+```bash
+# Install the SDK
+npm install @lavarage/telemetry
+
+# If you want to use React hooks, also install React (peer dependency)
+npm install react
+```
+
+### Quick Start
+
+```typescript
+import { LavarageTelemetry } from '@lavarage/telemetry';
+// Import React hooks from the separate entry point
+import { useTrackedState } from '@lavarage/telemetry/react';
+
+const telemetry = new LavarageTelemetry({
+  apiEndpoint: 'https://telemetry.lavarage.com',
+  platform: 'lavarage-web',
+});
+
+function MyComponent() {
+  // Automatically tracks all state changes
+  const [count, setCount] = useTrackedState(0, {
+    stateName: 'counter',
+    telemetry: telemetry,
+    action: 'SET_COUNT'
+  });
+
+  return (
+    <button onClick={() => setCount(count + 1)}>
+      Count: {count}
+    </button>
+  );
+}
+```
+
+### Available Hooks
+
+#### `useTrackedState(initialState, config)`
+
+Wraps React's `useState` and automatically tracks state changes.
+
+```typescript
+const [state, setState] = useTrackedState(initialValue, {
+  stateName: 'userPreferences',  // Required: name for this state
+  telemetry: telemetryInstance,   // Required: telemetry instance
+  trackInitial: false,             // Optional: track initial state (default: false)
+  action: 'UPDATE_PREFERENCES',    // Optional: action name
+  metadata: { source: 'settings' }, // Optional: additional metadata
+  shouldTrack: (prev, next) => {   // Optional: filter which changes to track
+    return prev !== next;          // Only track if values actually changed
+  }
+});
+```
+
+#### `useTrackedReducer(reducer, initialState, config)`
+
+Wraps React's `useReducer` and automatically tracks state changes with action information.
+
+```typescript
+const [state, dispatch] = useTrackedReducer(reducer, initialState, {
+  stateName: 'cart',
+  telemetry: telemetryInstance,
+  trackInitial: false,
+  metadata: { userId: '123' }
+});
+
+// Dispatch actions normally - they'll be tracked automatically
+dispatch({ type: 'ADD_ITEM', payload: { id: 1, name: 'Product' } });
+```
+
+#### `useStateTracker(telemetry)`
+
+Returns a function to manually track state changes with more control.
+
+```typescript
+const trackState = useStateTracker(telemetry);
+
+const handleChange = (newValue) => {
+  trackState('theme', currentValue, newValue, 'SET_THEME', {
+    source: 'user-action'
+  });
+  setCurrentValue(newValue);
+};
+```
+
+### Configuration Options
+
+- **stateName** (required): A unique identifier for this state (e.g., 'cart', 'userPreferences', 'theme')
+- **telemetry** (required): Your telemetry instance
+- **trackInitial** (optional): Whether to track the initial state value (default: false)
+- **action** (optional): Action name to use when tracking (default: 'STATE_CHANGE')
+- **metadata** (optional): Additional context to include with each state change
+- **shouldTrack** (optional): Function to filter which changes to track - useful for avoiding noise
+
+### Example: Shopping Cart
+
+```typescript
+import { useTrackedState } from '@lavarage/telemetry/react';
+
+function ShoppingCart() {
+  const [items, setItems] = useTrackedState([], {
+    stateName: 'cartItems',
+    telemetry: telemetry,
+    action: 'CART_UPDATE',
+    shouldTrack: (prev, next) => {
+      // Only track if cart actually changed (not just reference)
+      return JSON.stringify(prev) !== JSON.stringify(next);
+    }
+  });
+
+  const addItem = (item) => {
+    setItems([...items, item]);
+    // State change is automatically tracked!
+  };
+
+  return (
+    <div>
+      {items.map(item => <div key={item.id}>{item.name}</div>)}
+      <button onClick={() => addItem({ id: 1, name: 'Product' })}>
+        Add Item
+      </button>
+    </div>
+  );
+}
+```
+
+### Example: User Preferences with useReducer
+
+```typescript
+import { useTrackedReducer } from '@lavarage/telemetry/react';
+
+function preferencesReducer(state, action) {
+  switch (action.type) {
+    case 'SET_THEME':
+      return { ...state, theme: action.payload };
+    case 'SET_LANGUAGE':
+      return { ...state, language: action.payload };
+    default:
+      return state;
+  }
+}
+
+function UserPreferences() {
+  const [prefs, dispatch] = useTrackedReducer(
+    preferencesReducer,
+    { theme: 'light', language: 'en' },
+    {
+      stateName: 'userPreferences',
+      telemetry: telemetry,
+      metadata: { userId: currentUser.id }
+    }
+  );
+
+  return (
+    <div>
+      <button onClick={() => dispatch({ type: 'SET_THEME', payload: 'dark' })}>
+        Dark Mode
+      </button>
+      {/* State changes are automatically tracked with action type! */}
+    </div>
+  );
+}
+```
+
 ## Event Types
 
 The SDK tracks the following event types:
@@ -343,6 +530,7 @@ The SDK tracks the following event types:
 - **request**: Network requests (fetch/Axios)
 - **system_event**: System-level events not tied to any wallet address (displayed in separate dashboard panel)
 - **log**: Custom log events (via `logWalletEvent()` or `sendLog()`)
+- **state_change**: React state changes (via `trackStateChange()` or React hooks)
 
 ## Batching
 

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { TelemetryConfig, TelemetryEvent, ErrorEvent, RequestEvent, HostFilterInput, HostFilterConfig, ErrorFilterConfig, SystemEvent } from './types';
 export type { TelemetryConfig, TelemetryEvent, ErrorEvent, RequestEvent, HostFilterInput, HostFilterConfig, ErrorFilterConfig, SystemEvent, };
+export type { StateChangeEvent } from './types';
 export declare class LavarageTelemetry {
     private apiEndpoint;
     private platform;
@@ -64,5 +65,15 @@ export declare class LavarageTelemetry {
      */
     sendLog(walletAddress: string, eventType: string, message: string, metadata?: object): Promise<void>;
     updateHostFilter(captureHosts: HostFilterInput): void;
+    /**
+     * Track a React state change
+     * Use this method to manually log state changes, or use the useTrackedState/useTrackedReducer hooks for automatic tracking
+     * @param stateName - Name/identifier for the state (e.g., 'userPreferences', 'cartItems', 'theme')
+     * @param previousValue - Previous state value (optional, will be sanitized)
+     * @param newValue - New state value (optional, will be sanitized)
+     * @param action - Action that caused the change (e.g., 'SET_USER', 'ADD_TO_CART', 'TOGGLE_THEME')
+     * @param metadata - Additional context about the state change
+     */
+    trackStateChange(stateName: string, previousValue?: any, newValue?: any, action?: string, metadata?: object): void;
     destroy(): void;
 }

package/dist/index.js

@@ -684,6 +684,36 @@ class LavarageTelemetry {
             // Silently fail
         }
     }
+    /**
+     * Track a React state change
+     * Use this method to manually log state changes, or use the useTrackedState/useTrackedReducer hooks for automatic tracking
+     * @param stateName - Name/identifier for the state (e.g., 'userPreferences', 'cartItems', 'theme')
+     * @param previousValue - Previous state value (optional, will be sanitized)
+     * @param newValue - New state value (optional, will be sanitized)
+     * @param action - Action that caused the change (e.g., 'SET_USER', 'ADD_TO_CART', 'TOGGLE_THEME')
+     * @param metadata - Additional context about the state change
+     */
+    trackStateChange(stateName, previousValue, newValue, action, metadata) {
+        try {
+            const event = {
+                type: 'state_change',
+                wallet: this.wallet,
+                platform: this.platform,
+                stateName,
+                previousValue: previousValue !== undefined ? this.sanitizePayload(previousValue) : undefined,
+                newValue: newValue !== undefined ? this.sanitizePayload(newValue) : undefined,
+                action: action || 'STATE_CHANGE',
+                metadata: metadata ? this.sanitizePayload(metadata) : undefined,
+                timestamp: Date.now(),
+                sessionId: this.sessionId,
+                url: typeof window !== 'undefined' ? window.location.href : '',
+            };
+            this.enqueue(event);
+        }
+        catch (error) {
+            // Silently fail
+        }
+    }
     destroy() {
         // Restore original functions
         if (this.originalFetch && typeof window !== 'undefined') {

package/dist/react.d.ts

@@ -0,0 +1,73 @@
+/**
+ * React hooks for automatic state change tracking
+ *
+ * These hooks wrap React's useState and useReducer to automatically
+ * track state changes to the telemetry system.
+ */
+import { Dispatch, SetStateAction, Reducer } from 'react';
+import { LavarageTelemetry } from './index';
+/**
+ * Configuration for tracked state
+ */
+export interface TrackedStateConfig {
+    /** Name/identifier for this state (e.g., 'userPreferences', 'cartItems') */
+    stateName: string;
+    /** Telemetry instance to use for tracking */
+    telemetry: LavarageTelemetry;
+    /** Whether to track the initial state value (default: false) */
+    trackInitial?: boolean;
+    /** Action name to use when tracking (default: 'STATE_CHANGE') */
+    action?: string;
+    /** Additional metadata to include with each state change */
+    metadata?: object;
+    /** Function to determine if a state change should be tracked (useful for filtering) */
+    shouldTrack?: (previousValue: any, newValue: any) => boolean;
+}
+/**
+ * Hook that wraps useState and automatically tracks state changes
+ *
+ * @example
+ * ```tsx
+ * const [count, setCount] = useTrackedState(0, {
+ *   stateName: 'counter',
+ *   telemetry: telemetryInstance,
+ *   action: 'SET_COUNT'
+ * });
+ * ```
+ */
+export declare function useTrackedState<T>(initialState: T | (() => T), config: TrackedStateConfig): [T, Dispatch<SetStateAction<T>>];
+/**
+ * Action type for tracked reducer
+ */
+export interface TrackedReducerAction {
+    type: string;
+    payload?: any;
+    [key: string]: any;
+}
+/**
+ * Hook that wraps useReducer and automatically tracks state changes
+ *
+ * @example
+ * ```tsx
+ * const [state, dispatch] = useTrackedReducer(reducer, initialState, {
+ *   stateName: 'cart',
+ *   telemetry: telemetryInstance
+ * });
+ * ```
+ */
+export declare function useTrackedReducer<TState, TAction extends TrackedReducerAction>(reducer: Reducer<TState, TAction>, initialState: TState, config: TrackedStateConfig): [TState, Dispatch<TAction>];
+/**
+ * Hook to manually track state changes with more control
+ * Useful when you want to track state changes but don't want to use the tracked hooks
+ *
+ * @example
+ * ```tsx
+ * const trackState = useStateTracker(telemetryInstance);
+ *
+ * const handleChange = (newValue) => {
+ *   trackState('userPreferences', currentValue, newValue, 'UPDATE_PREFERENCES');
+ *   setCurrentValue(newValue);
+ * };
+ * ```
+ */
+export declare function useStateTracker(telemetry: LavarageTelemetry): (stateName: string, previousValue?: any, newValue?: any, action?: string, metadata?: object) => void;

package/dist/react.js

@@ -0,0 +1,149 @@
+"use strict";
+/**
+ * React hooks for automatic state change tracking
+ *
+ * These hooks wrap React's useState and useReducer to automatically
+ * track state changes to the telemetry system.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useTrackedState = useTrackedState;
+exports.useTrackedReducer = useTrackedReducer;
+exports.useStateTracker = useStateTracker;
+const react_1 = require("react");
+/**
+ * Hook that wraps useState and automatically tracks state changes
+ *
+ * @example
+ * ```tsx
+ * const [count, setCount] = useTrackedState(0, {
+ *   stateName: 'counter',
+ *   telemetry: telemetryInstance,
+ *   action: 'SET_COUNT'
+ * });
+ * ```
+ */
+function useTrackedState(initialState, config) {
+    const { stateName, telemetry, trackInitial = false, action, metadata, shouldTrack } = config;
+    const [state, setState] = (0, react_1.useState)(initialState);
+    const previousStateRef = (0, react_1.useRef)(state);
+    const isInitialMount = (0, react_1.useRef)(true);
+    // Track initial state if configured
+    (0, react_1.useEffect)(() => {
+        if (trackInitial && isInitialMount.current) {
+            isInitialMount.current = false;
+            telemetry.trackStateChange(stateName, undefined, state, action || 'INITIAL_STATE', metadata);
+        }
+    }, []);
+    // Track state changes
+    (0, react_1.useEffect)(() => {
+        // Skip tracking on initial mount unless trackInitial is true
+        if (isInitialMount.current && !trackInitial) {
+            isInitialMount.current = false;
+            previousStateRef.current = state;
+            return;
+        }
+        if (isInitialMount.current) {
+            isInitialMount.current = false;
+            previousStateRef.current = state;
+            return;
+        }
+        const previousValue = previousStateRef.current;
+        // Check if we should track this change
+        if (shouldTrack && !shouldTrack(previousValue, state)) {
+            previousStateRef.current = state;
+            return;
+        }
+        // Track the state change
+        telemetry.trackStateChange(stateName, previousValue, state, action, metadata);
+        previousStateRef.current = state;
+    }, [state, stateName, telemetry, action, metadata, shouldTrack]);
+    // Wrapper for setState that ensures tracking
+    const trackedSetState = (value) => {
+        setState(value);
+    };
+    return [state, trackedSetState];
+}
+/**
+ * Hook that wraps useReducer and automatically tracks state changes
+ *
+ * @example
+ * ```tsx
+ * const [state, dispatch] = useTrackedReducer(reducer, initialState, {
+ *   stateName: 'cart',
+ *   telemetry: telemetryInstance
+ * });
+ * ```
+ */
+function useTrackedReducer(reducer, initialState, config) {
+    const { stateName, telemetry, trackInitial = false, metadata, shouldTrack } = config;
+    const [state, dispatch] = (0, react_1.useReducer)(reducer, initialState);
+    const previousStateRef = (0, react_1.useRef)(state);
+    const isInitialMount = (0, react_1.useRef)(true);
+    // Track initial state if configured
+    (0, react_1.useEffect)(() => {
+        if (trackInitial && isInitialMount.current) {
+            isInitialMount.current = false;
+            telemetry.trackStateChange(stateName, undefined, state, 'INITIAL_STATE', metadata);
+        }
+    }, []);
+    // Track state changes
+    (0, react_1.useEffect)(() => {
+        // Skip tracking on initial mount unless trackInitial is true
+        if (isInitialMount.current && !trackInitial) {
+            isInitialMount.current = false;
+            previousStateRef.current = state;
+            return;
+        }
+        if (isInitialMount.current) {
+            isInitialMount.current = false;
+            previousStateRef.current = state;
+            return;
+        }
+        const previousValue = previousStateRef.current;
+        // Check if we should track this change
+        if (shouldTrack && !shouldTrack(previousValue, state)) {
+            previousStateRef.current = state;
+            return;
+        }
+        // Track the state change (action type will be included in the reducer action)
+        telemetry.trackStateChange(stateName, previousValue, state, undefined, // Action will be determined by the reducer
+        metadata);
+        previousStateRef.current = state;
+    }, [state, stateName, telemetry, metadata, shouldTrack]);
+    // Wrapper for dispatch that tracks the action
+    const trackedDispatch = (action) => {
+        // Track before dispatching
+        const previousValue = previousStateRef.current;
+        dispatch(action);
+        // Note: The actual state change will be tracked in the useEffect above
+        // But we can also track the action here for immediate feedback
+        if (!shouldTrack || shouldTrack(previousValue, state)) {
+            telemetry.trackStateChange(stateName, previousValue, state, // This will be the old state, useEffect will track the new one
+            action.type || 'REDUCER_ACTION', {
+                ...metadata,
+                actionPayload: action.payload,
+                ...action
+            });
+        }
+    };
+    return [state, trackedDispatch];
+}
+/**
+ * Hook to manually track state changes with more control
+ * Useful when you want to track state changes but don't want to use the tracked hooks
+ *
+ * @example
+ * ```tsx
+ * const trackState = useStateTracker(telemetryInstance);
+ *
+ * const handleChange = (newValue) => {
+ *   trackState('userPreferences', currentValue, newValue, 'UPDATE_PREFERENCES');
+ *   setCurrentValue(newValue);
+ * };
+ * ```
+ */
+function useStateTracker(telemetry) {
+    return (stateName, previousValue, newValue, action, metadata) => {
+        telemetry.trackStateChange(stateName, previousValue, newValue, action, metadata);
+    };
+}

package/dist/types.d.ts

@@ -17,7 +17,7 @@ export interface ErrorFilterConfig {
     exclude?: string[];
 }
 export interface TelemetryEvent {
-    type: 'login' | 'pair_view' | 'error' | 'request' | 'system_event';
+    type: 'login' | 'pair_view' | 'error' | 'request' | 'system_event' | 'state_change';
     wallet: string | null;
     platform: string;
     timestamp: number;
@@ -53,3 +53,10 @@ export interface RequestEvent {
 export interface BatchIngestRequest {
     events: TelemetryEvent[];
 }
+export interface StateChangeEvent {
+    stateName: string;
+    previousValue?: any;
+    newValue?: any;
+    action?: string;
+    metadata?: object;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lavarage/telemetry",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Production telemetry SDK for Lavarage and partner applications",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -10,29 +10,56 @@
     "node-fetch": false
   },
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && tsc --project tsconfig.react.json",
+    "build:main": "tsc",
+    "build:react": "tsc --project tsconfig.react.json",
     "dev": "tsc --watch",
     "prepublishOnly": "npm run build",
     "test": "jest"
   },
-  "keywords": ["telemetry", "analytics", "monitoring", "lavarage"],
+  "keywords": [
+    "telemetry",
+    "analytics",
+    "monitoring",
+    "lavarage"
+  ],
   "author": "Lavarage",
   "license": "MIT",
   "peerDependencies": {
-    "node-fetch": "^2.6.0 || ^3.0.0"
+    "node-fetch": "^2.6.0 || ^3.0.0",
+    "react": "^16.8.0 || ^17.0.0 || ^18.0.0"
   },
   "peerDependenciesMeta": {
     "node-fetch": {
       "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./react": {
+      "import": "./dist/react.js",
+      "require": "./dist/react.js",
+      "types": "./dist/react.d.ts"
     }
   },
   "devDependencies": {
+    "@types/jest": "^29.0.0",
     "@types/node": "^20.0.0",
-    "typescript": "^5.0.0",
+    "@types/react": "^19.2.8",
+    "@types/react-dom": "^19.2.3",
     "jest": "^29.0.0",
-    "@types/jest": "^29.0.0",
-    "ts-jest": "^29.0.0"
+    "ts-jest": "^29.0.0",
+    "typescript": "^5.0.0"
   },
-  "files": ["dist", "README.md"]
+  "files": [
+    "dist",
+    "README.md"
+  ]
 }
-