@antzsoft/chat-core 1.0.3 → 1.0.4

package/docs/integration-guide.html

@@ -842,6 +842,14 @@ chatClient.<span class="fn">disconnect</span>();
   <span class="at">name</span>: <span class="str">'Design Team'</span>, <span class="at">participantIds</span>: [<span class="str">'user-1'</span>, <span class="str">'user-2'</span>],
 });
 
+<span class="cm">// Upload group icon after creation (admin only)</span>
+<span class="cm">// Web — pass a File object from an &lt;input type="file"&gt;</span>
+<span class="kw">await</span> conversationsApi.<span class="fn">uploadIcon</span>(group.id, file);
+
+<span class="cm">// React Native — pass { uri, name, type } from image picker</span>
+<span class="kw">await</span> conversationsApi.<span class="fn">uploadIcon</span>(group.id, { <span class="at">uri</span>: asset.uri, <span class="at">name</span>: <span class="str">'icon.jpg'</span>, <span class="at">type</span>: <span class="str">'image/jpeg'</span> });
+<span class="cm">// Returns updated conversation with fresh iconUrl. Old icon deleted from storage automatically.</span>
+
 <span class="cm">// Participants</span>
 <span class="kw">const</span> members = <span class="kw">await</span> conversationsApi.<span class="fn">getMembers</span>(conversationId);
 <span class="kw">await</span> conversationsApi.<span class="fn">addParticipants</span>(conversationId, [<span class="str">'user-3'</span>]);
@@ -857,33 +865,89 @@ chatClient.<span class="fn">disconnect</span>();
 
 <!-- ─── STEP 7: ROOMS ──────────────────────────────────────────────────── -->
 <section id="step-rooms">
-  <h2><span class="step">STEP 7</span> Join &amp; Leave a Room</h2>
-  <p>Joining a room subscribes your socket to real-time events for that conversation. Both <code>joinRoom</code> and <code>leaveRoom</code> are fire-and-forget — they silently no-op if the socket isn't connected.</p>
+  <h2><span class="step">STEP 7</span> Rooms — Auto-join, <code>joinRoom</code>, and <code>new_message</code></h2>
+
+  <h4>Auto-join on connect</h4>
+  <p>
+    <strong>On every socket connection, the server automatically joins the user into all their existing conversation rooms.</strong>
+    No client action is needed. The moment the socket connects, the user is already subscribed to real-time events
+    (<code>new_message</code>, <code>typing_indicator</code>, <code>read_receipt</code>, etc.) for every conversation they belong to.
+  </p>
+  <div class="callout info">
+    <strong>You do not need to call <code>joinRoom</code> when opening a chat screen.</strong>
+    The user is already in the room. Calling <code>joinRoom</code> on an already-joined room is safe (idempotent)
+    but triggers an unnecessary DB access check — avoid it in hot paths.
+  </div>
+
+  <h4>When to call <code>joinRoom</code></h4>
+  <p>
+    There is only one real use case — when the <strong>user is added to a conversation while their socket is already connected</strong>
+    (either someone created a new group and added them, or they were added to an existing group at runtime).
+    The server does <strong>not</strong> auto-join the user's socket to the new room — it only emits <code>conversation_created</code>
+    to the user's personal room. Without calling <code>joinRoom</code>, the socket will not receive any
+    <code>new_message</code>, <code>typing_indicator</code>, or other room events for that conversation.
+  </p>
+
+  <pre><code><span class="cm">// Fires when you're added to a new or existing conversation at runtime</span>
+client.socket.<span class="fn">on</span>(<span class="str">'conversation_created'</span>, (conv) => {
+  client.socket.emit.<span class="fn">joinRoom</span>(conv.id);
+});</code></pre>
+
+  <p><code>leaveRoom</code> is only needed if you want to intentionally stop receiving events for a room the user is still a member of (e.g. archiving client-side). It is not needed when navigating away from a screen.</p>
+
+  <h4>Where to listen to <code>new_message</code></h4>
+  <p>
+    Because the user is auto-joined to all rooms, <code>new_message</code> fires for <em>any</em> conversation — not just the one currently open.
+    Register <strong>one listener at app root level</strong>, right after <code>client.connect()</code>.
+    Never add it inside a screen or component. Use <code>message.conversationId</code> to route the message to the right place.
+  </p>
 
   <div data-p="rn web">
