npm package: @helping-desk/web-sdk
Description: Web SDK for Helping Desk - Ticket creation and support widget integration
Author: devapp864@gmail.com
Latest version: 1.0.0

# 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