@channelhub/widget 0.1.12 → 0.1.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md ADDED
@@ -0,0 +1,168 @@
1
+ # `@channelhub/widget` — Embeddable Omnichannel Inbox, Channels & AI Settings SDK
2
+
3
+ > **AI Coding Agent Guide**: This document and `dist/types.d.ts` contain the complete integration specification for embedding ChannelHub into any React / Next.js application (either as a **Standalone Shop / Direct Tenant** or as a **B2B2B Multi-Tenant SaaS Platform**).
4
+
5
+ ---
6
+
7
+ ## 1. Exported Components & Client
8
+
9
+ ```ts
10
+ import {
11
+ ChannelHubInbox, // Omnichannel chat inbox (Desktop 3-pane / Tablet 2-pane / Mobile stack)
12
+ ChannelHubSettings, // AI Assistant, Canned Responses (/shortcut), & Inbox Automation settings
13
+ ChannelHubChannels, // OAuth & Bot connection manager (Facebook, Zalo OA, Instagram, Telegram, LiveChat)
14
+ ChannelHubNotificationBell, // Real-time unread notification bell with SSE
15
+ ChannelHubClient, // Low-level REST + SSE client
16
+ } from '@channelhub/widget';
17
+ ```
18
+
19
+ ---
20
+
21
+ ## 2. Two Integration Architectures
22
+
23
+ ### Mode A: B2B2B SaaS Platform (POS, CRM, Clinic/Spa SaaS, E-Commerce Platform)
24
+ In this mode, the **Platform** provisions tenants via `POST /v1/platform/tenants` (using `Platform Key`) and hosts its own central AI / webhook logic.
25
+ - **Hide technical AI setup** (`hideTechnicalAiConfig: true`) so end-merchants never see API Keys, Model names, or Webhook URLs.
26
+ - **Inject platform-specific business parameters** (`customParameters`) so merchants configure domain rules (e.g. inventory lookup, booking URL, shipping policy) through simple toggles and inputs.
27
+ - **Read merchant settings in Platform Backend**: Call `GET /v1/settings` with the tenant token (or receive it via webhook / `onSettingsChange`). Custom parameters are stored in `settings.ai.parameters`.
28
+
29
+ ```tsx
30
+ import { ChannelHubInbox } from '@channelhub/widget';
31
+
32
+ export function PlatformEmbeddedInbox({ tenantToken, currentUser, staffList }) {
33
+ return (
34
+ <ChannelHubInbox
35
+ apiUrl="https://api.channelhub.io.vn"
36
+ token={tenantToken}
37
+ height="calc(100dvh - 64px)"
38
+ // 1. Staff assignment & sender attribution
39
+ currentAgent={{
40
+ id: currentUser.id,
41
+ name: currentUser.fullName,
42
+ title: currentUser.roleName,
43
+ avatarUrl: currentUser.avatar,
44
+ }}
45
+ teamAgents={staffList.map(u => ({
46
+ id: u.id,
47
+ name: u.fullName,
48
+ title: u.roleName,
49
+ avatarUrl: u.avatar,
50
+ }))}
51
+ // 2. Customize the built-in Settings modal (⚙️ button in Inbox)
52
+ settingsConfig={{
53
+ hideTechnicalAiConfig: true,
54
+ customParameters: [
55
+ {
56
+ key: 'allowStockCheck',
57
+ type: 'toggle',
58
+ label: 'Cho phép AI tự tra cứu & báo tồn kho',
59
+ description: 'Dựa trên dữ liệu kho hàng thời gian thực của cửa hàng',
60
+ defaultValue: true,
61
+ },
62
+ {
63
+ key: 'bookingUrl',
64
+ type: 'text',
65
+ label: 'Link đặt lịch hẹn của chi nhánh',
66
+ placeholder: 'https://booking.example.com/spa-q1',
67
+ },
68
+ {
69
+ key: 'shippingPolicy',
70
+ type: 'textarea',
71
+ label: 'Chính sách giao hàng & đổi trả',
72
+ placeholder: 'VD: Freeship đơn từ 300k, đổi trả trong 7 ngày...',
73
+ },
74
+ ],
75
+ starterTemplates: [
76
+ { title: 'Chào khách', shortcut: '/chao', content: 'Dạ chào Anh/Chị, bên em có thể tư vấn gì cho mình ạ?' },
77
+ { title: 'Xin SĐT', shortcut: '/sdt', content: 'Dạ Anh/Chị cho em xin SĐT để lễ tân giữ lịch hẹn cho mình nhé!' },
78
+ ],
79
+ }}
80
+ />
81
+ );
82
+ }
83
+ ```
84
+
85
+ ### Mode B: Standalone Shop (Direct Tenant — `platform_id = null`)
86
+ When a single shop integrates ChannelHub directly without an intermediary SaaS platform:
87
+ - Leave `hideTechnicalAiConfig` unset (`false`).
88
+ - `<ChannelHubSettings />` will display the full AI Connection section where the shop can choose **OpenAI / Google Gemini / Anthropic Claude** (inputting their own `apiKey`, `model`, and `systemPrompt`) or **External Webhook** (e.g. n8n / Dify / custom server).
89
+
90
+ ```tsx
91
+ import { ChannelHubInbox, ChannelHubSettings } from '@channelhub/widget';
92
+
93
+ // Standalone Settings Page (including Channels connection tab):
94
+ <ChannelHubSettings
95
+ apiUrl="https://api.channelhub.io.vn"
96
+ token={tenantToken}
97
+ tabs={['ai', 'templates', 'inbox', 'channels']}
98
+ />
99
+ ```
100
+
101
+ ---
102
+
103
+ ## 3. Reading Settings & Custom Parameters via REST API
104
+
105
+ Both the widget and your backend can read/update tenant settings via:
106
+
107
+ - **`GET /v1/settings`** (Header: `Authorization: Bearer <TENANT_TOKEN>`)
108
+ - **`PUT /v1/settings`** (Header: `Authorization: Bearer <TENANT_TOKEN>`)
109
+
110
+ Example response from `GET /v1/settings`:
111
+ ```json
112
+ {
113
+ "ai": {
114
+ "mode": "autopilot",
115
+ "tone": "friendly",
116
+ "debounceSeconds": 5,
117
+ "autoPauseOnAgentAssign": true,
118
+ "autoPauseOnAgentReply": true,
119
+ "handoffOnPhone": true,
120
+ "handoffOnComplaint": true,
121
+ "schedule": "always",
122
+ "businessHours": { "start": "08:30", "end": "21:00" },
123
+ "provider": "webhook",
124
+ "systemPrompt": "...",
125
+ "parameters": {
126
+ "allowStockCheck": true,
127
+ "bookingUrl": "https://booking.example.com/spa-q1",
128
+ "shippingPolicy": "Freeship đơn từ 300k"
129
+ }
130
+ },
131
+ "inbox": {
132
+ "autoAssignOnFirstReply": true,
133
+ "soundNotification": true,
134
+ "quickReplies": ["Cảm ơn bạn đã liên hệ 🙏", "Mình sẽ kiểm tra ngay"],
135
+ "welcomeMessageEnabled": false,
136
+ "welcomeMessageText": "",
137
+ "awayMessageEnabled": false,
138
+ "awayMessageText": ""
139
+ },
140
+ "isPlatformManaged": true
141
+ }
142
+ ```
143
+
144
+ ---
145
+
146
+ ## 4. Extending Inbox with CRM Data (`extensions` prop)
147
+
148
+ Pass `extensions` to `<ChannelHubInbox />` to display CRM profile rows in the right-hand Contact Info panel, add CTA buttons (e.g. "Tạo đơn hàng", "Đặt lịch hẹn"), or enrich messages matching regex patterns (e.g. phone numbers or order codes):
149
+
150
+ ```tsx
151
+ import type { Extension } from '@channelhub/widget';
152
+
153
+ const crmExtension: Extension = {
154
+ contactInfoRows: async ({ contact }) => [
155
+ { label: 'Mã KH', value: contact.externalId ?? 'Chưa liên kết' },
156
+ { label: 'Hạng thẻ', value: 'VIP Gold', badge: { text: 'Giảm 10%', color: '#b45309', bg: '#fef3c7' } },
157
+ ],
158
+ sidebarActions: [
159
+ {
160
+ label: 'Tạo đơn hàng mới',
161
+ variant: 'primary',
162
+ onClick: ({ contact, conversation }) => {
163
+ openCreateOrderModal({ contact, conversationId: conversation.id });
164
+ },
165
+ },
166
+ ],
167
+ };
168
+ ```
@@ -1 +1 @@
1
- {"version":3,"file":"ChannelHubInbox.d.ts","sourceRoot":"","sources":["../src/ChannelHubInbox.tsx"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAmB,qBAAqB,EAAuI,WAAW,EAAE,MAAM,YAAY,CAAC;AA+H3N,eAAO,MAAM,eAAe,+GA4b1B,CAAC"}
1
+ {"version":3,"file":"ChannelHubInbox.d.ts","sourceRoot":"","sources":["../src/ChannelHubInbox.tsx"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAmB,qBAAqB,EAAwL,WAAW,EAAE,MAAM,YAAY,CAAC;AA+H5Q,eAAO,MAAM,eAAe,+GAkiB1B,CAAC"}
@@ -0,0 +1,3 @@
1
+ import type { ChannelHubSettingsProps } from './types.js';
2
+ export declare function ChannelHubSettings({ apiUrl, token, theme, initialTab, tabs, hideTechnicalAiConfig, customParameters, starterTemplates, onSettingsChange, onClose, }: ChannelHubSettingsProps): import("react").JSX.Element;
3
+ //# sourceMappingURL=ChannelHubSettings.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"ChannelHubSettings.d.ts","sourceRoot":"","sources":["../src/ChannelHubSettings.tsx"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAKV,uBAAuB,EAGxB,MAAM,YAAY,CAAC;AAwGpB,wBAAgB,kBAAkB,CAAC,EACjC,MAAM,EACN,KAAK,EACL,KAAK,EACL,UAAiB,EACjB,IAAI,EACJ,qBAAqB,EACrB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,OAAO,GACR,EAAE,uBAAuB,+BAmqDzB"}
package/dist/api.d.ts CHANGED
@@ -1,4 +1,5 @@
1
- import type { ChannelHubAgent, Connection, Conversation, Message, MessageAttachment, Page } from './types.js';
1
+ import type { CannedResponse, ChannelHubAgent, ChannelHubTenantSettings, Connection, Conversation, Message, MessageAttachment, Page } from './types.js';
2
+ export declare const DEFAULT_TENANT_SETTINGS: ChannelHubTenantSettings;
2
3
  export declare class ChannelHubClient {
3
4
  private readonly apiUrl;
4
5
  private readonly token;
@@ -16,12 +17,22 @@ export declare class ChannelHubClient {
16
17
  getMessage(messageId: string): Promise<Message>;
17
18
  sendMessage(conversationId: string, text?: string, attachments?: MessageAttachment[]): Promise<unknown>;
18
19
  markRead(conversationId: string): Promise<void>;
19
- listCannedResponses(search?: string): Promise<{
20
- id: string;
20
+ listCannedResponses(search?: string): Promise<CannedResponse[]>;
21
+ createCannedResponse(data: {
21
22
  title: string;
22
23
  content: string;
23
- shortcut: string | null;
24
- }[]>;
24
+ shortcut?: string;
25
+ }): Promise<CannedResponse>;
26
+ updateCannedResponse(id: string, data: {
27
+ title?: string;
28
+ content?: string;
29
+ shortcut?: string | null;
30
+ }): Promise<CannedResponse>;
31
+ deleteCannedResponse(id: string): Promise<void>;
32
+ private settingsStorageKey;
33
+ private mergeWithDefaultSettings;
34
+ getSettings(): Promise<ChannelHubTenantSettings>;
35
+ updateSettings(patch: Partial<ChannelHubTenantSettings>): Promise<ChannelHubTenantSettings>;
25
36
  getNote(conversationId: string): Promise<{
26
37
  id: string;
27
38
  content: string;
package/dist/api.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,YAAY,EAAE,OAAO,EAAE,iBAAiB,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAE9G,qBAAa,gBAAgB;IACf,OAAO,CAAC,QAAQ,CAAC,MAAM;IAAU,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAtC,MAAM,EAAE,MAAM,EAAmB,KAAK,EAAE,MAAM;YAE7D,OAAO;IAerB,YAAY,IAAI,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,CAAC,EAAE,eAAe,GAAG,IAAI,CAAA;KAAE,CAAC;IAI/F,kBAAkB,CAAC,cAAc,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,IAAI,GAAG,OAAO,CAAC,YAAY,CAAC;IAOhG,eAAe,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAExC,iBAAiB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAI/D,YAAY,CAAC,cAAc,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAI7E,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAI/C,WAAW,CAAC,cAAc,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,iBAAiB,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAQjG,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQrD,mBAAmB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,EAAE,CAAC;IAKxH,OAAO,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAInG,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAOxG,UAAU,CAAC,cAAc,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAO1G,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAE,CAAC;IAUtG,UAAU,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI;CAuBvE"}
1
+ {"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,wBAAwB,EAAE,UAAU,EAAE,YAAY,EAAE,OAAO,EAAE,iBAAiB,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAExJ,eAAO,MAAM,uBAAuB,EAAE,wBAiCrC,CAAC;AAEF,qBAAa,gBAAgB;IACf,OAAO,CAAC,QAAQ,CAAC,MAAM;IAAU,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAtC,MAAM,EAAE,MAAM,EAAmB,KAAK,EAAE,MAAM;YAE7D,OAAO;IAerB,YAAY,IAAI,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,CAAC,EAAE,eAAe,GAAG,IAAI,CAAA;KAAE,CAAC;IAI/F,kBAAkB,CAAC,cAAc,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,IAAI,GAAG,OAAO,CAAC,YAAY,CAAC;IAOhG,eAAe,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAExC,iBAAiB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAI/D,YAAY,CAAC,cAAc,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAI7E,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAI/C,WAAW,CAAC,cAAc,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,iBAAiB,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAQjG,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQrD,mBAAmB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAK/D,oBAAoB,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,cAAc,CAAC;IAO1G,oBAAoB,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,OAAO,CAAC,cAAc,CAAC;IAOzH,oBAAoB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUrD,OAAO,CAAC,kBAAkB;IAI1B,OAAO,CAAC,wBAAwB;IAyB1B,WAAW,IAAI,OAAO,CAAC,wBAAwB,CAAC;IAyBhD,cAAc,CAAC,KAAK,EAAE,OAAO,CAAC,wBAAwB,CAAC,GAAG,OAAO,CAAC,wBAAwB,CAAC;IAgDjG,OAAO,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAInG,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAOxG,UAAU,CAAC,cAAc,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAO1G,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAE,CAAC;IAUtG,UAAU,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI;CAuBvE"}