@meandr/chat-sdk 0.0.2 → 0.0.3
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 +83 -16
- package/dist/api.d.ts +1 -0
- package/dist/errors.d.ts +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.js +547 -359
- package/dist/index.js.map +3 -3
- package/dist/markdown.js +90 -90
- package/dist/markdown.js.map +1 -1
- package/dist/meandr-chat.js +9 -9
- package/dist/meandr-chat.js.map +3 -3
- package/dist/types.d.ts +47 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -41,17 +41,18 @@ const result = await chat.send("Where is my order?");
|
|
|
41
41
|
The client does nothing until it's used, so create it with the page: until then it sends nothing, loads nothing and
|
|
42
42
|
leaves nothing behind. Create one client per page, not one per component render. It activates in one of three ways:
|
|
43
43
|
|
|
44
|
-
- **`open()`**, when the visitor shows interest: opens the chat, or starts typing. It loads their latest conversation
|
|
44
|
+
- **`open()`**, when the visitor shows interest: opens the chat, or starts typing. It loads their latest conversation
|
|
45
|
+
they haven't ended, its last 20 messages.
|
|
45
46
|
- **`send(text)`** opens by itself.
|
|
46
47
|
- **`start()`** has the assistant speak first, such as a greeting or a summary of what needs the visitor's attention.
|
|
47
|
-
What it does is the chat's own start instructions,
|
|
48
|
+
What it does is the chat's own start instructions, its **Intro prompt** setting (`CHAT_START_PROMPT`), so a page or a visitor
|
|
48
49
|
can't supply them; the visitor sees only the answer. Without them, it's refused (`start_not_allowed`). With no
|
|
49
50
|
conversation shown, after `newConversation()` say, it speaks in a new one.
|
|
50
51
|
|
|
51
52
|
## Who the user is
|
|
52
53
|
|
|
53
54
|
Give the client one way to get your user's token. A token is a JWT your backend signs with the chat's **Session
|
|
54
|
-
|
|
55
|
+
secret key**. See the help center's "Sign your users in to Meandr Chat".
|
|
55
56
|
|
|
56
57
|
| Option | For | The client |
|
|
57
58
|
|---|---|---|
|
|
@@ -97,15 +98,21 @@ can't silently resume someone's session.
|
|
|
97
98
|
| `send(text, { files })` | sends the message and streams the answer into the state. `files` are those `attach` gave, as ChatFiles or ids; with any, `text` may be `""`. Resolves with `{ ok: true, message, stop }`, the stored answer, or `{ ok: false, error }` |
|
|
98
99
|
| `attach(file, { name, onProgress, signal })` | uploads a `File` or `Blob` for a message of the visitor's within the hour, opening the session if need be: see [Files](#files). `name` is the file's own unless given, else `"file"`; `onProgress(sent, total)` follows its bytes; `signal` cancels it. Resolves with `{ ok: true, file }`, a ChatFile, or `{ ok: false, error }`, and changes nothing in the state |
|
|
99
100
|
| `readFile(file, { signal })` | fetches a file the visitor attached, by its ChatFile or id, with the session's credentials, opening the session if need be. Resolves with `{ ok: true, blob }` or `{ ok: false, error }` |
|
|
100
|
-
| `start()` | has the assistant speak first, as the chat's start instructions say, and streams the answer: in the user's latest conversation, usually the one shown, or a new one when none is shown
|
|
101
|
-
| `
|
|
101
|
+
| `start()` | has the assistant speak first, as the chat's start instructions say, and streams the answer: in the user's latest conversation they haven't ended, usually the one shown, or a new one when none is shown. Resolves as `send` does |
|
|
102
|
+
| `endConversation()` | ends the conversation shown and forgets it at once, so no page shows it again by itself: see [Conversations](#conversations). Resolves once the chat has it, or after about a minute of trying; never rejects |
|
|
103
|
+
| `newConversation()` | ends the conversation shown, as `endConversation()` does: the next message, or `start()`, starts a new one |
|
|
104
|
+
| `listConversations({ before, signal })` | lists the user's conversations, 20 at a time, most recently active first, opening the session if need be: see [Conversations](#conversations). `before`, a Conversation or its id, goes on after that one; `signal` cancels it. Resolves with `{ ok: true, conversations, hasMore }`, each with its `title`, or `{ ok: false, error }`, and changes nothing in the state |
|
|
105
|
+
| `openConversation(conversation)` | shows that conversation, a Conversation or its id, in place of the current one once it's read: its last 20 messages. It ends nothing, and the next message goes there. Resolves with `{ ok: true, conversation }`, or `{ ok: false, error }` with the current one still shown |
|
|
106
|
+
| `deleteConversation(conversation)` | deletes that conversation, a Conversation or its id, with its messages and files, opening the session if need be. One already gone counts as deleted; the one shown is forgotten. Resolves with `{ ok: true }` or `{ ok: false, error }`, and is refused as `busy` while an answer is being written in it |
|
|
107
|
+
| `loadOlder()` | adds the 20 messages before the oldest shown to the front of `messages`, while `hasOlder`. Resolves with `{ ok: true, messages }`, those it added, or `{ ok: false, error }` |
|
|
102
108
|
| `reopen({ token })` | the user changed without a page load: signed in, signed out or switched team. Forgets everything shown and, if the chat was open, opens it again. Pass `token` when you give `token` |
|
|
103
109
|
| `signOut()` | ends the session and forgets the user, even if the page never showed the chat. Call it from your sign-out and await it before you navigate: it settles within three seconds, and never rejects |
|
|
104
110
|
| `destroy()` | stops everything this client does; it sends nothing more |
|
|
105
111
|
|
|
106
112
|
No member rejects for a chat failure: the result and the state carry it. Members work passed around on their own, as
|
|
107
|
-
in `onClick={chat.
|
|
108
|
-
so call those yourself rather than handing them
|
|
113
|
+
in `onClick={chat.endConversation}` or `onFocus={chat.open}`; `send`, `attach`, `readFile`, `listConversations`,
|
|
114
|
+
`openConversation`, `deleteConversation` and `reopen` take arguments, so call those yourself rather than handing them
|
|
115
|
+
an event.
|
|
109
116
|
|
|
110
117
|
## The state
|
|
111
118
|
|
|
@@ -113,8 +120,9 @@ so call those yourself rather than handing them an event.
|
|
|
113
120
|
|---|---|
|
|
114
121
|
| `status` | `"idle"` before opening, `"opening"`, `"ready"`, or `"error"` when opening failed (`error` says why) |
|
|
115
122
|
| `anonymous` | whether the session is an anonymous visitor's; `null` before opening |
|
|
116
|
-
| `conversation` | `{ id, createdAt, updatedAt }`, or `null` before the first message |
|
|
117
|
-
| `messages` | the conversation's stored messages, oldest first: `{ id, role, text, tools?, toolTitles?, files?, createdAt }`. `tools` names the tools the answer used, and `toolTitles`, with it, gives each one's title by name, its name where the chat knows none; `files` are the ChatFiles the visitor attached |
|
|
123
|
+
| `conversation` | `{ id, createdAt, updatedAt, endedAt }`, or `null` before the first message. `endedAt` is when the user ended it, `null` while they haven't; their next message there reopens it |
|
|
124
|
+
| `messages` | the conversation's stored messages, oldest first: its last 20 when it's shown, and older ones as `loadOlder()` adds them. Each is `{ id, role, text, tools?, toolTitles?, files?, createdAt }`. `tools` names the tools the answer used, and `toolTitles`, with it, gives each one's title by name, its name where the chat knows none; `files` are the ChatFiles the visitor attached |
|
|
125
|
+
| `hasOlder` | the conversation shown has messages older than those in `messages`: `loadOlder()` adds them |
|
|
118
126
|
| `outgoing` | the text of the message being sent, `""` with files alone, until the page shows it stored. With `error` set, it may not have reached the chat: offer to send it again, with its files, which never stores it twice |
|
|
119
127
|
| `answer` | the answer being written in this page: `{ text, tools: [{ name, status, title }] }`, or `null`. Show a tool's `title`: its name when the chat knows none |
|
|
120
128
|
| `answering` | an answer is being written in this conversation: in this page, or one the page lost or a previous page left running |
|
|
@@ -122,6 +130,7 @@ so call those yourself rather than handing them an event.
|
|
|
122
130
|
| `stop` | why the last answer ended: `"end"`, `"max_tokens"` (cut short), `"refusal"` or `"paused"`; `null` when unknown |
|
|
123
131
|
| `error` | the last failure, until the next action |
|
|
124
132
|
| `files` | what the chat takes, as its session says: `{ types, maxBytes, perMessage }`, the media types, a file's most bytes and a message's most files. `null` before opening and while it takes no file: offer attaching only when it isn't `null` |
|
|
133
|
+
| `conversationList` | whether the chat lists the user's conversations, as its session says: offer the list, and opening and deleting conversations from it, only while it's `true`. `null` before opening |
|
|
125
134
|
|
|
126
135
|
Show `messages`, then `outgoing`, then `answer`. Disable sending while `answering` or `status` is `"opening"`. An
|
|
127
136
|
assistant's `text` is Markdown from a model: render it with `@meandr/chat-sdk/markdown`, or another renderer that
|
|
@@ -129,9 +138,66 @@ never passes raw HTML through. A user's text is plain text.
|
|
|
129
138
|
|
|
130
139
|
The state is replaced, never changed in place. Messages that didn't change keep their objects, and so does `files`.
|
|
131
140
|
|
|
141
|
+
## Conversations
|
|
142
|
+
|
|
143
|
+
A conversation goes on, through reloads and a closed chat, until the user ends it. Then no page shows it again by
|
|
144
|
+
itself, and the next message, or `start()`, begins a new one. Offer ending always. Messages come 20 at a time: a
|
|
145
|
+
conversation shows its last 20, and `loadOlder()` adds the 20 before the oldest shown while `hasOlder`. Where the
|
|
146
|
+
chat's **Conversation list** setting is on (`CHAT_CONVERSATION_LIST`), a page may also offer the user's conversations,
|
|
147
|
+
ended ones included, to open or delete:
|
|
148
|
+
|
|
149
|
+
```js
|
|
150
|
+
endButton.onclick = () => {
|
|
151
|
+
chat.endConversation(); // shows none at once; the end outlives the page
|
|
152
|
+
panel.hidden = true;
|
|
153
|
+
};
|
|
154
|
+
newButton.onclick = chat.newConversation; // ends it too: the next message begins another
|
|
155
|
+
listButton.hidden = !state.conversationList; // the list, opening and deleting: only while the chat lists them
|
|
156
|
+
|
|
157
|
+
const page = await chat.listConversations(); // the 20 most recently active, and page.hasMore
|
|
158
|
+
if (page.ok) rows = page.conversations; // { id, title, createdAt, updatedAt, endedAt }
|
|
159
|
+
const next = await chat.listConversations({ before: rows[rows.length - 1] }); // the 20 after those
|
|
160
|
+
|
|
161
|
+
await chat.openConversation(rows[2]); // shows it, ending none: the next message goes there
|
|
162
|
+
await chat.deleteConversation(rows[3]); // with its messages and files
|
|
163
|
+
|
|
164
|
+
scroller.onscroll = () => {
|
|
165
|
+
if (scroller.scrollTop === 0 && chat.getState().hasOlder) chat.loadOlder(); // then keep the visitor's place
|
|
166
|
+
};
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
- **Ending** forgets the conversation shown at once, and tells the chat with `keepalive`, so the end goes through
|
|
170
|
+
when the page navigates away right after. It's tried again through about a minute while the chat can't be reached
|
|
171
|
+
or asks to wait. `endConversation()` resolves once the chat has it, and never rejects. A first message or `start()`
|
|
172
|
+
still on its way, its new conversation not named yet, resolves `aborted` at once but goes on unseen until the chat
|
|
173
|
+
names that conversation, which is then ended. Called before the session opens, it ends the conversation the session
|
|
174
|
+
opens on, which the page then never shows; with no opening under way, it resolves at once. `newConversation()` does
|
|
175
|
+
the same, for a "New conversation" that begins the next one at once.
|
|
176
|
+
- **The list** comes most recently active first, 20 at a time: pass the last one shown as `before` for the next 20,
|
|
177
|
+
while `hasMore`. A conversation that gets a message meanwhile moves to the top, so the walk may miss it or show it
|
|
178
|
+
twice: read the first page again to see what's new. A `title` is the start of the conversation's first message, `""`
|
|
179
|
+
while it has none, as after a `start()` alone; only the list carries it. `endedAt` says which ones the user ended.
|
|
180
|
+
- **Opening** one reads it, then shows its last 20 messages in place of the current one, following an answer still
|
|
181
|
+
being written in it. The current one isn't ended, and stays shown when the read fails. One the user ended shows with
|
|
182
|
+
its `endedAt`, and their next message there reopens it. A `newConversation()`, a later `openConversation()`, or a
|
|
183
|
+
message or `start()` before it's shown wins, and it resolves `aborted`. A conversation that isn't the user's is
|
|
184
|
+
`not_found`.
|
|
185
|
+
- **Deleting** one takes its messages and files with it. One already gone counts as deleted, and the one shown is
|
|
186
|
+
forgotten. While an answer is being written in it, it's refused as `busy`.
|
|
187
|
+
- **Older messages** go to the front of `messages`; `loadOlder()` resolves with them, `[]` when none remain, and calls
|
|
188
|
+
while one runs share it. A conversation read again, as when the client follows a lost stream, keeps those it loaded.
|
|
189
|
+
- **Where the chat lists none** (`conversationList` is `false`), `listConversations()` and `deleteConversation()` are
|
|
190
|
+
refused without a request (`conversation_list_off`), and a conversation the user ended is gone for them. Opening the
|
|
191
|
+
others and loading older messages work either way.
|
|
192
|
+
- **Gone elsewhere:** a conversation shown that another tab deleted, or ended where the chat lists none, reads as
|
|
193
|
+
missing. The client forgets it at its next read or message, which says `not_found`.
|
|
194
|
+
- **`start()`** speaks in the user's latest conversation they haven't ended, which may not be the one shown: the page
|
|
195
|
+
then shows that conversation, with the answer alone. With none shown, after `endConversation()` say, it speaks in a
|
|
196
|
+
new one.
|
|
197
|
+
|
|
132
198
|
## Files
|
|
133
199
|
|
|
134
|
-
Where the chat's
|
|
200
|
+
Where the chat's **Attachments** setting is on (`CHAT_ATTACHMENTS`), a visitor may attach them to a message for the model to
|
|
135
201
|
read: images (PNG, JPEG, WebP, GIF), PDFs, and text (plain, Markdown, CSV). They never reach your workspace's tools.
|
|
136
202
|
|
|
137
203
|
```js
|
|
@@ -223,10 +289,11 @@ Show your own words for the code:
|
|
|
223
289
|
| `attachments_off` | This chat doesn't take files. |
|
|
224
290
|
| `unsupported_type` | That kind of file can't be attached. |
|
|
225
291
|
| `storage_full` | You can't attach more files for now. (The visitor's files, those in conversations included, fill the space the chat allows.) |
|
|
292
|
+
| `conversation_list_off` | (nothing: offer the list, opening and deleting only while `conversationList` is `true`) |
|
|
226
293
|
| `not_found` | This conversation is gone. (From `readFile`: That file is gone.) |
|
|
227
|
-
| `busy` | Still answering your previous message. |
|
|
294
|
+
| `busy` | Still answering your previous message. (From `deleteConversation`: It's still answering there. Try again when it's done.) |
|
|
228
295
|
| `too_large` | That message is too long. (From `attach`: That file is too large.) |
|
|
229
|
-
| `rate_limited` | You're sending messages too fast. Try again in a moment. |
|
|
296
|
+
| `rate_limited` | You're sending messages too fast. Try again in a moment. (Also when the workspace is past its plan's limit on requests.) |
|
|
230
297
|
| `overloaded` | The chat is busy. Try again in a moment. (The chat's machine is short of memory.) |
|
|
231
298
|
| `model_busy` | The assistant is busy. Try again in a moment. |
|
|
232
299
|
| `interrupted`, `timeout`, `unavailable`, `no_answer` | The answer failed. Try again. |
|
|
@@ -249,10 +316,10 @@ Codes the client doesn't know may come: show a general error for those.
|
|
|
249
316
|
settings change: it tries again briskly through the first minute, then every 15 to 30 s, until the chat answers or
|
|
250
317
|
the page leaves. `waiting` says so meanwhile, so the page never needs a reload, and a `send` or `start` called
|
|
251
318
|
meanwhile waits with it.
|
|
252
|
-
- **Waiting:** it waits as long as the chat says, up to a minute, when the visitor writes too fast
|
|
253
|
-
machine is short of memory, and up to two minutes when the user's
|
|
254
|
-
perhaps. Past the answers the chat writes at once, an answer waits
|
|
255
|
-
refused for it.
|
|
319
|
+
- **Waiting:** it waits as long as the chat says, up to a minute, when the visitor writes too fast, the workspace is
|
|
320
|
+
past its plan's limit on requests or the chat's machine is short of memory, and up to two minutes when the user's
|
|
321
|
+
previous answer is still running, in another tab perhaps. Past the answers the chat writes at once, an answer waits
|
|
322
|
+
its turn on the open stream, so nothing is refused for it.
|
|
256
323
|
- **Nothing twice:** it tries a message again only when the chat refused it before storing it. When the connection
|
|
257
324
|
drops or the chat fails while sending, it looks for the message in the conversation before saying it failed. A
|
|
258
325
|
start that fails with `network` may have begun, so calling it again can have the assistant speak twice.
|
package/dist/api.d.ts
CHANGED
package/dist/errors.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import type { Message } from "./types.js";
|
|
2
|
-
export type ChatErrorCode = "unauthorized" | "token_expired" | "token_failed" | "session_expired" | "origin_not_allowed" | "origin_required" | "workspace_not_available" | "start_not_allowed" | "attachments_off" | "storage_full" | "not_found" | "busy" | "too_large" | "unsupported_type" | "rate_limited" | "overloaded" | "not_connected" | "interrupted" | "timeout" | "unavailable" | "model_busy" | "no_answer" | "network" | "aborted" | "bad_request" | "internal" | "protocol";
|
|
2
|
+
export type ChatErrorCode = "unauthorized" | "token_expired" | "token_failed" | "session_expired" | "origin_not_allowed" | "origin_required" | "workspace_not_available" | "start_not_allowed" | "attachments_off" | "storage_full" | "conversation_list_off" | "not_found" | "busy" | "too_large" | "unsupported_type" | "rate_limited" | "overloaded" | "not_connected" | "interrupted" | "timeout" | "unavailable" | "model_busy" | "no_answer" | "network" | "aborted" | "bad_request" | "internal" | "protocol";
|
|
3
3
|
export interface ChatErrorInit {
|
|
4
4
|
status?: number;
|
|
5
5
|
retryAfter?: number | null;
|
package/dist/index.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
1
|
export { createChat } from "./client.js";
|
|
2
2
|
export { ChatError, isChatError } from "./errors.js";
|
|
3
3
|
export type { ChatErrorCode } from "./errors.js";
|
|
4
|
-
export type { Answer, AttachOptions, AttachResult, Chat, ChatFile, ChatOptions, ChatState, ChatStatus, Conversation, FileLimits, Message, PageContext, ReadFileOptions, ReadFileResult, ReopenOptions, SendOptions, SendResult, Stop, TokenRequest, TokenSource, ToolProgress, ToolStatus, Waiting, } from "./types.js";
|
|
4
|
+
export type { Answer, AttachOptions, AttachResult, Chat, ChatFile, ChatOptions, ChatState, ChatStatus, Conversation, DeleteConversationResult, FileLimits, ListConversationsOptions, ListConversationsResult, LoadOlderResult, Message, OpenConversationResult, PageContext, ReadFileOptions, ReadFileResult, ReopenOptions, SendOptions, SendResult, Stop, TokenRequest, TokenSource, ToolProgress, ToolStatus, Waiting, } from "./types.js";
|