@poolse/react 2.29.0 → 3.1.0

package/README.md

@@ -1,10 +1,12 @@
 # `@poolse/react`
 
-React hooks library for realtime chat. Wraps [`@poolse/sdk`](https://www.npmjs.com/package/@poolse/sdk) in `PoolseProvider` + a typed hook per resource — `useMessages`, `useThread`, `useReactions`, `useTyping`, `usePresence`, `useMembers`, `useAttachmentUpload`. Works in both web React and React Native — same hook surface, same behaviour, same types. No UI: for components see [`@poolse/react-ui`](https://www.npmjs.com/package/@poolse/react-ui) (web) or [`@poolse/react-native`](https://www.npmjs.com/package/@poolse/react-native) (mobile).
+React provider and hooks for [poolse](https://poolse.dev), on top of
+[`@poolse/sdk`](https://www.npmjs.com/package/@poolse/sdk). No UI. The same
+hooks work on the web and in React Native. For components, see
+[`@poolse/react-ui`](https://www.npmjs.com/package/@poolse/react-ui) (web)
+or [`@poolse/react-native`](https://www.npmjs.com/package/@poolse/react-native).
 
-> **MIT-licensed alternative to `sendbird-chat-react`, `stream-chat-react`, and `talkjs-react`.** Hooks-only by design — bring your own UI, or drop into the components when you don't want to.
-
-> **⚠️ Upgrading from 1.x?** See [MIGRATING.md](https://github.com/poolse-hq/js-sdk/blob/main/MIGRATING.md). `useUser`, `useTyping`, `usePresence`, and `useMembers().removeMember` all key by your `external_id` now instead of poolse uuids.
+Full reference: <https://poolse.dev/docs/sdk/react>
 
 ## Install
 
@@ -12,34 +14,37 @@ React hooks library for realtime chat. Wraps [`@poolse/sdk`](https://www.npmjs.c
 npm install @poolse/react @poolse/sdk
 ```
 
-`react@>=18` is a peer dependency. React 19 works.
+Peer: `react` ≥ 18. `@poolse/sdk` is a dependency; keep the same major
+version if you also install it.
 
 ## Quick start
 
 ```tsx
-import { PoolseProvider, useMessages } from '@poolse/react';
+import { PoolseProvider, useMessages, type PoolseConfig } from '@poolse/react';
+
+const config: PoolseConfig = {
+  getToken: async () => {
+    const res = await fetch('/api/chat-token', { method: 'POST' });
+    const { token } = await res.json();
+    return token;
+  },
+  userResolver: async (externalId) => {
+    const u = await fetch(`/api/users/${externalId}`).then((r) => r.json());
+    return { displayName: u.name, avatarUrl: u.avatar_url };
+  },
+};
 
-function App() {
+export function App() {
   return (
-    <PoolseProvider
-      config={{
-        apiUrl: 'https://api.poolse.dev',
-        getToken: async () => {
-          const res = await fetch('/api/chat-token', { method: 'POST' });
-          const { token } = await res.json();
-          return token;
-        },
-      }}
-    >
-      <Chat conversationId="00000000-0000-0000-0000-000000000000" />
+    <PoolseProvider config={config}>
+      <Chat conversationId="…" />
     </PoolseProvider>
   );
 }
 
 function Chat({ conversationId }: { conversationId: string }) {
   const { messages, send, loading } = useMessages(conversationId);
-
-  if (loading) return <div>Loading…</div>;
+  if (loading) return <p>Loading…</p>;
   return (
     <ul>
       {messages.map((m) => (
@@ -51,285 +56,58 @@ function Chat({ conversationId }: { conversationId: string }) {
 }
 ```
 
-## `<PoolseProvider>`
-
-```tsx
-<PoolseProvider config={config}>{children}</PoolseProvider>
-```
-
-`config` is the same `PoolseConfig` the bare SDK accepts (see [`@poolse/sdk`](https://www.npmjs.com/package/@poolse/sdk) for the full reference).
-
-The provider builds **one** `Poolse` instance per mount. Connection-shaped fields (`apiUrl`, `wsUrl`, `socketPath`) are captured at construction and don't react to subsequent changes; the development build warns when you change them after mount. Function-valued fields (`getToken`, `fetch`, `userResolver`, `generateIdempotencyKey`, `onSocketError`) are read from a ref on every call, so passing fresh closures on every render is safe and expected:
-
-```tsx
-// Fine — getToken is re-read through a ref each call.
-<PoolseProvider config={{ apiUrl, getToken: () => session.token }}>
-```
-
-To force a fresh client (sign-out, tenant swap, environment switch), remount the provider with a new `key`. On unmount, `chat.destroy()` runs, which closes the WebSocket and drops every joined channel.
-
-### `usePoolse()`
-
-Escape hatch — returns the underlying `Poolse` instance for callers that need direct REST or realtime access. Throws if there's no provider above it.
-
-```ts
-const chat = usePoolse();
-const me = await chat.me.show();
-```
+The provider creates one `Poolse` instance per mount. Function options are
+read through a ref, so new closures on each render are fine. Remount with a
+new `key` to switch user.
 
 ## Hooks
 
-Each hook below is briefly described, then documented in full. All hooks that touch a conversation subscribe to its realtime channel for the duration of the component's lifetime.
-
-### `useMe(): { me, loading, error }`
-
-Fetches `GET /v1/me` once on mount. Identity is stable for the JWT's lifetime, so the hook doesn't refetch on its own — remount the provider to switch users.
-
-### `useConversation(id): { conversation, loading, error, refetch }`
-
-Single conversation, REST-only. Settings changes (name, avatar) won't show up live on this hook — call `refetch()` after a mutation. Live message activity for the same conversation flows through `useMessages` instead. Pass `null` to skip the fetch.
-
-### `useConversations(): { conversations, create, unreadCounts, markConversationRead, ... }`
-
-The user's conversation list. On mount it fetches `GET /v1/conversations` and subscribes to the user's own `user:<id>` channel for two events: `conversation:created` (fires both when this user creates a conversation and when someone else adds them to one) and `conversation:updated` (fires after every message sent in any of their conversations).
-
-Return shape:
-
-```ts
-const { conversations, loading, error, refetch, create, unreadCounts, markConversationRead } =
-  useConversations();
-```
-
-`conversations` is the list of `Conversation` rows. `refetch()` does an explicit re-sync. `create(attrs)` calls `POST /v1/conversations` and optimistically prepends the result; when the realtime echo arrives with the same id, id-based dedup replaces the row in place so there's no double-insert.
-
-`unreadCounts` is `Record<Uuid, number>`. Initial values come from the server's `Conversation.unread_count`. The `conversation:updated` subscription keeps them live without polling: when another member sends a message, the corresponding row's preview, timestamp, and unread badge update in place; when YOU send (`by_user_id` equals your id) the row floats to the top and unread stays at 0 (the server already advanced your read cursor in the same transaction). `markConversationRead(conversationId)` zeroes the badge locally — wire this from `ConversationView.onMarkedRead` so the sidebar clears immediately, before the server's read-receipt echo round-trips.
-
-### `useMessages(conversationId): { messages, send, edit, delete, loadMore, hasMore, markReadUpTo, ... }`
-
-Live messages for one conversation. Initial fetch is the newest 50; pagination loads older pages with `loadMore()`. Subscribes to `message:new`, `message:updated`, `message:deleted` on the channel.
-
-```ts
-const {
-  messages, // Message[] — newest-LAST (the wire is newest-first; reversed)
-  loading,
-  error,
-  hasMore,
-  loadMore, // () => Promise<void>
-  send, // (attrs: MessageCreateRequest) => Promise<Message>
-  edit, // (messageId: Uuid, body: string) => Promise<Message>
-  delete: del, // (messageId: Uuid) => Promise<void>
-  markReadUpTo, // (messageId: Uuid) => Promise<void>
-} = useMessages(conversationId);
-```
-
-**Optimistic sends with id-based dedup.** `send()` generates a UUID client-side, appends an optimistic row sorted to the very end (`sequence: MAX_SAFE_INTEGER`), then POSTs with that same id. Whichever lands first — the REST response or the realtime `message:new` echo — wins via `upsertById`; the other arrival is a no-op replace. Errors filter the temp row by id.
-
-**Thread routing.** Realtime `message:new` events with `thread_root_id` set are **not** added to `messages` (replies live in the thread side-pane). Instead the hook finds the root locally and increments its `reply_count`. The REST list excludes replies too (`WHERE thread_root_id IS NULL`), so a refresh and a realtime burst stay consistent.
-
-**Edits and deletes.** Both are optimistic with synchronous rollback on error. The hook captures a snapshot before mutating so the rollback isn't racing React's update queue.
-
-**Read cursor.** `markReadUpTo(messageId)` fires the read against `POST /v1/conversations/:id/read`. The server broadcasts `member:read` to other clients; this hook itself doesn't mutate state (the `useMembers` hook does — see below).
-
-### `useThread(conversationId, rootMessageId): { replies, sendReply, edit, delete, loadMore, hasMore, ... }`
-
-Side-pane replies for one root message. The wire returns replies oldest-first; the hook keeps that order. The default fetch is 500 replies in one round-trip — most threads load whole. `loadMore()` paginates with an `after` cursor when a thread overflows.
-
-```ts
-const {
-  replies, // Message[] — oldest-first
-  loading,
-  error,
-  hasMore,
-  loadMore,
-  sendReply, // (attrs: Omit<MessageCreateRequest, 'reply_to_id'>) => Promise<Message>
-  edit,
-  delete: del,
-} = useThread(conversationId, rootMessageId);
-```
-
-Subscriptions filter by `thread_root_id === rootMessageId` so unrelated messages in the same conversation don't end up here. `sendReply` auto-fills `reply_to_id` with the root id — same optimistic-id dedup pattern as `useMessages.send`.
-
-### `useReactions(messageId, opts): { reactions, addReaction, removeReaction }`
-
-Live reaction map for one message. Subscribes to `reaction:added` / `reaction:removed` filtered to the message id.
-
-```ts
-const { reactions, addReaction, removeReaction } = useReactions(messageId, {
-  conversationId,
-  initialReactions: msg.reactions, // seed from the Message you already have
-  currentUserId: meId, // enables optimistic add/remove
-});
-```
-
-`reactions` is a `Record<emoji, Uuid[]>` (matching `Message.reactions`). Adds + removes are optimistic when `currentUserId` is provided; the optimistic delta is rolled back on error.
-
-### `useTyping(conversationId): { typing, signalTyping }`
-
-```ts
-const { typing, signalTyping } = useTyping(conversationId);
-// typing: Set<Uuid> of users currently typing (your own id is filtered out)
-// signalTyping: client-side debounced to ≤ 1 ping / 500ms
-```
-
-Call `signalTyping` on every keystroke; the hook drops events that arrive within 500ms of the last one, and the server has its own rate limit per (user, conversation) on top.
-
-### `usePresence(conversationId): { online }`
-
-```ts
-const { online } = usePresence(conversationId);
-// online: Set<Uuid> of users currently joined to the channel
-```
-
-Replays the initial `presence_state` snapshot on join, then applies `presence_diff` deltas. Pass an empty string id to opt out (the set stays empty).
-
-### `useMembers(conversationId): { members, addMembers, removeMember, refetch, ... }`
-
-Conversation roster. Initial fetch is `GET /v1/conversations/:id/members`. Subscribes to `member:read` on the channel and advances the matching membership's `last_read_message_id` and `last_read_at` in place — which is how `<MessageBubble>`'s read-receipt glyph (in `@poolse/react-ui`) flips from sent to read in real time.
-
-```ts
-const {
-  members, // Membership[]
-  loading,
-  error,
-  refetch,
-  addMembers, // (externalIds: string[], { role? }?) => Promise<Membership[]>
-  removeMember, // (userId: Uuid) => Promise<void>
-} = useMembers(conversationId);
-```
-
-`addMembers` deduplicates by id (server returns an idempotent add). `removeMember` is optimistic with snapshot rollback.
-
-Empty `conversationId` opts out of the fetch (returns `{ members: [], loading: false }`).
-
-`member:read` events that arrive before the initial fetch lands are buffered and replayed after `setMembers` commits — without that, reads in the subscribe → fetch-response gap would silently no-op against an empty member list.
-
-### `useAttachmentUpload(): { queue, upload, uploadAll, cancel, remove, reset, ... }`
-
-Queued multi-file uploads with per-item progress and cancel.
-
-```ts
-const { queue, upload, uploadAll, cancel, remove, reset, uploading, error } = useAttachmentUpload();
-
-// Single file
-const att = await upload({
-  body: file,
-  contentType: file.type,
-  byteSize: file.size,
-  filename: file.name,
-});
-
-// Batch (parallel PUTs, returned in input order)
-const atts = await uploadAll(
-  files.map((f) => ({ body: f, contentType: f.type, byteSize: f.size, filename: f.name })),
-);
-```
-
-Each `UploadItem` carries `{ localId, filename, contentType, byteSize, status, loaded, attachment, error }` with `status` cycling through `'pending' → 'uploading' → 'ready' | 'error' | 'cancelled'`. `loaded` is byte progress (browser-only — `fetch` doesn't expose upload progress, so the hook switches to XHR when `onProgress` is wired internally). Cancellation per item via `cancel(localId)`; full teardown via `reset()`.
-
-The hook tracks a `mountedRef` so a fast unmount aborts all in-flight uploads instead of leaking promises.
-
-### `useAttachmentUrl(attachmentId): { url, loading, error }`
-
-Fetches a presigned GET URL for an attachment. Pass `null` to skip.
-
-The URL has a ~1 hour TTL server-side. The hook doesn't auto-refresh — most UI lifetimes are shorter than the TTL anyway, and silently re-fetching mid-render would break image elements. If you have a long-lived dashboard, remount the hook (or wrap it in a parent that re-keys on a timer).
-
-### `useUser(userId): { profile, loading }`
-
-Resolves a poolse `user_id` to your customer-supplied display name + avatar via the `userResolver` you configured on the provider. Cached + deduplicated across the app.
-
-```ts
-const { profile, loading } = useUser(message.sender_id);
-// profile: { displayName: string; avatarUrl: string | null } | null
-```
-
-If you don't configure `userResolver`, the hook always returns `{ profile: null, loading: false }`. Components in `@poolse/react-ui` (sender labels, mention dropdowns, member lists) fall back to a stable color-tinted initials avatar in that case.
-
-Pass falsy `userId` to no-op the hook (used internally by self-message bubbles, which don't need to resolve the sender).
-
-### `useRealtimeStatus(): RealtimeStatus`
-
-```ts
-const status = useRealtimeStatus();
-// 'idle' | 'connecting' | 'connected' | 'reconnecting' | 'closed'
-```
-
-For "Reconnecting…" banners without coupling to socket internals.
-
-## Wiring user identity
-
-The SDK doesn't store names or avatars — that's your app's data. Wire `userResolver` once on the provider and every component that renders a sender lights up:
-
-```tsx
-<PoolseProvider
-  config={{
-    apiUrl,
-    getToken,
-    userResolver: async (poolseUserId) => {
-      // Translate poolse's user_id to your own user record.
-      const u = await fetch(`/api/users/by-poolse-id/${poolseUserId}`).then((r) => r.json());
-      return { displayName: u.full_name, avatarUrl: u.avatar_url };
-    },
-  }}
->
-```
-
-Resolved profiles are cached in-memory and concurrent lookups for the same id share one in-flight promise. Resolver errors are logged once (via `console.error` with `[poolse]` prefix) and cached as `null` so a single transient failure doesn't trigger a retry storm.
-
-## What you can rely on
-
-- **Mount-once SDK instance.** Stable WebSocket and channel subscriptions for the life of the provider; safe to pass fresh inline callbacks on every render.
-- **Auto-rejoin on reconnect.** Phoenix handles channel rejoin internally; the JWT is re-read from `getToken` each handshake.
-- **Optimistic dedup by client-generated id.** `useMessages.send` and `useThread.sendReply` insert under the same id the server will assign, so the realtime echo upserts in place rather than duplicating.
-- **Synchronous rollback for optimistic edits.** Edit / delete / `removeReaction` / `removeMember` capture a ref snapshot before mutating, then restore the snapshot on error rather than relying on `setState((prev) => ...)`.
-- **Buffered early events.** `useMembers` buffers `member:read` events that race the initial member fetch.
-- **Abort-safe.** Hooks that fetch on mount cancel in-flight requests on unmount and ignore `AbortError`. Aborted fetches don't surface as "Failed to load" errors.
-
-## Exports
-
-```ts
-// Provider
-export { PoolseProvider, usePoolse, type PoolseProviderProps };
-
-// Hooks
-export { useMe, useConversation, useConversations, useMembers, useMessages };
-export { useReactions, type ReactionMap };
-export { useThread, useTyping, usePresence, useRealtimeStatus };
-export { useAttachmentUpload, type UploadItem, type UploadItemStatus };
-export { useAttachmentUrl, useUser, type UseUserState };
-
-// Re-exported SDK types (so you don't have to add @poolse/sdk to your imports)
-export type {
-  Attachment,
-  AttachmentStatus,
-  AttachmentUploadInput,
-  AttachmentUploadRequest,
-  AttachmentUploadResponse,
-  Conversation,
-  ConversationCreateRequest,
-  Me,
-  MemberRole,
-  Membership,
-  Message,
-  MessageCreateRequest,
-  MessageType,
-  PoolseConfig,
-  PoolseUserProfile,
-  RealtimeStatus,
-  Uuid,
-};
-
-// Re-exported error classes
-export { ApiError, AuthError, PoolseError, NetworkError, RateLimitedError };
-```
+| Hook                                                                             | Returns                                                                                                              |
+| -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `usePoolse()`                                                                    | The `Poolse` instance.                                                                                               |
+| `useMe()`                                                                        | `{ me, loading, error }`                                                                                             |
+| `useConversation(id \| null)`                                                    | `{ conversation, loading, error, refetch }`                                                                          |
+| `useConversations()`                                                             | `{ conversations, loading, error, refetch, create, unreadCounts, markConversationRead }`                             |
+| `useMessages(conversationId)`                                                    | `{ messages, loading, error, hasMore, loadMore, send, edit, delete, markReadUpTo, refetch }`, oldest first           |
+| `useThread(conversationId, rootId)`                                              | `{ replies, loading, error, hasMore, loadMore, sendReply, edit, delete }`                                            |
+| `useReactions(messageId, { conversationId, initialReactions?, currentUserId? })` | `{ reactions, addReaction, removeReaction }`                                                                         |
+| `useTyping(conversationId)`                                                      | `{ typing: Set<externalId>, signalTyping }`                                                                          |
+| `usePresence(conversationId)`                                                    | `{ online: Set<externalId> }`                                                                                        |
+| `useMembers(conversationId)`                                                     | `{ members, loading, error, refetch, addMembers(externalIds, { role? }), removeMember(externalId) }`                 |
+| `useAttachmentUpload()`                                                          | `{ queue, attachment, uploading, error, upload(input), uploadAll(inputs), cancel(localId), remove(localId), reset }` |
+| `useAttachmentUrl(id \| null)`                                                   | `{ url, loading, error }` (not renewed; URLs last one hour)                                                          |
+| `useUser(externalId)`                                                            | `{ profile, loading }`                                                                                               |
+| `useRealtimeStatus()`                                                            | `'idle' \| 'connecting' \| 'connected' \| 'reconnecting' \| 'closed'`                                                |
+| `useReadReceipts()`                                                              | `{ visible, mode, shared, canChange, setShared }`                                                                    |
+| `useLiveCall(conversationId \| null)`                                            | `{ call, participantIds, refresh }`                                                                                  |
+| `useRoom(conversationId \| null, { livekit })`                                   | `{ live, presentIds, joined, joining, join, leave, media, error }`                                                   |
+| `useCallRoom(conversationId \| null, { livekit, … })`                            | Call media: participants, mic, camera, devices                                                                       |
+
+Helpers: `canEditOwnMessage`, `EDIT_WINDOW_MS`, `receiptsOf`,
+`computeGroupPosition`, `sameGroup`, `sameDay`, `formatDayLabel`, plus
+re-exports of the SDK's error classes, call-log helpers and wire types.
+
+Notes that trip people up:
+
+- `useTyping`, `usePresence`, `useUser` and `useMembers().removeMember` use
+  **your** user ids (`external_id`). `useReactions`' `currentUserId` and the
+  `reactions` map use **poolse** user ids (`me.id`).
+- `useMessages().send` removes the optimistic row and rejects if the request
+  fails.
+- `useAttachmentUpload().upload` takes `{ body, contentType, byteSize, filename? }`,
+  not a bare `File`. Send `item.attachment.id`, not `item.localId`.
+- From 3.1, `useMessages` (the newest 50, merged in) and `useConversations`
+  reload from REST after the socket reconnects. The first connect doesn't
+  count as a reconnect.
+- If the user is removed from a conversation, its mounted hooks stop
+  updating; hooks mounted later join a fresh channel.
 
 ## Links
 
-- Full docs — <https://poolse.dev/docs/react>
-- SDK reference — [`@poolse/sdk`](https://www.npmjs.com/package/@poolse/sdk)
-- UI components — [`@poolse/react-ui`](https://www.npmjs.com/package/@poolse/react-ui)
-- Source — <https://github.com/poolse-hq/js-sdk>
+- Docs: <https://poolse.dev/docs/sdk/react>
+- Source: <https://github.com/poolse-hq/js-sdk>
 
 ## License
 
-MIT
+Licensed under the [poolse SDK License](./LICENSE) from 3.0.0; versions
+before 3.0.0 remain MIT.

package/dist/index.cjs

@@ -173,9 +173,21 @@ function useConversations() {
       const fromMe = by_user_id === me.id;
       setConversations((prev) => mergeUpdated(prev, conversation, fromMe));
     });
+    let wasConnected = chat.realtime.getStatus() === "connected";
+    let connectedBefore = wasConnected;
+    const offStatus = chat.realtime.onStatus((status) => {
+      const reconnected = status === "connected" && !wasConnected && connectedBefore;
+      connectedBefore ||= status === "connected";
+      if (reconnected) {
+        chat.conversations.list().then((list) => setConversations(list.data)).catch(() => {
+        });
+      }
+      wasConnected = status === "connected";
+    });
     return () => {
       offCreated();
       offUpdated();
+      offStatus();
     };
   }, [chat, me]);
   const markConversationRead = react.useCallback((conversationId) => {
@@ -382,11 +394,24 @@ function useMessages(conversationId) {
         return updated;
       });
     });
+    let wasConnected = chat.realtime.getStatus() === "connected";
+    let connectedBefore = wasConnected;
+    const offStatus = chat.realtime.onStatus((status) => {
+      const reconnected = status === "connected" && !wasConnected && connectedBefore;
+      wasConnected = status === "connected";
+      connectedBefore ||= wasConnected;
+      if (!reconnected || cancelled) return;
+      handle.list({ limit: PAGE_SIZE }).then((page) => {
+        if (!cancelled) setMessages((prev) => mergeLatest(prev, page.data));
+      }).catch(() => {
+      });
+    });
     return () => {
       cancelled = true;
       offNew();
       offUpdated();
       offDeleted();
+      offStatus();
     };
   }, [chat, conversationId]);
   const loadMore = react.useCallback(async () => {
@@ -527,6 +552,11 @@ function upsertById(prev, msg) {
   next[idx] = msg;
   return next;
 }
+function mergeLatest(prev, page) {
+  let next = prev;
+  for (const msg of page) next = upsertById(next, msg);
+  return next === prev ? prev : [...next].sort((a, b) => a.sequence - b.sequence);
+}
 function useReactions(messageId, opts) {
   const chat = usePoolse();
   const [reactions, setReactions] = react.useState(opts.initialReactions ?? {});
@@ -1276,9 +1306,11 @@ function useLiveCall(conversationId) {
       apply(null);
     });
     let wasConnected = chat.realtime.getStatus() === "connected";
+    let connectedBefore = wasConnected;
     const offStatus = chat.realtime.onStatus((status) => {
-      if (status === "connected" && !wasConnected) refresh();
+      if (status === "connected" && !wasConnected && connectedBefore) refresh();
       wasConnected = status === "connected";
+      connectedBefore ||= wasConnected;
     });
     return () => {
       offStarted();