@realtimexsco/live-chat 1.3.0 → 1.3.1

package/README.md

@@ -60,19 +60,20 @@ Socket.IO client, REST API client, Zustand store, Radix UI, emoji picker, and al
 17. [All component slots + examples](#all-component-slots--examples)
 18. [All classNames keys](#all-classnames-keys)
 19. [Wrapping package defaults (`packageDefaultComponents`)](#wrapping-package-defaults-packagedefaultcomponents)
-20. [ChatMain props reference](#chatmain-props-reference)
-21. [Chat provider (composable mode)](#chat-provider-composable-mode)
-22. [Hooks & store](#hooks--store)
-23. [React (Vite) — full setup](#react-vite--full-setup)
-24. [Next.js — full setup](#nextjs--full-setup)
-25. [Environment variables](#environment-variables)
-26. [Dev proxy (CORS)](#dev-proxy-cors)
-27. [Architecture](#architecture)
-28. [All exports](#all-exports)
-29. [Troubleshooting](#troubleshooting)
-30. [Setup checklist](#setup-checklist)
-31. [Package development (maintainers)](#package-development-maintainers)
-32. [License](#license)
+20. [API query params](#api-query-params)
+21. [ChatMain props reference](#chatmain-props-reference)
+22. [Chat provider (composable mode)](#chat-provider-composable-mode)
+23. [Hooks & store](#hooks--store)
+24. [React (Vite) — full setup](#react-vite--full-setup)
+25. [Next.js — full setup](#nextjs--full-setup)
+26. [Environment variables](#environment-variables)
+27. [Dev proxy (CORS)](#dev-proxy-cors)
+28. [Architecture](#architecture)
+29. [All exports](#all-exports)
+30. [Troubleshooting](#troubleshooting)
+31. [Setup checklist](#setup-checklist)
+32. [Package development (maintainers)](#package-development-maintainers)
+33. [License](#license)
 
 ---
 
@@ -1164,6 +1165,166 @@ Also exported for reference:
 
 ---
 
+## API query params
+
+Pass extra query string params from your app into package HTTP requests. Params are merged in the axios interceptor (built-in params like `limit` / `page` / `conversationId` still win if they conflict).
+
+**Default behavior:** `queryParams` apply to **all GET APIs** only (`queryParamApis` defaults to `['get']`). Login, create group, and other POST/PATCH calls are **not** affected unless you opt in with `queryParamApis={['all']}`.
+
+---
+
+### 1. Default — same params on every GET API
+
+**When to use:** Your app needs the same filter (e.g. `branchId`) on every list/fetch GET call inside the chat package.
+
+**Explanation:** You only pass `queryParams`. You do **not** need `queryParamApis` — it defaults to `['get']`, so every GET endpoint below receives these params. POST/PATCH stay clean.
+
+```tsx
+<ChatMain
+  {...chatConfig}
+  queryParams={{ branchId: "12" }}
+  // queryParamApis default = ['get']
+/>
+```
+
+**What happens on the network:**
+
+| Request | Query string |
+|---------|----------------|
+| `GET /user/list` | `?branchId=12` |
+| `GET /conversation/list` | `?limit=20&page=1&branchId=12` |
+| `GET /message/get-all-from-conversation` | `?conversationId=…&limit=…&branchId=12` |
+| `GET …/pinned-messages` | `?conversationId=…&branchId=12` |
+| `POST /user/login/client-user` | *(no extra query params)* |
+
+**GET APIs covered by default (`CHAT_GET_API_KEYS`):**
+
+| Key | Endpoint |
+|-----|----------|
+| `users` | `GET /user/list` |
+| `conversations` | `GET /conversation/list` |
+| `conversationInfo` | `GET /conversation/get/information/:id` |
+| `messages` | `GET /message/get-all-from-conversation` |
+| `pinnedMessages` | `GET message/pinned-messages` |
+| `starredMessages` | `GET message/starred-messages` |
+| `searchMessages` | `GET /message/search-messages` |
+| `searchMessagesContext` | `GET /message/searched-message/context` |
+
+```tsx
+import { CHAT_GET_API_KEYS, CHAT_API_KEYS } from "@realtimexsco/live-chat";
+```
+
+---
+
+### 2. Different params per GET API
+
+**When to use:** Each endpoint needs its own query keys (e.g. conversations need `branchId`, messages need `locale`, users need `orgId`).
+
+**Explanation:** Use `queryParamsByApi` with named API keys. Only the APIs you list get params — and each can have a different object. You do not need `queryParams` or `queryParamApis` for this pattern.
+
+```tsx
+<ChatMain
+  {...chatConfig}
+  queryParamsByApi={{
+    conversations: { branchId: "12" },
+    messages: { locale: "en" },
+    users: { orgId: "x" },
+  }}
+/>
+```
+
+**What happens on the network:**
+
+| Request | Query string |
+|---------|----------------|
+| `GET /conversation/list` | `?…&branchId=12` |
+| `GET /message/get-all-from-conversation` | `?…&locale=en` |
+| `GET /user/list` | `?orgId=x` |
+| Other GET APIs (not listed) | *(no extra params from this prop)* |
+
+---
+
+### 3. Only one GET API
+
+**When to use:** You want shared-style `queryParams`, but only on a single endpoint (e.g. conversation list), not on messages or users.
+
+**Explanation:** Pass `queryParams` for the values, and restrict with `queryParamApis={['conversations']}`. Other GET APIs will not receive `branchId`.
+
+```tsx
+<ChatMain
+  {...chatConfig}
+  queryParams={{ branchId: "12" }}
+  queryParamApis={["conversations"]}
+/>
+```
+
+**What happens on the network:**
+
+| Request | Query string |
+|---------|----------------|
+| `GET /conversation/list` | `?limit=20&page=1&branchId=12` |
+| `GET /message/get-all-from-conversation` | *(no `branchId`)* |
+| `GET /user/list` | *(no `branchId`)* |
+
+You can also target multiple selected GETs:
+
+```tsx
+<ChatMain
+  {...chatConfig}
+  queryParams={{ orgId: "x" }}
+  queryParamApis={["messages", "users"]}
+/>
+```
+
+---
+
+### Bonus: shared + per-API together
+
+**Explanation:** Shared params apply to the APIs in `queryParamApis`. Per-API params from `queryParamsByApi` merge on top for that endpoint.
+
+```tsx
+<ChatMain
+  {...chatConfig}
+  queryParams={{ tenant: "abc" }}
+  queryParamApis={["conversations", "messages"]}
+  queryParamsByApi={{
+    conversations: { branchId: "12" },
+    messages: { locale: "en" },
+  }}
+/>
+```
+
+- conversations → `?tenant=abc&branchId=12`
+- messages → `?tenant=abc&locale=en`
+
+---
+
+### `queryParamApis` options
+
+| Value | Meaning |
+|-------|---------|
+| `['get']` | **Default.** All GET endpoints in the table above |
+| `['all']` | Every `apiClient` request (GET + POST + PATCH) |
+| Specific keys | Only those endpoints (e.g. `['conversations']`) |
+
+### Imperative helpers
+
+```tsx
+import {
+  setChatQueryParams,
+  setChatQueryParamApis,
+  setChatQueryParamsByApi,
+} from "@realtimexsco/live-chat";
+
+setChatQueryParams({ branchId: "12" });
+setChatQueryParamApis(["conversations"]);
+setChatQueryParamsByApi({ messages: { locale: "en" } });
+```
+
+Socket connection query and S3 presigned uploads are **not** changed by these props.
+
+---
+
 ## ChatMain props reference
 
 | Prop | Type | Default | Description |
@@ -1173,6 +1334,9 @@ Also exported for reference:
 | `loggedUserDetails` | `object` | — | **Required.** `{ _id, name, email }` — `_id` must match JWT |
 | `apiUrl` | `string` | — | **Required.** REST API ending with `/api/v1` (pass from your env/config) |
 | `socketUrl` | `string` | derived | Optional socket host (no `/api/v1`). Defaults to `apiUrl` without `/api/v1` |
+| `queryParams` | `Record<string, string \| number \| boolean>` | — | Shared query params for selected APIs (see `queryParamApis`) |
+| `queryParamApis` | `ChatApiKey[]` | `['get']` | Which APIs receive `queryParams`. Default = all GET endpoints |
+| `queryParamsByApi` | `ChatQueryParamsByApi` | — | Different query params per API key |
 | `viewportHeight` | `"full" \| "screen" \| string` | `"full"` | Chat root height. Use `"screen"` for full page, or `"calc(100dvh - 4rem)"` below fixed header |
 | `viewportClassName` | `string` | — | Extra classes on the built-in viewport wrapper |
 | `colorMode` | `"light" \| "dark"` | — | Controlled light/dark (use with your app theme) |
@@ -1247,6 +1411,9 @@ export default function ChatPage() {
 | `loggedUserDetails` | `object` | Yes | User profile |
 | `apiUrl` | `string` | No | REST base URL |
 | `socketUrl` | `string` | No | Socket host |
+| `queryParams` | `ChatQueryParams` | No | Shared query params (default target: all GET APIs) |
+| `queryParamApis` | `ChatApiKey[]` | No | Which APIs receive `queryParams` (default `['get']`) |
+| `queryParamsByApi` | `ChatQueryParamsByApi` | No | Per-API query params |
 | `themeColor` | `string` | No | Accent color |
 | `uiConfig` | `UIConfig` | No | `components`, `classNames`, `features` |
 | `onMessageReceived` | `(msg) => void` | No | Background message callback |
@@ -1531,12 +1698,26 @@ import ChatMain, {
   setChatClientId,
   setChatAccessToken,
   setChatBaseURL,
+  setChatSocketUrl,
+  setChatQueryParams,
+  getChatQueryParams,
+  setChatQueryParamApis,
+  getChatQueryParamApis,
+  setChatQueryParamsByApi,
+  getChatQueryParamsByApi,
+  CHAT_API_KEYS,
+  CHAT_GET_API_KEYS,
+  resolveChatApiKey,
   socketService,
   getSocketConfig,
   showNotification,
   downloadFile,
 
   // ── Types ──
+  type ChatApiKey,
+  type ChatGetApiKey,
+  type ChatQueryParams,
+  type ChatQueryParamsByApi,
   type ChatComponents,
   type ChatClassNames,
   type ChatFeatures,