@botpress/webchat 4.3.2 → 4.4.0

package/ARCHITECTURE.md

@@ -0,0 +1,737 @@
+Webchat Components Architecture
+
+## Target Architecture
+
+### Component Tree
+
+```
+<WebchatProvider clientId apiUrl userCredentials conversationId>
+  Context {
+    client: Client (raw HTTP client, not scoped)
+    clientState, setClientState
+    conversationId
+    userCredentials (UserCredentials)
+    error, setError
+    emitter (full event emitter object)
+    openConversation
+    isTyping
+    isAwaitingResponse
+    setAwaitingResponse
+  }
+
+  // Hooks available inside provider (subscribe to stores + build scoped clients):
+  // const { messages, participants, sendMessage, saveMessageFeedback, sendEvent, uploadFile, conversationId, status, on, error, isTyping, isAwaitingResponse } = useActiveConversation()
+  // const { listConversations, openConversation } = useConversations()
+  // const { getUser, updateUser } = useUser()
+  //
+  // Future: useConversations will include reactive history
+  // const { listConversations, openConversation, history: { data, isLoading, error, refetch } } = useConversations()
+
+  <Chat />
+</WebchatProvider>
+```
+
+### Core Concepts
+
+#### WebchatProvider
+
+- Top-level provider component that **replaces the deprecated `useWebchat` hook**
+- Props: `clientId`, `apiUrl`, `userCredentials`, `conversationId`
+- **Only responsible for initialization**: creates client, starts conversation, sets up event handlers
+- Context exposes connection state + the raw `Client` — but NOT a `ScopedClient`, NOT actions, NOT conversation data
+- Does NOT contain rendering logic
+
+**Migration from `useWebchat`:** The `useWebchat` hook is deprecated. Use `WebchatProvider` with the new hooks (`useActiveConversation`, `useConversations`, `useUser`) instead. See Migration Path section for details.
+
+#### Context — What it provides
+
+The context is purely connection state:
+
+- `client` — the raw `Client` instance (not scoped). Hooks use this to implement actions.
+- `clientState` — `'connecting' | 'connected' | 'error' | 'disconnected'`
+- `setClientState` — function to update the client state
+- `conversationId` — active conversation ID
+- `userCredentials` — `UserCredentials` (`userId`, `userToken`)
+- `error` — `WebchatError | undefined`
+- `setError` — function to update the error state
+- `emitter` — full event emitter object (includes `on`, `emit`, etc.)
+- `openConversation` — opens/switches to a conversation (accepts object with `conversationId?` and `userToken?`, returns Promise)
+- `isTyping` — boolean (set by event handlers in the provider)
+- `isAwaitingResponse` — boolean (set by event handlers in the provider)
+- `setAwaitingResponse` — function to update the awaiting response state
+
+The context does **not** provide conversation data (`messages`, `participants`) or actions (`sendMessage`, `uploadFile`, etc.). Those belong in the hooks.
+
+#### Hooks — Where data + actions live
+
+Each hook reads `client`, `conversationId`, and `user` from context, subscribes to stores for reactive data, and implements its own scoped operations:
+
+**Public Hooks (exported to consumers):**
+
+- **`useActiveConversation()`** — `messages`, `participants`, `sendMessage`, `saveMessageFeedback`, `sendEvent`, `uploadFile`, `conversationId`, `status`, `on`, `error`, `isTyping`, `isAwaitingResponse` (operations on the current active conversation + connection state)
+- **`useConversations()`** — `listConversations`, `openConversation` (conversation management and switching). Future: will include `history` for reactive conversation list.
+- **`useUser()`** — `getUser`, `updateUser`
+
+**Internal Hooks (NOT exported publicly):**
+
+- **`useMessages()`** — message data and actions (used internally by `useWebchat` and `useActiveConversation`)
+- **`useParticipants()`** — participant data (used internally by `useWebchat` and `useActiveConversation`)
+- **`useEvent()`** — event subscription and emission (used internally by `useWebchat` and `useActiveConversation`)
+- **`useFiles()`** — file upload functionality (used internally by `useWebchat` and `useActiveConversation`)
+- **`useConversationList()`** — SWR-based conversation list with caching (used internally by `useConversations`). Returns `conversations`, `isLoading`, `error`, `refresh`.
+- **`useInitialization()`** — initialization logic (used internally by `WebchatProvider`)
+
+This separation means:
+
+- Context is purely connection state (what came out of initialization)
+- Hooks own all conversation data (via store subscriptions) and all actions (via raw client)
+- Public hooks can be used independently inside the provider
+- Hooks subscribe to stores directly — they don't go through context for conversation data
+- During migration, `useActiveConversation` internally composes `useMessages`, `useParticipants`, `useEvent`, and `useFiles` to provide a unified API
+
+#### Plugin System (Future)
+
+- Not implemented yet, placeholder for future feature
+- Idea: plugins as objects with event handler hooks using middleware pattern
+- Each handler receives a `vanilla` callback (the default behavior)
+
+```typescript
+// Future API concept:
+type Plugin = {
+  onMessageCreated?: (vanilla: () => void) => void
+}
+
+const myPlugin: Plugin = {
+  onMessageCreated: (vanilla) => {
+    doSomething()
+    vanilla()
+  },
+}
+```
+
+---
+
+## Implementation Plan
+
+### Context Shape
+
+```typescript
+type ClientStates = 'connecting' | 'connected' | 'error' | 'disconnected'
+
+type WebchatContext = {
+  // Raw HTTP client — hooks use this to implement actions
+  client: Client | undefined
+
+  // Connection state
+  clientState: ClientStates
+  setClientState: (state: ClientStates) => void
+  conversationId: string | undefined
+  userCredentials: UserCredentials | undefined
+  error: WebchatError | undefined
+  setError: (error?: WebchatError) => void
+
+  // UI state (set by event handlers in the provider)
+  isTyping: boolean
+  isAwaitingResponse: boolean
+  setAwaitingResponse: (state: boolean, timeout?: number) => void
+
+  // Controls
+  openConversation: (params: { conversationId?: string; userToken?: string }) => Promise<void>
+
+  // Events
+  emitter: ReturnType<typeof createEventEmitter<Events>>
+}
+```
+
+### useActiveConversation Hook
+
+```typescript
+type UseActiveConversationReturn = {
+  // Conversation ID
+  conversationId?: string
+
+  // Reactive state (subscribed to stores directly)
+  messages: BlockMessage[]
+  participants: User[]
+
+  // Actions (business logic: HTTP queries + store mutations)
+  sendMessage: (payload: IntegrationMessage['payload']) => Promise<void>
+  saveMessageFeedback: (messageId: string, feedback: Feedback) => Promise<void>
+  sendEvent: (
+    event: Record<string, unknown>,
+    options?: { bindConversation?: boolean; bindUser?: boolean }
+  ) => Promise<void>
+  uploadFile: (file: File) => Promise<{ fileUrl: string; name: string; type: FileType; fileId: string }>
+
+  // Connection state
+  status: ClientStates
+  error?: WebchatError
+  isTyping: boolean
+  isAwaitingResponse: boolean
+
+  // Event subscription
+  on: ReturnType<typeof createEventEmitter<Events>>['on']
+}
+```
+
+The hook internally:
+
+1. Reads `client`, `conversationId`, `user` from context
+2. **During migration**: composes internal hooks to provide unified API:
+   - Calls `useMessages()` to get `messages`, `sendMessage`, `saveMessageFeedback`
+   - Calls `useParticipants()` to get `participants`
+   - Calls `useEvent()` to get `sendEvent`
+   - Calls `useFiles()` to get `uploadFile`
+
+**Note**: The internal hooks (`useMessages`, `useParticipants`, `useEvent`, `useFiles`) handle:
+
+- Store subscriptions (e.g., `getUseMessagesStore(conversationId)` for reactive data)
+- Business logic (e.g., optimistic updates with clientMessageId, nanoid in `sendMessage`)
+- HTTP operations (e.g., presigned URL upload in `uploadFile`)
+
+### useConversations Hook
+
+```typescript
+type UseConversationsReturn = {
+  listConversations: () => Promise<ListConversationsResponse>
+  openConversation: (conversationId?: string) => void
+}
+```
+
+The hook internally:
+
+1. Reads `client`, `openConversation`, `userCredentials` from context
+2. Implements `listConversations` via the raw client
+3. Exposes a wrapped `openConversation` from context for switching conversations
+
+**Note**: This hook provides conversation management operations (listing, switching between conversations). Use `useActiveConversation` for working with the current conversation's messages and participants. The current conversation ID is available via `useActiveConversation().conversationId`.
+
+### useUser Hook
+
+```typescript
+type UseUserReturn = {
+  getUser: () => Promise<UserResponse>
+  updateUser: (user: UserProfile) => Promise<User>
+}
+```
+
+The hook internally:
+
+1. Reads `client` from context
+2. Implements `getUser` and `updateUser` via the raw client
+
+### useEvent Hook (Internal - Migration)
+
+```typescript
+type UseEventProps = {
+  client?: Client
+  conversationId?: string
+  user?: UserCredentials
+}
+
+type UseEventReturn = {
+  sendEvent: (
+    event: Record<string, unknown>,
+    options?: { bindConversation?: boolean; bindUser?: boolean }
+  ) => Promise<void>
+}
+```
+
+The hook internally:
+
+1. Accepts `client`, `conversationId`, `user` as props for composability
+2. Implements `sendEvent` via the raw client (creates event with optional binding)
+
+**Note**: This hook is NOT exported publicly. It's used internally by `useWebchat` (deprecated) and `useConversation` during the migration period. Consumers access event sending through `useConversation().sendEvent` and event subscription through context's `on`.
+
+### useMessages Hook (Internal - Migration)
+
+```typescript
+type UseMessagesReturn = {
+  messages: BlockMessage[]
+  sendMessage: (payload: IntegrationMessage['payload']) => Promise<void>
+  saveMessageFeedback: (messageId: string, feedback: Feedback) => Promise<void>
+}
+```
+
+The hook internally:
+
+1. Reads `client`, `conversationId`, `user` from context
+2. Subscribes to `getUseMessagesStore(conversationId)` for reactive `messages`
+3. Implements `sendMessage` business logic (optimistic updates with clientMessageId, nanoid)
+4. Implements `saveMessageFeedback` (local-first update + HTTP call)
+
+**Note**: This hook is NOT exported publicly. It's used internally by `useWebchat` (deprecated) and `useConversation` during the migration period. Consumers access messages through `useConversation().messages`. The method was renamed from `updateMessageFeedback` to `saveMessageFeedback` for consistency with store terminology.
+
+### useParticipants Hook (Internal - Migration)
+
+```typescript
+type UseParticipantsReturn = {
+  participants: User[]
+}
+```
+
+The hook internally:
+
+1. Reads `conversationId` from context
+2. Subscribes to `getUseParticipantStore(conversationId)` for reactive `participants`
+
+**Note**: This hook is NOT exported publicly. It's used internally by `useWebchat` (deprecated) and `useConversation` during the migration period. Consumers access participants through `useConversation().participants`.
+
+### useFiles Hook (Internal - Migration)
+
+```typescript
+type UseFilesProps = {
+  client?: Client
+  conversationId?: string
+  user?: UserCredentials
+}
+
+type UseFilesReturn = {
+  uploadFile: (file: File) => Promise<{ fileUrl: string; name: string; type: FileType; fileId: string }>
+}
+```
+
+The hook internally:
+
+1. Accepts `client`, `conversationId`, `user` as props (not from context) for composability
+2. Implements `uploadFile` (file buffer reading via `getFileBuffer` utility, presigned URL upload, etc.)
+
+**Note**: This hook is NOT exported publicly. It's used internally by `useWebchat` (deprecated) and `useConversation` during the migration period. Consumers access file upload through `useConversation().uploadFile`.
+
+**Implementation Detail**: Refactored to accept props instead of reading from context directly, making it properly composable within both `useWebchat` and `useConversation`. The `getFileBuffer` utility is extracted to `src/utils/file.ts` for reuse.
+
+### Usage in WebchatProvider
+
+```typescript
+// Provider creates the raw client and manages stores directly
+const [httpClient, setHttpClient] = useState<Client | undefined>(undefined)
+
+// In openConversation (initialization):
+const messagesStore = getUseMessagesStore(conversation.id)
+messagesStore.getState().setMessages(blockMessages)
+
+const participantsStore = getUseParticipantStore(conversation.id)
+participantsStore.getState().setParticipants(participants)
+
+// Event handlers access stores directly (no closure issues):
+on('message_created', (ev) => {
+  messagesStore.getState().saveMessage(integrationMessageToBlockMessage(ev))
+})
+on('participant_added', (ev) => {
+  participantsStore.getState().addParticipant(ev.participant)
+})
+
+// Context value — purely connection state:
+const contextValue = {
+  client: httpClient,
+  clientState,
+  setClientState,
+  conversationId: activeConversationId,
+  userCredentials,
+  error,
+  setError,
+  isTyping,
+  isAwaitingResponse,
+  setAwaitingResponse,
+  openConversation,
+  emitter,
+}
+```
+
+### Usage by Consumers
+
+```typescript
+// Inside WebchatProvider — hooks read from context + stores:
+const {
+  conversationId,
+  messages,
+  participants,
+  sendMessage,
+  saveMessageFeedback,
+  uploadFile,
+  sendEvent,
+  status,
+  error,
+  isTyping,
+  isAwaitingResponse,
+  on,
+} = useActiveConversation()
+
+const { listConversations, openConversation } = useConversations()
+const { getUser, updateUser } = useUser()
+
+// Example: Subscribe to events
+on('message_created', (event) => {
+  console.log('New message:', event)
+})
+
+// Example: Switch conversations
+const response = await listConversations()
+openConversation(response.conversations[0].id)
+
+// Future: Reactive conversation history
+// const { history, openConversation } = useConversations()
+// if (history.isLoading) return <Spinner />
+// history.data.map(conv => <ConversationItem key={conv.id} onClick={() => openConversation(conv.id)} />)
+```
+
+---
+
+## Data Flow
+
+1. `WebchatProvider` receives `clientId`, `apiUrl`, `userCredentials`, `conversationId`
+2. Provider initializes connection via `initializeConversation`
+3. Populates message and participant stores directly (imperative access)
+4. Sets up event handlers that mutate stores directly (no closure issues)
+5. Context exposes connection state + raw client to children
+6. `useConversation` subscribes to stores for reactive data (`messages`, `participants`)
+7. Hooks (`useActiveConversation`, `useConversations`, `useUser`) read `client` from context and implement actions, with `useActiveConversation` internally composing `useMessages`, `useParticipants`, `useEvent`, and `useFiles`
+8. `<Chat />` and other components consume context + hooks
+
+## Store Architecture
+
+- **Message store**: per-conversation Zustand store (`getUseMessagesStore(convId)`)
+  - Keyed by `messages-{conversationId}` (no custom storageKey prefix)
+  - NOT persisted (in-memory only)
+  - Has `saveMessage` for clientMessageId deduplication
+- **Participant store**: per-conversation Zustand store (`getUseParticipantStore(convId)`)
+  - Keyed by `participants-{conversationId}` (no custom storageKey prefix)
+  - NOT persisted (in-memory only)
+- **Composer file store**: per-conversation Zustand store (accessed via `useFiles` hook)
+  - Stores files being composed in the message composer
+  - Persisted to localStorage for persistence across page reloads
+  - Managed internally by `useFiles` hook
+- Stores populated imperatively by the provider (init + event handlers)
+- Stores subscribed reactively by hooks (`useActiveConversation`) for React rendering
+
+## Key Design Decisions
+
+- **`useWebchat` is DEPRECATED** — migrate to `WebchatProvider` with `useActiveConversation`, `useConversations`, and `useUser` hooks
+- Context is purely connection state — no conversation data, no actions
+- Conversation data (`messages`, `participants`) lives in hooks via direct store subscriptions
+- Actions live in hooks (`useActiveConversation`, `useConversations`, `useUser`), not in the context
+- Context provides the raw `Client`, NOT a `ScopedClient` — hooks build scoped operations themselves
+- Event handlers access stores directly via `store.getState()` (not through hook closures)
+- Provider handles all initialization; child components are purely presentational
+- Strict Mode double-mount handled with `cancelled` flag in useEffect
+- Internal hooks (`useMessages`, `useParticipants`, `useEvent`, `useFiles`) are composed by public hooks to provide focused functionality
+- Shared utilities extracted to `src/utils/` (e.g., `getFileBuffer`)
+- Method naming follows store conventions: `saveMessageFeedback` (not `updateMessageFeedback` or `addMessageFeedback`)
+
+## Migration Path
+
+### ⚠️ Deprecation Notice
+
+**`useWebchat` is deprecated.** Please migrate to the new provider-based architecture.
+
+#### Before (Deprecated):
+
+```typescript
+import { useWebchat } from '@botpress/webchat'
+
+function MyComponent() {
+  const { messages, participants, client, sendMessage, listConversations } = useWebchat({ clientId, apiUrl, user })
+
+  // Use the data...
+}
+```
+
+#### After (Recommended):
+
+```typescript
+import { WebchatProvider, useActiveConversation, useConversations, useUser } from '@botpress/webchat'
+
+function App() {
+  return (
+    <WebchatProvider clientId={clientId} apiUrl={apiUrl} user={user}>
+      <MyComponent />
+    </WebchatProvider>
+  )
+}
+
+function MyComponent() {
+  // Active conversation operations + connection state
+  const {
+    conversationId,
+    messages,
+    participants,
+    sendMessage,
+    uploadFile,
+    status,
+    error,
+    isTyping,
+    isAwaitingResponse,
+    on
+  } = useActiveConversation()
+
+  // Conversation management
+  const { listConversations, openConversation } = useConversations()
+
+  // User operations
+  const { getUser, updateUser } = useUser()
+
+  // Use the data...
+}
+```
+
+### Migration Details
+
+- `useWebchat` → deprecated, initialization logic moves into `WebchatProvider`. During migration, `useWebchat` composes `useMessages`, `useParticipants`, and `useFiles` internally.
+- `useMessages` → refactored as internal hook with message data + actions, NOT exported publicly
+- `useParticipants` → refactored as internal hook with participant data, NOT exported publicly
+- `useEvent` → created as internal hook for event operations, NOT exported publicly
+- `useFiles` → created as internal hook for file upload, NOT exported publicly
+- `useActiveConversation` → new public hook that composes `useMessages`, `useParticipants`, `useEvent`, and `useFiles` internally to provide unified API for the active conversation. Returns conversation data, actions, connection state, and event subscription.
+- `useConversations` → new public hook for conversation management (listing, switching conversations)
+- `useConversationList` → internal hook using SWR for cached conversation list (NOT exported publicly, used internally by `useConversations`)
+- `ScopedClient` methods → split across `useActiveConversation` (messages, events, file uploads), `useConversations` (conversation management), and `useUser` (user operations)
+- Public API exposes `useActiveConversation` (current conversation operations + state), `useConversations` (conversation management), and `useUser` (user operations)
+- Internal hooks (useMessages, useParticipants, useEvent, useFiles, useInitialization, useConversationList) are NO LONGER exported publicly
+- Stores remain unchanged (they are the source of truth)
+
+**Internal Hook Composition Pattern:**
+Both deprecated `useWebchat` and new `useActiveConversation` internally use:
+
+- `useMessages()` for message data and actions
+- `useParticipants()` for participant data
+- `useEvent()` for event subscription and emission
+- `useFiles()` for file uploads
+
+This allows code reuse during migration while presenting a clean public API.
+
+---
+
+## Future Roadmap
+
+### Planned API Changes
+
+#### 1. Enhanced `useConversations` Hook
+
+**Current State:**
+
+```typescript
+const { listConversations, openConversation } = useConversations()
+
+// Manual conversation list management
+const conversations = await listConversations()
+```
+
+**Future State:**
+The `useConversations` hook will internally use `useConversationList` (which will remain internal) to provide reactive conversation history with SWR-based caching:
+
+```typescript
+const {
+  // Actions
+  listConversations, // One-off manual fetch
+  openConversation, // Switch to a conversation
+
+  // Reactive conversation history (SWR-powered)
+  history: {
+    data, // Conversations array (sorted, filtered, enriched)
+    error, // WebchatError | undefined
+    isLoading, // boolean
+    refetch, // () => Promise<void>
+  },
+} = useConversations()
+```
+
+**Benefits:**
+
+- **Single source of truth** - All conversation operations in one hook
+- **Reactive by default** - Components automatically re-render when history changes
+- **Grouped state** - Related data grouped under `history` namespace
+- **Automatic caching** - SWR handles deduplication, revalidation, and cache management
+- **Clean API** - `useConversationList` stays internal, reducing API surface
+
+**Implementation:**
+
+- `useConversationList` will remain an internal hook (not exported)
+- `useConversations` will compose `useConversationList` internally
+- The `history` object provides the SWR-powered reactive state
+- Consumers use a single hook instead of two
+
+**Example Usage:**
+
+```typescript
+function ConversationSwitcher() {
+  const { history, openConversation } = useConversations()
+
+  if (history.isLoading) return <Spinner />
+  if (history.error) return <Error error={history.error} />
+
+  return (
+    <div>
+      {history.data.map(conv => (
+        <button key={conv.id} onClick={() => openConversation(conv.id)}>
+          {conv.lastMessage.text}
+        </button>
+      ))}
+      <button onClick={history.refetch}>Refresh</button>
+    </div>
+  )
+}
+```
+
+#### 2. Consistent Reactive State Pattern Across All Hooks
+
+All public hooks will adopt the same pattern of grouping reactive state into nested objects, similar to the `history` pattern:
+
+**Examples:**
+
+```typescript
+// useActiveConversation - Future state grouping
+const {
+  // Current conversation
+  conversationId,
+
+  // Reactive message state
+  messages: {
+    data, // BlockMessage[]
+    isLoading,
+    error,
+  },
+
+  // Reactive participant state
+  participants: {
+    data, // User[]
+    isLoading,
+    error,
+  },
+
+  // Actions
+  sendMessage,
+  saveMessageFeedback,
+  sendEvent,
+  uploadFile,
+
+  // Connection state
+  status,
+  on,
+  isTyping,
+  isAwaitingResponse,
+} = useActiveConversation()
+
+// useUser - Future state grouping
+const {
+  profile: {
+    data, // UserProfile
+    isLoading,
+    error,
+    refetch,
+  },
+  updateUser,
+} = useUser()
+```
+
+**Benefits:**
+
+- Consistent API patterns across all hooks
+- Clear distinction between actions and reactive state
+- Better TypeScript inference
+- Easier to understand loading and error states
+
+#### 3. Optional Override Functions
+
+Public hooks will accept optional configuration to override default behavior:
+
+```typescript
+// Custom file upload implementation
+const { uploadFile } = useActiveConversation({
+  customUploadFile: async (file: File) => {
+    // Custom upload logic (e.g., direct S3 upload, compression, etc.)
+    const url = await myCustomUploadService(file)
+    return { fileUrl: url, name: file.name, type: 'image', fileId: generateId() }
+  },
+})
+
+// Custom message sending
+const { sendMessage } = useActiveConversation({
+  customSendMessage: async (payload) => {
+    // Custom pre-processing, validation, etc.
+    await validateMessage(payload)
+    return defaultSendMessage(payload)
+  },
+})
+
+// Custom conversation list fetching
+const { history } = useConversations({
+  customListConversations: async () => {
+    // Custom filtering, sorting, or data source
+    return await myCustomConversationSource()
+  },
+})
+```
+
+**Use Cases:**
+
+- Custom file upload services (direct S3, Cloudinary, etc.)
+- Message preprocessing/validation
+- Custom data sources or caching strategies
+- Analytics tracking on actions
+- Rate limiting or throttling
+- Custom error handling
+
+**Implementation Pattern:**
+
+```typescript
+type UseActiveConversationOptions = {
+  customUploadFile?: (file: File) => Promise<UploadResult>
+  customSendMessage?: (payload: MessagePayload) => Promise<void>
+  onError?: (error: WebchatError) => void
+}
+
+function useActiveConversation(options?: UseActiveConversationOptions) {
+  // Use custom implementations when provided, fall back to defaults
+  const uploadFile = options?.customUploadFile ?? defaultUploadFile
+  // ...
+}
+```
+
+#### 4. Internal Hooks
+
+The following hooks will remain internal (not exported publicly):
+
+- `useMessages` - Message data and actions
+- `useParticipants` - Participant data
+- `useEvent` - Event operations
+- `useFiles` - File upload functionality
+- `useInitialization` - Provider initialization logic
+- **`useConversationList`** - SWR-based conversation list (used by `useConversations`)
+
+**Rationale:**
+
+- Reduces API surface area
+- Encourages using the high-level, composed hooks
+- Allows internal refactoring without breaking changes
+- Provides clear migration path for consumers
+
+---
+
+## Files
+
+### Created
+
+- ✅ `src/providers/WebchatProvider.tsx` — provider component
+- ✅ `src/hooks/useActiveConversation.ts` — active conversation data + actions hook (composes `useMessages`, `useParticipants`, `useEvent`, `useFiles` internally)
+- ✅ `src/hooks/useConversations.ts` — conversation management hook (list, switch conversations)
+- ✅ `src/hooks/useUser.ts` — user actions hook
+- ✅ `src/hooks/useEvent.ts` — internal event hook (NOT exported publicly, used by `useWebchat` and `useActiveConversation`)
+- ✅ `src/hooks/useFiles.ts` — internal file upload hook (NOT exported publicly, used by `useWebchat` and `useActiveConversation`)
+- ✅ `src/utils/file.ts` — file utilities (`getFileBuffer`)
+
+### Modified
+
+- ✅ `src/hooks/useWebchat.ts` — deprecated, refactored to compose `useMessages`, `useParticipants`, `useEvent`, `useFiles` internally
+- ✅ `src/hooks/useMessages.ts` — refactored to internal implementation (NOT exported publicly), renamed `updateMessageFeedback` → `saveMessageFeedback`
+- ✅ `src/hooks/useParticipants.ts` — refactored to internal implementation (NOT exported publicly)
+- ✅ `src/hooks/useFiles.ts` — refactored to accept props for composability (no longer reads from context directly)
+- ✅ `src/hooks/index.ts` — exports public hooks (`useActiveConversation`, `useConversations`, `useUser`) only; internal hooks (useMessages, useParticipants, useEvent, useFiles, useInitialization, useConversationList) are no longer exported
+- ✅ `src/providers/index.ts` — exports `WebchatProvider`
+- ✅ `src/index.ts` — exports new public API (`useActiveConversation`, `useConversations`, `useUser`, `useWebchat`)
+- ✅ `src/types/client.ts` — exports `UserResponse`, `UserProfile`, `User` types
+- ✅ `src/utils/index.ts` — re-exports file utilities
+
+### Deleted
+
+- ✅ `src/utils/uploadFile.ts` — functionality moved into `useFiles` hook