@webority/chat-react 0.0.0-stage → 0.21.0

package/LICENSE

@@ -0,0 +1,5 @@
+Copyright (c) Webority Technologies. All rights reserved.
+
+This software and its source code are proprietary and confidential to
+Webority Technologies. Use is restricted to Webority products and teams under
+internal license. Redistribution outside Webority Technologies is prohibited.

package/README.md

@@ -1,3 +1,233 @@
-# Temporary Holding Version
+# @webority/chat-react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An AI assistant for a React portal: a client that streams the assistant's reply, a chat hook with
+no store of its own, and the pieces of the assistant's UI (a floating launcher, a side panel, the
+conversation, reply ratings, a past-chats list and support action cards). It talks to the chat
+endpoint the product's backend hosts with `Webority.Ai.Chat.AspNetCore`, and it is built on
+`@webority/ui-react` and `@webority/theme`, so it looks like the rest of the portal with no extra
+CSS.
+
+## Install
+
+```bash
+npm install @webority/chat-react @webority/ui-react react-bootstrap bootstrap@5.3.3
+```
+
+`@webority/ui-react`, `react`, `react-dom`, `react-bootstrap` and `bootstrap` are peer
+dependencies: the portal already has them. Pin `@webority/chat-react` to the same exact version as
+`@webority/ui-react`.
+
+## Wire it up
+
+Give the client the portal's own axios instance. That instance already carries the bearer token,
+the tenant headers and the refresh on 401, so the chat calls sign in the same way as every other
+call. The package never handles auth.
+
+```jsx
+import { ChatLauncher, ChatPanel, createChatClient, useChat } from "@webority/chat-react";
+import { createSupportClient } from "@webority/support-react";
+import { useState } from "react";
+import { Link, useLocation, useNavigate } from "react-router-dom";
+import { userClient } from "./services/api/clients";
+
+const chatClient = createChatClient(userClient, { base: "/api/assistant" });
+const supportClient = createSupportClient(userClient, "/api/support");
+
+// Reply links look like [label](scheme:kind/id); map the ones the product knows to a route.
+const resolveLink = (href) => {
+    const [scheme, rest] = href.split(":");
+    if (scheme === "ticket") return `/support?ticket=${rest.split("/")[1]}`;
+    return null;
+};
+
+export function Assistant() {
+    const [open, setOpen] = useState(false);
+    const navigate = useNavigate();
+    const { pathname } = useLocation();
+    const chat = useChat({ client: chatClient, pageContext: { path: pathname } });
+
+    return (
+        <>
+            <ChatLauncher open={open} onClick={() => setOpen(true)} style={{ bottom: "5rem" }} />
+            <ChatPanel
+                chat={chat}
+                open={open}
+                onClose={() => setOpen(false)}
+                resolveLink={resolveLink}
+                linkComponent={Link}
+                confirmAction={supportClient.confirmAction}
+                onViewTicket={(ticket) => navigate(`/support?ticket=${ticket.id}`)}
+            />
+        </>
+    );
+}
+```
+
+Call `chat.reset()` when the person signs out or switches account, so nothing of one person's chat
+shows to the next. The hook keeps its state in the component that calls it; mount it once, above
+the routes, so the conversation survives navigation.
+
+The streamed reply is read through axios's XHR adapter, the browser default. An instance forced
+onto the fetch adapter still works, but the reply then appears whole at the end.
+
+## The client
+
+`createChatClient(http, { base })` takes an axios instance (`get`, `post`, `put`, `delete`
+resolving to `{ data }`) and the prefix the API maps the chat endpoints under. Every method
+rejects with a `ChatApiError` carrying `code`, `status`, `resetsAtUtc` and a `message` written for
+the person, which the components show as-is. `code` is the server's code, `network` when no
+response arrived, or `aborted` when the request was cancelled.
+
+| Method | Request |
+|---|---|
+| `sendMessage({ message, conversationId, pageContext }, { signal, onEvent })` | `POST {base}/chat`, streamed; resolves with the `done` event |
+| `getAllowance()` | `GET {base}/allowance` |
+| `listConversations({ skip, take })` | `GET {base}/conversations?skip=&take=` |
+| `getConversation(id)` | `GET {base}/conversations/{id}` |
+| `deleteConversation(id)` | `DELETE {base}/conversations/{id}` |
+| `rateMessage(conversationId, messageId, { rating, note })` | `PUT {base}/conversations/{conversationId}/messages/{messageId}/rating` |
+
+`onEvent(name, data)` is called with `delta`, `reset` and `actions` as they arrive.
+`createSseParser(onEvent)` is exported too, for reading the same stream elsewhere.
+
+## The server contract
+
+### `POST {base}/chat`
+
+Request body, JSON: `{ message, conversationId?, pageContext? }`. Leave `conversationId` out to
+start a conversation. `pageContext` is whatever the product chooses to describe the screen, and
+it is passed through untouched.
+
+A refusal before any reply is plain JSON `{ code, message, resetsAtUtc? }` with a non-2xx status:
+
+| Status | `code` |
+|---|---|
+| 400 | `message-required`, `message-too-long` |
+| 404 | `conversation-not-found` |
+| 429 | `daily-limit`, with `resetsAtUtc` |
+| 503 | `assistant-at-capacity`, `assistant-disabled`, `assistant-unavailable` |
+
+Otherwise the response is `text/event-stream`:
+
+| Event | Data | What the client does |
+|---|---|---|
+| `delta` | `{ text }` | Appends the text. |
+| `reset` | `{}` | Discards the text shown so far. |
+| `actions` | `{ actions: [{ token, kind, ticketId, ticketNumber, category, subject, body, expiresDateTimeUtc }] }` | Holds support cards; `kind` is `RaiseTicket`, `Reply` or `Reopen`. |
+| `done` | `{ conversationId, messageId, reply, messagesLeftToday }` | Ends the turn. `reply` is the reply of record and replaces the streamed text. `messageId` is null when storing failed; `messagesLeftToday` is null with no daily limit. |
+| `error` | `{ code, message }` | Ends the turn with a failure. |
+
+Exactly one `done` or `error` ends each stream.
+
+### Read endpoints the product implements
+
+The chat endpoint writes one turn. The product hosts these beside it, in this shape, for the
+allowance, past chats and ratings:
+
+| Request | Response |
+|---|---|
+| `GET {base}/allowance` | `{ messagesLeftToday }`, null with no daily limit |
+| `GET {base}/conversations?skip&take` | `[{ publicId, title, createdDateTimeUtc, lastMessageDateTimeUtc }]`, newest first |
+| `GET {base}/conversations/{id}` | `{ publicId, title, messages: [{ publicId, role, content, actionsJson, rating, ratingNote, createdDateTimeUtc }] }` |
+| `DELETE {base}/conversations/{id}` | any 2xx |
+| `PUT {base}/conversations/{conversationId}/messages/{messageId}/rating` | body `{ rating, note }`; any 2xx |
+
+`role` is `User` or `Assistant`; `rating` is `Up`, `Down` or null; `actionsJson` is the support
+actions offered with a reply, as a JSON array, or null. A failure answers `{ code, message }`.
+
+### Support actions
+
+A support card's Confirm calls the `confirmAction(token)` it is given. With
+`@webority/support-react` that is `supportClient.confirmAction`, which sends
+`POST {supportBase}/actions/confirm` with `{ token }` and resolves to the ticket it acted on. Nothing
+reaches support until the person confirms.
+
+## The hook
+
+`useChat({ client, pageContext })` returns:
+
+| Field | What it is |
+|---|---|
+| `turns` | `[{ id, question, answer, streaming, error, actions, messageId, rating, ratingNote }]`, oldest first |
+| `conversationId` | The conversation being continued, or null |
+| `messagesLeftToday` | From the last answer or `refreshAllowance()`; null with no daily limit |
+| `streaming` | An answer is arriving |
+| `loading`, `loadError` | `openConversation` is loading, or failed |
+| `submit(message)` | Asks a question. Ignored while an answer is still arriving. |
+| `openConversation(id)` | Replaces the thread with a stored conversation |
+| `newConversation()` | Clears the thread; the next question starts a conversation |
+| `rate(turnId, rating, note?)` | Saves a rating, shown at once; a failed save puts the old one back and rejects |
+| `refreshAllowance()` | Reads the questions left today |
+| `reset()` | Clears everything, for sign-out or an account switch |
+
+An answer still arriving is cancelled on `reset`, `newConversation`, `openConversation` and
+unmount. A failed turn keeps the question, drops the half-streamed text and carries `error`
+(`{ code, message, resetsAtUtc }`). After `daily-limit`, `messagesLeftToday` becomes 0; after
+`conversation-not-found`, the next question starts a new conversation.
+
+## Components
+
+Every component takes `labels`, any subset of `DEFAULT_CHAT_LABELS`, to change its wording.
+
+### `<ChatLauncher />`
+
+The floating pill that opens the panel. `onClick`, `open` (announced on the button), `position`
+(`end` or `start`, the bottom corner), `icon`, and `className` and `style` on the floating
+wrapper to move it clear of other fixed controls, such as `ReportIssue`. The launcher is left out
+of `ReportIssue`'s page capture.
+
+### `<ChatPanel />`
+
+The drawer: 440px from the right (`width`), the full screen on a phone. Focus stays inside it,
+Escape closes it, and the question box takes focus when it opens.
+
+| Prop | What it does |
+|---|---|
+| `chat` | The `useChat` result. |
+| `open`, `onClose` | Open state and close handler. |
+| `title`, `titleIcon` | Header title (default "Assistant") and its library icon. |
+| `headerActions` | Extra header controls before New chat, e.g. a past-chats button. |
+| `empty` | Shown before the first question. |
+| `disclaimer` | The footnote under the question box. |
+| `maxLength` | The server's message limit. Default 4000. |
+| `allowanceThreshold` | Show the questions left once this many or fewer remain. Default 10. |
+| `resolveLink`, `linkComponent` | Reply links; see Replies below. |
+| `confirmAction`, `onViewTicket` | Support action cards; see `ActionCard`. |
+| `rating` | Offer ratings under stored replies. Default true. |
+
+### `<ChatThread />`, `<ChatMessage />`, `<ChatComposer />`
+
+The panel's parts, for a product that lays out its own assistant page. `ChatThread` takes
+`turns`, `empty`, `onRate`, `resolveLink`, `linkComponent`, `confirmAction` and `onViewTicket`.
+Each answer is a polite live region, marked busy while it streams. `ChatComposer` takes
+`onSubmit`, `busy`, `disabled`, `maxLength` and `inputRef`; Enter sends, Shift and Enter starts a
+new line.
+
+### `<ReplyRating />`
+
+Helpful and Not helpful under a reply. Either saves at once; Not helpful then offers an optional
+note, saved with the same rating. Takes `rating` and `onRate(rating, note?)`.
+
+### `<ChatConversationList />`
+
+Past chats, newest first, for a page or a panel: `client`, `onOpen(conversation)`,
+`onDeleted(id)` and `pageSize` (default 20). It pages with Show more and deletes after a confirm.
+
+### `<ActionCard />`
+
+One support action under a reply: what will be sent, then Confirm or Not now. It moves through
+sending to done (with View ticket when `onViewTicket` is given), and an expired action shows
+without a button. Takes `action`, `confirmAction(token)` and `onViewTicket(ticket)`.
+
+## Replies
+
+`<ChatMarkdown text resolveLink linkComponent />` renders a reply from a small, safe subset of
+Markdown: paragraphs, bold, italics, inline code, bullet and numbered lists, simple tables,
+headings (as bold lines) and code blocks. It never renders HTML: every character reaches the page
+as text. Text still arriving updates the last block in place, and an unclosed `**` shows as typed
+until its partner arrives.
+
+A link shows only when its href has the form `scheme:kind/id` (for example `ticket:support/3f2a`)
+and `resolveLink(href)` returns an in-app route starting with `/`. Any other link, including every
+web address, shows its label as plain text. Pass the router's `Link` as `linkComponent` so a link
+navigates inside the portal.