@meandr/chat-sdk 0.0.1 → 0.0.2

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 CHANGED
@@ -82,6 +82,7 @@ inherits it. A page that gives no way resumes it.
82
82
  | `tokenUrl` | `string`: an address, absolute or relative to the page |
83
83
  | `getToken` | `({ expired, signal }) => string \| null \| Promise<string \| null>` |
84
84
  | `fetch` | your own `fetch`, for tests or a wrapper. Add no headers: the chat's CORS allows only `Authorization` and `Content-Type`, so a tracing header such as `traceparent` fails every request |
85
+ | `context` | `() => PageContext \| undefined \| Promise<PageContext \| undefined>`: what your page tells the model of itself, read at each `send()` and `start()`: see [Page context](#page-context) |
85
86
 
86
87
  An option the client doesn't know, or a token option set to `undefined`, is an error, so a typo or a missing value
87
88
  can't silently resume someone's session.
@@ -93,7 +94,9 @@ can't silently resume someone's session.
93
94
  | `getState()` | the current state, below |
94
95
  | `subscribe(listener)` | calls `listener(state)` now and on every change; returns the function that unsubscribes |
95
96
  | `open()` | opens the session: call it when the visitor shows interest. Calling it again while open does nothing. Resolves with the state once it opened, or failed for a reason waiting won't fix: see `status` and `error` |
96
- | `send(text)` | sends the message and streams the answer into the state. Resolves with `{ ok: true, message, stop }`, the stored answer, or `{ ok: false, error }` |
97
+ | `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
+ | `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
+ | `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 }` |
97
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 or the chat is set so. Resolves as `send` does |
98
101
  | `newConversation()` | forgets the current conversation: the next message, or `start()`, starts a new one |
99
102
  | `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` |
@@ -101,8 +104,8 @@ can't silently resume someone's session.
101
104
  | `destroy()` | stops everything this client does; it sends nothing more |
102
105
 
103
106
  No member rejects for a chat failure: the result and the state carry it. Members work passed around on their own, as
104
- in `onClick={chat.newConversation}` or `onFocus={chat.open}`; `send` and `reopen` take arguments, so call those
105
- yourself rather than handing them an event.
107
+ in `onClick={chat.newConversation}` or `onFocus={chat.open}`; `send`, `attach`, `readFile` and `reopen` take arguments,
108
+ so call those yourself rather than handing them an event.
106
109
 
107
110
  ## The state
108
111
 
@@ -111,19 +114,94 @@ yourself rather than handing them an event.
111
114
  | `status` | `"idle"` before opening, `"opening"`, `"ready"`, or `"error"` when opening failed (`error` says why) |
112
115
  | `anonymous` | whether the session is an anonymous visitor's; `null` before opening |
113
116
  | `conversation` | `{ id, createdAt, updatedAt }`, or `null` before the first message |
114
- | `messages` | the conversation's stored messages, oldest first: `{ id, role, text, tools?, createdAt }`. `tools` names the tools the answer used |
115
- | `outgoing` | the message being sent, until the page shows it stored. With `error` set, it may not have reached the chat: offer to send it again, which never stores it twice |
116
- | `answer` | the answer being written in this page: `{ text, tools: [{ name, status }] }`, or `null` |
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 |
118
+ | `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
+ | `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 |
117
120
  | `answering` | an answer is being written in this conversation: in this page, or one the page lost or a previous page left running |
118
121
  | `waiting` | `{ code, until }` while the client waits by itself, such as `rate_limited`, or `null`. `until` is a time in milliseconds, as from `Date.now()` |
119
122
  | `stop` | why the last answer ended: `"end"`, `"max_tokens"` (cut short), `"refusal"` or `"paused"`; `null` when unknown |
120
123
  | `error` | the last failure, until the next action |
124
+ | `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` |
121
125
 
122
126
  Show `messages`, then `outgoing`, then `answer`. Disable sending while `answering` or `status` is `"opening"`. An
123
127
  assistant's `text` is Markdown from a model: render it with `@meandr/chat-sdk/markdown`, or another renderer that
124
128
  never passes raw HTML through. A user's text is plain text.
125
129
 
126
- The state is replaced, never changed in place. Messages that didn't change keep their objects.
130
+ The state is replaced, never changed in place. Messages that didn't change keep their objects, and so does `files`.
131
+
132
+ ## Files
133
+
134
+ Where the chat's settings take files (`CHAT_ATTACHMENTS`), a visitor may attach them to a message for the model to
135
+ read: images (PNG, JPEG, WebP, GIF), PDFs, and text (plain, Markdown, CSV). They never reach your workspace's tools.
136
+
137
+ ```js
138
+ const { types } = state.files; // offer attaching only while state.files isn't null
139
+ input.accept = types.concat(types.includes("text/plain") ? [".txt", ".md", ".csv"] : []).join(",");
140
+
141
+ const files = []; // the message's, as the visitor picks them
142
+ const picked = await chat.attach(input.files[0], { onProgress: (sent, total) => (bar.value = sent / total) });
143
+ if (picked.ok) files.push(picked.file); // or picked.error, such as unsupported_type
144
+ await chat.send(text, { files }); // once every upload is in; text may be ""
145
+
146
+ const read = await chat.readFile(message.files[0]);
147
+ if (read.ok) img.src = URL.createObjectURL(read.blob);
148
+ ```
149
+
150
+ - **Offer attaching only while the state's `files` isn't `null`.** Its `types` can be your `<input>`'s `accept`:
151
+ browsers often give Markdown and CSV files no type, so add `.txt`, `.md` and `.csv` when it lists `text/plain`, which
152
+ the chat takes with the other two. A message takes at most `perMessage` files.
153
+ - **Upload each file as it's picked**, showing its progress, and send the message once all are in. The chat deletes a
154
+ file no message takes within an hour, and a message takes each file once.
155
+ - **A ChatFile** is `{ id, name, type, size, createdAt }`: its name as the chat keeps it, its media type as the chat
156
+ reads it from its bytes, and its size in bytes.
157
+ - **Progress** comes from `XMLHttpRequest`, since `fetch` reports none: with `onProgress`, the upload doesn't go through
158
+ a `fetch` you gave.
159
+ - **Refused before sending,** with status 0, since a browser may see a refusal that comes mid-upload as a network
160
+ error: a file past `maxBytes` (`too_large`), and any file once a session says the chat takes none (`attachments_off`).
161
+ Until a session says, or from a chat that doesn't, a file past 10 MiB, which no chat takes, is refused the same way.
162
+ - **Showing a file:** `readFile` fetches it with the session's cookie or token, so make an object URL of its blob: an
163
+ `<img>` pointing at the chat can't carry the token. The blob keeps an image's type; anything else is
164
+ `application/octet-stream`, a file to save rather than one the browser renders. Files already sent stay readable
165
+ while the chat takes no new ones.
166
+
167
+ ## Page context
168
+
169
+ Each message and start can tell the model what the visitor's page shows, so "this order" or "the drawer I have open"
170
+ means something to it. The `context` option is read at each `send()` and `start()`, so it's always the current view:
171
+
172
+ ```js
173
+ const chat = createChat({
174
+ url: "https://calm-otter.meandr.io",
175
+ tokenUrl: "/chat_token",
176
+ context: () => ({
177
+ url: location.origin + location.pathname, // the query and hash can carry tokens
178
+ title: document.title,
179
+ view: { section: "Orders", drawer: { open: true, order: "A-1042", tab: "Refunds" } },
180
+ }),
181
+ });
182
+ ```
183
+
184
+ The chat gets, beside the message:
185
+
186
+ ```json
187
+ {"timezone":"Europe/Tallinn","url":"https://console.shop.example/orders","title":"Orders · Console","view":{"section":"Orders","drawer":{"open":true,"order":"A-1042","tab":"Refunds"}}}
188
+ ```
189
+
190
+ - **Known keys,** all optional: `url` (at most 2048 bytes), `title` (512) and `timezone` (an IANA name, 64). Any other
191
+ key goes as you give it.
192
+ - **The browser's time zone** goes by default, under what the option gives, so the model knows the visitor's local
193
+ time: give `timezone` to name another, or `timezone: undefined` to send none. Without the option, every message and
194
+ start carries the time zone alone.
195
+ - **Send only what you mean to.** The model reads it as what the page reports, information rather than instructions,
196
+ and the chat stores it with the message. URLs can carry tokens, such as a reset link's or a sign-in code:
197
+ `location.origin + location.pathname` leaves out the query and the hash.
198
+ - **The visitor's browser sends it,** so a visitor can change it, fooling only their own conversation: never let it
199
+ decide what a user may do. Facts your backend vouches for, such as the user's name, go in the token's `profile`
200
+ claim instead.
201
+ - **Never at the message's cost:** past the chat's limit (8 KiB by default, as its session says), with a `url`,
202
+ `title` or `timezone` the chat would refuse, or when the option throws, gives no object or takes over 5 s, the
203
+ message goes without the page's part, keeping the time zone, and the console warns once for each reason. A chat
204
+ older than page context, whose session says no limit, gets the time zone alone.
127
205
 
128
206
  ## Errors
129
207
 
@@ -142,9 +220,12 @@ Show your own words for the code:
142
220
  | `origin_not_allowed`, `origin_required` | The chat isn't available on this site. (The error's message names the site.) |
