humanbehavior-js/WIZARD_USAGE_GUIDE.md

SDK for HumanBehavior session and event recording

# 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! 🚀