@filigran/chatbot 3.11.1 → 3.12.0

package/README.md

@@ -13,7 +13,7 @@ Filigran chat panel — a standalone React + Tailwind chatbot component with SSE
 - 📥 **Agent-Generated Files** — Renders downloadable file cards from agent output and strips the `[[FILE:id]]` markers from the prose
 - 📝 **Full Markdown** — Tables (mis-delimited ones repaired), code blocks with copy button, lists, blockquotes, soft line breaks, inline images with a lightbox
 - 🖼️ **Image Previews** — `data:image/*` charts and image attachments render inline, click to expand
-- 📋 **Copy & Rate** — Copy any answer; optional 👍/👎 feedback wired to the host
+- 📋 **Message Footer** — Every message says when it was sent; copy any message, rate an answer 👍/👎 (stored by the backend or handed to the host, with an optional comment on a 👎) and have it read aloud — see [Message feedback](#message-feedback)
 - 🧰 **Composer Toolbar** — Prompt library and quota indicator, both driven by whether the host serves the route; plus a slot for the host's own controls
 - 🧠 **Context Gauge** — Ring + percentage showing how full the model's context window is, so a long chat's silent summarising is visible before it happens
 - 🎙️ **Dictation** — Speech-to-text via the browser's own Web Speech API; no endpoint, no key, hidden where unsupported
@@ -83,7 +83,8 @@ import { ChatPanel } from '@filigran/chatbot';
 | `onWidthChange`     | `(width: number) => void`                 | —            | Called when sidebar width changes during resize                  |
 | `onResizeStart`     | `() => void`                              | —            | Called when resize drag starts                                   |
 | `onResizeEnd`       | `() => void`                              | —            | Called when resize drag ends                                     |
-| `onMessageFeedback` | `(id, feedback, message) => void`         | —            | Enables 👍/👎 on completed assistant answers and receives each rating (`null` clears it). Omit to hide the affordance — the panel stores nothing itself. |
+| `onMessageFeedback` | `(id, feedback, message) => void`         | —            | Receives each rating of an answer (`null` clears it); `id` is the message's persisted id when the backend reported one (`done.message_id`, a restored entry's `id`), else the panel's own. On its own it enables 👍/👎 and the panel stores nothing; with `apiEndpoints.feedback` set it is called once the backend has stored the rating. With neither, no thumbs. |
+| `locale`            | `string`                                  | browser's    | BCP 47 language tag the message times are written in and answers are read aloud in (the platform's language, e.g. `'fr-FR'`) |
 | `disableImagePreviews` | `boolean`                              | `false`      | Render image attachments as download cards instead of inline previews |
 | `contextUsageEnabled` | `boolean`                               | `true`       | Show how full the model's context window is for the current conversation (ring + percentage in the composer toolbar). Data-driven, so it stays absent until the backend reports occupancy — see [Context usage](#context-usage). |
 | `composerToolbar`   | `React.ReactNode`                         | —            | Extra controls appended to the composer toolbar. The escape hatch for host-specific affordances (XTM One's session-tool picker) — the package never learns what they are. Pass nothing and the toolbar simply has none. |
@@ -175,12 +176,26 @@ Restores conversation history (and, implicitly, resolves the session).
 {
   "conversation_id": "uuid-here",
   "messages": [
-    { "role": "user", "content": "Hello" },
-    { "role": "assistant", "content": "Hi! How can I help?" }
+    { "id": "msg-1", "role": "user", "content": "Hello", "created_at": "2026-06-10T08:30:00Z" },
+    {
+      "id": "msg-2",
+      "role": "assistant",
+      "content": "Hi! How can I help?",
+      "created_at": "2026-06-10T08:30:04Z",
+      "feedback": { "rating": "positive", "comment": null }
+    }
   ]
 }
 ```
 
+`id`, `created_at` and `feedback` are optional. `id` is the message's
+persisted id, what its rating is stored against (see
+[Message feedback](#message-feedback));
+`created_at` (ISO 8601) is when it was sent, shown in its footer - a message
+without one shows no time. `feedback` is the caller's own rating of an
+assistant answer: the thumbs are then locked on it ("Feedback already
+submitted").
+
 The response **should echo a `conversation_id`**. When the stored
 `conversation_id` no longer exists (e.g. the platform was reset but the
 browser kept an old id in `localStorage`), the backend is expected to
@@ -280,9 +295,13 @@ data: {"type": "status", "status": "analyzing"}
 data: {"type": "status", "status": "streaming"}
 data: {"type": "stream", "content": "The weather "}
 data: {"type": "stream", "content": "today is sunny."}
-data: {"type": "done", "content": "The weather today is sunny.", "conversation_id": "new-uuid", "tool_names": ["search_web"], "tool_call_count": 1, "iterations": 1, "reasoning": "Let me check the weather data first.", "tool_call_trace": [{"name": "search_web", "input": "{\"query\": \"weather\"}", "output": "Sunny, 24C", "success": true}], "transfer_chain": [{"agent_id": "uuid", "agent_name": "General"}], "is_truncated": false}
+data: {"type": "done", "content": "The weather today is sunny.", "conversation_id": "new-uuid", "message_id": "msg-2", "tool_names": ["search_web"], "tool_call_count": 1, "iterations": 1, "reasoning": "Let me check the weather data first.", "tool_call_trace": [{"name": "search_web", "input": "{\"query\": \"weather\"}", "output": "Sunny, 24C", "success": true}], "transfer_chain": [{"agent_id": "uuid", "agent_name": "General"}], "is_truncated": false}
 ```
 
+The optional `message_id` on `done` is the answer's persisted id: without it
+(and without a restore naming the message) the answer cannot be rated through
+`apiEndpoints.feedback`.
+
 The optional `reasoning` field on `done` (and on restored session messages)
 carries the accumulated model reasoning / pre-tool preamble prose for the
 turn. When present it is surfaced in the per-message reasoning-details dialog
@@ -530,6 +549,58 @@ abandonment, never the person deciding.
 
 REST backend only: `legacy` and `ag-ui` never meet this gate.
 
+### Message feedback
+
+Every message ends with a footer. An assistant answer (once it has finished
+streaming) shows when it was sent, the "i" reasoning details, **Copy
+response**, 👍 / 👎 and **Read aloud**; a user message shows **Copy message**
+and its time, right-aligned. The time is written in the `locale` prop's
+language (the time alone today, the date and time before; the full date in
+the tooltip). Time and "i" are always visible; the other actions appear when
+the message is hovered or focused, and always on a touch screen. A rating
+given, or the answer being read, stays visible.
+
+The thumbs render when `apiEndpoints.feedback` is set **or**
+`onMessageFeedback` is passed. **Opt-in: `feedback` has no default path**
+(the same choice as `approve`): a host names its route, or the panel stores
+nothing.
+
+```
+POST   {apiBaseUrl}{apiEndpoints.feedback}/{conversation_id}/messages/{message_id}/feedback
+       { "rating": "positive" | "negative", "comment": string | null }
+       -> 200 { "rating": ..., "comment": ... }
+DELETE {apiBaseUrl}{apiEndpoints.feedback}/{conversation_id}/messages/{message_id}/feedback
+       -> 204
+```
+
+Both are sent with `credentials: 'include'` and your `requestHeaders`
+(XTM One: `feedback: '/chat/conversations'`). `message_id` is the answer's
+persisted id — the `done` event's `message_id`, or the restored entry's
+`id` — so an answer the backend did not identify shows no thumbs.
+
+- A thumb is shown as given at once and rolled back, with "Could not submit
+  feedback." (or "Could not retract feedback." for a retraction) under the
+  message, when the backend refuses it or cannot be reached.
+- Clicking the given thumb again retracts it (`DELETE`).
+- Once a 👎 is stored the panel asks what went wrong: **Save** re-posts the
+  rating with the comment (trimmed, at most 2000 characters), **Skip** keeps
+  the rating without one.
+- A rating restored with the conversation (`feedback` on a restored entry) is
+  final: only its thumb is shown, "Feedback already submitted".
+- `onMessageFeedback`, when passed too, is called once the backend has
+  stored the rating. On its own it receives every rating and the panel
+  stores nothing (no comment step, since the callback has nowhere to put
+  one).
+
+REST backend only, and not in `singleEndpoint` mode (there is no per-path
+routing to name a feedback route with).
+
+**Read aloud** uses the browser's own speech synthesis — no endpoint, hidden
+where unsupported, and absent on an answer with nothing to say (code only). It
+reads the answer's text without its markdown or file markers, in the `locale`
+prop's language, one answer at a time; switching conversation, sending a
+message or leaving the panel stops it.
+
 ## Customization
 
 ### Custom Logo
@@ -685,16 +756,26 @@ Every key the package can ask for, grouped by where it appears:
 - `'Copied'`
 - `'Copied!'`
 - `'Copy code'`
+- `'Copy message'`
 - `'Copy response'`
+- `'Could not retract feedback.'`
+- `'Could not submit feedback.'`
 - `'Download'`
 - `'Expand image'`
+- `'Feedback already submitted'`
 - `'Good response'`
 - `'Image could not be loaded'`
 - `'Image preview'`
 - `'Load earlier messages'`
 - `'Loading image…'`
+- `'Read aloud'`
 - `'Reasoning details'`
 - `'Reasoning details — turn limit reached'`
+- `'Save'`
+- `'Skip'`
+- `'Stop reading'`
+- `'Tell us what went wrong (optional)'`
+- `'What could be improved?'`
 
 **Agent status**
 
@@ -787,6 +868,10 @@ Every key the package can ask for, grouped by where it appears:
 - `'Quota reached'`
 - `'Usage'`
 - `'Usage · {period}'`
+- `'this month'`
+- `'this year'`
+- `'today'`
+- `'{quota} (shared across all users)'`
 
 **Notices, errors and timestamps**
 
@@ -823,12 +908,20 @@ backend cannot answer, and there is no mode flag to keep in step.
 | Endpoint | Default path | Response |
 | --- | --- | --- |
 | Prompt library | `GET {apiBaseUrl}/chat/prompts` | `[{ id, title, content, description? }]` (or `{ prompts: [...] }`) |
-| Quota status | `GET {apiBaseUrl}/chat/quota` | `{ used: number, limit: number \| null, period: string }` |
+| Quota status | `GET {apiBaseUrl}/chat/quota` | `{ used: number, limit: number \| null, period: string, scope?: 'user' \| 'global' }` |
 | Agent suggestions | `GET {apiBaseUrl}/chat/suggestions?agent_slug=<slug>` | `["..."]` (or `{ suggestions: [...] }`, or objects with `prompt`/`label`/`text`) |
 
 Set either to `null` in `apiEndpoints` to hide it. `limit: null` means no
 ceiling — the indicator then shows consumption without a bar. The quota is
-re-read whenever a turn finishes.
+re-read whenever a turn finishes. The periods XTM One sets a quota for
+(`daily`, `monthly`, `yearly`) are translated (`today`, `this month`,
+`this year`), any other one is shown as sent; `scope: 'global'` says the
+limit is shared across all users.
+
+A host behind its own proxy points the routes at it, relative to its
+`apiBaseUrl` — OpenCTI and OpenAEV pass
+`{ prompts: '/prompts', quota: '/quota', feedback: '/conversations' }`
+(`feedback`: see [Message feedback](#message-feedback)).
 
 The welcome screen names the selected agent and shows its own suggestions —
 which is also how switching agent is confirmed: the thread resets to that

package/dist/index.d.ts

@@ -125,6 +125,21 @@ interface ApiEndpoints {
      * both today's generic suggestions and per-agent (later per-user) ones.
      */
     suggestions?: string | null;
+    /**
+     * Base path of the persisted message feedback resource. A rating is sent as
+     * `POST {apiBaseUrl}{feedback}/{conversation_id}/messages/{message_id}/feedback`
+     * with `{ rating: 'positive' | 'negative', comment: string | null }` and
+     * retracted with a `DELETE` on the same URL. XTM One's platform router
+     * serves it at `/chat/conversations`.
+     *
+     * No default, for the same reason as {@link ApiEndpoints.approve}: a host
+     * proxying the chat names the route once it exposes it, and a panel upgraded
+     * before its host never rates into a 404. Unset, the thumbs still render
+     * when the host passes `onMessageFeedback`, as they always did.
+     *
+     * REST backend only, and not in `singleEndpoint` mode.
+     */
+    feedback?: string | null;
 }
 /** A reusable prompt the user can insert into the composer. */
 interface ChatPromptTemplate {
@@ -144,8 +159,18 @@ interface ChatQuotaStatus {
     used: number;
     /** null means unlimited — the indicator then shows usage without a bar. */
     limit: number | null;
-    /** Human-readable period label, e.g. "monthly". */
+    /**
+     * The period the limit applies to: `daily`, `monthly` and `yearly` are
+     * translated ("today", "this month", "this year"), any other value is shown
+     * as sent.
+     */
     period: string;
+    /**
+     * Whose actions count against the limit: `global` is one allowance shared
+     * by every user of the platform, which the indicator says in its tooltip.
+     * Absent reads as the user's own.
+     */
+    scope?: 'user' | 'global';
 }
 /**
  * One tool call the agent wants to make and is waiting on a human to approve.
@@ -345,12 +370,22 @@ interface ChatPanelProps {
      */
     onTaskComplete?: (title: string, body: string) => void;
     /**
-     * Enables the 👍/👎 affordance on completed assistant messages and receives
-     * each rating. `feedback` is `null` when the user clears a previous rating.
-     * Omit to hide the affordance entirely — the chatbot stores nothing itself,
-     * so a host without a feedback endpoint should not show the buttons.
+     * Receives each rating of an assistant answer. `messageId` is the persisted
+     * id when the backend reported one (`serverId`), else the panel's own id;
+     * `feedback` is `null` when the user clears a previous rating.
+     *
+     * With {@link ApiEndpoints.feedback} set the panel stores the rating itself
+     * and calls this once the backend accepted it. Without it, passing this is
+     * what shows the 👍/👎 affordance: the host stores the rating, so a host with
+     * neither shows no buttons.
      */
     onMessageFeedback?: (messageId: string, feedback: MessageFeedback | null, message: ChatMessage) => void;
+    /**
+     * The user's language as a BCP 47 tag (`'fr'`, `'en-US'`): formats the time
+     * under each message and is the language answers are read aloud in. Default:
+     * the browser's own.
+     */
+    locale?: string;
     /**
      * Disable the inline preview of image attachments (they render as ordinary
      * download cards instead). Previews fetch the image through the host download
@@ -391,10 +426,29 @@ interface ChatToggleButtonProps {
     icon?: React.ReactNode;
 }
 interface ChatMessage {
+    /** The panel's own key for the row; stable for the life of the row. */
     id: string;
+    /**
+     * The backend's id for the message: the `done` event's `message_id` for a
+     * live answer, the entry's `id` for a restored one. What feedback is stored
+     * against; absent until the backend reports it.
+     */
+    serverId?: string;
     role: 'user' | 'assistant';
     content: string;
+    /** When the message was sent: the entry's `created_at` for a restored one. */
     timestamp: Date;
+    /**
+     * True for a restored message whose backend did not say when it was sent:
+     * `timestamp` is then the time of the restore, and the footer shows no time
+     * rather than that one.
+     */
+    timestampUnknown?: boolean;
+    /**
+     * The rating the user gave this answer before the conversation was restored.
+     * The panel locks the thumbs on it ("Feedback already submitted").
+     */
+    feedback?: ChatMessagePersistedFeedback;
     /**
      * The agent that produced *this* message, when the backend says so.
      *
@@ -433,6 +487,11 @@ interface ChatMessage {
      */
     isTruncated?: boolean;
 }
+/** A rating as the feedback endpoint stores it. */
+interface ChatMessagePersistedFeedback {
+    rating: 'positive' | 'negative';
+    comment: string | null;
+}
 /** One tool call in the reasoning-details execution trace. */
 interface ToolCallTraceEntry {
     name: string;
@@ -516,4 +575,4 @@ interface TransferredAgent {
 }
 
 export { ChatPanel, ChatToggleButton };
-export type { ApiEndpoints, BackendType, ChatAttachment, ChatContextBreakdown, ChatContextUsage, ChatConversationSummary, ChatFile, ChatMessage, ChatMode, ChatPanelProps, ChatPromptTemplate, ChatQuotaStatus, ChatToggleButtonProps, MessageFeedback, ToolApprovalDecision, ToolApprovalProposal, ToolApprovalVerdict, TransferredAgent, Translate, XtmAgent };
+export type { ApiEndpoints, BackendType, ChatAttachment, ChatContextBreakdown, ChatContextUsage, ChatConversationSummary, ChatFile, ChatMessage, ChatMessagePersistedFeedback, ChatMode, ChatPanelProps, ChatPromptTemplate, ChatQuotaStatus, ChatToggleButtonProps, MessageFeedback, ToolApprovalDecision, ToolApprovalProposal, ToolApprovalVerdict, TransferredAgent, Translate, XtmAgent };