143
221
  | `workspace_not_available`, `not_connected` | The chat isn't available right now. |
144
222
  | `start_not_allowed` | (nothing: the chat isn't set to speak first) |
145
- | `not_found` | This conversation is gone. |
223
+ | `attachments_off` | This chat doesn't take files. |
224
+ | `unsupported_type` | That kind of file can't be attached. |
225
+ | `storage_full` | You can't attach more files for now. (The visitor's files, those in conversations included, fill the space the chat allows.) |
226
+ | `not_found` | This conversation is gone. (From `readFile`: That file is gone.) |
146
227
  | `busy` | Still answering your previous message. |
147
- | `too_large` | That message is too long. |
228
+ | `too_large` | That message is too long. (From `attach`: That file is too large.) |
148
229
  | `rate_limited` | You're sending messages too fast. Try again in a moment. |
149
230
  | `overloaded` | The chat is busy. Try again in a moment. (The chat's machine is short of memory.) |
150
231
  | `model_busy` | The assistant is busy. Try again in a moment. |
@@ -175,6 +256,10 @@ Codes the client doesn't know may come: show a general error for those.
175
256
  - **Nothing twice:** it tries a message again only when the chat refused it before storing it. When the connection
176
257
  drops or the chat fails while sending, it looks for the message in the conversation before saying it failed. A
177
258
  start that fails with `network` may have begun, so calling it again can have the assistant speak twice.
259
+ - **Files:** an upload the chat refused before keeping it is tried again as a message is: an ended session is opened
260
+ again once, and it waits up to a minute as the chat says. One whose answer was lost, such as with `network`, isn't,
261
+ since the chat may have kept it: attach it again. An upload is given up on when it stops moving for 30 s, or, without
262
+ `onProgress`, when no answer starts within 30 s plus its size's time at 32 KB/s.
178
263
  - **A lost stream:** the answer runs on and is stored. The client asks for the conversation every few seconds, for up
179
264
  to ten minutes, until the answer ends, as it does when it opens on an answer a previous page left running. An answer
180
265
  still waiting its turn when its stream closed was dropped: that's `no_answer`, and sending again stores the message
@@ -246,7 +331,8 @@ the chat's, and only signed-in users can chat: your server must answer for them.
246
331
 
247
332
  ## Content Security Policy
248
333
 
249
- Allow `connect-src` for your workspace's URL and your token address.
334
+ Allow `connect-src` for your workspace's URL and your token address, and `img-src blob:` to show files through object
335
+ URLs.
250
336
 
251
337
  ## License
252
338
 
package/dist/api.d.ts CHANGED
@@ -4,16 +4,19 @@ export interface Call {
4
4
  method: "GET" | "POST" | "DELETE";
5
5
  path: string;
6
6
  body?: unknown;
7
+ type?: string;
7
8
  bearer?: string | null;
8
9
  signal?: AbortSignal;
9
10
  stream?: boolean;
11
+ progress?: (sent: number) => void;
10
12
  }
11
13
  export declare function apiBase(url: string): string;
12
14
  export declare function aborted(): ChatError;
13
15
  export declare function within<T>(p: Promise<T>, signal: AbortSignal | undefined, ms: number, late: () => Error): Promise<T>;
14
- export declare function timed(fetchFn: Fetch, url: string, init: RequestInit, signal?: AbortSignal): Promise<Response>;
16
+ export declare function timed(fetchFn: Fetch, url: string, init: RequestInit, signal?: AbortSignal, ms?: number): Promise<Response>;
15
17
  export declare function request(fetchFn: Fetch, base: string, c: Call): Promise<Response>;
16
18
  export declare function discard(res: Response): void;
19
+ export declare function chunks(res: Response, signal?: AbortSignal): Promise<Uint8Array<ArrayBuffer>[]>;
17
20
  export declare function body(res: Response, signal?: AbortSignal): Promise<unknown>;
18
21
  export declare function readJSON(res: Response, signal?: AbortSignal): Promise<unknown>;
19
22
  export declare function failure(res: Response, signal?: AbortSignal): Promise<ChatError>;
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" | "not_found" | "busy" | "too_large" | "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" | "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, Chat, ChatOptions, ChatState, ChatStatus, Conversation, Message, ReopenOptions, SendResult, Stop, TokenRequest, TokenSource, ToolProgress, ToolStatus, Waiting, } from "./types.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";