@dsrcjs/ai-widget 0.0.0-stage → 1.0.5
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/LICENSE +64 -0
- package/README.md +296 -2
- package/dist/ai-dana-chat.js +76 -0
- package/dist/avatar/model.d.ts +12 -0
- package/dist/drag.d.ts +44 -0
- package/dist/echarts-B6eiFnZN.js +18 -0
- package/dist/i18n.d.ts +287 -0
- package/dist/index-D2Riqtpn.js +19 -0
- package/dist/index.d.ts +57 -0
- package/dist/index.js +1 -0
- package/dist/markdown-impl-Cu_bBFxI.js +34 -0
- package/dist/stream-entry-CNdFWIwY.js +8 -0
- package/dist/theme.d.ts +82 -0
- package/package.json +36 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
ЧЕРНОВИК. Текст лицензии не проверен юристом и не является окончательным;
|
|
2
|
+
до проверки не публикуйте пакет и не ссылайтесь на эти условия в договорах.
|
|
3
|
+
|
|
4
|
+
DRAFT — this licence has not been reviewed by a lawyer and is not final; do not
|
|
5
|
+
publish the package or rely on these terms until it has been reviewed.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
AI-Dana Widget Licence (draft)
|
|
10
|
+
|
|
11
|
+
Copyright (c) 2026 DSRC. All rights reserved.
|
|
12
|
+
|
|
13
|
+
"Software" means the compiled files distributed in this package (the `dist/`
|
|
14
|
+
directory) and this file.
|
|
15
|
+
|
|
16
|
+
1. Permission granted
|
|
17
|
+
|
|
18
|
+
You may, free of charge, download the Software, embed it in any website or
|
|
19
|
+
web application you control, and use it there for any purpose, including
|
|
20
|
+
commercial use. You may serve a verbatim copy of the Software from your own
|
|
21
|
+
servers or from a public CDN as part of that use.
|
|
22
|
+
|
|
23
|
+
2. Restrictions
|
|
24
|
+
|
|
25
|
+
You may not:
|
|
26
|
+
|
|
27
|
+
a. modify, adapt or translate the Software, or create derivative works from
|
|
28
|
+
it;
|
|
29
|
+
b. decompile, disassemble or otherwise reverse-engineer the Software, or
|
|
30
|
+
attempt to reconstruct its source code, except to the extent this
|
|
31
|
+
restriction is void under applicable law;
|
|
32
|
+
c. distribute a modified copy of the Software, under this or any other name;
|
|
33
|
+
d. extract, reuse or incorporate any part of the Software into another
|
|
34
|
+
product, library or package;
|
|
35
|
+
e. remove or alter this licence, the copyright notice, or any attribution in
|
|
36
|
+
the Software;
|
|
37
|
+
f. sublicense, sell or rent the Software on its own, apart from a website or
|
|
38
|
+
application that uses it.
|
|
39
|
+
|
|
40
|
+
Configuring the Software through its documented public interface — options,
|
|
41
|
+
HTML attributes, CSS custom properties and `::part()` selectors — is use, not
|
|
42
|
+
modification.
|
|
43
|
+
|
|
44
|
+
3. Service
|
|
45
|
+
|
|
46
|
+
The Software talks to the AI-Dana API, which is a separate service under its
|
|
47
|
+
own terms, quotas and availability. Nothing here grants a right to that
|
|
48
|
+
service. Access to the API may be limited, suspended or withdrawn at any
|
|
49
|
+
time, for any user or for any site, without notice and without affecting this
|
|
50
|
+
licence.
|
|
51
|
+
|
|
52
|
+
4. No warranty
|
|
53
|
+
|
|
54
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
55
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
56
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
57
|
+
COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
|
|
58
|
+
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
|
|
59
|
+
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
|
60
|
+
|
|
61
|
+
5. Termination
|
|
62
|
+
|
|
63
|
+
This licence ends automatically if you breach any of its terms. On
|
|
64
|
+
termination you must stop using the Software and remove it from your sites.
|
package/README.md
CHANGED
|
@@ -1,3 +1,297 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @dsrcjs/ai-widget
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The AI-Dana chat as an embeddable widget for other sites: a launcher button (draggable) and a chat window that slides in from the right (60% of the page, dimming the rest) over
|
|
4
|
+
the page. One self-contained file, React and styles inside, rendered in a Shadow DOM so the page's CSS does not leak in
|
|
5
|
+
and the widget's CSS does not leak out.
|
|
6
|
+
|
|
7
|
+
Features: streaming answers with markdown, agent steps, stop, 1–5 rating and feedback, branches/regenerate, the
|
|
8
|
+
visitor's chat history, mode picker, attachments (when the site allows files), kk/ru/en, light/dark/auto, a daily
|
|
9
|
+
limit banner, mobile fullscreen.
|
|
10
|
+
|
|
11
|
+
## Install
|
|
12
|
+
|
|
13
|
+
The package is on the public npm registry as [`@dsrcjs/ai-widget`](https://www.npmjs.com/package/@dsrcjs/ai-widget):
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
npm i @dsrcjs/ai-widget
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
It ships only the built files; the source is not public. See [LICENSE](LICENSE): embedding and using it is free,
|
|
20
|
+
modifying, reverse-engineering and redistributing it are not.
|
|
21
|
+
|
|
22
|
+
### `<script>` tag
|
|
23
|
+
|
|
24
|
+
One tag, no build step. AI-Dana serves the widget itself, and this address always carries the current release — it
|
|
25
|
+
reaches your page within minutes of a release, nothing to bump on your side:
|
|
26
|
+
|
|
27
|
+
```html
|
|
28
|
+
<script src="https://ai-dana.example.kz/widget/ai-dana-chat.js" defer></script>
|
|
29
|
+
<ai-dana-chat api-url="https://ai-dana.example.kz" launcher></ai-dana-chat>
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Want to pin a version instead? The same file by exact version never changes and is cached forever:
|
|
33
|
+
|
|
34
|
+
```html
|
|
35
|
+
<script src="https://ai-dana.example.kz/widget/v/1.2.3/ai-dana-chat.js" defer></script>
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
Do not put `integrity="…"` (SRI) on the rolling address: the hash is tied to the bytes of one release, and the next
|
|
39
|
+
one would stop your page loading the widget. Pin a version if you need SRI.
|
|
40
|
+
|
|
41
|
+
The package is also on npm, and jsDelivr mirrors it (`@1` = the current major, updated within a day or so):
|
|
42
|
+
`https://cdn.jsdelivr.net/npm/@dsrcjs/ai-widget@1/dist/ai-dana-chat.js`.
|
|
43
|
+
|
|
44
|
+
`api-url` is required on any page that is not the backend itself: the published bundle has no backend address
|
|
45
|
+
baked in, and without the attribute the widget calls the page's own origin. No key: the backend answers such a
|
|
46
|
+
visitor as the **anonymous tier** (the shared daily budget,
|
|
47
|
+
the default modes and theme, `Access-Control-Allow-Origin: *`, so any site may embed it). A site that asked for its
|
|
48
|
+
own branding, origins and higher limits gets a key and adds `site-key="…"` (see [Site key](#site-key)) from the ready snippet
|
|
49
|
+
AI-Dana gives with the key.
|
|
50
|
+
|
|
51
|
+
| Attribute | Meaning |
|
|
52
|
+
| ------------------- | ----------------------------------------------------------------------------------------------------- |
|
|
53
|
+
| `site-key` | Public key of the widget site; without it the anonymous tier |
|
|
54
|
+
| `api-url` | Backend origin (required on other sites); absent or `""` = the page's own origin |
|
|
55
|
+
| `launcher` | Launcher button + floating window. Without it only the window is rendered (size the element yourself) |
|
|
56
|
+
| `lang` | `kk` \| `ru` \| `en` (observed) |
|
|
57
|
+
| `theme` | `light` \| `dark` \| `auto` (observed) |
|
|
58
|
+
| `position` | `bottom-right` (default) \| `bottom-left` |
|
|
59
|
+
| `draggable="false"` | Pin the launcher |
|
|
60
|
+
| `open` | Open on load |
|
|
61
|
+
|
|
62
|
+
The element has `open()`, `close()`, `setTheme(theme)` and `setLang(lang)` and fires `openchange`
|
|
63
|
+
(`event.detail.open`). The script also exposes the global `AiDanaChat` with `mountLauncher` and `mount`.
|
|
64
|
+
|
|
65
|
+
### npm / ESM
|
|
66
|
+
|
|
67
|
+
```ts
|
|
68
|
+
import { mountLauncher, mount } from '@dsrcjs/ai-widget';
|
|
69
|
+
|
|
70
|
+
// Everything is optional; a key only for sites that have one
|
|
71
|
+
const chat = mountLauncher({ lang: 'ru' });
|
|
72
|
+
chat.setTheme({ primary: '#0a7d4f' });
|
|
73
|
+
|
|
74
|
+
// Or the window alone, inside your own container (you size it and decide when to show it)
|
|
75
|
+
const inline = mount(document.getElementById('chat')!, { siteKey: 'YOUR_SITE_KEY' });
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
`mountLauncher(options)` appends its host to `document.body`; `mountLauncher(container, options)` renders into
|
|
79
|
+
`container`. The ES build lazy-loads the markdown renderer as a separate chunk; the IIFE includes everything.
|
|
80
|
+
|
|
81
|
+
### Options
|
|
82
|
+
|
|
83
|
+
| Option | Type | Default | Notes |
|
|
84
|
+
| -------------- | --------------------------------- | ---------------------------------------- | -------------------------------------------------------------------------- |
|
|
85
|
+
| `siteKey` | `string` | — (anonymous tier) | Only for sites that were given a key |
|
|
86
|
+
| `apiUrl` | `string` | `''` (no address in the published build) | Backend origin; calls go to `{apiUrl}/api/v1/widget/…`; `''` = same origin |
|
|
87
|
+
| `lang` | `'kk' \| 'ru' \| 'en'` | `<html lang>` → browser language → `ru` | |
|
|
88
|
+
| `theme` | `ThemeOptions` | `{}` | Layer 2, see [Theming](#theming) |
|
|
89
|
+
| `position` | `'bottom-right' \| 'bottom-left'` | `'bottom-right'` | Launcher corner |
|
|
90
|
+
| `draggable` | `boolean` | `true` | Never draggable below 640px |
|
|
91
|
+
| `defaultOpen` | `boolean` | `false` (`true` for `mount`) | |
|
|
92
|
+
| `onOpenChange` | `(open: boolean) => void` | — | |
|
|
93
|
+
| `visitorId` | `string` (UUID) | kept in `localStorage.aid_visitor` | Pass your own id to keep a visitor's history across devices |
|
|
94
|
+
|
|
95
|
+
### Handle
|
|
96
|
+
|
|
97
|
+
```ts
|
|
98
|
+
interface Handle {
|
|
99
|
+
open(): void;
|
|
100
|
+
close(): void;
|
|
101
|
+
unmount(): void; // removes the React root, the shadow content and (for mountLauncher without container) the host
|
|
102
|
+
setTheme(theme: ThemeOptions): void; // merges into layer 2; `{ primary: undefined }` drops a key
|
|
103
|
+
setLang(lang: 'kk' | 'ru' | 'en'): void;
|
|
104
|
+
}
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
## Public contract
|
|
108
|
+
|
|
109
|
+
These are the things other sites depend on, so they change **only in a major version** (see
|
|
110
|
+
[Versioning](#versioning)):
|
|
111
|
+
|
|
112
|
+
| What | Where |
|
|
113
|
+
| -------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
|
|
114
|
+
| `mount(container, options)`, `mountLauncher([container,] options)`, the `Handle` they return | [npm / ESM](#npm--esm), [Options](#options), [Handle](#handle) |
|
|
115
|
+
| `<ai-dana-chat>` and its attributes, methods and `openchange` event | [`<script>` tag](#script-tag) |
|
|
116
|
+
| The global `AiDanaChat` of the IIFE build (`mount`, `mountLauncher`) | [`<script>` tag](#script-tag) |
|
|
117
|
+
| The `--aid-*` CSS variables | [`--aid-*` variables](#aid--variables) |
|
|
118
|
+
| The `::part()` names | [Parts](#parts) |
|
|
119
|
+
| The `localStorage` keys | [Storage](#storage) |
|
|
120
|
+
|
|
121
|
+
Everything else — the DOM inside the shadow root, class names, the structure of the React tree, the names of the
|
|
122
|
+
internal modules and the chunk layout of the ES build — is private and may change in any release. A `::part()` that
|
|
123
|
+
is not in the table does not exist; style only the parts listed there.
|
|
124
|
+
|
|
125
|
+
A removal or a rename of anything in the table is a major release; a new option, attribute, variable or part is a
|
|
126
|
+
minor one.
|
|
127
|
+
|
|
128
|
+
## Theming
|
|
129
|
+
|
|
130
|
+
Four layers, the higher one wins: **site CSS variables > JS `theme` > admin theme > kit defaults**. `::part()` rules
|
|
131
|
+
are plain CSS on top of all of them.
|
|
132
|
+
|
|
133
|
+
```ts
|
|
134
|
+
interface ThemeOptions {
|
|
135
|
+
primary?: string; // hex, rgb(), hsl() or a basic name; hover/pressed/foreground (WCAG contrast) are derived
|
|
136
|
+
radius?: string | number; // a number means px
|
|
137
|
+
font?: string; // font-family; the widget uses a system stack by default (no web font is embedded)
|
|
138
|
+
scheme?: 'light' | 'dark' | 'auto';
|
|
139
|
+
logoUrl?: string;
|
|
140
|
+
title?: string;
|
|
141
|
+
launcher?: 'icon' | 'label'; // icon only (default) or icon + launcherLabel
|
|
142
|
+
launcherLabel?: string; // default: «Задать вопрос» in the visitor's language
|
|
143
|
+
launcherShape?: 'circle' | 'rounded' | 'square'; // launcher corners, default circle
|
|
144
|
+
background?: string; // window colours; unset ones follow the kit and the scheme
|
|
145
|
+
foreground?: string;
|
|
146
|
+
bubble?: string; // assistant bubble and muted surfaces
|
|
147
|
+
border?: string;
|
|
148
|
+
windowWidth?: number; // px; site CSS --aid-window-width / --aid-offset-x still wins
|
|
149
|
+
windowHeight?: number;
|
|
150
|
+
position?: 'bottom-right' | 'bottom-left'; // the JS `position` option wins over this
|
|
151
|
+
offsetX?: number;
|
|
152
|
+
offsetY?: number;
|
|
153
|
+
}
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
Dana is one drawn character with no colour options; `logoUrl` replaces her in the header only. Her pictures are
|
|
157
|
+
fetched from the backend (`<apiUrl>/static/avatars/dana/`). Site CSS can still style the box around her through
|
|
158
|
+
`::part(avatar)`.
|
|
159
|
+
|
|
160
|
+
1. **Admin** — the «Оформление» and «Кнопка запуска» sections of the widget site (colour picker, choices, live
|
|
161
|
+
preview); they are stored as `theme` JSON with the same keys, keys the form does not know are kept:
|
|
162
|
+
`{"primary": "#7b1fa2", "radius": 12, "scheme": "dark", "title": "Shop assistant", "logoUrl": "https://…/logo.svg"}`.
|
|
163
|
+
`welcome` (`{"ru": "…", "kk": "…", "en": "…"}`) is the greeting in an empty chat. Both arrive with `GET config`.
|
|
164
|
+
2. **JS** — `theme` option or `handle.setTheme({ primary: '#0a7d4f', radius: 16 })`.
|
|
165
|
+
3. **CSS variables** — on the host element, inherited into the shadow root. Any CSS colour format works.
|
|
166
|
+
|
|
167
|
+
```css
|
|
168
|
+
ai-dana-chat {
|
|
169
|
+
--aid-primary: #c2185b;
|
|
170
|
+
--aid-radius: 4px;
|
|
171
|
+
--aid-font: Georgia, serif;
|
|
172
|
+
}
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
For `mountLauncher()` without a container the host is `div[data-ai-dana-chat]`.
|
|
176
|
+
|
|
177
|
+
4. **`::part()`**
|
|
178
|
+
|
|
179
|
+
```css
|
|
180
|
+
ai-dana-chat::part(launcher) {
|
|
181
|
+
box-shadow: 0 0 0 4px gold;
|
|
182
|
+
}
|
|
183
|
+
ai-dana-chat::part(header) {
|
|
184
|
+
background: #fde68a;
|
|
185
|
+
color: #111;
|
|
186
|
+
}
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
### `--aid-*` variables
|
|
190
|
+
|
|
191
|
+
| Variable | Default | Meaning |
|
|
192
|
+
| ------------------------------------------------ | -------------------- | ----------------------------------------------------------------------------------------- |
|
|
193
|
+
| `--aid-primary` | kit primary | Accent: launcher, user bubble, send button |
|
|
194
|
+
| `--aid-primary-foreground` | derived from primary | Text on primary |
|
|
195
|
+
| `--aid-primary-hovered`, `--aid-primary-pressed` | derived from primary | Button states, launcher hover |
|
|
196
|
+
| `--aid-secondary`, `--aid-ring` | primary at 10% / 50% | Soft backgrounds; focus ring (a 3px outline with a 3px offset on the launcher) |
|
|
197
|
+
| `--aid-background`, `--aid-foreground` | kit, per scheme | Window background and text |
|
|
198
|
+
| `--aid-muted`, `--aid-border` | kit, per scheme | Muted surfaces, borders |
|
|
199
|
+
| `--aid-radius` | kit radius (12px) | Corner radius; the window card is 6px rounder, the settings panel 4px |
|
|
200
|
+
| `--aid-font` | system stack | `font-family` |
|
|
201
|
+
| `--aid-z-index` | `2147483000` | Launcher, overlay and window |
|
|
202
|
+
| `--aid-offset-x`, `--aid-offset-y` | `20px` | Launcher distance from its corner |
|
|
203
|
+
| `--aid-window-width` | `60vw` | Width of the window card on desktop: at least 720px, never wider than the page minus 48px |
|
|
204
|
+
| `--aid-overlay` | `rgb(2 6 23 / 0.35)` | Dimming of the page behind the window |
|
|
205
|
+
|
|
206
|
+
The colours of errors, warnings, success, mode states and secondary text are **not** variables: they come from the kit
|
|
207
|
+
and the widget, and stay readable only on a window background that suits the colour scheme.
|
|
208
|
+
|
|
209
|
+
Colour variables set on the host apply to both light and dark schemes; scope them yourself
|
|
210
|
+
(`@media (prefers-color-scheme: dark)`) if they should differ.
|
|
211
|
+
|
|
212
|
+
### Parts
|
|
213
|
+
|
|
214
|
+
`launcher`, `launcher-label`, `badge`, `overlay`, `window`, `sidebar` (with `data-state`), `header`, `logo`, `title`,
|
|
215
|
+
`new-chat`, `search`, `history`, `thread-item`, `settings-button`, `settings`, `toolbar`, `expand`, `close`,
|
|
216
|
+
`mode-select`, `mode-list`, `mode-option`, `messages`, `scroll-down`, `empty`, `avatar`, `welcome`, `example`,
|
|
217
|
+
`message` (with `data-role`), `bubble`, `user-bubble`, `assistant-bubble`, `error-bubble`, `markdown`, `steps`,
|
|
218
|
+
`actions`, `copy`, `regenerate`, `rating`, `feedback`, `branch`, `edit`, `edit-button`, `attachment`, `composer`,
|
|
219
|
+
`composer-file`, `attach`, `input`, `send`, `stop`, `counter`, `source`, `intro`, `answer-blocks`, `clarification`, `data-table`, `disclaimer`,
|
|
220
|
+
`limit-banner` (with `data-state` `low`, `blocked`, `overloaded`), `notice`, `category` (a category card of the empty chat, «What can be done»), `dashboard-preview`
|
|
221
|
+
(the compact chart under an answer), `dashboard-toggle` («Dashboard» / «Hide dashboard» under an answer), `files`
|
|
222
|
+
(the export files of an answer), `report` (the report block: «Generate report» button and its files), `dashboard`
|
|
223
|
+
(the panel, with `data-fullscreen`), `dashboard-tabs` («Chat / Dashboard» in the toolbar of a window narrower than
|
|
224
|
+
1280px).
|
|
225
|
+
|
|
226
|
+
Parts that came with the chat redesign, and parts that were always there but were not listed. The «Parts» above and
|
|
227
|
+
these are one list: the widget is tested to draw every part named here and to name every part it draws.
|
|
228
|
+
|
|
229
|
+
- `plan` (the chips «What was counted» over an answer), `catalog` (the catalog card), `answer-actions` (the row of
|
|
230
|
+
block actions under an answer), `data-toggle` («Data» in it), `methodology` (the «Methodology» link),
|
|
231
|
+
`section-chart` (the chart of a dashboard section and the compact one under an answer).
|
|
232
|
+
|
|
233
|
+
- `history-toggle` (the «History» button of the window row while the panel is hidden; the hidden panel stays as an empty `sidebar` with `data-state="collapsed"`, and `settings-button` now sits in the window row).
|
|
234
|
+
|
|
235
|
+
- `mode-health` (the state of a mode in words with a dot — «Free», «Busy», «Unavailable»; `data-level` `idle`, `busy`, `unavailable`; in the mode button and in its list).
|
|
236
|
+
|
|
237
|
+
- `composer-hint` (the line over the field when the chosen mode is unavailable or there are no modes).
|
|
238
|
+
|
|
239
|
+
- `file-type` (the coloured tile with a file's type: the selected file, a file under a question, the files of a report; `data-kind` `pdf`, `doc`, `ppt`, `xls`, `csv`, `other`).
|
|
240
|
+
|
|
241
|
+
- `feedback-saved` (the saved reason and text of a feedback under an answer).
|
|
242
|
+
|
|
243
|
+
## Storage
|
|
244
|
+
|
|
245
|
+
| `localStorage` key | Value |
|
|
246
|
+
| ------------------ | ----------------------------------------------------- |
|
|
247
|
+
| `aid_visitor` | Anonymous visitor UUID (unless `visitorId` is passed) |
|
|
248
|
+
| `aid_pos` | Dragged launcher offset `{x, y}` from its corner |
|
|
249
|
+
| `aid_mode` | Last selected mode slug |
|
|
250
|
+
| `aid_prefs` | Visitor's settings `{lang, scheme}` |
|
|
251
|
+
| `aid_sidebar` | `collapsed` / `expanded` |
|
|
252
|
+
| `aid_intro_ack` | `1` once the intro notice was acknowledged |
|
|
253
|
+
|
|
254
|
+
No cookies are used. With blocked storage (sandboxed iframe, strict private mode) the widget works with a per-load
|
|
255
|
+
visitor and forgets the position.
|
|
256
|
+
|
|
257
|
+
## Size
|
|
258
|
+
|
|
259
|
+
`dist/ai-dana-chat.js` (IIFE): about 360 KB gzip with React, markdown, charts and styles.
|
|
260
|
+
|
|
261
|
+
## Site key
|
|
262
|
+
|
|
263
|
+
AI-Dana issues the key together with the site's allowed origins (exact origins, e.g. `https://shop.kz`; no `*`, no
|
|
264
|
+
paths), modes, limits, files and theme, and gives you the ready snippet with it.
|
|
265
|
+
|
|
266
|
+
## Limits and CORS
|
|
267
|
+
|
|
268
|
+
- Every request carries `X-Visitor-Id`, and `X-Widget-Key` only when the site has a key. Without a key the request
|
|
269
|
+
is served as the anonymous tier and CORS answers `Access-Control-Allow-Origin: *`, so the widget works on any site.
|
|
270
|
+
- With a key the browser's `Origin` must be in the site's `allowed_origins` exactly (scheme, host and port). A wrong
|
|
271
|
+
origin or key gets no CORS headers, so in the browser it looks like a network error: check the origin first.
|
|
272
|
+
- `503`: the shared daily budget for anonymous messages is spent. The widget locks the input and says «the service is
|
|
273
|
+
overloaded, try later» in the limit banner (`::part(limit-banner)` with `data-state="overloaded"`) instead of a bare
|
|
274
|
+
error code; sites with a key are not affected.
|
|
275
|
+
- No cookies and no `Access-Control-Allow-Credentials`; the widget never sees the main site's session.
|
|
276
|
+
- `daily_messages_per_visitor` (per site and visitor) and `rate_per_minute` are enforced by the backend. The widget
|
|
277
|
+
shows the remaining count when it runs low, disables the input at zero and shows the reset time on `429`.
|
|
278
|
+
- The question length limit comes from `max_query_chars` in `GET config`.
|
|
279
|
+
- Files: only when both the site (`allow_files`) and the mode allow them; the mode's `max_file_mb` applies.
|
|
280
|
+
- Links from answers open in a new tab with `noopener`; only `http(s)` links are clickable. Images are loaded only
|
|
281
|
+
from the AI-Dana attachments API (with the widget headers), never from arbitrary URLs.
|
|
282
|
+
|
|
283
|
+
## Versioning
|
|
284
|
+
|
|
285
|
+
[SemVer](https://semver.org/). The major version changes only when something in
|
|
286
|
+
[Public contract](#public-contract) is removed or renamed; a new option, attribute, variable or part is a minor one;
|
|
287
|
+
everything else is a patch. What changed is in [CHANGELOG.md](CHANGELOG.md) (Keep a Changelog); each release moves the
|
|
288
|
+
`Unreleased` entries into a version heading.
|
|
289
|
+
|
|
290
|
+
## Known limitations
|
|
291
|
+
|
|
292
|
+
- The focus trap is on whenever the window is open, also on desktop where the window is not modal: Tab does not
|
|
293
|
+
leave the widget until it is closed (Esc).
|
|
294
|
+
- On mobile the fullscreen window does not lock the page scroll behind it.
|
|
295
|
+
- Fonts are not embedded: `--aid-font`/`font` must name a font the page has already loaded.
|
|
296
|
+
- No unread badge yet (the `badge` part exists but nothing feeds it).
|
|
297
|
+
- The custom element observes only `lang` and `theme`; other attributes are read on connect.
|