@cognitiondesk/widget 1.2.0 → 1.2.1

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.
Files changed (2) hide show
  1. package/README.md +212 -44
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,6 +1,7 @@
1
1
  # @cognitiondesk/widget
2
2
 
3
- Embed a CognitionDesk AI chat widget into any website with a single API key.
3
+ Embed a CognitionDesk AI chat widget into any website with a single API key.
4
+ Supports React, Vue, plain HTML, WordPress, and Shopify — no build step required for script-tag usage.
4
5
 
5
6
  ## Installation
6
7
 
@@ -8,7 +9,11 @@ Embed a CognitionDesk AI chat widget into any website with a single API key.
8
9
  npm install @cognitiondesk/widget
9
10
  ```
10
11
 
11
- ## Quick start — React
12
+ ---
13
+
14
+ ## Quick start
15
+
16
+ ### React — minimal (recommended)
12
17
 
13
18
  ```jsx
14
19
  import { CognitionDeskWidget } from '@cognitiondesk/widget/react';
@@ -16,86 +21,249 @@ import { CognitionDeskWidget } from '@cognitiondesk/widget/react';
16
21
  export default function App() {
17
22
  return (
18
23
  <>
19
- {/* your app */}
24
+ <YourApp />
25
+ {/* Loads all config from the platform using widgetId */}
20
26
  <CognitionDeskWidget
21
27
  apiKey="YOUR_API_KEY"
22
- assistantId="YOUR_ASSISTANT_ID" // optional
23
- theme="light" // 'light' | 'dark' | 'auto'
28
+ widgetId="YOUR_WIDGET_ID"
29
+ />
30
+ </>
31
+ );
32
+ }
33
+ ```
34
+
35
+ ### React — full inline config
36
+
37
+ ```jsx
38
+ import { CognitionDeskWidget } from '@cognitiondesk/widget/react';
39
+
40
+ export default function App() {
41
+ return (
42
+ <>
43
+ <YourApp />
44
+ <CognitionDeskWidget
45
+ apiKey="YOUR_API_KEY"
46
+ assistantId="YOUR_ASSISTANT_ID"
47
+ theme="light"
24
48
  primaryColor="#2563eb"
25
49
  botName="Support Bot"
26
- welcomeMessage="Hello! How can I help you today?"
50
+ botEmoji="🤖"
51
+ welcomeMessage="Hi! How can I help?"
52
+ placeholder="Type a message…"
53
+ defaultOpen={false}
54
+ streaming={true}
55
+ onOpen={() => console.log('chat opened')}
56
+ onClose={() => console.log('chat closed')}
27
57
  />
28
58
  </>
29
59
  );
30
60
  }
31
61
  ```
32
62
 
33
- ## Quick start — Vanilla JS
63
+ ### React — programmatic control via ref
64
+
65
+ ```jsx
66
+ import { useRef } from 'react';
67
+ import { CognitionDeskWidget } from '@cognitiondesk/widget/react';
68
+
69
+ export default function App() {
70
+ const widgetRef = useRef(null);
71
+
72
+ return (
73
+ <>
74
+ <button onClick={() => widgetRef.current?.open()}>Open chat</button>
75
+ <CognitionDeskWidget
76
+ ref={widgetRef}
77
+ apiKey="YOUR_API_KEY"
78
+ widgetId="YOUR_WIDGET_ID"
79
+ />
80
+ </>
81
+ );
82
+ }
83
+ ```
84
+
85
+ ### Vanilla JS
34
86
 
35
87
  ```js
36
- import { CognitionDeskWidget } from '@cognitiondesk/widget';
88
+ import CognitionDeskWidget from '@cognitiondesk/widget';
37
89
 
38
90
  const widget = new CognitionDeskWidget({
39
- apiKey: 'YOUR_API_KEY',
40
- assistantId: 'YOUR_ASSISTANT_ID',
91
+ apiKey: 'YOUR_API_KEY',
92
+ widgetId: 'YOUR_WIDGET_ID', // fetches full config from platform
41
93
  });
42
- widget.mount(); // appends to document.body
94
+
95
+ await widget.mount(); // async when widgetId is set
43
96
  ```
44
97
 
45
- ## Script tag (CDN)
98
+ ### Script tag / CDN (no build step)
46
99
 
47
100
  ```html
48
- <!-- Auto-init via data attributes -->
101
+ <!-- Minimal — loads config from the platform -->
102
+ <script
103
+ src="https://cdn.jsdelivr.net/npm/@cognitiondesk/widget/dist/widget.umd.cjs"
104
+ data-api-key="YOUR_API_KEY"
105
+ data-widget-id="YOUR_WIDGET_ID">
106
+ </script>
107
+ ```
108
+
109
+ ```html
110
+ <!-- Full inline config -->
49
111
  <script
50
112
  src="https://cdn.jsdelivr.net/npm/@cognitiondesk/widget/dist/widget.umd.cjs"
