@tivagent/tiva-chat 1.0.4 → 1.0.8
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 +337 -60
- package/dist/components/chatbot.d.ts +1 -1
- package/dist/index.cjs.js +188 -65
- package/dist/index.esm.js +1278 -1147
- package/dist/index.umd.js +279 -156
- package/dist/test.html +24 -24
- package/dist/utils/APIRequests.d.ts +8 -7
- package/dist/utils/ChatbotStyles.d.ts +1 -0
- package/dist/utils/EmbeddedFontStyles.d.ts +1 -0
- package/package.json +79 -73
package/README.md
CHANGED
|
@@ -8,23 +8,295 @@ This package provides:
|
|
|
8
8
|
- A Web Component: `<tiva-chatbot>`
|
|
9
9
|
- ESM, CJS, and UMD build outputs
|
|
10
10
|
|
|
11
|
-
##
|
|
11
|
+
## Install
|
|
12
12
|
|
|
13
13
|
```bash
|
|
14
14
|
npm install @tivagent/tiva-chat react react-dom
|
|
15
15
|
```
|
|
16
16
|
|
|
17
|
-
##
|
|
17
|
+
## Choose Integration Type
|
|
18
|
+
|
|
19
|
+
- Use `Chatbot` for React/Next.js React rendering.
|
|
20
|
+
- Use `<tiva-chatbot>` for framework-agnostic integration (HTML, Vue, Svelte, Angular, Nuxt, Astro, Solid, and others).
|
|
21
|
+
|
|
22
|
+
## Required Inputs
|
|
23
|
+
|
|
24
|
+
- `uiKey` / `ui-key`: required, used to fetch UI config.
|
|
25
|
+
- `baseUrl` / `base-url`: backend host URL without version path. Example: `https://api.example.com`
|
|
26
|
+
- `version`: optional API version, default is `v1`.
|
|
27
|
+
- `apiKey` / `api-key`: optional API key sent as `TIVA-API-Key`.
|
|
28
|
+
- `configurations`: optional user preference overrides.
|
|
29
|
+
|
|
30
|
+
## React Props
|
|
31
|
+
|
|
32
|
+
| Prop | Type | Required | Description |
|
|
33
|
+
| ---------------- | ----------------------- | -------- | -------------------------------------- |
|
|
34
|
+
| `uiKey` | `string` | Yes | UI key used to fetch widget config. |
|
|
35
|
+
| `version` | `string` | No | API version (default: `v1`). |
|
|
36
|
+
| `apiKey` | `string` | No | API key sent in request headers. |
|
|
37
|
+
| `baseUrl` | `string` | No | Backend base URL without version path. |
|
|
38
|
+
| `configurations` | `PreferencesDefinition` | No | User preference overrides. |
|
|
39
|
+
|
|
40
|
+
## Web Component Attributes
|
|
41
|
+
|
|
42
|
+
| Attribute | Type | Required | Description |
|
|
43
|
+
| ---------------- | ------------- | -------- | ------------------------------------- |
|
|
44
|
+
| `ui-key` | `string` | Yes | Same as `uiKey`. |
|
|
45
|
+
| `version` | `string` | No | Same as `version`. |
|
|
46
|
+
| `api-key` | `string` | No | Same as `apiKey`. |
|
|
47
|
+
| `base-url` | `string` | No | Same as `baseUrl`. |
|
|
48
|
+
| `configurations` | `JSON string` | No | JSON form of `PreferencesDefinition`. |
|
|
49
|
+
|
|
50
|
+
`configurations` fields:
|
|
51
|
+
|
|
52
|
+
- `theme`: `"system" | "light" | "dark"`
|
|
53
|
+
- `language`: `"system" | string`
|
|
54
|
+
- `dir`: `"system" | "ltr" | "rtl"`
|
|
55
|
+
- `direction`: `"system" | "ltr" | "rtl"`
|
|
56
|
+
- `userMessagesPosition`: `"system" | "left" | "right"`
|
|
57
|
+
- `buttonPosition`: `"system" | "left" | "right"`
|
|
58
|
+
- `unreadFlagPosition`: `"system" | "left" | "right"`
|
|
59
|
+
|
|
60
|
+
## 1) Plain HTML From Scratch (unpkg CDN)
|
|
61
|
+
|
|
62
|
+
### Step 1: Create a project folder
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
mkdir tiva-chat-html
|
|
66
|
+
cd tiva-chat-html
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
### Step 2: Create `index.html`
|
|
70
|
+
|
|
71
|
+
```html
|
|
72
|
+
<!doctype html>
|
|
73
|
+
<html lang="en">
|
|
74
|
+
<head>
|
|
75
|
+
<meta charset="UTF-8" />
|
|
76
|
+
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
|
77
|
+
<title>Tiva Chat HTML</title>
|
|
78
|
+
</head>
|
|
79
|
+
<body>
|
|
80
|
+
<h1>Tiva Chat Demo (HTML + unpkg)</h1>
|
|
81
|
+
|
|
82
|
+
<tiva-chatbot
|
|
83
|
+
ui-key="YOUR_UI_KEY"
|
|
84
|
+
base-url="https://api.example.com"
|
|
85
|
+
version="v1"
|
|
86
|
+
api-key="YOUR_API_KEY"
|
|
87
|
+
configurations='{"theme":"system","language":"system","buttonPosition":"right"}'
|
|
88
|
+
></tiva-chatbot>
|
|
89
|
+
|
|
90
|
+
<script src="https://unpkg.com/@tivagent/tiva-chat/dist/index.umd.js"></script>
|
|
91
|
+
</body>
|
|
92
|
+
</html>
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
### Step 3: Run locally
|
|
96
|
+
|
|
97
|
+
```bash
|
|
98
|
+
npx serve .
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
Open the local URL shown by `serve` (usually `http://localhost:3000`).
|
|
102
|
+
|
|
103
|
+
### Step 4: Test
|
|
104
|
+
|
|
105
|
+
1. Open the page and confirm chat button appears.
|
|
106
|
+
2. Open browser devtools Network tab.
|
|
107
|
+
3. Verify `GET /v1/get_ui_config?ui_key=...` returns `200`.
|
|
108
|
+
4. Send a message and verify `POST /v1/messages` streams response.
|
|
109
|
+
|
|
110
|
+
## 2) React From Scratch (npm + Vite)
|
|
111
|
+
|
|
112
|
+
### Step 1: Create React app
|
|
113
|
+
|
|
114
|
+
```bash
|
|
115
|
+
npm create vite@latest tiva-chat-react -- --template react-ts
|
|
116
|
+
cd tiva-chat-react
|
|
117
|
+
npm install
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
### Step 2: Install package
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
npm install @tivagent/tiva-chat react react-dom
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
### Step 3: Update `src/App.tsx`
|
|
18
127
|
|
|
19
128
|
```tsx
|
|
20
129
|
import { Chatbot } from "@tivagent/tiva-chat";
|
|
21
130
|
|
|
22
131
|
export default function App() {
|
|
132
|
+
return (
|
|
133
|
+
<main>
|
|
134
|
+
<h1>Tiva Chat + React</h1>
|
|
135
|
+
<Chatbot
|
|
136
|
+
uiKey="YOUR_UI_KEY"
|
|
137
|
+
baseUrl="https://api.example.com"
|
|
138
|
+
version="v1"
|
|
139
|
+
apiKey="YOUR_API_KEY"
|
|
140
|
+
configurations={{
|
|
141
|
+
theme: "system",
|
|
142
|
+
language: "system",
|
|
143
|
+
buttonPosition: "right",
|
|
144
|
+
}}
|
|
145
|
+
/>
|
|
146
|
+
</main>
|
|
147
|
+
);
|
|
148
|
+
}
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
### Step 4: Run app
|
|
152
|
+
|
|
153
|
+
```bash
|
|
154
|
+
npm run dev
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
### Step 5: Test
|
|
158
|
+
|
|
159
|
+
1. Confirm widget button renders.
|
|
160
|
+
2. Open chat and send one message.
|
|
161
|
+
3. Confirm streaming response appears.
|
|
162
|
+
4. Check browser Network for `/v1/get_ui_config` and `/v1/messages`.
|
|
163
|
+
|
|
164
|
+
## 3) Vue 3 From Scratch (npm + Vite)
|
|
165
|
+
|
|
166
|
+
Use the Web Component mode in Vue.
|
|
167
|
+
|
|
168
|
+
### Step 1: Create Vue app
|
|
169
|
+
|
|
170
|
+
```bash
|
|
171
|
+
npm create vue@latest tiva-chat-vue
|
|
172
|
+
cd tiva-chat-vue
|
|
173
|
+
npm install
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
### Step 2: Install package
|
|
177
|
+
|
|
178
|
+
```bash
|
|
179
|
+
npm install @tivagent/tiva-chat react react-dom
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
### Step 3: Tell Vue compiler `tiva-chatbot` is a custom element
|
|
183
|
+
|
|
184
|
+
Update `vite.config.ts`:
|
|
185
|
+
|
|
186
|
+
```ts
|
|
187
|
+
import { defineConfig } from "vite";
|
|
188
|
+
import vue from "@vitejs/plugin-vue";
|
|
189
|
+
|
|
190
|
+
export default defineConfig({
|
|
191
|
+
plugins: [
|
|
192
|
+
vue({
|
|
193
|
+
template: {
|
|
194
|
+
compilerOptions: {
|
|
195
|
+
isCustomElement: (tag) => tag === "tiva-chatbot",
|
|
196
|
+
},
|
|
197
|
+
},
|
|
198
|
+
}),
|
|
199
|
+
],
|
|
200
|
+
});
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
### Step 4: Load the widget bundle once
|
|
204
|
+
|
|
205
|
+
Update `src/main.ts`:
|
|
206
|
+
|
|
207
|
+
```ts
|
|
208
|
+
import { createApp } from "vue";
|
|
209
|
+
import App from "./App.vue";
|
|
210
|
+
import "@tivagent/tiva-chat/dist/index.esm.js";
|
|
211
|
+
|
|
212
|
+
createApp(App).mount("#app");
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
### Step 5: Use `<tiva-chatbot>` in `src/App.vue`
|
|
216
|
+
|
|
217
|
+
```vue
|
|
218
|
+
<script setup lang="ts">
|
|
219
|
+
const configurationsJson = JSON.stringify({
|
|
220
|
+
theme: "system",
|
|
221
|
+
language: "system",
|
|
222
|
+
buttonPosition: "right",
|
|
223
|
+
});
|
|
224
|
+
</script>
|
|
225
|
+
|
|
226
|
+
<template>
|
|
227
|
+
<main>
|
|
228
|
+
<h1>Tiva Chat + Vue</h1>
|
|
229
|
+
<tiva-chatbot
|
|
230
|
+
ui-key="YOUR_UI_KEY"
|
|
231
|
+
base-url="https://api.example.com"
|
|
232
|
+
version="v1"
|
|
233
|
+
api-key="YOUR_API_KEY"
|
|
234
|
+
:configurations="configurationsJson"
|
|
235
|
+
></tiva-chatbot>
|
|
236
|
+
</main>
|
|
237
|
+
</template>
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
### Step 6: Run and test
|
|
241
|
+
|
|
242
|
+
```bash
|
|
243
|
+
npm run dev
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
Test exactly like the React checklist above.
|
|
247
|
+
|
|
248
|
+
## 4) Next.js From Scratch (App Router)
|
|
249
|
+
|
|
250
|
+
Use client-side dynamic import to avoid SSR issues.
|
|
251
|
+
|
|
252
|
+
### Step 1: Create Next.js app
|
|
253
|
+
|
|
254
|
+
```bash
|
|
255
|
+
npx create-next-app@latest tiva-chat-next --typescript --eslint --app
|
|
256
|
+
cd tiva-chat-next
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
### Step 2: Install package
|
|
260
|
+
|
|
261
|
+
```bash
|
|
262
|
+
npm install @tivagent/tiva-chat react react-dom
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
### Step 3: Create client widget wrapper
|
|
266
|
+
|
|
267
|
+
Create `app/components/TivaChatbotWidget.tsx`:
|
|
268
|
+
|
|
269
|
+
```tsx
|
|
270
|
+
"use client";
|
|
271
|
+
|
|
272
|
+
import dynamic from "next/dynamic";
|
|
273
|
+
import type { ComponentType } from "react";
|
|
274
|
+
|
|
275
|
+
type TivaChatProps = {
|
|
276
|
+
uiKey: string;
|
|
277
|
+
version?: string;
|
|
278
|
+
apiKey?: string;
|
|
279
|
+
baseUrl?: string;
|
|
280
|
+
configurations?: Record<string, unknown>;
|
|
281
|
+
};
|
|
282
|
+
|
|
283
|
+
const Chatbot = dynamic<TivaChatProps>(
|
|
284
|
+
() =>
|
|
285
|
+
import("@tivagent/tiva-chat").then(
|
|
286
|
+
(mod) => mod.Chatbot as ComponentType<TivaChatProps>,
|
|
287
|
+
),
|
|
288
|
+
{ ssr: false },
|
|
289
|
+
);
|
|
290
|
+
|
|
291
|
+
export default function TivaChatbotWidget() {
|
|
23
292
|
return (
|
|
24
293
|
<Chatbot
|
|
25
|
-
uiKey="YOUR_UI_KEY"
|
|
26
|
-
baseUrl=
|
|
27
|
-
|
|
294
|
+
uiKey={process.env.NEXT_PUBLIC_TIVA_UI_KEY ?? "YOUR_UI_KEY"}
|
|
295
|
+
baseUrl={
|
|
296
|
+
process.env.NEXT_PUBLIC_TIVA_BASE_URL ?? "https://api.example.com"
|
|
297
|
+
}
|
|
298
|
+
version="v1"
|
|
299
|
+
apiKey={process.env.NEXT_PUBLIC_TIVA_API_KEY}
|
|
28
300
|
configurations={{
|
|
29
301
|
theme: "system",
|
|
30
302
|
language: "system",
|
|
@@ -35,80 +307,84 @@ export default function App() {
|
|
|
35
307
|
}
|
|
36
308
|
```
|
|
37
309
|
|
|
38
|
-
|
|
310
|
+
### Step 4: Use widget on page
|
|
311
|
+
|
|
312
|
+
Update `app/page.tsx`:
|
|
39
313
|
|
|
40
314
|
```tsx
|
|
41
|
-
import "
|
|
315
|
+
import TivaChatbotWidget from "./components/TivaChatbotWidget";
|
|
42
316
|
|
|
43
|
-
export default function
|
|
317
|
+
export default function Home() {
|
|
44
318
|
return (
|
|
45
|
-
<
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
configurations='{"theme":"system","buttonPosition":"right"}'
|
|
50
|
-
/>
|
|
319
|
+
<main>
|
|
320
|
+
<h1>Tiva Chat + Next.js</h1>
|
|
321
|
+
<TivaChatbotWidget />
|
|
322
|
+
</main>
|
|
51
323
|
);
|
|
52
324
|
}
|
|
53
325
|
```
|
|
54
326
|
|
|
55
|
-
|
|
327
|
+
### Step 5: (Optional) add `.env.local`
|
|
56
328
|
|
|
57
|
-
```
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
|
63
|
-
<title>Tiva Chat Demo</title>
|
|
64
|
-
</head>
|
|
65
|
-
<body>
|
|
66
|
-
<tiva-chatbot
|
|
67
|
-
ui-key="YOUR_UI_KEY"
|
|
68
|
-
api-key="YOUR_API_KEY"
|
|
69
|
-
base-url="https://api.example.com/v1"
|
|
70
|
-
configurations='{"theme":"system"}'
|
|
71
|
-
></tiva-chatbot>
|
|
329
|
+
```bash
|
|
330
|
+
NEXT_PUBLIC_TIVA_UI_KEY=YOUR_UI_KEY
|
|
331
|
+
NEXT_PUBLIC_TIVA_BASE_URL=https://api.example.com
|
|
332
|
+
NEXT_PUBLIC_TIVA_API_KEY=YOUR_API_KEY
|
|
333
|
+
```
|
|
72
334
|
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
335
|
+
### Step 6: Run and test
|
|
336
|
+
|
|
337
|
+
```bash
|
|
338
|
+
npm run dev
|
|
76
339
|
```
|
|
77
340
|
|
|
78
|
-
|
|
341
|
+
Open `http://localhost:3000` and verify the same API calls and message flow.
|
|
79
342
|
|
|
80
|
-
|
|
81
|
-
| ---------------- | ----------------------- | -------- | ---------------------------------------------------- |
|
|
82
|
-
| `uiKey` | `string` | Yes | UI key used to fetch UI configuration. |
|
|
83
|
-
| `version` | `string` | No | API version (default backend behavior usually `v1`). |
|
|
84
|
-
| `apiKey` | `string` | No | API key sent with requests. |
|
|
85
|
-
| `baseUrl` | `string` | No | Backend base URL. |
|
|
86
|
-
| `configurations` | `PreferencesDefinition` | No | User preference overrides. |
|
|
343
|
+
## 5) Any Other Framework (Generic Web Component Path)
|
|
87
344
|
|
|
88
|
-
|
|
345
|
+
If your framework can render custom HTML elements, use this path.
|
|
89
346
|
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
| `version` | `string` | No | Same as `version`. |
|
|
94
|
-
| `api-key` | `string` | No | Same as `apiKey`. |
|
|
95
|
-
| `base-url` | `string` | No | Same as `baseUrl`. |
|
|
96
|
-
| `configurations` | `JSON string` | No | JSON form of `PreferencesDefinition`. |
|
|
347
|
+
### Step 1: Create your project
|
|
348
|
+
|
|
349
|
+
Use your framework CLI (Svelte, Nuxt, Astro, Angular, Solid, etc.).
|
|
97
350
|
|
|
98
|
-
|
|
351
|
+
### Step 2: Install package
|
|
352
|
+
|
|
353
|
+
```bash
|
|
354
|
+
npm install @tivagent/tiva-chat react react-dom
|
|
355
|
+
```
|
|
356
|
+
|
|
357
|
+
### Step 3: Load web component on client side
|
|
358
|
+
|
|
359
|
+
In your client entry file (or client-only lifecycle hook):
|
|
360
|
+
|
|
361
|
+
```ts
|
|
362
|
+
import "@tivagent/tiva-chat/dist/index.esm.js";
|
|
363
|
+
```
|
|
364
|
+
|
|
365
|
+
For SSR frameworks, make sure this import runs only in the browser.
|
|
366
|
+
|
|
367
|
+
### Step 4: Render the element
|
|
99
368
|
|
|
100
369
|
```html
|
|
101
370
|
<tiva-chatbot
|
|
102
371
|
ui-key="YOUR_UI_KEY"
|
|
372
|
+
base-url="https://api.example.com"
|
|
373
|
+
version="v1"
|
|
103
374
|
api-key="YOUR_API_KEY"
|
|
104
|
-
|
|
105
|
-
configurations='{"theme":"dark","language":"en","buttonPosition":"left"}'
|
|
375
|
+
configurations='{"theme":"system","language":"system","buttonPosition":"right"}'
|
|
106
376
|
></tiva-chatbot>
|
|
107
377
|
```
|
|
108
378
|
|
|
379
|
+
### Step 5: Run and test
|
|
380
|
+
|
|
381
|
+
- Run your framework dev server.
|
|
382
|
+
- Confirm the widget renders.
|
|
383
|
+
- Confirm `/v1/get_ui_config` and `/v1/messages` are called successfully.
|
|
384
|
+
|
|
109
385
|
## Backend API Requirements
|
|
110
386
|
|
|
111
|
-
The widget expects
|
|
387
|
+
The widget expects backend endpoints:
|
|
112
388
|
|
|
113
389
|
- `POST /messages` (SSE stream)
|
|
114
390
|
- `POST /get_session`
|
|
@@ -118,22 +394,23 @@ The widget expects specific backend endpoints, including:
|
|
|
118
394
|
- `POST /reports`
|
|
119
395
|
- `GET /get_ui_config`
|
|
120
396
|
|
|
121
|
-
Full contract: `CHATBOT_API.md` in
|
|
397
|
+
Full contract: `CHATBOT_API.md` in `https://github.com/tivagent/tiva-chatbot`.
|
|
122
398
|
|
|
123
399
|
## Styling and Shadow DOM
|
|
124
400
|
|
|
125
|
-
`<tiva-chatbot>` uses open Shadow DOM and injects its own styles
|
|
401
|
+
- `<tiva-chatbot>` uses open Shadow DOM and injects its own styles.
|
|
402
|
+
- React `Chatbot` injects required global style once at runtime.
|
|
126
403
|
|
|
127
404
|
## Build Outputs
|
|
128
405
|
|
|
129
|
-
|
|
406
|
+
`dist/` includes:
|
|
130
407
|
|
|
131
408
|
- `index.esm.js`
|
|
132
409
|
- `index.cjs.js`
|
|
133
410
|
- `index.umd.js`
|
|
134
411
|
- `index.d.ts`
|
|
135
412
|
|
|
136
|
-
## Local Development
|
|
413
|
+
## Local Development (for this package repo)
|
|
137
414
|
|
|
138
415
|
```bash
|
|
139
416
|
npm install
|
|
@@ -148,9 +425,9 @@ Useful commands:
|
|
|
148
425
|
|
|
149
426
|
## Publishing
|
|
150
427
|
|
|
151
|
-
|
|
428
|
+
Release and publish workflow: `PUBLISHING.md` in `https://github.com/tivagent/tiva-chatbot`.
|
|
152
429
|
|
|
153
430
|
## Additional Notes
|
|
154
431
|
|
|
155
|
-
- Consumer
|
|
156
|
-
- Contributor
|
|
432
|
+
- Consumer integration guidance is in this README.
|
|
433
|
+
- Contributor workflow notes are in `INSTRUCTIONS.md` in `https://github.com/tivagent/tiva-chatbot`.
|
|
@@ -2,9 +2,9 @@ import { FC } from 'react';
|
|
|
2
2
|
import { PreferencesDefinition } from '../types/ChatbotConfig';
|
|
3
3
|
export interface ChatbotProps {
|
|
4
4
|
uiKey: string;
|
|
5
|
-
version?: string;
|
|
6
5
|
apiKey?: string;
|
|
7
6
|
baseUrl?: string;
|
|
7
|
+
version?: string;
|
|
8
8
|
configurations?: PreferencesDefinition;
|
|
9
9
|
}
|
|
10
10
|
declare const Chatbot: FC<ChatbotProps>;
|