@arbidocs/react 0.3.16 → 0.3.17

package/README.md

@@ -1,16 +1,14 @@
 # @arbidocs/react
 
-React hooks and provider for the ARBI SDK. Built on `@arbidocs/sdk` and `@tanstack/react-query`.
+React hooks and provider for building ARBI-powered apps. Includes `@arbidocs/sdk` and `@tanstack/react-query` — one install gets you everything.
 
-## Install
+## Quickstart
 
 ```bash
 npm install @arbidocs/react
 ```
 
-## Quick Start
-
-Wrap your app with `ArbiProvider` and a React Query `QueryClientProvider`:
+### 1. Set up providers
 
 ```tsx
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
@@ -21,142 +19,108 @@ const queryClient = new QueryClient()
 function App() {
   return (
     <QueryClientProvider client={queryClient}>
-      <ArbiProvider url="https://arbi.mycompany.com">
-        <MyApp />
+      <ArbiProvider url="https://www.arbidocs.com">
+        <Chat />
       </ArbiProvider>
     </QueryClientProvider>
   )
 }
 ```
 
-Then use the hooks in any component:
+### 2. Build a streaming chat
 
 ```tsx
-import { useArbi, useWorkspaces, useDocuments } from '@arbidocs/react'
+import { useState, useRef } from 'react'
+import { useArbi, useDocuments, useAssistantQuery } from '@arbidocs/react'
 
-function WorkspaceView() {
+function Chat() {
   const arbi = useArbi()
-  const { data: workspaces, isLoading } = useWorkspaces()
+  const [workspaceId, setWorkspaceId] = useState<string>()
+
+  if (!workspaceId) {
+    return (
+      <button onClick={async () => {
+        await arbi.login('user@example.com', 'password')
+        const ws = await arbi.workspaces.list()
+        await arbi.selectWorkspace(ws[0].external_id)
+        setWorkspaceId(ws[0].external_id)
+      }}>
+        Connect
+      </button>
+    )
+  }
+
+  return <ChatWindow workspaceId={workspaceId} />
+}
 
-  if (isLoading) return <div>Loading...</div>
+function ChatWindow({ workspaceId }: { workspaceId: string }) {
+  const { data: docs } = useDocuments(workspaceId)
+  const mutation = useAssistantQuery()
+  const [input, setInput] = useState('')
+  const [response, setResponse] = useState('')
+  const lastId = useRef<string | null>(null)
 
   return (
-    <ul>
-      {workspaces?.map((ws) => (
-        <li key={ws.external_id}>{ws.name}</li>
-      ))}
-    </ul>
+    <div>
+      <div>{response}</div>
+      <form onSubmit={(e) => {
+        e.preventDefault()
+        setResponse('')
+        mutation.mutate({
+          question: input,
+          docIds: docs?.map((d) => d.external_id) ?? [],
+          previousResponseId: lastId.current,
+          onToken: (t) => setResponse((r) => r + t),
+          onStreamStart: ({ assistant_message_ext_id }) => {
+            lastId.current = assistant_message_ext_id
+          },
+        })
+        setInput('')
+      }}>
+        <input value={input} onChange={(e) => setInput(e.target.value)} />
+        <button type="submit" disabled={mutation.isPending}>Send</button>
+      </form>
+    </div>
   )
 }
 ```
 