51
113
  data-api-key="YOUR_API_KEY"
52
114
  data-assistant-id="YOUR_ASSISTANT_ID"
53
115
  data-theme="light"
54
- ></script>
55
-
56
- <!-- Or manual init -->
57
- <script src="https://cdn.jsdelivr.net/npm/@cognitiondesk/widget/dist/widget.umd.cjs"></script>
58
- <script>
59
- CognitionDesk.init({ apiKey: 'YOUR_API_KEY' });
116
+ data-primary-color="#2563eb"
117
+ data-bot-name="Support Bot"
118
+ data-bot-emoji="🤖"
119
+ data-welcome-message="Hi! How can I help?"
120
+ data-placeholder="Type a message…"
121
+ data-streaming="true">
60
122
  </script>
61
123
  ```
62
124
 
63
- ## API Keys
125
+ ---
126
+
127
+ ## Authentication
128
+
129
+ Every request is authenticated with an **API key** passed via the `apiKey` prop (or `data-api-key` attribute for script-tag usage).
130
+
131
+ Generate and manage API keys in your [CognitionDesk dashboard](https://app.cognitiondesk.com) under **Settings → API Keys**.
64
132
 
65
- Generate and manage API keys in your [CognitionDesk dashboard](https://app.cognitiondesk.com/dashboard/api-keys).
133
+ Each API key:
134
+ - Authenticates widget requests to the AI backend
135
+ - Tracks usage against your plan quotas
136
+ - Associates conversations with your account
66
137
 
67
- Each API key is scoped to your account and used to:
68
- - Authenticate widget requests to the AI backend
69
- - Track usage against your plan quotas
70
- - Associate conversations with the correct assistant
138
+ ---
71
139
 
72
140
  ## Configuration options
73
141
 
142
+ ### Core props
143
+
144
+ | Prop / Attribute | Type | Default | Description |
145
+ |---|---|---|---|
146
+ | `apiKey` / `data-api-key` | `string` | **required** | Your CognitionDesk API key |
147
+ | `widgetId` / `data-widget-id` | `string` | `undefined` | Widget ID from the platform — fetches full config automatically |
148
+ | `assistantId` / `data-assistant-id` | `string` | `undefined` | Use a specific assistant (falls back to account default) |
149
+ | `theme` / `data-theme` | `'light'│'dark'│'auto'` | `'light'` | Color scheme |
150
+ | `primaryColor` / `data-primary-color` | `string` | `'#2563eb'` | Brand accent color (any CSS color) |
151
+ | `botName` / `data-bot-name` | `string` | `'AI Assistant'` | Name shown in the widget header |
152
+ | `botEmoji` / `data-bot-emoji` | `string` | `'🤖'` | Avatar emoji |
153
+ | `welcomeMessage` / `data-welcome-message` | `string` | `'Hello! How can I help you today?'` | First message shown to the user |
154
+ | `placeholder` / `data-placeholder` | `string` | `'Type a message…'` | Input placeholder text |
155
+ | `streaming` / `data-streaming` | `boolean` | `true` | Enable streaming (SSE) responses |
156
+ | `defaultOpen` | `boolean` | `false` | Open widget on load *(React only)* |
157
+ | `backendUrl` / `data-backend-url` | `string` | auto | Override backend URL (self-hosted setups) |
158
+
159
+ ### Rate limiting props
160
+
161
+ Control how many messages a single visitor can send to prevent abuse and excessive API usage.
162
+ Limits are enforced **both client-side** (instant feedback) and **server-side** (can't be bypassed).
163
+
74
164
  | Prop | Type | Default | Description |
75
165
  |---|---|---|---|
76
- | `apiKey` | `string` | **required** | Your CognitionDesk API key |
77
- | `assistantId` | `string` | `undefined` | Specific assistant to use (uses account default otherwise) |
78
- | `theme` | `'light'│'dark'│'auto'` | `'light'` | Color scheme |
79
- | `primaryColor` | `string` | `'#2563eb'` | Brand accent color (CSS color) |
80
- | `botName` | `string` | `'AI Assistant'` | Name shown in the widget header |
81
- | `botEmoji` | `string` | `'🤖'` | Avatar emoji shown in the header |
82
- | `welcomeMessage` | `string` | `'Hello! How can I help you today?'` | First message shown to the user |
83
- | `placeholder` | `string` | `'Type a message…'` | Input placeholder |
84
- | `defaultOpen` | `boolean` | `false` | Open the widget on load *(React only)* |
85
- | `backendUrl` | `string` | auto | Override backend URL (self-hosted setups) |
86
-
87
- ## Widget methods (vanilla JS)
166
+ | `maxMessagesPerSession` | `number` | `0` | Max total messages per visitor session. `0` = unlimited |
167
+ | `maxMessagesPerMinute` | `number` | `0` | Max messages per minute per visitor. `0` = unlimited |
168
+ | `limitReachedMessage` | `string` | `"You've reached the message limit for this session."` | Message shown when session limit is hit |
169
+ | `rateLimitMessage` | `string` | `"You're sending messages too quickly. Please wait a moment."` | Message shown when per-minute limit is hit |
170
+
171
+ > **Note:** When using `widgetId`, rate limit settings are fetched from the platform and override any props you pass here. Configure them in the **Web Widget creator** on the platform dashboard.
172
+
173
+ #### Example — React
174
+
175
+ ```jsx
176
+ <CognitionDeskWidget
177
+ apiKey="YOUR_API_KEY"
178
+ assistantId="YOUR_ASSISTANT_ID"
179
+ maxMessagesPerSession={50}
180
+ maxMessagesPerMinute={10}
181
+ limitReachedMessage="You've used all your messages for this session."
182
+ rateLimitMessage="Slow down — please wait a few seconds."
183
+ />
184
+ ```
185
+
186
+ #### Example — Vanilla JS
187
+
188
+ ```js
189
+ const widget = new CognitionDeskWidget({
190
+ apiKey: 'YOUR_API_KEY',
191
+ assistantId: 'YOUR_ASSISTANT_ID',
192
+ rateLimiting: {
193
+ enabled: true,
194
+ maxMessagesPerSession: 50,
195
+ maxMessagesPerMinute: 10,
196
+ limitReachedMessage: "You've used all your messages for this session.",
197
+ rateLimitMessage: "Slow down — please wait a few seconds.",
198
+ },
199
+ });
200
+ widget.mount();
201
+ ```
202
+
203
+ ### Callbacks *(React only)*
204
+
205
+ | Prop | Type | Description |
206
+ |---|---|---|
207
+ | `onOpen` | `() => void` | Called when the chat panel opens |
208
+ | `onClose` | `() => void` | Called when the chat panel closes |
209
+
210
+ ---
211
+
212
+ ## Widget methods
213
+
214
+ Available on the class instance (vanilla JS) or via `ref` (React).
88
215
 
89
216
  ```js
