@icanbwell/baileyai-chat-ui 1.0.16 → 1.0.18

package/README.md

@@ -142,6 +142,166 @@ that case. If a host needs `privacyNote` to survive this (e.g. it's a persistent
 disclosure rather than a first-impression nicety), pass `privacyNote={{ ..., alwaysVisible: true }}`
 to render it in every state, not just the empty one.
 
+## Using the Bailey client
+
+`createBaileyClient` is a framework-free client for the Bailey API. It implements
+`BaileyChatTransport` (so it can be passed straight to `useBaileyChat`) and adds conversation
+calls. The host supplies only `baseUrl` and `getHeaders`; the library never reads or stores tokens.
+
+```tsx
+import { createBaileyClient, useBaileyChat, useBaileyConversations, createSessionConversationStorage } from '@icanbwell/baileyai-chat-ui';
+
+const client = createBaileyClient({
+    baseUrl: 'https://api.example.com/bailey/v1', // the API root, including /bailey/v1
+    getHeaders: async () => ({ Authorization: `Bearer ${await getAuthToken()}` }),
+    onAuthError: (error) => signOut(error.status), // fires once on 401/403
+});
+
+const chat = useBaileyChat({
+    transport: client,
+    model: 'bailey-default',
+    instructions: 'You are Bailey...',
+    storage: createSessionConversationStorage(), // optional; see below
+});
+const history = useBaileyConversations({ client }); // conversations, loadMore, refresh, remove
+```
+
+- Client methods: `listConversations`, `getConversation`, `deleteConversation`, `submitFeedback`,
+  `clearFeedback`, and `streamChat`. Failures reject with `BaileyApiError` (`status`, and `kind` of
+  `http`, `network`, `timeout`, `aborted` or `invalid-response`); its message is fixed per kind and never
+  contains a response body. For `network` and `timeout`, `error.cause` holds the original thrown error
+  (the failed fetch's error, or the abort reason); `http`, `invalid-response` and `aborted` have no cause.
+  Browsers do not expose whether a failed fetch was CORS, DNS or offline (all are a generic `TypeError`),
+  so `kind` plus `cause` is all a host can show or log. Do not show `cause.message` to users without
+  review, and do not log the request URL. `invalid-response` means a read (`listConversations`, `getConversation`) got a 2xx whose body was
+  not JSON (or a 204); writes (`submitFeedback`, `clearFeedback`, `deleteConversation`) still accept an
+  empty or non-JSON success body. `streamChat` keeps the `BaileyChatTransport` contract: it returns the
+  HTTP status and raw body for non-2xx responses instead of throwing. If the connection drops after the
+  response began it returns `interrupted: true`, and `useBaileyChat` then ends the turn in the error
+  state (the partial text stays visible, `onAssistantMessageComplete` does not fire). A custom
+  transport should set `interrupted: true` in that case, and must resolve `streamChat` only when the
+  response body has closed.
+  When no response arrives (`fetch` rejects, or `getHeaders` throws) `streamChat` still resolves with
+  `status: undefined` and the fixed `errorMessage: 'Request failed'`, and now also sets `errorKind: 'network'`
+  so a host can choose its own copy. `errorCause` carries the error `fetch` threw; it is not set when
+  `getHeaders` threw (it can carry auth detail). Both fields are optional and additive, and
+  `useBaileyChat`'s copy is unchanged. A caller abort and the idle timeout still reject with the abort
+  reason (`TimeoutError` for the idle timeout), and a mid-stream drop still resolves `interrupted: true`
+  without `errorKind`. Browsers do not distinguish CORS, DNS or offline, so do not show `errorCause.message`
+  to users without review and do not log the request URL.
+  A multi-byte character cut off at the end of the stream is flushed as a final `onChunk`.
+- Every call has a timeout (`requestTimeoutMs`, default 30s; the stream uses an idle timeout,
+  `idleTimeoutMs`). A failed best-effort cleanup is reported through `onCleanupError` and never thrown.
+- **Nothing is logged** by the client or the hooks, and request/response bodies are never placed in
+  errors or callbacks.
+- **Conversation id.** `useBaileyChat` returns a read-only `conversationId`. It comes from the
+  `conversationId` option (a seed), from `storage`, or from the `X-Conversation-Id` response header
+  the transport reports via `onConversationId`. `newChat()` clears it. The library does not create
+  ids. Once an id is held it is sent as the `x-chat-id` header, and **only the newest message** goes in
+  `input` because the server prepends its stored history and does not deduplicate. With no id held
+  (for example the first turn, before the server reports one) the full transcript is sent, exactly
+  as before. Pass `sendFullTranscript: true` to always send the full transcript **and never the id**
+  (stateless requests; escape hatch, e.g. where the server does not persist; the library cannot
+  detect that itself). The id is withheld because with one the server would prepend its stored
+  history to the full transcript and duplicate it in the model context.
+- **`conversationVia` (opt-in, default `'header'`).** `createBaileyClient({ conversationVia: 'body' })`
+  sends the held id as the `conversation` field of the request body instead of `x-chat-id` (never
+  both). See the `conversationVia` JSDoc for when it is safe to switch. Independently of that option,
+  `useBaileyChat` also adopts `response.conversation.id` from `response.completed` / `response.created`
+  events when present (non-empty string only), ahead of the `X-Conversation-Id` header value.
+- **The id is persisted in sessionStorage by default (per tab).** A reload resumes the conversation
+  (the messages themselves are loaded with `loadConversation`). Pass `storage: false` to disable
+  persistence, or your own `BaileyConversationStorage` to store it elsewhere. A storage that throws
+  (Safari private mode, blocked storage) never reaches your render: chat continues with the id in
+  memory, `persistence` becomes `'degraded'` (`'ok'` normally, `'off'` for `storage: false`) and
+  `onStorageError(error, operation)` is called. A `sub` that is provided but blank is a host error
+  reported the same way (operation `'key'`); the id then stays in memory and the shared key is not used.
+  Append your own surface name to `storageKey` so surfaces do not share a conversation. Selecting an
+  old conversation (`loadConversation`) always replaces the stored id. Hosts should clear the stored
+  id on logout through the same `storage`; the library has no logout hook.
+- **`sub` keys and validates the stored id (optional).** Pass the signed-in user's `sub` and the stored
+  id lives under `${storageKey}:${sub}` and is rejected (and removed) on read unless it starts with
+  `<sub>:`, so a different user in the same browser session never inherits the previous user's id. A
+  seed and any id reported by the transport are validated the same way. `sub` is used for nothing
+  else: **the library never creates a conversation id**, it only reads the one the server reports
+  (`X-Conversation-Id`) or one you seed. Without `sub` the stored id is held unvalidated; after a
+  shared-browser user switch the server rejects the foreign id and the library adopts the
+  server-reported one, so the worst case is a lost first-turn context.
+- **Lost server context is surfaced.** A turn that sent a held id signals context loss when the
+  server did not continue that conversation, for one of two reasons. `reason: 'id'`: it came back
+  with no id, or a different one (persistence off, an id it does not know). `reason: 'history'`: it
+  reported the same id but `conversation.history_status` on `response.created` / `response.completed`
+  (the last one the turn carries wins) is `'failed'` or `'empty'`, meaning the stored history was not
+  loaded. In both cases the hook drops the held id and its stored value, clears the paging state, sets
+  `contextLost: true` until the next turn, and calls `onContextLoss({ sentId, reportedId, reason })`
+  (the library always sets `reason`, though it is optional in the type; `reportedId` is absent when the server reported none); the next turn sends
+  the full transcript. `'loaded'`, an absent field and any unrecognised value change nothing, and a
+  first turn (no id sent) never signals loss. A host-seeded id whose turn reports `'empty'` also
+  signals loss: a seeded id is only valid for resuming a stored conversation. The backend also sends
+  `history_loaded` (number of prior messages loaded); the library does not read it, it is for host
+  diagnostics. A turn that fails outright (4xx/5xx) is reported as an error as before. Older backends
+  do not send `history_status`, so for them only `reason: 'id'` can occur and a history load that
+  fails while the server reports the same id is still not detectable. Residual risk until the backend
+  change (baileyai PR #554, language-model-common PR #136) is deployed and released: the `'history'`
+  path is inert.
+- **Persistence off on the server.** Stable conversation ids only help where the server persists
+  conversations (the conversation routes return 503 when persistence is off). The library does not
+  probe for this: enable stable ids (pass a `client` and keep the default storage) only in environments
+  where persistence is on, and otherwise set `sendFullTranscript: true` so every request carries the
+  full transcript and no conversation id.
+- Existing hosts that pass none of these options behave as before until a transport reports a
+  conversation id: a custom `BaileyChatTransport` keeps working (`conversationId` and
+  `onConversationId` are optional transport params, and `conversationId` is only passed once an id is
+  held), and none of the hosts' transports report one today. Only a transport that does (such as this
+  client) makes the hook hold, persist and send an id.
+- **Loading a conversation.** Pass `client` to `useBaileyChat` to get `loadConversation({ conversationId })`
+  (newest 100 messages), `loadEarlier()` / `hasEarlier` (older pages) and `historyStatus`. Hidden rows
+  are dropped, each assistant message gets `serverMessageId`, and a stored rating is mapped to
+  `message.feedback`. Loading holds the id, so the next turn sends only the newest message and the
+  loaded history is not re-sent. Failures reject with `BaileyApiError`, leave the messages intact and
+  set `historyStatus` to `'error'`; a response that arrives after `newChat()` or another load is
+  discarded. `mapTranscript` and `mergeEarlierPage` are exported for hosts that fetch transcripts
+  themselves. `loadMessages` still never changes the held id.
+- **Feedback.** `createBaileyFeedbackHandlers({ client, getConversationId })` returns `onSubmit` / `onClear`
+  for `BaileyFeedbackButtons`:
+
+  ```tsx
+  const handlers = createBaileyFeedbackHandlers({ client, getConversationId: () => chat.conversationId });
+  // inside renderMessageActions:
+  <BaileyFeedbackButtons messageId={m.serverMessageId} initialRating={m.feedback?.rating} {...handlers} />
+  ```
+
+  Any rejection (including a 404, or no conversation id held) is a failure the buttons show; nothing is
+  retried automatically. The comment goes only into the request body.
+- Not included yet: automatic resume on mount. A restored id does not load the transcript; call
+  `loadConversation` yourself (the history drawer below does this when the user picks a row).
+
+## Conversation history drawer
+
+An opt-in, built-in history UI: pass a Bailey client to the panel and the "Chat history" item in the
+"..." menu opens a drawer inside the panel (no dialog dependency, nothing fetched until it opens).
+
+```tsx
+const client = createBaileyClient({ baseUrl, getHeaders });
+const chat = useBaileyChat({ transport: client, client, model: 'bailey-default', instructions: '...' });
+
+<BaileyChatPanel chat={chat} history={{ client }} locale="en" />
+```
+
+- Rows show the title (or "Untitled conversation"), a relative time, and the message count (hidden in
+  narrow panels); the active conversation is marked with a tint, an accent bar and the word "Current".
+  Selecting a row calls `chat.loadConversation` and closes the drawer. Delete asks for an inline
+  confirmation (no undo window); deleting the active conversation resets the chat. "Load more" follows
+  the server's cursor.
+- Errors show fixed copy (a separate "session expired" message for a 401/403 on the list call, the
+  connection message otherwise) with Retry; error text and titles never reach logs or `title` attributes.
+- `onHistoryClick` is the host override: when both `history` and `onHistoryClick` are given, your callback
+  runs and the drawer never mounts. A host that passes neither renders exactly as before.
+- Every string is a `labels` key (`historyTitle`, `historyEmptyTitle`, `historySessionExpiredTitle`, and so
+  on, all with English defaults). The session-expired wording is a default for copy review. Relative times
+  use `Intl.RelativeTimeFormat` with `locale` (default `navigator.language`): a future time shows "now",
+  and a time without an offset is read as UTC.
+
 ## Resuming a conversation
 
 `useBaileyChat` also returns `loadMessages(messages)`, for restoring a transcript a host fetched
@@ -167,7 +327,8 @@ be mid-stream.
 
 `loadMessages` only replaces `useBaileyChat`'s own state — a host still owns fetching the
 transcript and its own loading/error UI, and owns conversation identity (which id is active,
-where it's persisted) entirely outside this package.
+where it's persisted) outside this package, unless it opts in to the id handling described in
+[Using the Bailey client](#using-the-bailey-client).
 
 ### Known limitations
 
@@ -236,6 +397,43 @@ Pass `privacyNote` to render a short compliance/privacy disclosure as a footer b
 
 By default the note only renders in the empty state, before the first message. Pass `alwaysVisible: true` to keep it showing for the entire conversation instead — see [Sending a hidden turn](#sending-a-hidden-turn) above for why a host might need this.
 
+## Collecting feedback
+
+`BaileyFeedbackButtons` renders thumbs up/down on an assistant message, with an inline form (reason chips and a comment) after a thumbs-down or an "Add a comment" click. It is opt-in and never calls an API itself: your app owns auth and networking and passes `onSubmit`/`onClear`. No extra install or subpath; it is part of the base entry.
+
+```tsx
+<BaileyChatPanel
+    chat={chat}
+    renderMessageActions={(message) =>
+        message.serverMessageId ? (
+            <BaileyFeedbackButtons
+                messageId={message.serverMessageId}
+                onSubmit={({ messageId, rating, reasonCodes, comment }) =>
+                    submitFeedback({ messageId, rating, reasonCodes, comment })
+                }
+                onClear={({ messageId }) => clearFeedback({ messageId })}
+            />
+        ) : null
+    }
+/>
+```
+
+Pass a stable function for `renderMessageActions`. The control renders nothing when `messageId` is empty.
+
+**Message ID.** `BaileyMessage.serverMessageId` is the backend's assistant message ID (the `id` field is minted client-side and is not usable for this). `useBaileyChat` reads it from the `message_id` field of the `response.completed` SSE event. A transport that reads it from a response header (`X-Message-Id`, non-streaming responses) can report it early through the optional `onMessageId(messageId)` callback of `streamChat`, parallel to `onRequestId`. `X-Message-Id` is only readable from a browser cross-origin if the backend exposes it through CORS (`Access-Control-Expose-Headers`), so browser hosts should prefer the `response.completed` event (or the `message_id` in the response body) over the header. A missing or non-string `message_id` is ignored, leaving `serverMessageId` undefined, so the control does not render against an older backend.
+
+**Behavior.**
+
+- Clicking a thumb calls `onSubmit({ messageId, rating })` immediately. The form's Submit calls `onSubmit` again with `{ messageId, rating, reasonCodes?, comment? }` (omitted when empty); the backend call is an upsert, so this replaces the earlier write. Clicking the selected thumb, or Undo, calls `onClear({ messageId })`.
+- At most one request is in flight per `messageId`; edits made meanwhile are coalesced to the latest state and sent afterwards.
+- A rejected promise means failure: the optimistic selection reverts, `labels.feedbackErrorText` is shown and the draft is kept.
+- Any rejection, including a 404, is shown as an error and is never retried automatically; the user retries by hand. The backend emits `message_id` only after the assistant message is committed, so a message that carries a `serverMessageId` exists and a 404 on it is a real failure. Render the control only for messages that have a `serverMessageId`.
+- `reasonOptions` selects a subset (and order) of the backend codes `inaccurate`, `unhelpful`, `unsafe`, `too_long`, `other`; an unknown code is treated as `other`. `maxCommentLength` defaults to 2000 and can only be lowered. `initialRating` shows a previously stored rating.
+- The comment is PHI-capable. It is passed to `onSubmit` only, never to the console, the trace panel or any other callback. Do not log it in your handler either.
+- Strings are overridable through the `labels` prop (`BaileyFeedbackLabels`), merged shallowly with English defaults, like `BaileyChatPanel`'s labels.
+
+Minimum backend: the assistant `message_id` on `response.completed` (and `X-Message-Id` for non-streaming responses) and the feedback routes from BAI-1231 (baileyai, BAI-1234). On a backend without them the buttons simply do not appear. A `503` from the feedback API means feedback is disabled for that environment; hide the control from your side for the session.
+
 ## Localization
 
 Every visible string in `BaileyChatPanel` defaults to English. Pass a `labels` prop with