-## Hooks
-
-### `useArbi()`
-
-Returns the `Arbi` instance from context. Use this for imperative operations like login, workspace selection, and direct API calls.
-
-```tsx
-const arbi = useArbi()
-
-await arbi.login('user@example.com', 'password')
-await arbi.selectWorkspace('wrk-123')
-```
-
-### `useWorkspaces(options?)`
-
-Fetches the user's workspaces. Automatically enabled when logged in.
-
-```tsx
-const { data, isLoading, error } = useWorkspaces()
-const { data } = useWorkspaces({ enabled: false }) // manual control
-```
-
-### `useDocuments(workspaceId, options?)`
-
-Fetches documents for a workspace. Automatically disabled when `workspaceId` is undefined.
-
-```tsx
-const { data: docs } = useDocuments('wrk-123')
-const { data: docs } = useDocuments(undefined) // won't fetch
-```
-
-### `useConversations(workspaceId, options?)`
-
-Fetches conversations for a workspace.
-
-```tsx
-const { data: conversations } = useConversations('wrk-123')
-```
-
-### `useTags(workspaceId, options?)`
-
-Fetches tags for a workspace.
+That's it — three hooks and you have a streaming RAG chat.
 
-```tsx
-const { data: tags } = useTags('wrk-123')
-```
+## Hooks
 
-### `useHealth(options?)`
+| Hook | Returns | Auto-enabled when |
+|------|---------|-------------------|
+| `useArbi()` | `Arbi` instance | Always |
+| `useWorkspaces()` | User's workspaces | Logged in |
+| `useDocuments(workspaceId)` | Workspace documents | Workspace selected |
+| `useConversations(workspaceId)` | Workspace conversations | Workspace selected |
+| `useTags(workspaceId)` | Workspace tags | Workspace selected |
+| `useAssistantQuery()` | Streaming mutation | Call `.mutate()` |
+| `useHealth()` | Backend status | Pass `{ enabled: true }` |
 
-Checks backend health.
+## Streaming callbacks
 
-```tsx
-const { data } = useHealth({ enabled: true })
-// { status: 'ok' }
-```
+Pass these to `mutation.mutate()` alongside `question` and `docIds`:
 
-### `useAssistantQuery()`
+| Callback | Description |
+|----------|-------------|
+| `onToken(token)` | Each text chunk as it streams |
+| `onStreamStart({ assistant_message_ext_id })` | Stream started — save the ID for follow-up queries |
+| `onAgentStep(step)` | Agent tool usage (searching, reading, etc.) |
+| `onError(message)` | Error during streaming |
+| `onComplete()` | Stream finished |
 
-Returns a React Query mutation for streaming AI queries.
-
-```tsx
-const mutation = useAssistantQuery()
-
-const handleAsk = () => {
-  mutation.mutate({
-    question: 'What does section 3 say?',
-    docIds: ['doc-123'],
-    onToken: (token) => setResponse((prev) => prev + token),
-    onComplete: () => console.log('Done'),
-  })
-}
-```
-
-## Query Keys
-
-All hooks use the `arbiQueryKeys` factory for cache management:
+## Cache invalidation
 
 ```tsx
 import { arbiQueryKeys } from '@arbidocs/react'
 import { useQueryClient } from '@tanstack/react-query'
 
 const queryClient = useQueryClient()
-
-// Invalidate all documents
-queryClient.invalidateQueries({ queryKey: arbiQueryKeys.documents('wrk-123') })
-
-// Available keys:
-arbiQueryKeys.workspaces()            // ['arbi', 'workspaces']
-arbiQueryKeys.documents(workspaceId)  // ['arbi', 'documents', workspaceId]
-arbiQueryKeys.conversations(workspaceId)
-arbiQueryKeys.tags(workspaceId)
-arbiQueryKeys.health()
+queryClient.invalidateQueries({ queryKey: arbiQueryKeys.documents(workspaceId) })
 ```
 
-## Re-exports
-
-The package re-exports key types from `@arbidocs/sdk/browser` for convenience:
-
-```tsx
-import { Arbi, ArbiError } from '@arbidocs/react'
-import type { ArbiOptions, QueryOptions, SSEStreamResult, SSEStreamCallbacks } from '@arbidocs/react'
-```
-
-## Examples
-
-See the **[React Chat App](../../examples/react-chat/)** for a complete working example with login, workspace selection, document picker, and streaming chat.
-
-## Peer Dependencies
+## Peer dependencies
 
 - `react` >= 18