@ethora/chat-component 26.10.5 → 26.10.7

package/README.md

@@ -363,7 +363,7 @@ Below is a grouped reference for all `config` options.
 | --- | --- | --- |
 | `disableHeader` | `boolean` | Hide chat header. |
 | `disableMedia` | `boolean` | Disable media sending/processing paths. |
-| `attachments` | `{ maxFiles?; maxFileSizeMb?; accept? }` | Composer attachment limits. `maxFiles` defaults to `10` (also the hard cap, set by the stanza payload size); `maxFileSizeMb` adds a client-side per-file check (omit for none); `accept` is passed straight to the file picker. Picking several files sends them as **one** message. |
+| `attachments` | `{ maxFiles?; maxFileSizeMb?; accept?; captionMode? }` | Composer attachment limits. `maxFiles` defaults to `10` (also the hard cap, set by the stanza payload size); `maxFileSizeMb` adds a client-side per-file check (omit for none); `accept` is passed straight to the file picker. Picking several files sends them as **one** message. `captionMode` (`'inline' \| 'separate'`, default `'separate'`) sets where the text typed with the files goes: `'separate'` sends the media message without the caption and then the text as a normal text message once the media send settles (also in e2ee rooms); `'inline'` puts the caption on the media message (`<data caption>`, `captionMentions`). See Backend compatibility. |
 | `pdfPreview` | `{ enabled?; workerSrc?; libUrl?; maxFileSizeMb? }` | First-page PDF thumbnails inside bubbles and in the composer tray. On by default; `enabled: false` keeps the static document card. pdf.js is code-split and only fetched when a PDF actually shows up. By default it runs on the main thread, which needs no bundler asset wiring: set `workerSrc` to a pdf.js worker URL you host to move parsing off it. Set `libUrl` to the URL of a pdf.js ES module build to load it at runtime instead of the copy bundled with the component (pair it with `workerSrc`); useful when you ship the component as one self-contained script and do not want pdf.js (about 1.7 MB) inside it. `maxFileSizeMb` (default `25`) is the size past which a document is not auto-rendered. |
 | `disableRooms` | `boolean` | Hide/disable room list area. |
 | `disableRoomMenu` | `boolean` | Disable room menu controls. |
@@ -450,9 +450,27 @@ Below is a grouped reference for all `config` options.
 | `pushNotifications.serviceWorkerScope` | `string` | Service worker scope, default `/`. |
 | `pushNotifications.iconPath` | `string` | Custom icon URL/path for OS push notifications. |
 | `pushNotifications.badgePath` | `string` | Custom badge URL/path for OS push notifications. Falls back to `iconPath`. |
+| `pushNotifications.clickPath` | `string` | Same-origin path a push tap opens when no window is open yet (for example `/app/chat`). The tapped room and message are appended as `fromPush=1&chatId=...&messageId=...` (ids only). Defaults to the origin root. |
 | `pushNotifications.softAsk` | `boolean` | Do not immediately trigger browser permission prompt. |
 | `pushNotifications.onClick` | `(params) => void \| Promise<void>` | Callback invoked when the user clicks an OS push notification (including cold start via URL marker). |
 
+### Backend compatibility
+
+Some features call routes that not every backend deployment serves yet. Each
+switch below keeps that client code off until your backend has the route. The
+defaults are the safe choice for a backend that has not been updated.
+
+| Option | Default | Why |
+| --- | --- | --- |
+| `features.userBlock` | `false` | `/v1/chats/blocked` is not served by the production backend yet (404), so the "Block user" item would always fail. Set `true` once your backend serves it. |
+| `attachments.captionMode` | `'separate'` | The caption goes out as its own text message after the media (the 26.9.8 wire shape), which older web builds, React Native and server push all show. `'inline'` puts it on the media message as `<data caption>`, which those readers do not render yet. |
+| `uploads.endpoint` | `'auto'` | `'auto'` tries `/v2/files/secure` and falls back to `/v1/files/`. Secure-files URLs can be unreadable on a backend that is not updated, so `'legacy'` posts straight to `/v1/files/`. `'secure'` never falls back. |
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `features` | `{ userBlock?: boolean }` | Opt-in backend features. `userBlock` (default `false`) shows the "Block user" item in 1-1 chat menus and enables the `/v1/chats/blocked` calls. `disableUserBlock: true` still hides the item. |
+| `uploads` | `{ endpoint?: 'auto' \| 'secure' \| 'legacy' }` | Attachment upload route. `'auto'` (default) tries `POST /v2/files/secure` and falls back to `POST /v1/files/` when the backend rejects it. `'legacy'` always uses `/v1/files/` (no `chatName`); `'secure'` uses the secure route and never falls back. |
+
 ### Error handling and crash containment
 
 The SDK renders inside your application's React tree. Without a boundary, one
@@ -645,6 +663,19 @@ The badge has no per-push override: it is `pushNotifications.badgePath`, then th
 
 Clicking a push opens `<origin>/chat?chatId=<room>&messageId=<message>` (or the `url` carried by the push) and calls `pushNotifications.onClick`; see the deep link section above.
 
