@convai/web-widget 0.1.1-beta.1 → 0.1.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 (3) hide show
  1. package/README.md +74 -27
  2. package/package.json +3 -3
  3. package/runtime.js +1792 -1773
package/README.md CHANGED
@@ -2,29 +2,50 @@
2
2
 
3
3
  Add a Convai character to any website with one custom element and one script tag.
4
4
 
5
+ ## Quickstart
6
+
7
+ Paste this, replace two values, and you have a working widget. It puts your API
8
+ key in the page, which is fine on your own machine and **not fine in
9
+ production** — [step two](#before-you-ship) moves it to your server.
10
+
5
11
  ```html
6
- <convai-widget character-id="YOUR_CHARACTER_ID" token-endpoint="/api/convai-token"></convai-widget>
7
- <script src="https://cdn.jsdelivr.net/npm/@convai/web-widget@0.1.1-beta.1/v1.js" async></script>
12
+ <convai-widget character-id="YOUR_CHARACTER_ID" api-key="YOUR_API_KEY"></convai-widget>
13
+ <script src="https://cdn.jsdelivr.net/npm/@convai/web-widget@0.1.1/v1.js" async></script>
8
14
  ```
9
15
 
10
- A launcher bubble appears in the bottom-right corner. Clicking it loads the
11
- widget, opens the panel, and starts the conversation.
16
+ A launcher bubble appears in the bottom-right corner. Click it: the runtime
17
+ downloads, the panel opens, and you can talk to your character by text or by
18
+ voice.
12
19
 
13
- ## Why it is built this way
20
+ ### React
14
21
 
15
- - **The script tag costs 8 KB.** It paints the launcher immediately and
16
- nothing else. The full SDK — around 230 KB gzipped — is fetched only when a
17
- visitor actually engages, so a page nobody talks to pays almost nothing.
18
- - **Your CSS and the widget's cannot collide.** Everything renders inside a
19
- closed shadow root, so the host page cannot reach in and the widget cannot
20
- leak out. Theming happens through eight documented custom properties.
21
- - **Your API key stays on your server.** `token-endpoint` points at a route on
22
- your own backend that mints a short-lived, revocable token. The key is never
23
- in page source.
22
+ The script tag goes in your HTML shell; the element is ordinary JSX.
23
+
24
+ ```html
25
+ <!-- index.html -->
26
+ <script src="https://cdn.jsdelivr.net/npm/@convai/web-widget@0.1.1/v1.js" async></script>
27
+ ```
28
+
29
+ ```jsx
30
+ <convai-widget character-id={CHARACTER_ID} api-key={API_KEY} />
31
+ ```
32
+
33
+ In Next.js, use `next/script` with `strategy="afterInteractive"` — it injects a
34
+ classic script tag, which is what the loader needs.
24
35
 
25
- ## Authentication
36
+ > **Do not `import` this package into an app bundle.** The loader derives the
37
+ > runtime chunk's URL from its own `<script src>`, so a bundled import (or a
38
+ > `<script type="module">`) leaves it with nothing to derive from: the bubble
39
+ > paints and then fails on click with `could not resolve the runtime URL`. Load
40
+ > it from a script tag. The npm package exists so you can self-host `v1.js` and
41
+ > `runtime.js` from your own origin.
26
42
 
27
- `token-endpoint` is a route you host. Its entire job is to relay one call:
43
+ ## Before you ship
44
+
45
+ `api-key` is visible to anyone who views source, never expires, and is scoped
46
+ to your whole account — the widget logs a one-time warning saying so. Replace
47
+ it with `token-endpoint`, a single route you host whose entire job is to relay
48
+ one call:
28
49
 
29
50
  ```js
30
51
  app.post('/api/convai-token', async (req, res) => {
@@ -37,32 +58,58 @@ app.post('/api/convai-token', async (req, res) => {
37
58
  })
38
59
  ```
39
60
 
