@helping-desk/web-sdk
v1.0.0
Published
Web SDK for Helping Desk - Ticket creation and support widget integration
Downloads
5
Maintainers
devapp864Readme
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
npm install @helping-desk/web-sdk
# or
yarn add @helping-desk/web-sdkUsing CDN (UMD build)
<script src="https://cdn.example.com/helping-desk-sdk.umd.js"></script>Quick Start
Basic Usage (Simplest - Widget Appears Automatically!)
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
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:
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)
<!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
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 titledata.description(string, required): Ticket descriptiondata.priority(string, optional): Priority level ('low' | 'medium' | 'high' | 'urgent')data.category(string, optional): Ticket categorydata.tags(string[], optional): Array of tags
Returns: Promise resolving to the created ticket object
Example:
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:
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:
interface SDKError {
message: string; // Error message
status?: number; // HTTP status code (if applicable)
details?: any; // Additional error details
}Example:
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 for complete integration examples:
Documentation
- Quick Start Guide - Get started quickly
License
MIT