humanbehavior-js 0.3.7 → 0.3.9

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/dist/cjs/angular/index.cjs

@@ -0,0 +1,53 @@
+'use strict';
+
+var index = require('../index');
+
+// Angular NgModule for legacy Angular applications
+class HumanBehaviorModule {
+    static forRoot(config) {
+        return {
+            ngModule: HumanBehaviorModule,
+            providers: [
+                {
+                    provide: 'HUMANBEHAVIOR_API_KEY',
+                    useValue: config.apiKey
+                },
+                {
+                    provide: index.HumanBehaviorTracker,
+                    useFactory: (apiKey) => {
+                        return index.HumanBehaviorTracker.init(apiKey);
+                    },
+                    deps: ['HUMANBEHAVIOR_API_KEY']
+                }
+            ]
+        };
+    }
+}
+// Angular service for dependency injection
+class HumanBehaviorService {
+    constructor(apiKey) {
+        this.tracker = index.HumanBehaviorTracker.init(apiKey);
+    }
+    // Expose core tracker methods
+    identifyUser(userProperties) {
+        return this.tracker.identifyUser({ userProperties });
+    }
+    getSessionId() {
+        return this.tracker.getSessionId();
+    }
+    setRedactedFields(fields) {
+        return this.tracker.setRedactedFields(fields);
+    }
+    getRedactedFields() {
+        return this.tracker.getRedactedFields();
+    }
+}
+// Helper function for standalone Angular initialization
+function initializeHumanBehavior(apiKey) {
+    return index.HumanBehaviorTracker.init(apiKey);
+}
+
+exports.HumanBehaviorModule = HumanBehaviorModule;
+exports.HumanBehaviorService = HumanBehaviorService;
+exports.initializeHumanBehavior = initializeHumanBehavior;
+//# sourceMappingURL=index.cjs.map

package/dist/cjs/angular/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sources":["../../../src/angular/index.ts"],"sourcesContent":[null],"names":["HumanBehaviorTracker"],"mappings":";;;;AAEA;MACa,mBAAmB,CAAA;IAC9B,OAAO,OAAO,CAAC,MAA0B,EAAA;QACvC,OAAO;AACL,YAAA,QAAQ,EAAE,mBAAmB;AAC7B,YAAA,SAAS,EAAE;AACT,gBAAA;AACE,oBAAA,OAAO,EAAE,uBAAuB;oBAChC,QAAQ,EAAE,MAAM,CAAC;AAClB,iBAAA;AACD,gBAAA;AACE,oBAAA,OAAO,EAAEA,0BAAoB;AAC7B,oBAAA,UAAU,EAAE,CAAC,MAAc,KAAI;AAC7B,wBAAA,OAAOA,0BAAoB,CAAC,IAAI,CAAC,MAAM,CAAC;oBAC1C,CAAC;oBACD,IAAI,EAAE,CAAC,uBAAuB;AAC/B;AACF;SACF;IACH;AACD;AAED;MACa,oBAAoB,CAAA;AAG/B,IAAA,WAAA,CAAY,MAAc,EAAA;QACxB,IAAI,CAAC,OAAO,GAAGA,0BAAoB,CAAC,IAAI,CAAC,MAAM,CAAC;IAClD;;AAGA,IAAA,YAAY,CAAC,cAAmC,EAAA;QAC9C,OAAO,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,cAAc,EAAE,CAAC;IACtD;IAEA,YAAY,GAAA;AACV,QAAA,OAAO,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE;IACpC;AAEA,IAAA,iBAAiB,CAAC,MAAgB,EAAA;QAChC,OAAO,IAAI,CAAC,OAAO,CAAC,iBAAiB,CAAC,MAAM,CAAC;IAC/C;IAEA,iBAAiB,GAAA;AACf,QAAA,OAAO,IAAI,CAAC,OAAO,CAAC,iBAAiB,EAAE;IACzC;AACD;AAED;AACM,SAAU,uBAAuB,CAAC,MAAc,EAAA;AACpD,IAAA,OAAOA,0BAAoB,CAAC,IAAI,CAAC,MAAM,CAAC;AAC1C;;;;;;"}

package/dist/cjs/{index.js → index.cjs}

@@ -1,7 +1,5 @@
 'use strict';
 
-Object.defineProperty(exports, '__esModule', { value: true });
-
 /******************************************************************************
 Copyright (c) Microsoft Corporation.
 
@@ -14207,6 +14205,10 @@ if (isBrowser) {
 /**
  * Main entry point for the HumanBehavior SDK
  */
+// Installation wizard is exported separately to avoid Node.js dependencies in browser bundles
+// Import from 'humanbehavior-js/install-wizard' for Node.js usage
+// Note: Default export removed to avoid mixed export warnings
+// Use: import { HumanBehaviorTracker } from 'humanbehavior-js'
 // For UMD builds, expose the main class globally
 if (typeof window !== 'undefined') {
     window.HumanBehaviorTracker = HumanBehaviorTracker;
@@ -14216,7 +14218,6 @@ exports.HumanBehaviorAPI = HumanBehaviorAPI;
 exports.HumanBehaviorTracker = HumanBehaviorTracker;
 exports.MAX_CHUNK_SIZE_BYTES = MAX_CHUNK_SIZE_BYTES;
 exports.RedactionManager = RedactionManager;
-exports.default = HumanBehaviorTracker;
 exports.isChunkSizeExceeded = isChunkSizeExceeded;
 exports.logDebug = logDebug;
 exports.logError = logError;
@@ -14226,4 +14227,4 @@ exports.logger = logger;
 exports.redactionManager = redactionManager;
 exports.splitLargeEvent = splitLargeEvent;
 exports.validateSingleEventSize = validateSingleEventSize;
-//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.cjs.map