humanbehavior-js 0.0.9 → 0.1.0

package/dist/types/index.d.ts

@@ -83,6 +83,7 @@ declare const redactionManager: RedactionManager;
 declare global {
     interface Window {
         HumanBehaviorTracker: typeof HumanBehaviorTracker;
+        __humanBehaviorGlobalTracker?: HumanBehaviorTracker;
     }
 }
 declare class HumanBehaviorTracker {
@@ -102,11 +103,46 @@ declare class HumanBehaviorTracker {
     initializationPromise: Promise<void> | null;
     private redactionManager;
     private originalConsole;
-    private originalLogger;
     private consoleTrackingEnabled;
+    navigationTrackingEnabled: boolean;
+    private currentUrl;
+    private previousUrl;
+    private originalPushState;
+    private originalReplaceState;
+    private navigationListeners;
+    private _connectionBlocked;
+    /**
+     * Initialize the HumanBehavior tracker
+     * This is the main entry point - call this once per page
+     */
+    static init(apiKey: string, options?: {
+        ingestionUrl?: string;
+        logLevel?: 'none' | 'error' | 'warn' | 'info' | 'debug';
+        redactFields?: string[];
+    }): HumanBehaviorTracker;
     constructor(apiKey: string | undefined, ingestionUrl?: string);
     private init;
     private ensureInitialized;
+    /**
+     * Setup navigation event tracking for SPA navigation
+     */
+    private setupNavigationTracking;
+    /**
+     * Track navigation events and send custom events
+     */
+    trackNavigationEvent(type: string, fromUrl: string, toUrl: string): Promise<void>;
+    /**
+     * Track a page view event (PostHog-style)
+     */
+    trackPageView(url?: string): Promise<void>;
+    /**
+     * Track a custom event (PostHog-style)
+     */
+    customEvent(eventName: string, properties?: Record<string, any>): Promise<void>;
+    /**
+     * Cleanup navigation tracking
+     */
+    private cleanupNavigationTracking;
     static logToStorage(message: string): void;
     /**
      * Configure logging behavior for the SDK
@@ -125,9 +161,6 @@ declare class HumanBehaviorTracker {
      * Disable console event tracking
      */
     disableConsoleTracking(): void;
-    /**
-     * Track console events
-     */
     private trackConsoleEvent;
     private setupPageUnloadHandler;
     viewLogs(): void;
@@ -137,7 +170,6 @@ declare class HumanBehaviorTracker {
      * @param authFields Array of field names to check for existing users (e.g., ['email', 'phoneNumber'])
      */
     auth(authFields: string[]): Promise<void>;
-    customEvent(eventName: string, eventProperties?: Record<string, any>): Promise<void>;
     start(): Promise<void>;
     stop(): Promise<void>;
     addEvent(event: any): Promise<void>;
@@ -163,6 +195,28 @@ declare class HumanBehaviorTracker {
      * Get the currently selected fields for redaction
      */
     getRedactedFields(): string[];
+    /**
+     * Get the current session ID
+     */
+    getSessionId(): string;
+    /**
+     * Get the current URL being tracked
+     */
+    getCurrentUrl(): string;
+    /**
+     * Test if the tracker can reach the ingestion server
+     */
+    testConnection(): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * Get connection status and recommendations
+     */
+    getConnectionStatus(): {
+        blocked: boolean;
+        recommendations: string[];
+    };
 }
 
 declare const MAX_CHUNK_SIZE_BYTES: number;
@@ -183,13 +237,7 @@ declare class HumanBehaviorAPI {
     sendEventsChunked(events: any[], sessionId: string): Promise<any[]>;
     sendUserData(userId: string, userData: Record<string, any>, sessionId: string): Promise<any>;
     sendUserAuth(userId: string, userData: Record<string, any>, sessionId: string, authFields: string[]): Promise<any>;
-    sendSessionComplete(sessionId: string): Promise<void>;
-    sendCustomEvent(eventName: string, eventProperties: Record<string, any>, sessionId: string): Promise<any>;
-    sendCustomEvents(events: any[], sessionId: string): Promise<any>;
-    sendBeaconEvents(events: any[], sessionId: string, isSessionComplete?: boolean): void;
-    sendBeaconSessionComplete(sessionId: string): void;
-    sendBeaconCustomEvent(eventName: string, eventProperties: Record<string, any>, sessionId: string): boolean;
-    sendBeaconCustomEvents(events: any[], sessionId: string): boolean;
+    sendBeaconEvents(events: any[], sessionId: string): void;
 }
 
 declare enum LogLevel {

package/dist/types/react/index.d.ts

@@ -1,19 +1,18 @@
 import React, { ReactNode } from 'react';
 import { HumanBehaviorTracker } from '..';
+export { HumanBehaviorTracker } from '..';
 
-interface HumanBehaviorInterface {
-    addEvent: (event: any) => void;
-    addUserInfo: (userProperties: Record<string, any>) => Promise<void>;
-    start: () => void;
-    stop: () => void;
-    viewLogs: () => void;
-}
 interface HumanBehaviorProviderProps {
     apiKey?: string;
     client?: HumanBehaviorTracker;
     children: ReactNode;
+    options?: {
+        ingestionUrl?: string;
+        logLevel?: 'none' | 'error' | 'warn' | 'info' | 'debug';
+        redactFields?: string[];
+    };
 }
-declare const HumanBehaviorProvider: ({ apiKey, client, children }: HumanBehaviorProviderProps) => React.JSX.Element;
-declare const useHumanBehavior: () => HumanBehaviorInterface;
+declare const HumanBehaviorProvider: ({ apiKey, client, children, options }: HumanBehaviorProviderProps) => React.JSX.Element;
+declare const useHumanBehavior: () => HumanBehaviorTracker;
 
 export { HumanBehaviorProvider, useHumanBehavior };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "humanbehavior-js",
-  "version": "0.0.9",
+  "version": "0.1.0",
   "description": "SDK for HumanBehavior session and event recording",
   "type": "module",
   "main": "./dist/cjs/index.js",
@@ -29,6 +29,7 @@
   "license": "ISC",
   "dependencies": {
     "@types/react": "^19.0.12",
+    "humanbehavior-js": "^0.0.9",
     "react": "^19.0.0",
     "rrweb": "^2.0.0-alpha.4",
     "uuid": "^11.1.0"

package/readme.md

@@ -1,145 +1,167 @@
 # HumanBehavior SDK
 
-A JavaScript SDK for session recording and user behavior analytics.
+A simplified session recording and analytics SDK that maintains session continuity across page navigations.
 
-## Installation
+## Quick Start
 
-```bash
-npm install humanbehavior-js
+### Single Page Application (Recommended)
+
+For the best session continuity experience, use the SPA approach:
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+    <script src="dist/index.min.js"></script>
+</head>
+<body>
+    <script>
+        // Initialize once - session persists across all navigation
+        const tracker = HumanBehaviorTracker.init('your-api-key', {
+            logLevel: 'debug',
+            redactFields: ['password', 'credit_card']
+        });
+        
+        // Your SPA navigation logic here
+        function navigateToPage(page) {
+            // Update content without page reload
+            loadPageContent(page);
+            
+            // Track navigation
+            tracker.trackNavigationEvent('spa_navigation', currentPage, page);
+        }
+    </script>
+</body>
+</html>
 ```
 
-## Usage
+### Traditional Multi-Page Setup
 
-### Vanilla JavaScript
+For traditional HTML pages, the tracker will automatically restore sessions:
 
 ```html
-<script src="https://unpkg.com/humanbehavior-js@0.0.7/dist/index.min.js"></script>
+<!-- index.html -->
+<script src="dist/index.min.js"></script>
 <script>
-    const tracker = new HumanBehaviorTracker("your-api-key-here");
-    tracker.start();
-    
-    // Set up redaction for sensitive fields
-    tracker.setRedactedFields(['#password', 'input[type="password"]']);
+    const tracker = HumanBehaviorTracker.init('your-api-key');
+</script>
+
+<!-- about.html -->
+<script src="dist/index.min.js"></script>
+<script>
+    const tracker = HumanBehaviorTracker.init('your-api-key'); // Reuses existing session
 </script>
 ```
 
-### Next.js
+## API Reference
+
+### Initialization
 
-Add the following to your `providers.tsx` file:
+```javascript
+// Main initialization method
+const tracker = HumanBehaviorTracker.init(apiKey, options);
+```
 
-```tsx
-"use client"
+**Options:**
+- `ingestionUrl`: Custom ingestion server URL
+- `logLevel`: 'none' | 'error' | 'warn' | 'info' | 'debug'
+- `redactFields`: Array of CSS selectors to redact
 
-import { HumanBehaviorTracker } from "humanbehavior-js";
-import { HumanBehaviorProvider } from "humanbehavior-js/react";
-import { useEffect, useState } from "react";
+### Session Management
 
-export function HumanBehaviorProviderWrapper({ children }: { children: React.ReactNode }) {
-    const [tracker, setTracker] = useState<HumanBehaviorTracker | null>(null);
+```javascript
+// Get current session ID
+const sessionId = tracker.getSessionId();
 
-    useEffect(() => {
-        const apiKey = process.env.NEXT_PUBLIC_HUMANBEHAVIOR_API_KEY;
-        if (apiKey) {
-            const tracker = new HumanBehaviorTracker(apiKey);
-            setTracker(tracker);
-        }
-    }, []);
-
-    return (
-        <HumanBehaviorProvider client={tracker}>
-            {children}
-        </HumanBehaviorProvider>  
-    )
-}
+// Get current URL
+const currentUrl = tracker.getCurrentUrl();
+
+// Test connection to ingestion server
+const result = await tracker.testConnection();
 ```
 
-Or use the simpler approach with just an API key:
+### Event Tracking
 
-```tsx
-"use client"
+```javascript
+// Track custom events
+await tracker.customEvent('button_click', { button: 'submit' });
 
-import { HumanBehaviorProvider } from "humanbehavior-js/react";
+// Track page views
+await tracker.trackPageView();
 
-export function HumanBehaviorProviderWrapper({ children }: { children: React.ReactNode }) {
-    return (
-        <HumanBehaviorProvider apiKey={process.env.NEXT_PUBLIC_HUMANBEHAVIOR_API_KEY}>
-            {children}
-        </HumanBehaviorProvider>  
-    )
-}
+// Track navigation (for SPAs)
+await tracker.trackNavigationEvent('pushState', '/home', '/about');
 ```
 
-Next, add the provider to your root app layout:
-
-```tsx
-export default async function RootLayout({
-  children
-}: {
-  children: React.ReactNode;
-}) {
-  return (
-    <html lang='en' suppressHydrationWarning>
-      <body>
-        <HumanBehaviorProviderWrapper>
-          {children}
-        </HumanBehaviorProviderWrapper>
-      </body>
-    </html>
-  );
-}
-```
+### Data Redaction
 
-### Using the Hook
+```javascript
+// Redact sensitive fields
+tracker.setRedactedFields(['input[type="password"]', '#email']);
 
-In any component within the provider:
+// Check if redaction is active
+const isActive = tracker.isRedactedFields();
+```
 
-```tsx
-import { useHumanBehavior } from "humanbehavior-js/react";
+### Debugging
 
-export function MyComponent() {
-    const humanBehavior = useHumanBehavior();
-    
-    const handleUserAction = async () => {
-        // Add user information
-        await humanBehavior.addUserInfo({
-            email: "user@example.com",
-            name: "John Doe"
-        });
-        
-        // Track custom events
-        humanBehavior.addEvent({
-            type: "custom",
-            name: "button_clicked",
-            data: { buttonId: "submit" }
-        });
-    };
-    
-    return <button onClick={handleUserAction}>Click me</button>;
-}
+```javascript
+// View logs
+tracker.viewLogs();
+
+// Get connection status
+const status = tracker.getConnectionStatus();
 ```
 
-## Environment Variables
+## Session Continuity
 
-For security, store your API key in environment variables:
+The SDK automatically handles session continuity:
 
-```bash
-# .env.local
-NEXT_PUBLIC_HUMANBEHAVIOR_API_KEY=your-api-key-here
-NEXT_PUBLIC_INGESTION_URL=https://ingestion.humanbehavior.ai
-```
+1. **Session Restoration**: Automatically restores sessions within 30 minutes
+2. **Activity Tracking**: Updates activity timestamp on user interactions
+3. **Cross-Page Persistence**: Session persists across page navigations
+
+## Demo
+
+Check out `simple-spa.html` for a complete single-page application demo that shows:
+
+- True session continuity across navigation
+- Interactive event tracking
+- Real-time status updates
+- Modern UI with smooth transitions
 
-## Features
+## Troubleshooting
 
-- **Session Recording**: Automatic recording of user interactions
-- **Data Redaction**: Protect sensitive information in recordings
-- **User Identification**: Track users across sessions
-- **Custom Events**: Send custom analytics events
-- **React Integration**: Hooks and providers for React applications
+### Ad Blocker Issues
 
-## Build
+If you see `net::ERR_BLOCKED_BY_CLIENT` errors:
 
-To build the SDK locally:
+1. Check if ad blockers are active
+2. Use `tracker.getConnectionStatus()` to diagnose
+3. Consider whitelisting your domain
+
+### Session Issues
+
+- Sessions automatically expire after 30 minutes of inactivity
+- Each page load calls `/init` but reuses existing sessions when possible
+- Check browser console for session restoration logs
+
+## Development
 
 ```bash
+# Build the SDK
 npm run build
-```
+
+# Watch for changes
+npm run dev
+
+# Run tests
+npm test
+```
+
+## Architecture
+
+- **Frontend**: TypeScript SDK with session restoration
+- **Backend**: Node.js ingestion server with Redis storage
+- **Archiver**: Processes completed sessions to S3 and Prisma
+- **Session Continuity**: localStorage + cookie-based session management