supportkit-sdk
v1.2.0
Published
Developer-first customer support chat SDK - Add beautiful, real-time chat widgets to your website in minutes
Maintainers
onahReadme
💬 SupportKit SDK
Developer-first customer support chat widget built with Lit web components
✨ Features
- 🚀 Lightweight - Only ~60KB gzipped
- ⚡ Real-time - WebSocket powered instant messaging
- 🎨 Customizable - Full theme and positioning control
- 📱 Responsive - Works on desktop, tablet, and mobile
- 🌍 i18n Ready - Multi-language support
- 🔒 Secure - API key authentication
- 💾 Offline Support - Message queuing when offline
- 🎯 Framework Agnostic - Works with React, Vue, Angular, or vanilla JS
📦 Installation
Via NPM
npm install supportkit-sdkVia CDN
<script src="https://cdn.jsdelivr.net/npm/supportkit-sdk@latest/dist/supportkit.umd.js"></script>🚀 Quick Start
Basic Usage
import { SupportKit } from 'supportkit-sdk';
SupportKit.init({
apiKey: 'sk_your_api_key_here',
position: 'bottom-right',
user: {
id: 'user_123',
name: 'John Doe',
email: '[email protected]',
},
});CDN Usage
<!DOCTYPE html>
<html>
<head>
<title>My Website</title>
</head>
<body>
<h1>Welcome!</h1>
<!-- SupportKit will appear in bottom-right corner -->
<script src="https://cdn.jsdelivr.net/npm/supportkit-sdk@latest/dist/supportkit.umd.js"></script>
<script>
SupportKit.init({
apiKey: 'sk_your_api_key_here',
});
</script>
</body>
</html>⚙️ Configuration
All Options
SupportKit.init({
// Required
apiKey: string, // Your API key from dashboard
// Optional
position?: 'bottom-right' // Widget position
| 'bottom-left'
| 'top-right'
| 'top-left',
theme?: {
primaryColor?: string, // Default: '#3B82F6'
backgroundColor?: string, // Default: '#FFFFFF'
textColor?: string, // Default: '#1F2937'
fontFamily?: string, // Default: system-ui
borderRadius?: string, // Default: '12px'
zIndex?: number, // Default: 9999
},
locale?: string, // Default: 'en'
user?: {
id?: string, // User identifier
name?: string, // User display name
email?: string, // User email
avatar?: string, // User avatar URL
},
});Theme Customization
SupportKit.init({
apiKey: 'sk_your_key',
theme: {
primaryColor: '#10B981', // Green
backgroundColor: '#F9FAFB', // Light gray
textColor: '#111827', // Dark gray
fontFamily: 'Inter, sans-serif',
borderRadius: '16px',
zIndex: 10000,
},
});🎮 API Methods
Open Chat
const sdk = SupportKit.getInstance();
sdk.open();Close Chat
sdk.close();Update User
sdk.updateUser({
id: 'user_456',
name: 'Jane Smith',
email: '[email protected]',
});Destroy Widget
sdk.destroy();Get Configuration
const config = sdk.getConfig();
console.log(config);🌍 Internationalization
SupportKit.init({
apiKey: 'sk_your_key',
locale: 'es', // Spanish
});Supported locales:
en- English (default)es- Spanishfr- Frenchde- Germanpt- Portugueseja- Japanesezh- Chinese
🔌 Framework Integration
React
import { useEffect } from 'react';
import { SupportKit } from 'supportkit-sdk';
function App() {
useEffect(() => {
const sdk = SupportKit.init({
apiKey: process.env.REACT_APP_SUPPORTKIT_API_KEY,
user: {
id: currentUser.id,
name: currentUser.name,
email: currentUser.email,
},
});
return () => sdk.destroy();
}, []);
return <div>Your App</div>;
}Vue
<script setup>
import { onMounted, onUnmounted } from 'vue';
import { SupportKit } from 'supportkit-sdk';
let sdk;
onMounted(() => {
sdk = SupportKit.init({
apiKey: import.meta.env.VITE_SUPPORTKIT_API_KEY,
});
});
onUnmounted(() => {
sdk?.destroy();
});
</script>
<template>
<div>Your App</div>
</template>Next.js
'use client';
import { useEffect } from 'react';
export default function SupportKitProvider() {
useEffect(() => {
// Dynamic import to avoid SSR issues
import('supportkit-sdk').then(({ SupportKit }) => {
SupportKit.init({
apiKey: process.env.NEXT_PUBLIC_SUPPORTKIT_API_KEY,
});
});
}, []);
return null;
}🛠️ Development
Setup
# Install dependencies
pnpm install
# Start dev server
pnpm dev
# Build for production
pnpm build
# Type check
pnpm type-checkBuild Output
dist/
├── supportkit.es.js # ES module
├── supportkit.umd.js # UMD bundle
└── index.d.ts # TypeScript definitions📝 Events
Listen to SDK events:
const sdk = SupportKit.getInstance();
// Get the widget element
const widget = document.querySelector('supportkit-chat-widget');
// Listen to custom events
widget.addEventListener('message-sent', (e) => {
console.log('Message sent:', e.detail);
});
widget.addEventListener('message-received', (e) => {
console.log('Message received:', e.detail);
});🔒 Security
- API keys are validated on initialization
- All communication is encrypted (HTTPS/WSS)
- Messages are stored securely in PostgreSQL
- No sensitive data in localStorage
- CORS protection on API endpoints
🐛 Troubleshooting
Widget not showing
// Check if SDK initialized
const sdk = SupportKit.getInstance();
console.log(sdk ? 'Initialized' : 'Not initialized');
// Check browser console for errors
// Verify API key is correctWebSocket connection issues
// The SDK automatically falls back to polling
// Check dashboard WebSocket server is running
// Verify CORS settings allow your domain📄 License
🎯 Roadmap
- [ ] File upload support
- [ ] Voice messages
- [ ] Video chat
- [ ] Screen sharing
- [ ] Emoji picker
- [ ] Message reactions
- [ ] Rich text formatting
- [ ] Custom branding
- [ ] Analytics dashboard
- [ ] AI-powered responses
Made with ❤️ by the SupportKit team