@poolse/react 0.2.0-alpha.7 → 1.0.0-rc.0

package/CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to `@poolse/react` are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
 [semver](https://semver.org).
 
+## [1.0.0-beta.0] — 2026-06-01
+
+First beta of the stable API. Promotes the full 0.2.x hook surface
+(useMessages with reply_count routing, useThread with full-thread
+fetch, useMembers with buffered read-receipt events,
+useConversations with unreadCounts + markConversationRead) to a
+stable namespace. No breaking changes relative to `0.2.0-alpha.7`
+— version bump + removed verbose diagnostic logs.
+
 ## [0.2.0] — 2026-06-01
 
 ### Fixed

package/README.md

@@ -49,21 +49,43 @@ function Chat({ conversationId }: { conversationId: string }) {
 
 ## Hooks at a glance
 
-| Hook                            | Returns                                                           |
-| ------------------------------- | ----------------------------------------------------------------- |
-| `useMe()`                       | The signed-in End User                                            |
-| `useConversations()`            | List + `create` + realtime new-conversation push                  |
-| `useConversation(id)`           | Single conversation read + refetch                                |
-| `useMembers(convId)`            | Membership list + add/remove helpers                              |
-| `useMessages(convId)`           | Live messages + `send` + pagination + optimistic dedup            |
-| `useThread(convId, rootId)`     | Replies + `sendReply` + pagination                                |
-| `useTyping(convId)`             | Live `typing` set + `signalTyping` (debounced)                    |
-| `usePresence(convId)`           | Live `online` set                                                 |
-| `useReactions(messageId, opts)` | Live reaction map + add/remove                                    |
-| `useAttachmentUpload()`         | Stateful `upload(file)` with `uploading` + `error`                |
-| `useAttachmentUrl(id)`          | Presigned download URL                                            |
-| `useRealtimeStatus()`           | Socket lifecycle (connecting / connected / reconnecting / closed) |
-| `usePoolse()`                   | Raw `Poolse` instance (escape hatch)                              |
+| Hook                            | Returns                                                                              |
+| ------------------------------- | ------------------------------------------------------------------------------------ |
+| `useMe()`                       | The signed-in End User                                                               |
+| `useConversations()`            | List + `create` + realtime new-conversation push                                     |
+| `useConversation(id)`           | Single conversation read + refetch                                                   |
+| `useMembers(convId)`            | Membership list + add/remove helpers                                                 |
+| `useMessages(convId)`           | Live messages + `send` + pagination + optimistic dedup                               |
+| `useThread(convId, rootId)`     | Replies + `sendReply` + pagination                                                   |
+| `useTyping(convId)`             | Live `typing` set + `signalTyping` (debounced)                                       |
+| `usePresence(convId)`           | Live `online` set                                                                    |
+| `useReactions(messageId, opts)` | Live reaction map + add/remove                                                       |
+| `useAttachmentUpload()`         | Upload queue with per-item progress, `upload` / `uploadAll` / `cancel` / `remove`    |
+| `useAttachmentUrl(id)`          | Presigned download URL                                                               |
+| `useUser(userId)`               | Customer-supplied profile via `config.userResolver`, cached + dedup'd                |
+| `useRealtimeStatus()`           | Socket lifecycle (connecting / connected / reconnecting / closed)                    |
+| `usePoolse()`                   | Raw `Poolse` instance (escape hatch)                                                 |
+
+## Identity resolution (`userResolver`)
+
+The SDK doesn't know your users' names or where their avatars live. Wire a `userResolver` once on the provider and every component that renders a sender (`<MessageBubble>`, `<MemberList>`, `<TypingIndicator>`, `<MentionInput>`, …) lights up automatically:
+
+```tsx
+<PoolseProvider
+  config={{
+    apiUrl,
+    getToken,
+    userResolver: async (userId) => {
+      const u = await fetch(`/api/users/by-poolse-id/${userId}`).then((r) => r.json());
+      return { displayName: u.full_name, avatarUrl: u.avatar_url };
+    },
+  }}
+>
+  …
+</PoolseProvider>
+```
+
+Resolved profiles are cached in-memory and concurrent lookups dedupe — a busy chat with 50 messages from 5 senders fires the resolver 5 times, not 50.
 
 ## What the provider gives you
 

package/dist/index.cjs

@@ -32,7 +32,11 @@ function PoolseProvider({ config, children }) {
       ...initial.generateIdempotencyKey ? { generateIdempotencyKey: () => configRef.current.generateIdempotencyKey() } : {},
       ...initial.wsUrl !== void 0 ? { wsUrl: initial.wsUrl } : {},
       ...initial.socketPath !== void 0 ? { socketPath: initial.socketPath } : {},
-      ...initial.onSocketError ? { onSocketError: (err) => configRef.current.onSocketError(err) } : {}
+      ...initial.onSocketError ? { onSocketError: (err) => configRef.current.onSocketError(err) } : {},
+      // Customer's user metadata resolver — name + avatar lookup.
+      // Read through the ref so the customer can swap the closure
+      // (e.g. switch tenant context) without re-mounting.
+      ...initial.userResolver ? { userResolver: (id) => configRef.current.userResolver(id) } : {}
     });
   }, []);
   if (process.env.NODE_ENV !== "production") {
@@ -224,7 +228,6 @@ function useMembers(conversationId) {
         hasFetchedRef.current = true;
       } catch (err) {
         if (err?.name === "AbortError") return;
-        console.error("[poolse] useMembers fetch failed:", err);
         setError(err instanceof Error ? err : new Error(String(err)));
       } finally {
         setLoading(false);
@@ -243,7 +246,6 @@ function useMembers(conversationId) {
     if (!conversationId) return;
     const channel = chat.realtime.conversation(conversationId);
     const off = channel.onMemberRead((evt) => {
-      console.log("[poolse] member:read received", evt);
       if (!hasFetchedRef.current) {
         pendingReadsRef.current.push(evt);
         return;
@@ -783,45 +785,107 @@ function useRealtimeStatus() {
 }
 function useAttachmentUpload() {
   const chat = usePoolse();
-  const [attachment, setAttachment] = react.useState(null);
-  const [uploading, setUploading] = react.useState(false);
-  const [error, setError] = react.useState(null);
-  const inFlightRef = react.useRef(null);
-  const upload = react.useCallback(
-    async (input) => {
-      inFlightRef.current?.abort();
+  const [queue, setQueue] = react.useState([]);
+  const inFlightRef = react.useRef(/* @__PURE__ */ new Map());
+  const mountedRef = react.useRef(true);
+  react.useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+      for (const v of inFlightRef.current.values()) v.controller.abort();
+      inFlightRef.current.clear();
+    };
+  }, []);
+  const updateItem = react.useCallback((localId, patch) => {
+    if (!mountedRef.current) return;
+    setQueue((q) => q.map((it) => it.localId === localId ? { ...it, ...patch } : it));
+  }, []);
+  const runUpload = react.useCallback(
+    async (localId, input) => {
       const controller = new AbortController();
-      inFlightRef.current = controller;
-      setUploading(true);
-      setError(null);
+      inFlightRef.current.set(localId, { controller });
+      updateItem(localId, { status: "uploading", loaded: 0 });
       try {
-        const att = await chat.attachments.upload(input, { signal: controller.signal });
-        if (inFlightRef.current === controller) {
-          setAttachment(att);
-        }
+        const att = await chat.attachments.upload(input, {
+          signal: controller.signal,
+          onProgress: (e) => updateItem(localId, { loaded: e.loaded })
+        });
+        updateItem(localId, {
+          status: "ready",
+          loaded: input.byteSize,
+          attachment: att,
+          error: null
+        });
         return att;
       } catch (err) {
-        if (err?.name === "AbortError") throw err;
+        if (err?.name === "AbortError") {
+          updateItem(localId, { status: "cancelled" });
+          throw err;
+        }
         const e = err instanceof Error ? err : new Error(String(err));
-        setError(e);
+        updateItem(localId, { status: "error", error: e });
         throw e;
       } finally {
-        if (inFlightRef.current === controller) {
-          setUploading(false);
-          inFlightRef.current = null;
-        }
+        inFlightRef.current.delete(localId);
       }
     },
-    [chat]
+    [chat, updateItem]
+  );
+  const enqueue = react.useCallback((input) => {
+    const localId = generateLocalId();
+    const item = {
+      localId,
+      filename: input.filename ?? "file",
+      contentType: input.contentType,
+      byteSize: input.byteSize,
+      status: "pending",
+      loaded: 0,
+      attachment: null,
+      error: null
+    };
+    setQueue((q) => [...q, item]);
+    return item;
+  }, []);
+  const upload = react.useCallback(
+    (input) => {
+      const item = enqueue(input);
+      return runUpload(item.localId, input);
+    },
+    [enqueue, runUpload]
+  );
+  const uploadAll = react.useCallback(
+    (inputs) => {
+      const items = inputs.map((inp) => ({ item: enqueue(inp), input: inp }));
+      return Promise.all(items.map(({ item, input }) => runUpload(item.localId, input)));
+    },
+    [enqueue, runUpload]
+  );
+  const cancel = react.useCallback((localId) => {
+    const inf = inFlightRef.current.get(localId);
+    if (inf) inf.controller.abort();
+  }, []);
+  const remove = react.useCallback(
+    (localId) => {
+      const inf = inFlightRef.current.get(localId);
+      if (inf) inf.controller.abort();
+      setQueue((q) => q.filter((it) => it.localId !== localId));
+    },
+    []
   );
   const reset = react.useCallback(() => {
-    inFlightRef.current?.abort();
-    inFlightRef.current = null;
-    setAttachment(null);
-    setError(null);
-    setUploading(false);
+    for (const v of inFlightRef.current.values()) v.controller.abort();
+    inFlightRef.current.clear();
+    setQueue([]);
   }, []);
-  return { attachment, uploading, error, upload, reset };
+  const uploading = queue.some((it) => it.status === "pending" || it.status === "uploading");
+  const error = queue.reduce((acc, it) => it.error ?? acc, null);
+  const attachment = queue.reduce((acc, it) => it.attachment ?? acc, null);
+  return { queue, attachment, uploading, error, upload, uploadAll, cancel, remove, reset };
+}
+function generateLocalId() {
+  const c = globalThis.crypto;
+  if (c && typeof c.randomUUID === "function") return c.randomUUID();
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
 }
 function useAttachmentUrl(attachmentId) {
   const chat = usePoolse();
@@ -856,6 +920,35 @@ function useAttachmentUrl(attachmentId) {
   }, [chat, attachmentId]);
   return { url, loading, error };
 }
+var EMPTY = { profile: null, loading: false };
+function useUser(userId) {
+  const chat = usePoolse();
+  const [state, setState] = react.useState(() => {
+    if (!userId) return EMPTY;
+    const cached = chat.users.peek(userId);
+    if (cached === void 0) return { profile: null, loading: true };
+    return { profile: cached, loading: false };
+  });
+  react.useEffect(() => {
+    if (!userId) {
+      setState(EMPTY);
+      return;
+    }
+    const apply = () => {
+      const cached = chat.users.peek(userId);
+      if (cached === void 0) {
+        setState({ profile: null, loading: true });
+        void chat.users.get(userId);
+      } else {
+        setState({ profile: cached, loading: false });
+      }
+    };
+    const off = chat.users.subscribe(userId, apply);
+    apply();
+    return off;
+  }, [chat, userId]);
+  return state;
+}
 
 Object.defineProperty(exports, "ApiError", {
   enumerable: true,
@@ -891,5 +984,6 @@ exports.useReactions = useReactions;
 exports.useRealtimeStatus = useRealtimeStatus;
 exports.useThread = useThread;
 exports.useTyping = useTyping;
+exports.useUser = useUser;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map