You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
|`aiChat.tools.handlerMissing`| No client-side handler registered for tool "\{\{toolName\}\}". The page context may have changed while the response was streaming. |
180
+
|`aiChat.tools.id`| ID: \{\{id\}\}|
181
+
|`aiChat.tools.input`| Input |
182
+
|`aiChat.tools.output`| Output |
183
+
|`aiChat.tools.status.complete`| Complete |
184
+
|`aiChat.tools.status.error`| Error |
185
+
|`aiChat.tools.status.executing`| Executing... |
186
+
|`aiChat.tools.status.pending`| Pending |
187
+
|`aiChat.tools.status.running`| Running... |
188
+
116
189
Other plugins adopt the same convention as their phase-2 sweeps land.
Copy file name to clipboardExpand all lines: docs/content/docs/plugins/ai-chat.mdx
+83-9Lines changed: 83 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -347,11 +347,11 @@ The AI Chat plugin supports two distinct modes:
347
347
The AI Chat plugin provides the following API endpoints (mounted at your configured `apiBasePath`):
348
348
349
349
-**POST**`/chat` - Send a message and receive streaming response
350
-
-**GET**`/conversations` - List all conversations (authenticated mode only)
351
-
-**GET**`/conversations/:id` - Get a conversation with messages
352
-
-**POST**`/conversations` - Create a new conversation
353
-
-**PUT**`/conversations/:id` - Update (rename) a conversation
354
-
-**DELETE**`/conversations/:id` - Delete a conversation
350
+
-**GET**`/chat/conversations` - List all conversations (authenticated mode only)
351
+
-**GET**`/chat/conversations/:id` - Get a conversation with messages
352
+
-**POST**`/chat/conversations` - Create a new conversation
353
+
-**PUT**`/chat/conversations/:id` - Rename a conversation; the title is trimmed and must not be empty
354
+
-**DELETE**`/chat/conversations/:id` - Delete a conversation
355
355
356
356
### Page Routes
357
357
@@ -397,7 +397,30 @@ aiChatClientPlugin({
397
397
398
398
### Adding Authorization
399
399
400
-
To add authorization rules and customize behavior, you can use the lifecycle hooks defined in the API Reference section below. These hooks allow you to control access to API endpoints, add logging, and customize the plugin's behavior to fit your application's needs.
400
+
Use the `auth` provider on `StackProvider` for client-side route and control visibility, and backend lifecycle hooks for authoritative API authorization. Authenticated mode uses this permission map:
401
+
402
+
| Resource | Action | UI covered |
403
+
| --- | --- | --- |
404
+
|`ai-chat:conversation`|`read`|`/chat`, `/chat/:id`, and conversation history |
405
+
|`ai-chat:conversation`|`create`| New chat and the first persisted send |
406
+
|`ai-chat:conversation`|`update`| Continue, retry, edit, and rename; receives `{ id }` when available |
407
+
|`ai-chat:conversation`|`delete`| Delete; receives `{ id }`|
Without an auth provider, permission checks remain permissive for backward compatibility. Public mode intentionally bypasses conversation permission gates because it is stateless; protect the public streaming endpoint with backend rate limits or `onBeforeChat` as needed.
`useRenameConversationForm()` trims the submitted title, maps server validation issues to `fieldErrors.title`, sends success and non-field failures through the `StackProvider``notify` provider, and preserves the conversation detail cache while refreshing the list.
769
+
740
770
**Example usage:**
741
771
742
772
```tsx
@@ -745,6 +775,7 @@ import {
745
775
useConversation,
746
776
useCreateConversation,
747
777
useRenameConversation,
778
+
useRenameConversationForm,
748
779
useDeleteConversation,
749
780
} from"@btst/stack/plugins/ai-chat/client/hooks"
750
781
@@ -777,6 +808,35 @@ function ConversationsList() {
777
808
}
778
809
```
779
810
811
+
For a custom rename dialog, prefer the form lifecycle over calling the raw mutation directly:
812
+
813
+
```tsx
814
+
const renameForm =useRenameConversationForm({
815
+
conversation,
816
+
onSuccess: () =>setOpen(false),
817
+
})
818
+
819
+
awaitrenameForm.submit({ title })
820
+
821
+
returnrenameForm.fieldErrors.title? (
822
+
<prole="alert">{renameForm.fieldErrors.title}</p>
823
+
) :null
824
+
```
825
+
826
+
### Query keys and resource declaration
827
+
828
+
The server-safe query-key entry point exposes both the factory and the underlying declaration:
829
+
830
+
```ts
831
+
import {
832
+
aiChatResources,
833
+
createAiChatQueryKeys,
834
+
typeAiChatQueryKeys,
835
+
} from"@btst/stack/plugins/ai-chat/query-keys"
836
+
```
837
+
838
+
The stable keys remain `['conversations', 'list', 'all']` and `['conversations', 'detail', id]`, so existing dehydrated caches and manual invalidations continue to match.
839
+
780
840
## Model & Tools Configuration
781
841
782
842
### Using Different Models
@@ -988,7 +1048,7 @@ overrides={{
988
1048
```
989
1049
990
1050
<Callouttype="info">
991
-
In public mode, the sidebar is hidden, conversation history is not saved to the database, and only the `/chat` route is available.
1051
+
In public mode, the sidebar is hidden, conversation history is not saved to the database, only the `/chat` route is available, and client conversation permission gates are bypassed.
992
1052
</Callout>
993
1053
994
1054
### Local Storage Persistence
@@ -1036,9 +1096,9 @@ This pattern enables:
1036
1096
-**IndexedDB** - Larger storage for long conversations
1037
1097
-**External state management** - Redux, Zustand, etc.
1038
1098
1039
-
## Localization
1099
+
## Localization and notifications
1040
1100
1041
-
Customize UI strings by providing a `localization` override:
1101
+
All rendered AI Chat copy is routed through the `StackProvider``i18n` provider with `aiChat.<area>.<name>` keys. The legacy `localization` override remains supported and takes precedence when both are configured:
Rename, delete, and file-upload feedback uses the shared `notify` provider. Field validation and streaming errors remain inline:
1123
+
1124
+
```tsx
1125
+
<StackProvider
1126
+
notify={{
1127
+
success: (message) =>myToast.success(message),
1128
+
error: (message) =>myToast.error(message),
1129
+
}}
1130
+
// ...
1131
+
>
1132
+
{children}
1133
+
</StackProvider>
1134
+
```
1135
+
1062
1136
## Server-side Data Access
1063
1137
1064
1138
The AI Chat plugin exposes standalone getter functions for server-side use cases, giving you direct access to conversation history without going through HTTP.
0 commit comments