humanbehavior-js 0.4.16 → 0.4.17

package/package/WIZARD_USAGE_GUIDE.md

@@ -0,0 +1,381 @@
+# HumanBehavior SDK Auto-Installation Wizard
+
+The HumanBehavior SDK includes an intelligent auto-installation wizard that can detect your project's framework and automatically integrate the SDK with minimal user intervention.
+
+## 🚀 Quick Start
+
+### Single Command Installation
+
+**When the package is published to npm:**
+```bash
+npx humanbehavior-js auto-install YOUR_API_KEY
+```
+
+**For local development/testing:**
+```bash
+node path/to/humanbehavior-js/dist/cli/auto-install.js YOUR_API_KEY
+```
+
+That's it! The wizard will:
+- 🔍 Auto-detect your project's framework
+- 📦 Install the humanbehavior-js package
+- ✏️ Modify your codebase to integrate the SDK
+- 🔧 Create environment files with your API key
+- 🚀 Make your app ready to track user behavior
+
+## 📋 Supported Frameworks
+
+The wizard automatically detects and configures:
+
+- ✅ **React** (CRA, Vite, Webpack)
+- ✅ **Next.js** (App Router, Pages Router)
+- ✅ **Vue** (Vue CLI, Vite)
+- ✅ **Angular**
+- ✅ **Svelte** (SvelteKit, Vite)
+- ✅ **Nuxt.js**
+- ✅ **Vanilla JS/TS**
+- ✅ **Node.js** (CommonJS & ESM)
+
+## 🛠️ Installation Options
+
+### Basic Usage
+
+**When the package is published to npm:**
+```bash
+# Interactive mode (prompts for API key)
+npx humanbehavior-js auto-install
+
+# With API key as argument
+npx humanbehavior-js auto-install your-api-key-here
+
+# Skip all prompts
+npx humanbehavior-js auto-install your-api-key-here --yes
+```
+
+**For local development/testing:**
+```bash
+# Interactive mode (prompts for API key)
+node path/to/humanbehavior-js/dist/cli/auto-install.js
+
+# With API key as argument
+node path/to/humanbehavior-js/dist/cli/auto-install.js your-api-key-here
+
+# Skip all prompts
+node path/to/humanbehavior-js/dist/cli/auto-install.js your-api-key-here --yes
+```
+
+### Advanced Options
+
+**When the package is published to npm:**
+```bash
+# Specify project directory
+npx humanbehavior-js auto-install your-api-key -p /path/to/project
+
+# Dry run (show what would be changed without making changes)
+npx humanbehavior-js auto-install your-api-key --dry-run
+
+# Get help
+npx humanbehavior-js auto-install --help
+```
+
+**For local development/testing:**
+```bash
+# Specify project directory
+node path/to/humanbehavior-js/dist/cli/auto-install.js your-api-key -p /path/to/project
+
+# Dry run (show what would be changed without making changes)
+node path/to/humanbehavior-js auto-install.js your-api-key --dry-run
+
+# Get help
+node path/to/humanbehavior-js/dist/cli/auto-install.js --help
+```
+
+## 🔧 Framework-Specific Integration
+
+### React
+```jsx
+// The wizard automatically wraps your app with HumanBehaviorProvider
+import { HumanBehaviorProvider } from 'humanbehavior-js/react';
+
+function App() {
+  return (
+    <HumanBehaviorProvider apiKey={process.env.HUMANBEHAVIOR_API_KEY}>
+      {/* Your app content */}
+    </HumanBehaviorProvider>
+  );
+}
+```
+
+### Next.js (App Router)
+```tsx
+// Creates app/providers.tsx
+'use client';
+import { HumanBehaviorProvider } from 'humanbehavior-js/react';
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <HumanBehaviorProvider apiKey={process.env.HUMANBEHAVIOR_API_KEY}>
+      {children}
+    </HumanBehaviorProvider>
+  );
+}
+
+// Modifies app/layout.tsx to use Providers
+```
+
+### Next.js (Pages Router)
+```tsx
+// Creates components/providers.tsx
+'use client';
+import { HumanBehaviorProvider } from 'humanbehavior-js/react';
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <HumanBehaviorProvider apiKey={process.env.HUMANBEHAVIOR_API_KEY}>
+      {children}
+    </HumanBehaviorProvider>
+  );
+}
+
+// Modifies pages/_app.tsx to use Providers
+```
+
+### Vue
+```js
+// The wizard adds the plugin to your main.js/ts
+import { HumanBehaviorPlugin } from 'humanbehavior-js/vue';
+
+app.use(HumanBehaviorPlugin, {
+  apiKey: import.meta.env.VITE_HUMANBEHAVIOR_API_KEY
+});
+```
+
+### Angular
+```typescript
+// The wizard adds the module to app.module.ts
+import { HumanBehaviorModule } from 'humanbehavior-js/angular';
+
+@NgModule({
+  imports: [
+    // ... other imports
+    HumanBehaviorModule.forRoot({
+      apiKey: environment.humanBehaviorApiKey
+    })
+  ]
+})
+```
+
+### Svelte
+```javascript
+// The wizard adds the store to your main file
+import { humanBehaviorStore } from 'humanbehavior-js/svelte';
+
+humanBehaviorStore.init('your-api-key');
+```
+
+### Nuxt.js
+```typescript
+// Creates plugins/humanbehavior.client.ts
+import { HumanBehaviorPlugin } from 'humanbehavior-js/vue';
+
+export default defineNuxtPlugin((nuxtApp) => {
+  nuxtApp.vueApp.use(HumanBehaviorPlugin, {
+    apiKey: useRuntimeConfig().public.humanBehaviorApiKey
+  });
+});
+```
+
+## 🔐 Environment Variables
+
+The wizard intelligently handles environment files:
+
+### Smart File Detection
+The wizard checks for existing environment files in this order:
+1. `.env.local`
+2. `.env.development.local`
+3. `.env.development`
+4. `.env.local.development`
+5. `.env`
+6. `.env.production`
+7. `.env.staging`
+
+### Framework-Specific Variables
+- **React/Next.js**: `HUMANBEHAVIOR_API_KEY`
+- **Vue**: `VITE_HUMANBEHAVIOR_API_KEY`
+- **Svelte**: `PUBLIC_HUMANBEHAVIOR_API_KEY`
+- **Angular**: `humanBehaviorApiKey` (in environment.ts)
+- **Nuxt**: `HUMANBEHAVIOR_API_KEY`
+
+### Safe Environment Handling
+- ✅ **Preserves existing files** (never overwrites)
+- ✅ **Appends to existing files** (adds API key safely)
+- ✅ **Skips duplicates** (won't add same variable twice)
+- ✅ **Works with gitignored files** (finds .env files even if ignored)
+
+## 📁 Project Structure After Installation
+
+### React/Next.js Project
+```
+your-project/
+├── .env.local                    # Created with API key
+├── src/
+│   ├── App.tsx                   # Modified with provider
+│   └── index.tsx                 # Unchanged
+├── package.json                  # humanbehavior-js added
+└── node_modules/
+```
+
+### Next.js App Router
+```
+your-project/
+├── .env.local                    # Created with API key
+├── app/
+│   ├── layout.tsx                # Modified to use providers
+│   └── providers.tsx             # Created with provider
+├── package.json                  # humanbehavior-js added
+└── node_modules/
+```
+
+### Vue Project
+```
+your-project/
+├── .env.local                    # Created with API key
+├── src/
+│   └── main.js                   # Modified with plugin
+├── package.json                  # humanbehavior-js added
+└── node_modules/
+```
+
+## 🎯 What Gets Modified
+
+### Code Changes
+- **Main entry point**: Wrapped with provider/plugin
+- **Environment files**: API key added safely
+- **Package.json**: humanbehavior-js dependency added
+
+### Files Created
+- **Environment files**: `.env.local`, `.env`, etc.
+- **Provider files**: `providers.tsx` (Next.js)
+- **Plugin files**: `humanbehavior.client.ts` (Nuxt)
+
+### Files Modified
+- **Main app file**: `App.tsx`, `main.js`, `layout.tsx`, etc.
+- **Package.json**: Dependencies updated
+- **Environment files**: API key appended
+
+## 🚨 Troubleshooting
+
+### Common Issues
+
+**"Framework not detected"**
+- Ensure you're running the command from your project root
+- Check that `package.json` exists and has dependencies
+
+**"Permission denied"**
+- Make sure you have write permissions to your project directory
+- Try running with `sudo` if needed (not recommended)
+
+**"Package installation failed"**
+- Check your internet connection
+- Ensure npm/yarn is properly configured
+- Try running `npm install` manually first
+
+### Manual Fallback
+
+If the wizard fails, you can install manually:
+
+```bash
+# Install the package
+npm install humanbehavior-js
+
+# Add environment variable
+echo "HUMANBEHAVIOR_API_KEY=your-api-key" >> .env.local
+
+# Then follow framework-specific setup in the main README
+```
+
+## 🚀 Current Status
+
+**Note**: The auto-installation wizard is currently in development and not yet published to npm. To test it locally:
+
+1. **Clone the repository**:
+   ```bash
+   git clone https://github.com/humanbehavior-gh/humanbehavior-js.git
+   cd humanbehavior-js
+   ```
+
+2. **Build the wizard**:
+   ```bash
+   npm install
+   npm run build
+   ```
+
+3. **Test in your project**:
+   ```bash
+   node dist/cli/auto-install.js your-api-key --yes
+   ```
+
+Once the package is published to npm, you'll be able to use the `npx` commands shown above.
+
+## 🔍 Debugging
+
+### Dry Run Mode
+**When the package is published to npm:**
+```bash
+npx humanbehavior-js auto-install your-api-key --dry-run
+```
+
+**For local development/testing:**
+```bash
+node path/to/humanbehavior-js/dist/cli/auto-install.js your-api-key --dry-run
+```
+
+Shows what changes would be made without actually making them.
+
+### Verbose Output
+The wizard provides detailed output showing:
+- Framework detection results
+- Package installation status
+- Files created/modified
+- Next steps for the user
+
+## 📚 Next Steps After Installation
+
+Once the wizard completes:
+
+1. **Start your development server**
+   ```bash
+   npm start
+   # or
+   yarn dev
+   ```
+
+2. **Verify integration**
+   - Check browser console for SDK initialization
+   - Visit your app and trigger some interactions
+   - Check your HumanBehavior dashboard for sessions
+
+3. **Customize tracking** (optional)
+   ```javascript
+   // React
+   import { useHumanBehavior } from 'humanbehavior-js/react';
+   
+   function MyComponent() {
+     const { trackEvent } = useHumanBehavior();
+     
+     const handleClick = () => {
+       trackEvent('button_clicked', { button: 'submit' });
+     };
+   }
+   ```
+
+## 🎉 Success Indicators
+
+The wizard is successful when you see:
+- ✅ "Installation completed successfully!"
+- ✅ Framework detected correctly
+- ✅ Package installed without errors
+- ✅ Environment file created
+- ✅ Code modifications applied
+
+Your app is now ready to track user behavior! 🚀 

package/package/canvas-recording-demo.html

@@ -0,0 +1,143 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>HumanBehavior Canvas Recording Demo</title>
+    <style>
+        body { font-family: Arial, sans-serif; margin: 20px; }
+        .demo-section { margin: 20px 0; padding: 20px; border: 1px solid #ccc; }
+        canvas { border: 2px solid #333; margin: 10px; }
+        button { padding: 10px 20px; margin: 5px; }
+        .info { background: #f0f0f0; padding: 10px; border-radius: 5px; }
+    </style>
+</head>
+<body>
+    <h1>HumanBehavior Canvas Recording Demo</h1>
+    
+    <div class="info">
+        <h3>PostHog-Style Canvas Protection</h3>
+        <ul>
+            <li><strong>4 FPS Throttling:</strong> Prevents canvas overwhelm (vs 60 FPS default)</li>
+            <li><strong>40% Quality:</strong> WebP format with compression</li>
+            <li><strong>Opt-in Only:</strong> Disabled by default for safety</li>
+            <li><strong>Smart Sampling:</strong> Only captures when canvas changes</li>
+        </ul>
+    </div>
+
+    <div class="demo-section">
+        <h3>Canvas Drawing Demo</h3>
+        <canvas id="demoCanvas" width="400" height="300"></canvas>
+        <br>
+        <button onclick="drawRandom()">Draw Random Shape</button>
+        <button onclick="clearCanvas()">Clear Canvas</button>
+        <button onclick="animate()">Start Animation</button>
+    </div>
+
+    <div class="demo-section">
+        <h3>Canvas Recording Options</h3>
+        <button onclick="enableCanvasRecording()">Enable Canvas Recording</button>
+        <button onclick="disableCanvasRecording()">Disable Canvas Recording</button>
+        <p id="status">Canvas recording: <strong>Disabled</strong></p>
+    </div>
+
+    <script src="./dist/index.min.js"></script>
+    <script>
+        let tracker;
+        let canvas = document.getElementById('demoCanvas');
+        let ctx = canvas.getContext('2d');
+        let animationId;
+
+        // Initialize tracker without canvas recording
+        function initTracker(enableCanvas = false) {
+            tracker = HumanBehaviorTracker.init('13c3e029-ca45-4a3c-a33b-f5dcb297e31c', {
+                logLevel: 'warn',
+                suppressConsoleErrors: true,
+                recordCanvas: enableCanvas // PostHog-style protection
+            });
+            
+            updateStatus();
+            console.log('✅ Tracker initialized with canvas recording:', enableCanvas);
+        }
+
+        function updateStatus() {
+            const status = document.getElementById('status');
+            status.innerHTML = `Canvas recording: <strong>${tracker.recordCanvas ? 'Enabled' : 'Disabled'}</strong>`;
+        }
+
+        function enableCanvasRecording() {
+            if (tracker) {
+                tracker.stop();
+            }
+            initTracker(true);
+        }
+
+        function disableCanvasRecording() {
+            if (tracker) {
+                tracker.stop();
+            }
+            initTracker(false);
+        }
+
+        function drawRandom() {
+            const colors = ['#FF6B6B', '#4ECDC4', '#45B7D1', '#96CEB4', '#FFEAA7'];
+            const color = colors[Math.floor(Math.random() * colors.length)];
+            
+            ctx.fillStyle = color;
+            ctx.beginPath();
+            ctx.arc(
+                Math.random() * canvas.width,
+                Math.random() * canvas.height,
+                Math.random() * 50 + 10,
+                0,
+                2 * Math.PI
+            );
+            ctx.fill();
+            
+            // Track the drawing event
+            if (tracker) {
+                tracker.customEvent('canvas_draw', { 
+                    color: color,
+                    timestamp: Date.now()
+                });
+            }
+        }
+
+        function clearCanvas() {
+            ctx.clearRect(0, 0, canvas.width, canvas.height);
+            
+            if (tracker) {
+                tracker.customEvent('canvas_clear', { 
+                    timestamp: Date.now()
+                });
+            }
+        }
+
+        function animate() {
+            let angle = 0;
+            
+            function animateFrame() {
+                ctx.clearRect(0, 0, canvas.width, canvas.height);
+                
+                // Draw rotating rectangle
+                ctx.save();
+                ctx.translate(canvas.width / 2, canvas.height / 2);
+                ctx.rotate(angle);
+                ctx.fillStyle = '#FF6B6B';
+                ctx.fillRect(-25, -25, 50, 50);
+                ctx.restore();
+                
+                angle += 0.02;
+                animationId = requestAnimationFrame(animateFrame);
+            }
+            
+            animateFrame();
+        }
+
+        // Initialize tracker on page load
+        initTracker(false);
+        
+        console.log('🎨 Canvas demo ready! Try drawing or enabling canvas recording.');
+    </script>
+</body>
+</html>

package/package/clean-console-demo.html

@@ -0,0 +1,39 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>HumanBehavior Clean Console Demo</title>
+</head>
+<body>
+    <h1>HumanBehavior Clean Console Demo</h1>
+    <p>This demo shows how to suppress common rrweb errors for a clean console.</p>
+    
+    <!-- External images that would normally cause CORS errors -->
+    <img src="https://img.lumas.com/showimg_rwt01_search.jpg" alt="External image 1" style="width: 100px; height: 100px;">
+    <img src="https://media.lumas.de/homepage/2024/magazine-kachel-300x400.webp" alt="External image 2" style="width: 100px; height: 100px;">
+    
+    <button>Click me to test recording</button>
+    <input type="text" placeholder="Type something">
+    <input type="password" placeholder="Password (will be redacted)">
+
+    <script src="./dist/index.min.js"></script>
+    <script>
+        // Initialize the tracker with error suppression enabled (default)
+        const tracker = HumanBehaviorTracker.init('13c3e029-ca45-4a3c-a33b-f5dcb297e31c', {
+            redactFields: ['input[type="password"]'],
+            suppressConsoleErrors: true, // Enable error suppression (default)
+            logLevel: 'warn' // Only show warnings and errors
+        });
+        
+        console.log('✅ HumanBehavior tracker initialized with clean console mode');
+        console.log('✅ Canvas security errors and CORS issues will be suppressed');
+        
+        // Test that core functionality still works
+        tracker.customEvent('demo_started', { 
+            feature: 'clean_console',
+            timestamp: Date.now()
+        });
+    </script>
+</body>
+</html>