betabounty-sdk/README.md

BetaBounty SDK for integrating user testing widgets into web applications

# BetaBounty SDK

The BetaBounty SDK enables seamless integration of user testing widgets into web applications, allowing developers to collect valuable user feedback and testing data.

## Features

- 🎯 **Easy Integration** - Drop-in widget with minimal setup
- 📱 **Responsive Design** - Works on desktop and mobile devices  
- 🎥 **Video Support** - Built-in screen recording reminders for video-required bounties
- 📊 **Rich Context** - Automatic collection of technical context and user behavior
- 🔧 **TypeScript** - Full TypeScript support with type definitions
- 🎨 **Customizable** - Flexible styling and configuration options
- 🚀 **Production Ready** - Optimized logging and error handling

## Installation

```bash
npm install betabounty-sdk
```

## Quick Start

### Basic Usage

```javascript
import { initializeSDK } from 'betabounty-sdk'

// Initialize the SDK
initializeSDK({
  apiKey: 'your-api-key-here',
  debug: false // Set to true for development
})
```

### With Configuration

```javascript
import { initializeSDK } from 'betabounty-sdk'

initializeSDK({
  apiKey: 'your-api-key-here',
  baseUrl: 'https://api.betabounty.com', // Optional: custom API endpoint
  debug: true // Enable debug logging
})
```

## How It Works

1. **Session Detection** - The SDK automatically detects testing sessions from URL parameters
2. **Widget Display** - Shows an interactive testing widget when a session is detected
3. **User Testing** - Guides users through testing tasks with feedback collection
4. **Data Upload** - Automatically uploads testing results and technical context

## Session Flow

### Standard Testing Flow
1. User clicks "Start Testing Session"
2. Testing widget becomes active
3. User completes guided tasks
4. Session automatically completes and uploads data

### Video-Required Flow
1. User clicks "Start Testing (Video Required)"
2. Screen recording reminder appears with instructions
3. 10-second countdown after user confirms recording
4. Testing session begins
5. User completes tasks while recording
6. Session completes with video submission reminder

## Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `apiKey` | string | **required** | Your BetaBounty API key |
| `baseUrl` | string | `https://api.betabounty.com` | API endpoint URL |
| `debug` | boolean | `false` | Enable debug logging |

## TypeScript Support

The SDK is written in TypeScript and includes comprehensive type definitions:

```typescript
import { initializeSDK, type SDKConfig } from 'betabounty-sdk'

const config: SDKConfig = {
  apiKey: 'your-api-key',
  debug: true
}

initializeSDK(config)
```

## Widget Behavior

- **Automatic Detection** - Widget appears when session tokens are detected in URL
- **Session Validation** - Checks if sessions are completed/expired before showing
- **Responsive Design** - Adapts to different screen sizes
- **Non-Intrusive** - Positioned to avoid interfering with your application
- **Persistent State** - Maintains progress across page refreshes

## Development & Testing

For development and testing, you can use the mock mode:

```javascript
initializeSDK({
  apiKey: 'test_api_key_for_development', // Triggers mock mode
  debug: true
})
```

Mock mode provides:
- Simulated API responses
- Test data for development
- No actual API calls made

## Error Handling

The SDK includes comprehensive error handling:

- **Network Errors** - Graceful handling of API failures
- **Session Errors** - Clear messaging for invalid/expired sessions  
- **Recovery Options** - User-friendly retry mechanisms
- **Debug Logging** - Detailed logs in debug mode

## Browser Support

- Chrome (recommended)
- Firefox
- Safari
- Edge

## Examples

### React Application

```jsx
import { useEffect } from 'react'
import { initializeSDK } from 'betabounty-sdk'

function App() {
  useEffect(() => {
    initializeSDK({
      apiKey: process.env.REACT_APP_BETABOUNTY_API_KEY,
      debug: process.env.NODE_ENV === 'development'
    })
  }, [])

  return <div>Your Application</div>
}
```

### Vue Application

```vue
<template>
  <div>Your Application</div>
</template>

<script>
import { initializeSDK } from 'betabounty-sdk'

export default {
  mounted() {
    initializeSDK({
      apiKey: process.env.VUE_APP_BETABOUNTY_API_KEY,
      debug: process.env.NODE_ENV === 'development'
    })
  }
}
</script>
```

### Vanilla JavaScript

```html
<!DOCTYPE html>
<html>
<head>
  <title>My App</title>
</head>
<body>
  <div id="app">Your Application</div>
  
  <script type="module">
    import { initializeSDK } from 'betabounty-sdk'
    
    initializeSDK({
      apiKey: 'your-api-key-here'
    })
  </script>
</body>
</html>
```

## API Reference

### `initializeSDK(config: SDKConfig)`

Initializes the BetaBounty SDK with the provided configuration.

#### Parameters

- `config: SDKConfig` - Configuration object

#### Returns

- `void`

#### Example

```javascript
initializeSDK({
  apiKey: 'your-api-key',
  debug: true
})
```

## Contributing

This is a beta release. Please report issues or provide feedback through our GitHub repository.

## License

MIT License - see LICENSE file for details.

## Support

- 📧 Email: support@betabounty.com
- 🌐 Website: https://betabounty.com
- 📖 Documentation: https://docs.betabounty.com

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history and updates.

---

Made with ❤️ by the H.Silva