40
- The widget mints on first engagement and reuses the token for about an hour,
41
- so this runs once per hour of use, not once per conversation.
61
+ Then swap one attribute:
62
+
63
+ ```diff
64
+ - <convai-widget character-id="YOUR_CHARACTER_ID" api-key="YOUR_API_KEY"></convai-widget>
65
+ + <convai-widget character-id="YOUR_CHARACTER_ID" token-endpoint="/api/convai-token"></convai-widget>
66
+ ```
67
+
68
+ The widget mints on first engagement and reuses the token for about an hour, so
69
+ this runs once per hour of use, not once per conversation. `token-endpoint`
70
+ outranks `api-key`, so leaving both on during a migration is safe — but delete
71
+ the key anyway, it is still in your page source.
72
+
73
+ A third mode, `connect-endpoint`, proxies the full connect request for teams who
74
+ want to inspect or gate it server-side. All three are covered in the docs.
75
+
76
+ **If your character has Long-Term Memory enabled, add `end-user-id`** — the
77
+ connect request is rejected without it. Each distinct value consumes an account
78
+ resource, so read the guidance before pointing it at production traffic.
42
79
 
43
- Two other modes exist — a full connect proxy, and an `api-key` attribute for
44
- local development only. Both are covered in the documentation.
80
+ ## Why it is built this way
81
+
82
+ - **The script tag costs 8 KB.** It paints the launcher immediately and nothing
83
+ else. The full SDK — around 230 KB gzipped — is fetched only when a visitor
84
+ actually engages, so a page nobody talks to pays almost nothing.
85
+ - **Your CSS and the widget's cannot collide.** Everything renders inside a
86
+ closed shadow root, so the host page cannot reach in and the widget cannot
87
+ leak out. Theming happens through eight documented custom properties.
88
+ - **Your API key stays on your server** once you move to `token-endpoint`.
45
89
 
46
90
  ## Documentation
47
91
 
48
92
  **<https://docs.convai.com/embed>**
49
93
 
50
94
  Authentication in depth with working Express, Next.js and Cloudflare Worker
51
- recipes; the complete attribute and event reference; theming and `::part()`
52
- hooks; CSP requirements; and guidance on `end-user-id` and Long-Term Memory.
95
+ recipes; the complete attribute and event reference; a React and Next.js usage
96
+ guide; theming and `::part()` hooks; CSP requirements; and guidance on
97
+ `end-user-id` and Long-Term Memory.
53
98
 
54
99
  ## Beta
55
100
 
56
- This is a prerelease published to the `beta` dist-tag. **Pin the exact
57
- version** — `npm install @convai/web-widget` and the unversioned jsDelivr URL
58
- resolve `latest`, which does not exist yet:
101
+ This is a prerelease published to the `beta` dist-tag. While the beta runs,
102
+ `latest` is deliberately pointed at the current beta too, so
103
+ `npm install @convai/web-widget` and the unversioned jsDelivr URL both work —
104
+ and both give you a prerelease. **Pin the exact version anyway**: `latest`
105
+ moves as each beta ships, and interfaces may change between them.
59
106
 
60
107
  ```html
61
- <script src="https://cdn.jsdelivr.net/npm/@convai/web-widget@0.1.1-beta.1/v1.js" async></script>
108
+ <script src="https://cdn.jsdelivr.net/npm/@convai/web-widget@0.1.1/v1.js" async></script>
62
109
  ```
63
110
 
64
111
  ```bash
65
- npm install @convai/web-widget@beta
112
+ npm install @convai/web-widget@0.1.1 # for self-hosting the two files
66
113
  ```
67
114
 
68
115
  Interfaces may change before a stable release.
package/package.json CHANGED
@@ -1,14 +1,14 @@
1
1
  {
2
2
  "name": "@convai/web-widget",
3
- "version": "0.1.1-beta.1",
3
+ "version": "0.1.1",
4
4
  "description": "Two-line script-tag embed for the Convai chat widget. A <convai-widget> custom element with a closed shadow root and a lazily loaded runtime.",
5
5
  "homepage": "https://docs.convai.com/embed",
6
6
  "repository": {
7
7
  "type": "git",
8
- "url": "git+https://github.com/Conv-AI/convai-widget-embed.git"
8
+ "url": "git+https://github.com/Conv-AI/web-widget.git"
9
9
  },
10
10
  "bugs": {
11
- "url": "https://github.com/Conv-AI/convai-widget-embed/issues"
11
+ "url": "https://github.com/Conv-AI/web-widget/issues"
12
12
  },
13
13
  "license": "UNLICENSED",
14
14
  "type": "module",