90
- const widget = new CognitionDeskWidget({ apiKey: '...' });
91
- widget.mount(); // mount to DOM
92
- widget.open(); // programmatically open
93
- widget.close(); // close
94
- widget.toggle(); // toggle open/close
95
- widget.clearHistory(); // reset conversation
96
- widget.unmount(); // remove from DOM
217
+ widget.mount(el?) // Mount to DOM — pass an element or defaults to document.body
218
+ // Returns a Promise when widgetId is set (async config fetch)
219
+ widget.open() // Open the chat panel
220
+ widget.close() // Close the chat panel
221
+ widget.toggle() // Toggle open/closed
222
+ widget.clearHistory() // Reset the conversation
223
+ widget.unmount() // Remove from DOM and clean up
224
+ ```
225
+
226
+ ### React ref example
227
+
228
+ ```jsx
229
+ const ref = useRef(null);
230
+ // ...
231
+ <CognitionDeskWidget ref={ref} apiKey="..." widgetId="..." />
232
+
233
+ // Later:
234
+ ref.current?.open();
235
+ ref.current?.clearHistory();
97
236
  ```
98
237
 
238
+ ---
239
+
240
+ ## CDN data-attribute reference
241
+
242
+ All configuration options are available as `data-*` attributes for script-tag usage:
243
+
244
+ | Attribute | Description |
245
+ |---|---|
246
+ | `data-api-key` | **Required.** Your API key |
247
+ | `data-widget-id` | Widget ID (loads config from platform) |
248
+ | `data-assistant-id` | Direct assistant ID |
249
+ | `data-theme` | `"light"`, `"dark"`, or `"auto"` |
250
+ | `data-primary-color` | Hex color, e.g. `"#2563eb"` |
251
+ | `data-bot-name` | Display name |
252
+ | `data-bot-emoji` | Avatar emoji |
253
+ | `data-welcome-message` | Opening message |
254
+ | `data-placeholder` | Input placeholder |
255
+ | `data-streaming` | `"true"` or `"false"` |
256
+ | `data-backend-url` | Override API base URL |
257
+
258
+ ---
259
+
260
+ ## Platform integrations
261
+
262
+ Full installation guides for React, Vue, WordPress, and Shopify are available in the
263
+ [CognitionDesk documentation](https://docs.cognitiondesk.com/docs/web-widget).
264
+
265
+ ---
266
+
99
267
  ## License
100
268
 
101
269
  MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cognitiondesk/widget",
3
- "version": "1.2.0",
3
+ "version": "1.2.1",
4
4
  "description": "Embed a CognitionDesk AI chat widget into any website. Authenticate with an API key from your CognitionDesk dashboard.",
5
5
  "keywords": ["chat", "widget", "ai", "cognitiondesk", "chatbot", "react", "streaming", "mounaji"],
6
6
  "license": "MIT",