@filigran/chatbot 3.2.2 → 3.3.2

package/README.md

@@ -7,6 +7,7 @@ Filigran chat panel — a standalone React + Tailwind chatbot component with SSE
 - 🔄 **SSE Message Streaming** — Real-time response streaming with status indicators
 - 🤖 **Multi-Agent Support** — Switch between different AI agents
 - 📎 **File Attachments** — Upload and paste files (PDF, TXT, images)
+- 📥 **Agent-Generated Files** — Renders downloadable file cards from agent output and strips the `[[FILE:id]]` markers from the prose
 - 📝 **Full Markdown** — Tables, code blocks with copy button, lists, blockquotes
 - 🎨 **Customizable Theme** — Accent color and logo customization
 - 📱 **3 Display Modes** — Floating, sidebar (resizable), and fullscreen
@@ -32,20 +33,9 @@ function App() {
 
   return (
     <>
-      <ChatToggleButton
-        isOpen={isOpen}
-        onToggle={() => setIsOpen(!isOpen)}
-        label="Ask Assistant"
-        accentColor="#7b5cff"
-      />
+      <ChatToggleButton isOpen={isOpen} onToggle={() => setIsOpen(!isOpen)} label="Ask Assistant" accentColor="#7b5cff" />
       {isOpen && (
-        <ChatPanel
-          mode={mode}
-          onClose={() => setIsOpen(false)}
-          onModeChange={setMode}
-          apiBaseUrl="/api/assistant"
-          user={{ firstName: 'John' }}
-        />
+        <ChatPanel mode={mode} onClose={() => setIsOpen(false)} onModeChange={setMode} apiBaseUrl="/api/assistant" user={{ firstName: 'John' }} />
       )}
     </>
   );
@@ -64,23 +54,24 @@ import { ChatPanel } from '@filigran/chatbot';
 
 #### Props
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `mode` | `'floating' \| 'sidebar' \| 'fullscreen'` | **required** | Display mode |
-| `onClose` | `() => void` | **required** | Called when close button is clicked |
-| `onModeChange` | `(mode: ChatMode) => void` | **required** | Called when user switches display mode |
-| `apiBaseUrl` | `string` | **required** | Base URL for chat API endpoints |
-| `user` | `{ firstName: string }` | **required** | Current user info |
-| `topOffset` | `number` | `0` | Top offset in pixels (for sidebar/fullscreen with fixed headers) |
-| `agentDashboardUrl` | `string` | — | URL for "Browse agents" / "Create agent" links |
-| `t` | `(key: string) => string` | identity | Translation function for i18n |
-| `accentColor` | `string` | `'#7b5cff'` | Primary accent color (hex) |
-| `logoIcon` | `React.ReactNode` | default icon | Custom logo/icon for the assistant |
-| `promptSuggestions` | `string[]` | default list | Prompt suggestions shown on welcome screen |
-| `resizable` | `boolean` | `false` | Enable drag-to-resize for sidebar mode |
-| `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 |
+| Prop                | Type                                      | Default      | Description                                                      |
+| ------------------- | ----------------------------------------- | ------------ | ---------------------------------------------------------------- |
+| `mode`              | `'floating' \| 'sidebar' \| 'fullscreen'` | **required** | Display mode                                                     |
+| `onClose`           | `() => void`                              | **required** | Called when close button is clicked                              |
+| `onModeChange`      | `(mode: ChatMode) => void`                | **required** | Called when user switches display mode                           |
+| `apiBaseUrl`        | `string`                                  | **required** | Base URL for chat API endpoints                                  |
+| `user`              | `{ firstName: string }`                   | **required** | Current user info                                                |
+| `topOffset`         | `number`                                  | `0`          | Top offset in pixels (for sidebar/fullscreen with fixed headers) |
+| `agentDashboardUrl` | `string`                                  | —            | URL for "Browse agents" / "Create agent" links                   |
+| `t`                 | `(key: string) => string`                 | identity     | Translation function for i18n                                    |
+| `accentColor`       | `string`                                  | `'#7b5cff'`  | Primary accent color (hex)                                       |
+| `logoIcon`          | `React.ReactNode`                         | default icon | Custom logo/icon for the assistant                               |
+| `promptSuggestions` | `string[]`                                | default list | Prompt suggestions shown on welcome screen                       |
+| `pageContext`       | `Record<string, unknown>`                 | —            | Arbitrary host page context (e.g. `{ url: '/dashboard/...' }`) sent as `context` on each `rest` message so the agent knows where the user is. Must be JSON-serializable (skipped if not). Read fresh at send time; omitted when empty. |
+| `resizable`         | `boolean`                                 | `false`      | Enable drag-to-resize for sidebar mode                           |
+| `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                                     |
 
 #### Resizable Sidebar Example
 
@@ -117,13 +108,13 @@ import { ChatToggleButton } from '@filigran/chatbot';
 
 #### Props
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `isOpen` | `boolean` | **required** | Whether the chat panel is open |
-| `onToggle` | `() => void` | **required** | Called when button is clicked |
-| `label` | `string` | `'Chat'` | Tooltip/aria label |
-| `accentColor` | `string` | `'#7b5cff'` | Button background color |
-| `icon` | `React.ReactNode` | default icon | Custom icon |
+| Prop          | Type              | Default      | Description                    |
+| ------------- | ----------------- | ------------ | ------------------------------ |
+| `isOpen`      | `boolean`         | **required** | Whether the chat panel is open |
+| `onToggle`    | `() => void`      | **required** | Called when button is clicked  |
+| `label`       | `string`          | `'Chat'`     | Tooltip/aria label             |
+| `accentColor` | `string`          | `'#7b5cff'`  | Button background color        |
+| `icon`        | `React.ReactNode` | default icon | Custom icon                    |
 
 ## API Contract
 
@@ -150,6 +141,7 @@ Returns available AI agents.
 Restores conversation history.
 
 **Request:**
+
 ```json
 {
   "conversation_id": "uuid-here",
@@ -158,6 +150,7 @@ Restores conversation history.
 ```
 
 **Response:**
+
 ```json
 {
   "messages": [
@@ -167,19 +160,48 @@ Restores conversation history.
 }
 ```
 
+Assistant history messages **should echo the same `attachments[]` array** that
+was sent on the original `done` event (see [Agent-generated file attachments](#agent-generated-file-attachments)),
+keyed by `file_id`. The component re-surfaces the download cards on restore,
+so omitting them means download cards silently disappear after a page reload
+even though streaming downloads work:
+
+```json
+{
+  "messages": [
+    {
+      "role": "assistant",
+      "content": "Here is your export. [[FILE:0f3a...]]",
+      "attachments": [
+        { "file_id": "0f3a...", "filename": "iocs.csv", "type": "csv", "size": 2048, "content_type": "text/csv", "file_tag": "download_file" }
+      ]
+    }
+  ]
+}
+```
+
 ### `POST {apiBaseUrl}/chat/messages`
 
 Sends a message and streams the response via SSE.
 
 **Request:**
+
 ```json
 {
   "content": "What is the weather?",
   "conversation_id": "uuid-or-null",
-  "agent_slug": "general"
+  "agent_slug": "general",
+  "context": { "url": "/dashboard/analyses/reports/<id>/overview" }
 }
 ```
 
+The optional `context` object is forwarded verbatim from the `pageContext`
+prop (REST backend only) and is omitted entirely when empty. Use it to make
+the agent aware of the user's current location/page; the shape is up to the
+host and can be extended later (page title, selected entity, user role, etc.).
+It must be JSON-serializable — a non-serializable value (circular reference,
+`BigInt`, …) is skipped rather than breaking the request.
+
 **Response:** Server-Sent Events stream with these event types:
 
 ```
@@ -192,7 +214,35 @@ 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}
 ```
 
+#### Agent-generated file attachments
+
+When an agent produces a downloadable file, the `done` event carries an `attachments` array and the streamed prose embeds `[[FILE:<file_id>]]` markers. The component strips those markers and renders a download card per attachment:
+
+```json
+{
+  "type": "done",
+  "content": "Here is your export. [[FILE:0f3a...]]",
+  "conversation_id": "uuid",
+  "attachments": [
+    { "file_id": "0f3a...", "filename": "iocs.csv", "type": "csv", "size": 2048, "content_type": "text/csv", "file_tag": "download_file" }
+  ]
+}
+```
+
+Each attachment carries only `file_id` + display metadata — **never an absolute download URL**. Clicking a card issues:
+
+```
+GET {apiBaseUrl}{apiEndpoints.download ?? '/chat/files'}/{file_id}/download
+```
+
+with `credentials: 'include'` and your `requestHeaders`. Point `apiEndpoints.download` at your **own backend proxy** so the download is authenticated by your platform (the proxy mints any upstream token server-side) — the user never authenticates to the upstream chat service directly. Set `apiEndpoints.download` to `null` to disable download cards.
+
+The `/chat/files` default applies to REST-style endpoints. In `singleEndpoint` mode there is no per-path routing, so the default is **not** applied — download cards stay disabled unless you set `apiEndpoints.download` explicitly to a proxy route.
+
+Download failures (403/404/5xx/network) are reported through the optional `onDownloadError(error, attachment)` callback so the host can surface them via its own notification system (the chatbot has no toast surface of its own).
+
 **Status values:**
+
 - `thinking` — Agent is processing
 - `tool_start` — Agent is using tools (with `tools` array)
 - `analyzing` — Agent is analyzing tool results
@@ -200,6 +250,7 @@ data: {"type": "done", "content": "The weather today is sunny.", "conversation_i
 - `streaming` — Content is being streamed
 
 **Error event:**
+
 ```
 data: {"type": "error", "content": "Something went wrong"}
 ```
@@ -214,7 +265,7 @@ import { MyLogo } from './icons';
 <ChatPanel
   logoIcon={<MyLogo size={24} />}
   // ...
-/>
+/>;
 ```
 
 ### Custom Accent Color
@@ -230,11 +281,7 @@ import { MyLogo } from './icons';
 
 ```tsx
 <ChatPanel
-  promptSuggestions={[
-    'Help me write a report',
-    'Analyze this data',
-    'Summarize recent activity',
-  ]}
+  promptSuggestions={['Help me write a report', 'Analyze this data', 'Summarize recent activity']}
   // ...
 />
 ```
@@ -246,7 +293,7 @@ import { useTranslation } from 'react-i18next';
 
 function App() {
   const { t } = useTranslation();
-  
+
   return (
     <ChatPanel
       t={t}
@@ -257,6 +304,7 @@ function App() {
 ```
 
 **Translation keys used:**
+
 - `'Thinking...'`
 - `'Using tools…'`
 - `'Analyzing results…'`
@@ -270,6 +318,7 @@ function App() {
 - `'Browse agents'`
 - `'Create agent'`
 - `'Reasoning details'`
+- `'Download'`
 - `'tool call'` / `'tool calls'`
 - `'Uses AI. Verify results.'`
 - `'How can I help you, '`

package/dist/index.d.ts

@@ -18,6 +18,20 @@ interface ApiEndpoints {
     sessions?: string | null;
     /** Path for uploading files. Default: '/chat/upload'. Set to null to disable file uploads. */
     upload?: string | null;
+    /**
+     * Base path for downloading agent-generated files. Default: '/chat/files'.
+     * The download URL is built as
+     * `${apiBaseUrl}${download}/${fileId}/download`, resolved against the
+     * host app's own backend proxy. This keeps the download authenticated by
+     * the host platform (e.g. OpenCTI / OpenAEV session) — the proxy mints
+     * any upstream token server-side, so the user never authenticates to the
+     * upstream chat service directly. Set to null to disable download chips.
+     *
+     * Exception: in `singleEndpoint` mode the `/chat/files` default is NOT
+     * applied (there is no per-path routing), so download cards stay disabled
+     * unless this path is set explicitly to a proxy route.
+     */
+    download?: string | null;
 }
 interface ChatPanelProps {
     mode: ChatMode;
@@ -51,12 +65,37 @@ interface ChatPanelProps {
     disableFileManagement?: boolean;
     /** Called when a relative markdown link is clicked in assistant messages. */
     onRelativeLinkClick?: (href: string) => void;
+    /**
+     * Called when an agent-generated file download fails (non-2xx response or
+     * network error). Lets the host surface the failure through its own
+     * notification system (the chatbot has no toast surface of its own).
+     */
+    onDownloadError?: (error: unknown, attachment: ChatAttachment) => void;
     /** Maximum number of files attachable in one chat context. Default: 10. */
     maxFileCount?: number;
     /** Maximum total size in bytes for attached files. Default: 50 * 1024 * 1024 (50 MB). */
     maxTotalSize?: number;
     /** Additional HTTP headers added to chatbot API requests (messages, sessions, agents, uploads). */
     requestHeaders?: Record<string, string>;
+    /**
+     * Arbitrary contextual metadata about the host page/application, forwarded
+     * to the backend alongside every message as a `context` JSON object so the
+     * agent is aware of where the user is.
+     *
+     * The shape is up to the host. Today it typically carries the current
+     * relative URL, e.g.
+     * `{ url: '/dashboard/analyses/reports/<id>/overview' }`, and can be
+     * extended later (page title, selected entity, user role, etc.).
+     *
+     * Must be JSON-serializable — it is sent via `JSON.stringify`. A
+     * non-serializable value (circular reference, `BigInt`, etc.) is skipped
+     * rather than thrown, so it can never break message sending.
+     *
+     * Read fresh at send time, so it always reflects the page the user is on
+     * when the message is sent (not when the panel was opened). Only emitted
+     * for the `rest` backend, and omitted entirely when empty.
+     */
+    pageContext?: Record<string, unknown>;
     /**
      * CSS selector for the main content element that should be pushed when sidebar is open.
      * When set, the component will automatically apply margin-right to push the content.
@@ -84,10 +123,34 @@ interface ChatMessage {
     content: string;
     timestamp: Date;
     files?: ChatFile[];
+    /** Agent-generated downloadable files attached to an assistant message. */
+    attachments?: ChatAttachment[];
     toolNames?: string[];
     toolCallCount?: number;
     iterations?: number;
 }
+/**
+ * An agent-generated file produced during a chat turn (via the backend
+ * `generate_file` tool / custom-tool `$output_files`). Rendered as a
+ * download card in assistant messages.
+ *
+ * Intentionally carries no absolute URL: the download is resolved against
+ * the host app's backend proxy from `fileId` (see `ApiEndpoints.download`)
+ * so the user stays authenticated to the host platform only.
+ */
+interface ChatAttachment {
+    fileId: string;
+    filename: string;
+    /** Short extension-style label surfaced under the filename (e.g. "PDF"). */
+    type?: string;
+    size?: number;
+    contentType?: string;
+    /**
+     * `download_file` → prominent download card (user deliverable).
+     * `working_file` → de-emphasized scratch/working artifact chip.
+     */
+    fileTag?: 'download_file' | 'working_file';
+}
 interface ChatFile {
     name: string;
     type: string;
@@ -117,4 +180,4 @@ interface TransferredAgent {
 }
 
 export { ChatPanel, ChatToggleButton };
-export type { ApiEndpoints, BackendType, ChatFile, ChatMessage, ChatMode, ChatPanelProps, ChatToggleButtonProps, TransferredAgent, XtmAgent };
+export type { ApiEndpoints, BackendType, ChatAttachment, ChatFile, ChatMessage, ChatMode, ChatPanelProps, ChatToggleButtonProps, TransferredAgent, XtmAgent };