@kivox/widget 0.1.0-beta.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 (4) hide show
  1. package/README.md +166 -0
  2. package/dist/index.d.ts +1 -0
  3. package/dist/index.js +1 -0
  4. package/package.json +47 -0
package/README.md ADDED
@@ -0,0 +1,166 @@
1
+ # KIVOX Widget
2
+
3
+ `@kivox/widget` is the official embeddable web widget for interacting with KIVOX. It provides a ready-to-use chat and voice interface that can be embedded into any website or web application with minimal setup. The widget is built on top of the Kivox client and handles UI, audio I/O, session lifecycle, and real-time events automatically.
4
+
5
+ Features
6
+
7
+ - Embeddable custom element (`<kivox-widget>`)
8
+ - Chat and voice conversation modes
9
+ - Real-time streaming responses and events
10
+ - Built-in audio recording and playback
11
+ - Session lifecycle management
12
+ - Themeable UI (light/dark, future custom themes)
13
+ - Framework-agnostic (works in any site or SPA)
14
+
15
+ ## Documentation
16
+
17
+ <https://kivox.ju4n97.workers.dev/docs/clients/kivox-widget>
18
+
19
+ ## Installation
20
+
21
+ ```bash
22
+ # NPM
23
+ npm install @kivox/widget
24
+
25
+ # PNPM
26
+ pnpm add @kivox/widget
27
+
28
+ # Yarn
29
+ yarn add @kivox/widget
30
+
31
+ # Bun
32
+ bun add @kivox/widget
33
+ ```
34
+
35
+ ## Installation (CDN)
36
+
37
+ The widget can also be loaded directly from a CDN without a build step. This is the easiest way to embed Kivox into static sites or server-rendered pages.
38
+
39
+ ```html
40
+ <script type="module">
41
+ import 'https://cdn.jsdelivr.net/npm/@kivox/widget/dist/index.js';
42
+ </script>
43
+ ```
44
+
45
+ Or with a pinned version (recommended for production):
46
+
47
+ ```html
48
+ <script type="module">
49
+ import 'https://cdn.jsdelivr.net/npm/@kivox/widget@0.1.0/dist/index.js';
50
+ </script>
51
+ ```
52
+
53
+ Then use the custom element:
54
+
55
+ ```html
56
+ <kivox-widget
57
+ agent-id="019bb51e-e45f-75e3-b828-94fdf231711e"
58
+ base-url="http://localhost:8787"
59
+ mode="chat"
60
+ theme="light">
61
+ </kivox-widget>
62
+ ```
63
+
64
+ ## Basic example (HTML)
65
+
66
+ ```ts
67
+ <!DOCTYPE html>
68
+ <html lang="en">
69
+ <head>
70
+ <meta charset="utf-8" />
71
+ <title>Kivox Widget</title>
72
+ <script type="module">
73
+ import '@kivox/widget';
74
+ </script>
75
+ </head>
76
+ <body>
77
+ <kivox-widget
78
+ agent-id="019bb51e-e45f-75e3-b828-94fdf231711e"
79
+ base-url="http://localhost:8787"
80
+ mode="chat"
81
+ theme="light">
82
+ </kivox-widget>
83
+ </body>
84
+ </html>
85
+ ```
86
+
87
+ ## Basic example (JavaScript)
88
+
89
+ ```ts
90
+ import "@kivox/widget";
91
+
92
+ const widget = document.createElement("kivox-widget");
93
+
94
+ widget.agentId = "019bb51e-e45f-75e3-b828-94fdf231711e";
95
+ widget.baseUrl = "http://localhost:8787";
96
+ widget.mode = "voice";
97
+ widget.theme = "dark";
98
+
99
+ document.body.appendChild(widget);
100
+ ```
101
+
102
+ ## Authentication
103
+
104
+ ```ts
105
+ import "@kivox/widget";
106
+
107
+ const widget = document.createElement("kivox-widget");
108
+
109
+ widget.agentId = "019bb51e-e45f-75e3-b828-94fdf231711e";
110
+ widget.baseUrl = "http://localhost:8787";
111
+ widget.headers = {
112
+ Authorization: "Bearer token",
113
+ };
114
+
115
+ document.body.appendChild(widget);
116
+ ```
117
+
118
+ ## Attributes
119
+
120
+ | Name | Type | Description |
121
+ | ---------- | ------------------------ | ----------------------------- |
122
+ | `agent-id` | `string` | ID of the agent to connect to |
123
+ | `base-url` | `string` | Base URL of the Kivox API |
124
+ | `mode` | `"chat" \| "voice"` | Conversation mode |
125
+ | `theme` | `"light" \| "dark"` | Widget theme |
126
+ | `headers` | `Record<string, string>` | Additional HTTP headers |
127
+
128
+ ## Events
129
+
130
+ The widget emits DOM events for integration and observability.
131
+
132
+ ```ts
133
+ widget.addEventListener('kivox:ready', () => {
134
+ console.log('Widget ready');
135
+ });
136
+
137
+ widget.addEventListener('kivox:message', (e: any) => {
138
+ console.log('Message event:', e.detail);
139
+ });
140
+
141
+ widget.addEventListener('kivox:error', (e: any) => {
142
+ console.error('Widget error:', e.detail);
143
+ });
144
+ ```
145
+
146
+ ## Relationship to the Kivox Client
147
+
148
+ The widget is built on top of the official Kivox client:
149
+
150
+ - `@kivox/client` handles protocol, sessions, events, and audio primitives
151
+ - `@kivox/widget` adds UI, theming, and interaction layers
152
+
153
+ If you need full control over UX, state, or rendering, use the client directly instead of the widget.
154
+
155
+ ## Other examples
156
+
157
+ - [widget-chat-demo](https://github.com/ekisa-team/kivox/tree/main/examples/widget-chat-demo)
158
+ - [widget-voice-demo](https://github.com/ekisa-team/kivox/tree/main/examples/widget-voice-demo)
159
+
160
+ ## Contributing
161
+
162
+ [https://github.com/ekisa-team/kivox/blob/main/CONTRIBUTING.md](https://github.com/ekisa-team/kivox/blob/main/CONTRIBUTING.md)
163
+
164
+ ## License
165
+
166
+ [LICENSE](https://github.com/ekisa-team/kivox/blob/main/LICENSE)
package/dist/index.d.ts ADDED
@@ -0,0 +1 @@
1
+ export { src_default as default };
package/dist/index.js ADDED
@@ -0,0 +1 @@
1
+ console.log("Hello from KIVOX widget!");
package/package.json ADDED
@@ -0,0 +1,47 @@
1
+ {
2
+ "name": "@kivox/widget",
3
+ "version": "0.1.0-beta.1",
4
+ "description": "JavaScript/TypeScript client for KIVOX",
5
+ "homepage": "https://github.com/ekisa-team/kivox#readme",
6
+ "bugs": {
7
+ "url": "https://github.com/ekisa-team/kivox/issues"
8
+ },
9
+ "repository": {
10
+ "type": "git",
11
+ "url": "git+https://github.com/ekisa-team/kivox.git"
12
+ },
13
+ "author": {
14
+ "name": "Juan Mesa",
15
+ "email": "ju4n97@proton.me",
16
+ "url": "https://github.com/ju4n97"
17
+ },
18
+ "sideEffects": false,
19
+ "type": "module",
20
+ "exports": {
21
+ ".": {
22
+ "types": "./dist/index.d.ts",
23
+ "development": "./src/index.ts",
24
+ "import": "./dist/index.js"
25
+ }
26
+ },
27
+ "main": "./dist/index.js",
28
+ "module": "./dist/index.js",
29
+ "types": "./dist/index.d.ts",
30
+ "files": [
31
+ "dist",
32
+ "README.md"
33
+ ],
34
+ "scripts": {
35
+ "build": "bun run build.ts",
36
+ "test": "bun test",
37
+ "test:watch": "bun test --watch"
38
+ },
39
+ "devDependencies": {
40
+ "@types/bun": "latest",
41
+ "bun-dts": "^0.1.70",
42
+ "typescript": "5.9.3"
43
+ },
44
+ "publishConfig": {
45
+ "access": "public"
46
+ }
47
+ }