+#### Incoming call pushes (web)
+
+With `videoCalls.enabled: true` and push enabled, a data-only call push (`type: "call"`, `callId`, `callToken`, `room`, `kind`, `callerName`, `callerXmppUsername`) rings the same way as on mobile:
+
+- The worker asks every open window to ring (`CALL_PUSH`). A visible page that shows the ring answers (`CALL_PUSH_ACK`) and nothing else is shown. With no ack within 1.5 s (no window, a hidden tab, a dead socket) the worker shows a sticky notification "Incoming video call" with **Answer** and **Decline** actions, tag `call:<callId>` (`call:room:<room>` when the push has no `callId`). A page that already has that call connecting or in progress acks it, hidden or not, so a duplicate push never rings again; a page busy with a different call acks it as busy and the worker shows a plain "Missed call" instead of a ring. A push without `callToken` cannot be answered: it shows Decline only, and a tap opens the room. A tap or Answer with no window opens `pushNotifications.clickPath` (the page that mounts the chat); the call itself travels in the pending click, never in the url.
+- The push has no TTL, so freshness is read from the `exp` of `callToken`. With less than 3 s left nothing rings and a plain "Missed video call" notification (tag `missed-call:<room>`, tap opens the room) is shown instead. A token with no readable `exp` is treated as fresh. A ring the worker shows is never sticky for longer than 60 s (the backend's TTL for a call): at `exp`, or 60 s after the push when `exp` is unreadable or further away, it is replaced by the "Missed call" notification. A page that times a ring out in a hidden tab shows the same "Missed call" notification itself (same tag, shown once), so the result does not depend on whether the page or the worker gets there first.
+- Answer focuses or opens the app, raises the call and accepts it at once, so LiveKit connects with the push token (the browser may ask for microphone or camera). Tapping the notification body shows the ring screen. The click goes to every open window that announced it takes calls (the page has the call push listener mounted with `videoCalls.enabled`; `CALL_CLIENT_READY`), and the one that took it answers `CALL_PUSH_ANSWER_ACK` and is focused; a host page with no `<Chat>` is never picked just because it was focused last. With no ready window the worker does not wait: it keeps the click as the pending click and focuses and navigates an open tab to `pushNotifications.clickPath` (or opens it), and the new page accepts the call. The same happens when a ready window does not ack within 1.5 s, except that a refused `openWindow` (the click's user activation is short-lived) leaves the pending click for the next page load (2 min). The focus and the no-ready fallback run while the click is fresh; only the ack wait can outlast it, which is why a tab that was ready but silent is never the one navigated.
+- Decline goes to every open window the same way. The page that takes it (XMPP `call-state` plus `POST /v1/chats/call/state/decline/:callId`) answers `CALL_PUSH_DECLINE_ACK`; if no ack comes within 1.5 s (a host page with no `<Chat>`, the config not loaded yet) the worker declines over REST itself. With no page open the worker calls that endpoint directly, using the user token the page mirrors into Cache Storage (the token the SDK already keeps in this origin's localStorage; deleted on logout). Without that token Decline only closes the notification and the caller times out.
+- Several tabs of one origin can ring for the same call. Accepting or declining takes one per-call claim (a Web Lock), whether it comes from the notification's Answer and Decline or from the Accept and Decline buttons on the ring screen, so two tabs never both accept. A tab that does not get the claim does nothing. The tab that accepts, declines or sees the caller cancel broadcasts the outcome to the other tabs of the origin (on a `BroadcastChannel` named `ethora-call` and, for tabs without `BroadcastChannel`, as a `localStorage` write picked up by the `storage` event; a tab acts on whichever arrives first), and a tab still ringing for that call ends its ring quietly: no "Missed call", nothing sent to the caller, its notification closed. A ring that merely runs out is each tab's own. The outcome is also remembered for about 2 minutes (call keys and timestamps only, in `localStorage`), so a late push, a stale Answer or Decline, or a replay of the call token never raises, accepts or hangs up a call another tab already handled. A call with no `callId` is keyed by its room and is not remembered. Without Web Locks the tabs behave as before, and only the remembered outcome protects against a second accept.
+- Set `pushNotifications.clickPath` to the route where `<Chat>` is mounted (for example `/chat`), even though it is optional. It decides where Answer, a tap or a refused `openWindow` goes when no window that can take calls is open. It defaults to the origin root, which in most apps is a landing page or a login screen that does not mount `<Chat>`: the worker then opens a page that never hears the call push listener, so Answer lands on that page, nothing accepts, the pending click waits for the next page load (2 min) and the call is lost for the user. With `clickPath` pointing at the chat route, the new page mounts the chat, picks up the pending click and accepts the call. The same applies to a tab that is open on a page without `<Chat>`: it is not offered the click, the worker navigates it to `clickPath` instead.
+- A ring a page shows through the service worker registration (a hidden tab with a live socket) is persistent, so the page tells the worker (`CALL_RING_SHOWN`, with the call's `exp` and no token) and the worker ends it like a ring of its own, even if the tab is closed in the meantime. A "Missed call" shown by the page and by the worker at the same moment is shown once (both check and show under one Web Lock).
+- The call notification is closed whenever the ring ends (answered, declined, cancelled, timed out). A push that arrives before the chat config and the user are in Redux is held until they are, or until its token expires. On logout (or a switch to another account) the held call, the tap the worker keeps for the next page load and every call notification on screen are cleared.
+
 ## Auth Strategies
 
 | Strategy | Config shape | Best for |