@helping-desk/web-sdk
Version:
Web SDK for Helping Desk - Ticket creation and support widget integration
213 lines (158 loc) • 5.46 kB
Markdown
# Helping Desk Web SDK
A JavaScript/TypeScript SDK for integrating Helping Desk ticket creation functionality into any website or web application.
## Installation
### Using npm/yarn
```bash
npm install @helping-desk/web-sdk
# or
yarn add @helping-desk/web-sdk
```
### Using CDN (UMD build)
```html
<script src="https://cdn.example.com/helping-desk-sdk.umd.js"></script>
```
## Quick Start
### Basic Usage (Simplest - Widget Appears Automatically!)
```javascript
import { createSDK } from '@helping-desk/web-sdk';
// Just initialize the SDK with your tenantId from .env file - that's it!
const sdk = createSDK({
tenantId: process.env.HELPING_DESK_TENANT_ID, // Required: Your tenant ID from .env
});
// 🎉 A support widget automatically appears in the bottom-right corner!
// Users can click it to create tickets - no additional code needed!
```
**Note:** The API URL is automatically configured via the `HELPING_DESK_API_URL` environment variable. You don't need to provide it.
### Customize Widget Appearance
```javascript
const sdk = createSDK({
tenantId: process.env.HELPING_DESK_TENANT_ID,
widgetPosition: 'bottom-left', // Position: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'
widgetColor: '#ff5722', // Custom color
widgetIcon: '🎧', // Custom icon
});
```
### Programmatic Ticket Creation (Optional)
If you want 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',
priority: 'high',
category: 'technical',
tags: ['login', 'urgent'],
});
console.log('Ticket created:', ticket.id);
} catch (error) {
console.error('Failed to create ticket:', error.message);
}
```
### Browser Usage (UMD)
```html
<!DOCTYPE html>
<html>
<head>
<title>Helping Desk SDK Example</title>
<script src="https://cdn.example.com/helping-desk-sdk.umd.js"></script>
<script>
// Set API URL globally (configured by your backend)
window.HELPING_DESK_API_URL = 'https://api.helpingdesk.com';
</script>
</head>
<body>
<h1>My Website</h1>
<p>Look for the support widget in the bottom-right corner!</p>
<script>
// That's it! Widget appears automatically
// Only tenantId is required - API URL comes from environment
const sdk = new HelpingDeskSDK({
tenantId: 'your-tenant-id', // From your .env file
});
// Users can click the bubble to create tickets
// No additional code needed!
</script>
</body>
</html>
```
## API Reference
### Configuration
```typescript
interface SDKConfig {
tenantId: string; // Tenant ID from your .env file (required)
apiUrl?: string; // API URL (optional - reads from HELPING_DESK_API_URL env var)
showWidget?: boolean; // Show support widget (default: true)
widgetPosition?: string; // Widget position (default: 'bottom-right')
widgetColor?: string; // Widget primary color (default: '#667eea')
widgetIcon?: string; // Widget bubble icon (default: '💬')
}
```
**Environment Variables:**
- `HELPING_DESK_API_URL` - API base URL (set by your backend/service)
- `HELPING_DESK_TENANT_ID` - Your tenant ID (can be used instead of passing in config)
### Methods
#### `createTicket(data: CreateTicketData): Promise<Ticket>`
Creates a new support ticket.
**Parameters:**
- `data.title` (string, required): Ticket title
- `data.description` (string, required): Ticket description
- `data.priority` (string, optional): Priority level ('low' | 'medium' | 'high' | 'urgent')
- `data.category` (string, optional): Ticket category
- `data.tags` (string[], optional): Array of tags
**Returns:** Promise resolving to the created ticket object
**Example:**
```javascript
const ticket = await sdk.createTicket({
title: 'Bug Report',
description: 'The login button is not working',
priority: 'high',
category: 'bug',
tags: ['login', 'ui'],
});
```
#### `updateConfig(config: Partial<SDKConfig>): void`
Updates the SDK configuration.
**Example:**
```javascript
sdk.updateConfig({
widgetColor: '#ff5722',
});
```
#### `getConfig(): SDKConfig`
Returns the current SDK configuration.
#### `showWidget(): void`
Show the support widget (if it was hidden).
#### `hideWidget(): void`
Hide the support widget.
## Error Handling
The SDK throws errors with the following structure:
```typescript
interface SDKError {
message: string; // Error message
status?: number; // HTTP status code (if applicable)
details?: any; // Additional error details
}
```
**Example:**
```javascript
try {
await sdk.createTicket({ title: 'Test', description: 'Test' });
} catch (error) {
if (error.status === 400) {
console.error('Bad request:', error.message);
} else {
console.error('Unexpected error:', error);
}
}
```
## Tenant ID Requirement
All requests require a `tenantId` to be passed. The SDK automatically includes this with all requests to ensure proper routing and data isolation.
Your tenant ID is provided by your service administrator and should be kept secure.
## Examples
See the [examples directory](./examples/) for complete integration examples:
- [Basic HTML Example](./examples/simple-usage.html)
- [React Example](./examples/react-example.tsx)
## Documentation
- [Quick Start Guide](./QUICKSTART.md) - Get started quickly
## License
MIT