-    <pre><code><span class="kw">import</span> { socketEmit, onSocketStatus } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+    <pre><code><span class="cm">// Register once at app root — covers all conversations</span>
+client.socket.<span class="fn">on</span>(<span class="str">'new_message'</span>, (event: <span class="tp">NewMessageEvent</span>) => {
+  <span class="kw">const</span> { message } = event;
 
-<span class="fn">useEffect</span>(() => {
-  socketEmit.<span class="fn">joinRoom</span>(conversationId);
+  <span class="cm">// Update the open chat view if this conversation is active</span>
+  <span class="kw">if</span> (message.conversationId === activeConversationId) {
+    <span class="fn">appendMessageToView</span>(message);
+  }
 
-  <span class="cm">// Re-join if socket reconnects while this screen is open (e.g. after foreground)</span>
-  <span class="kw">const</span> unsub = <span class="fn">onSocketStatus</span>((s) => {
-    <span class="kw">if</span> (s === <span class="str">'connected'</span>) socketEmit.<span class="fn">joinRoom</span>(conversationId);
+  <span class="cm">// Always update conversation list (last message + unread badge)</span>
+  <span class="fn">updateConversationList</span>(message.conversationId, {
+    lastMessage: message,
+    <span class="cm">// Don't increment unread if the user sent it or is currently viewing that chat</span>
+    incrementUnread: message.conversationId !== activeConversationId
+                     &amp;&amp; message.senderId !== currentUserId,
   });
+});
 
-  <span class="kw">return</span> () => { socketEmit.<span class="fn">leaveRoom</span>(conversationId); unsub(); };
-}, [conversationId]);</code></pre>
+<span class="cm">// Only case where joinRoom is needed</span>
+client.socket.<span class="fn">on</span>(<span class="str">'conversation_created'</span>, (conv) => {
+  client.socket.emit.<span class="fn">joinRoom</span>(conv.id);
+});</code></pre>
   </div>
   <div data-p="node">
-    <pre><code><span class="kw">import</span> { socketEmit } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+    <pre><code><span class="cm">// Bot / headless — same pattern, one listener at startup</span>
+client.socket.<span class="fn">on</span>(<span class="str">'new_message'</span>, (event: <span class="tp">NewMessageEvent</span>) => {
+  <span class="kw">const</span> { message } = event;
+  console.<span class="fn">log</span>(<span class="str">`[</span>${message.conversationId}<span class="str">]`</span>, message.content.text);
+  client.socket.emit.<span class="fn">markRead</span>(message.conversationId, message.id);
+});
 
-socketEmit.<span class="fn">joinRoom</span>(conversationId);
-<span class="cm">// When done:</span>
-socketEmit.<span class="fn">leaveRoom</span>(conversationId);</code></pre>
+client.socket.<span class="fn">on</span>(<span class="str">'conversation_created'</span>, (conv) => {
+  client.socket.emit.<span class="fn">joinRoom</span>(conv.id);
+});</code></pre>
   </div>
+
   <div class="callout warn">
-    <strong>Room subscriptions don't survive reconnects.</strong>
-    The server forgets which rooms you were in if the socket disconnects. Always re-join after reconnect (the <code>onSocketStatus</code> pattern above handles this for React apps).
+    <strong>Summary of rules:</strong>
+    <ul>
+      <li>All existing rooms are auto-joined on socket connect — no <code>joinRoom</code> needed on screen open.</li>
+      <li>Call <code>joinRoom</code> only after a <code>conversation_created</code> event.</li>
+      <li>Add the <code>new_message</code> listener once at app root, never per screen.</li>
+      <li>Use <code>message.conversationId</code> to route to the right view or badge update.</li>
+      <li>Track <code>activeConversationId</code> to decide whether to increment the unread count.</li>
+    </ul>
   </div>
 </section>
 
@@ -970,18 +1034,113 @@ socket.<span class="fn">on</span>(<span class="str">'message_deleted'</span>, (e
   </div>
   <h4>All socket events</h4>
   <table>
-    <thead><tr><th>Event</th><th>When fired</th></tr></thead>
+    <thead><tr><th>Event</th><th>When fired</th><th>Where to listen / unlisten</th></tr></thead>
     <tbody>
-      <tr><td><code>'new_message'</code></td><td>New message in a joined room</td></tr>
-      <tr><td><code>'message_updated'</code></td><td>A message was edited</td></tr>
-      <tr><td><code>'message_deleted'</code></td><td>Deleted for everyone</td></tr>
-      <tr><td><code>'message_deleted_for_me'</code></td><td>Deleted for current user only</td></tr>
-      <tr><td><code>'reaction_updated'</code></td><td>Emoji reaction added/removed</td></tr>
-      <tr><td><code>'typing'</code></td><td>User started/stopped typing</td></tr>
-      <tr><td><code>'user_online'</code> / <code>'user_offline'</code></td><td>User went online/offline — auto-updates <code>useChatStore.lastSeen</code></td></tr>
-      <tr><td><code>'read_receipt'</code></td><td>Messages marked as read — auto-updates <code>useChatStore.lastRead</code></td></tr>
-      <tr><td><code>'message_ack'</code></td><td>Your sent message acknowledged (tempId → real ID)</td></tr>
-      <tr><td><code>'message_delivered'</code></td><td>Message delivered to recipient</td></tr>
+      <tr>
+        <td><code>'new_message'</code></td>
+        <td>New message in any of the user's conversations — all rooms are auto-joined on connect</td>
+        <td><strong>App root</strong> after <code>client.connect()</code>. Never remove this listener — it must stay alive for the full app session to keep the conversation list and unread badges up to date.</td>
+      </tr>
+      <tr>
+        <td><code>'message_updated'</code></td>
+        <td>A message was edited</td>
+        <td><strong>Chat detail screen</strong> — add on mount, remove on unmount (<code>socket.off</code>).</td>
+      </tr>
+      <tr>
+        <td><code>'message_deleted'</code></td>
+        <td>Deleted for everyone</td>
+        <td><strong>Chat detail screen</strong> — add on mount, remove on unmount.</td>
+      </tr>
+      <tr>
+        <td><code>'message_deleted_for_me'</code></td>
+        <td>Deleted for current user only (fired only to that user's socket)</td>
+        <td><strong>Chat detail screen</strong> — add on mount, remove on unmount.</td>
+      </tr>
+      <tr>
+        <td><code>'reaction_updated'</code></td>
+        <td>Emoji reaction added/removed</td>
+        <td><strong>Chat detail screen</strong> — add on mount, remove on unmount.</td>
+      </tr>
+      <tr>
+        <td><code>'message_pin_updated'</code></td>
+        <td>A message was pinned or unpinned</td>
+        <td><strong>Chat detail screen</strong> — add on mount, remove on unmount.</td>
+      </tr>
+      <tr>
+        <td><code>'typing_indicator'</code></td>
+        <td>User started/stopped typing (payload: <code>{ conversationId, userId, displayName, isTyping }</code>)</td>
+        <td><strong>Chat detail screen</strong> — add on mount, remove on unmount.</td>
+      </tr>
+      <tr>
+        <td><code>'user_online'</code></td>
+        <td>A participant came online</td>
+        <td><strong>App root</strong> — drives online indicators everywhere. Keep for full session.</td>
+      </tr>
+      <tr>
+        <td><code>'user_offline'</code></td>
+        <td>A participant went offline</td>
+        <td><strong>App root</strong> — drives online indicators and last-seen everywhere. Keep for full session.</td>
+      </tr>
+      <tr>
+        <td><code>'user_status'</code></td>
+        <td>Global presence broadcast (online/offline/away) to all connected clients</td>
+        <td><strong>App root</strong> — keep for full session.</td>
+      </tr>
+      <tr>
+        <td><code>'online_users'</code></td>
+        <td>Full list of online user IDs — sent on initial room join</td>
+        <td><strong>App root</strong> — keep for full session.</td>
+      </tr>
+      <tr>
+        <td><code>'read_receipt'</code></td>
+        <td>Messages marked as read by a participant</td>
+        <td><strong>Chat detail screen</strong> (to update tick marks) + <strong>app root</strong> (to clear your own unread count when read on another device).</td>
+      </tr>
+      <tr>
+        <td><code>'unread_count_changed'</code></td>
+        <td>Your unread count changed — sent to all your devices simultaneously</td>
+        <td><strong>App root / conversation list screen</strong> — keep alive as long as the list is rendered.</td>
+      </tr>
+      <tr>
+        <td><code>'message_ack'</code></td>
+        <td>Server acknowledged your sent message (tempId → real ID)</td>
+        <td><strong>Chat detail screen</strong> — add on mount, remove on unmount.</td>
+      </tr>
+      <tr>
+        <td><code>'message_delivered'</code></td>
+        <td>A single message you sent was delivered to all active recipients</td>
+        <td><strong>Chat detail screen</strong> — add on mount, remove on unmount.</td>
+      </tr>
+      <tr>
+        <td><code>'messages_delivered'</code></td>
+        <td>Batch delivery catch-up when a recipient comes online</td>
+        <td><strong>Chat detail screen</strong> — add on mount, remove on unmount.</td>
+      </tr>
+      <tr>
+        <td><code>'conversation_created'</code></td>
+        <td>A new conversation was created (or you were added to one)</td>
+        <td><strong>App root</strong> — call <code>joinRoom</code> here for the new conversation. Keep for full session.</td>
+      </tr>
+      <tr>
+        <td><code>'conversation_updated'</code></td>
+        <td>A conversation's last message or metadata changed</td>
+        <td><strong>App root</strong> — keep for full session. The server emits this for every message across all conversations; a global listener keeps the in-memory conversation list and unread badge always in sync.</td>
+      </tr>
+      <tr>
+        <td><code>'conversation_deleted'</code></td>
+        <td>A conversation was deleted</td>
+        <td><strong>App root / conversation list screen</strong> — remove the conversation from state and navigate away if it was open.</td>
+      </tr>
+      <tr>
+        <td><code>'participant_joined'</code></td>
+        <td>A new participant was added to a group conversation</td>
+        <td><strong>Chat detail screen</strong> — add on mount, remove on unmount.</td>
+      </tr>
+      <tr>
+        <td><code>'participant_left'</code></td>
+        <td>A participant left or was removed from a group conversation</td>
+        <td><strong>Chat detail screen</strong> — add on mount, remove on unmount.</td>
+      </tr>
     </tbody>
   </table>
 </section>
@@ -1910,19 +2069,114 @@ socket?.<span class="fn">on</span>(<span class="str">'unread_count_changed'</spa
   <span class="cm">// unreadCount is 0 — the conversation was just read.</span>
 });</code></pre>
 
-  <h3>Platform-specific badge updates</h3>
+  <h3>Chat icon badge — the key insight</h3>
+  <p>
+    If you use <code>@antzsoft/chat-web-sdk</code> or <code>@antzsoft/chat-rn-sdk</code>,
+    <strong>you do not need to listen to socket events manually</strong>.
+    <code>useConversations()</code> is already subscribed internally — every
+    <code>conversation_updated</code> and <code>unread_count_changed</code> event
+    automatically updates the hook's data. Just sum the counts:
+  </p>
 
-  <div data-p="rn">
-    <pre><code><span class="kw">import</span> * <span class="kw">as</span> Notifications <span class="kw">from</span> <span class="str">'expo-notifications'</span>;
-<span class="kw">import</span> { AppState } <span class="kw">from</span> <span class="str">'react-native'</span>;
+  <div data-p="web">
+    <pre><code><span class="kw">import</span> { useConversations } <span class="kw">from</span> <span class="str">'@antzsoft/chat-web-sdk'</span>;
+
+<span class="kw">function</span> <span class="fn">ChatIconButton</span>({ onClick }: { onClick: () => <span class="tp">void</span> }) {
+  <span class="kw">const</span> { conversations } = <span class="fn">useConversations</span>();
 
-<span class="cm">// Keep badge in sync while app is active</span>
+  <span class="cm">// Recalculates automatically on every socket update — no extra listener needed</span>
+  <span class="kw">const</span> totalUnread = conversations.<span class="fn">reduce</span>(
+    (sum, c) => sum + (c.unreadCount ?? <span class="num">0</span>), <span class="num">0</span>
+  );
+
+  <span class="kw">return</span> (
+    &lt;button onClick={onClick} style={{ position: <span class="str">'relative'</span> }}&gt;
+      💬
+      {totalUnread &gt; <span class="num">0</span> &amp;&amp; (
+        &lt;span style={{
+          position: <span class="str">'absolute'</span>, top: <span class="num">-6</span>, right: <span class="num">-6</span>,
+          backgroundColor: <span class="str">'#e53935'</span>, color: <span class="str">'#fff'</span>,
+          borderRadius: <span class="str">'50%'</span>, minWidth: <span class="num">18</span>, height: <span class="num">18</span>,
+          fontSize: <span class="num">11</span>, fontWeight: <span class="num">700</span>,
+          display: <span class="str">'flex'</span>, alignItems: <span class="str">'center'</span>, justifyContent: <span class="str">'center'</span>,
+          padding: <span class="str">'0 4px'</span>,
+        }}&gt;
+          {totalUnread &gt; <span class="num">99</span> ? <span class="str">'99+'</span> : totalUnread}
+        &lt;/span&gt;
+      )}
+    &lt;/button&gt;
+  );
+}
+
+<span class="cm">// Update browser tab title too</span>
 <span class="fn">useEffect</span>(() => {
   <span class="kw">const</span> total = conversations.<span class="fn">reduce</span>((s, c) => s + (c.unreadCount ?? <span class="num">0</span>), <span class="num">0</span>);
-  Notifications.<span class="fn">setBadgeCountAsync</span>(total);
-}, [conversations]);
+  document.title = total &gt; <span class="num">0</span> ? <span class="str">`(${total}) Antz Chat`</span> : <span class="str">'Antz Chat'</span>;
+}, [conversations]);</code></pre>
+  </div>
 
-<span class="cm">// Refresh when app comes to foreground (socket may have been down)</span>
+  <div data-p="rn">
+    <pre><code><span class="kw">import</span> { useConversations } <span class="kw">from</span> <span class="str">'@antzsoft/chat-rn-sdk'</span>;
+<span class="kw">import</span> * <span class="kw">as</span> Notifications <span class="kw">from</span> <span class="str">'expo-notifications'</span>;
+
+<span class="kw">function</span> <span class="fn">ChatTabIcon</span>({ color }: { color: <span class="tp">string</span> }) {
+  <span class="kw">const</span> { conversations } = <span class="fn">useConversations</span>();
+
+  <span class="cm">// Recalculates automatically on every socket update — no extra listener needed</span>
+  <span class="kw">const</span> totalUnread = conversations.<span class="fn">reduce</span>(
+    (sum, c) => sum + (c.unreadCount ?? <span class="num">0</span>), <span class="num">0</span>
+  );
+
+  <span class="cm">// Sync OS app icon badge</span>
+  <span class="fn">useEffect</span>(() => {
+    Notifications.<span class="fn">setBadgeCountAsync</span>(totalUnread);
+  }, [totalUnread]);
+
+  <span class="kw">return</span> (
+    &lt;View&gt;
+      &lt;Ionicons name=<span class="str">"chatbubbles-outline"</span> size={<span class="num">24</span>} color={color} /&gt;
+      {totalUnread &gt; <span class="num">0</span> &amp;&amp; (
+        &lt;View style={{
+          position: <span class="str">'absolute'</span>, top: <span class="num">-4</span>, right: <span class="num">-6</span>,
+          backgroundColor: <span class="str">'#e53935'</span>, borderRadius: <span class="num">9</span>,
+          minWidth: <span class="num">18</span>, height: <span class="num">18</span>, alignItems: <span class="str">'center'</span>,
+          justifyContent: <span class="str">'center'</span>, paddingHorizontal: <span class="num">4</span>,
+        }}&gt;
+          &lt;Text style={{ color: <span class="str">'#fff'</span>, fontSize: <span class="num">10</span>, fontWeight: <span class="str">'700'</span> }}&gt;
+            {totalUnread &gt; <span class="num">99</span> ? <span class="str">'99+'</span> : String(totalUnread)}
+          &lt;/Text&gt;
+        &lt;/View&gt;
+      )}
+    &lt;/View&gt;
+  );
+}
+
+<span class="cm">// Wire into Tab.Navigator</span>
+&lt;Tab.Screen
+  name=<span class="str">"Chat"</span>
+  component={ChatScreen}
+  options={{ tabBarIcon: ({ color }) =&gt; &lt;ChatTabIcon color={color} /&gt; }}
+/&gt;</code></pre>
+  </div>
+
+  <p style="margin:16px 0 8px;color:#c8d0e0;font-size:14px">
+    The full update chain — no polling, no manual socket code:
+  </p>
+  <pre style="background:var(--code-bg);padding:12px 16px;border-radius:8px;font-size:12px;color:#8892b0;border:1px solid var(--border)">New message sent
+  → server emits conversation_updated (DB-accurate unreadCount per participant)
+  → SocketProvider updates useConversations() React Query cache
+  → totalUnread recalculates → badge re-renders
+
+User reads conversation
+  → server emits unread_count_changed to ALL devices of that user simultaneously
+  → useConversations() cache updated → badge clears on every device at once</pre>
+
+  <h3>Platform-specific: foreground resume + tab title</h3>
+
+  <div data-p="rn">
+    <pre><code><span class="kw">import</span> { AppState } <span class="kw">from</span> <span class="str">'react-native'</span>;
+
+<span class="cm">// Refresh when app comes to foreground (socket may have been down while backgrounded)</span>
 <span class="fn">useEffect</span>(() => {
   <span class="kw">const</span> sub = AppState.<span class="fn">addEventListener</span>(<span class="str">'change'</span>, <span class="kw">async</span> (state) => {
     <span class="kw">if</span> (state === <span class="str">'active'</span>) {
@@ -1935,13 +2189,7 @@ socket?.<span class="fn">on</span>(<span class="str">'unread_count_changed'</spa
   </div>
 
   <div data-p="web">
-    <pre><code><span class="cm">// Browser tab title badge</span>
-<span class="fn">useEffect</span>(() => {
-  <span class="kw">const</span> total = conversations.<span class="fn">reduce</span>((s, c) => s + (c.unreadCount ?? <span class="num">0</span>), <span class="num">0</span>);
-  document.title = total > <span class="num">0</span> ? <span class="str">`(${total}) Antz Chat`</span> : <span class="str">'Antz Chat'</span>;
-}, [conversations]);
-
-<span class="cm">// Refresh when tab becomes visible (socket may have been down)</span>
+    <pre><code><span class="cm">// Refresh when tab becomes visible (socket may have been down)</span>
 <span class="fn">useEffect</span>(() => {
   <span class="kw">function</span> <span class="fn">onVisible</span>() {
     <span class="kw">if</span> (document.visibilityState === <span class="str">'visible'</span>) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antzsoft/chat-core",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Platform-agnostic core for Antz Chat — API, socket, stores, types. Works in browser, React Native (Expo or bare), and Node.js.",
   "author": "Antz",
   "license": "MIT",