@helping-desk/web-sdk/QUICKSTART.md

Web SDK for Helping Desk - Ticket creation and support widget integration

# Quick Start Guide

## Installation

### Option 1: npm/yarn (Recommended for modern projects)

```bash
npm install @helping-desk/web-sdk
# or
yarn add @helping-desk/web-sdk
```

### Option 2: CDN (For simple HTML pages)

```html
<script src="https://cdn.example.com/helping-desk-sdk.umd.js"></script>
```

## Basic Usage (Super Simple!)

### Just Initialize - Widget Appears Automatically!

```javascript
import { createSDK } from '@helping-desk/web-sdk';

// That's it! The support widget appears automatically
// Only tenantId is required - API URL comes from environment variables
const sdk = createSDK({
  tenantId: process.env.HELPING_DESK_TENANT_ID,  // Your tenant ID from .env file
});

// 🎉 Users can now click the bubble to create tickets!
// No additional code needed - the SDK handles everything!
```

**What users see:**
- 💬 Support widget in the bottom-right corner
- Click to open widget with ticket creation form
- Simple form to submit support requests

**Important:** 
- The `tenantId` is provided by your service administrator and is used to route requests correctly.
- The API URL is automatically configured via the `HELPING_DESK_API_URL` environment variable (set by your backend/service).

### Customize Widget (Optional)

```javascript
const sdk = createSDK({
  tenantId: process.env.HELPING_DESK_TENANT_ID,
  widgetPosition: 'bottom-left',  // Change position
  widgetColor: '#ff5722',          // Custom color
  widgetIcon: '🎧',                // Custom icon
});
```

### Programmatic Ticket Creation (Optional)

If you prefer to create tickets programmatically instead of using the widget:

```javascript
try {
  const ticket = await sdk.createTicket({
    title: 'Need help with login',
    description: 'I cannot log into my account. Error message says...',
    priority: 'high',  // 'low' | 'medium' | 'high' | 'urgent'
    category: 'technical',
    tags: ['login', 'authentication'],
  });
  
  console.log('Ticket created:', ticket.id);
} catch (error) {
  console.error('Error:', error.message);
}
```

## Configuration

### Required Configuration

- **tenantId**: Your tenant ID (from your .env file, provided by your service administrator)

### Optional Configuration

- **apiUrl**: API base URL (optional - automatically reads from `HELPING_DESK_API_URL` environment variable)
- **showWidget**: Show support widget (default: true)
- **widgetPosition**: Widget position - 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left' (default: 'bottom-right')
- **widgetColor**: Widget primary color (default: '#667eea')
- **widgetIcon**: Widget bubble icon (default: '💬')

### Environment Variables

The SDK reads these environment variables automatically:

- `HELPING_DESK_API_URL` - API base URL (set by your backend/service, not end users)
- `HELPING_DESK_TENANT_ID` - Tenant ID (can be used instead of passing in config)

## Error Handling

The SDK throws errors with useful information:

```javascript
try {
  await sdk.createTicket({ ... });
} catch (error) {
  console.error('Status:', error.status);      // HTTP status code
  console.error('Message:', error.message);    // Error message
  console.error('Details:', error.details);    // Additional details
}
```

## Common Issues

### 1. "Tenant not found" error

**Solution:** Verify your `tenantId` is correct and matches what was provided by your service administrator.

### 2. CORS errors

**Solution:** Ensure your API server has CORS configured to allow requests from your domain.


## Next Steps

- See [README.md](./README.md) for complete API documentation
- Check [examples/](./examples/) for integration examples
- Review the main [README.md](../README.md) for project setup