@antzsoft/chat-core 1.1.0 → 1.1.2

package/docs/integration-guide.html

@@ -155,7 +155,7 @@ section.sec>h2:hover{color:#fff}
 
   <div class="section-label">What's New</div>
   <ul>
-    <li><a href="#whats-new">v1.1.0 Release Notes</a></li>
+    <li><a href="#whats-new">v1.1.2 Release Notes</a></li>
   </ul>
 
   <div class="section-label">Getting Started</div>
@@ -242,12 +242,174 @@ section.sec>h2:hover{color:#fff}
   <h2>What's New</h2>
   <p style="color:var(--muted);font-size:13px;margin-bottom:20px">Version history and release notes. Click a version to expand.</p>
 
-  <!-- ── v1.1.0 (current) ── -->
-  <div class="wn-version open" id="wn-110">
+  <!-- ── v1.1.2 (current) ── -->
+  <div class="wn-version open" id="wn-112">
+    <div class="wn-header" onclick="toggleVersion('wn-112')">
+      <div class="wn-title">
+        <span class="wn-ver">v1.1.2</span>
+        <span class="wn-badge current">Current</span>
+        <span class="wn-date">May 2026</span>
+      </div>
+      <span class="wn-chevron">▲</span>
+    </div>
+    <div class="wn-body">
+
+      <div class="wn-item" id="wn-112-1">
+        <div class="wn-item-header" onclick="toggleItem('wn-112-1')">
+          <span class="wn-tag new">New</span>
+          <span class="wn-item-title">Participants stored in a dedicated collection</span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p>Participants are no longer embedded inside conversation documents. Each participant is now its own document in a separate <code>chat_conversation_participants</code> collection.</p>
+          <p>This removes the MongoDB 16 MB document size ceiling for large groups, eliminates write contention when many members join or leave simultaneously, and allows per-user data (mute, pin, notification settings) to be updated without touching the conversation document.</p>
+          <p><strong>No client API changes.</strong> All existing SDK calls, types, and socket events are unaffected.</p>
+        </div>
+      </div>
+
+      <div class="wn-item" id="wn-112-2">
+        <div class="wn-item-header" onclick="toggleItem('wn-112-2')">
+          <span class="wn-tag new">New</span>
+          <span class="wn-item-title">Transit encryption</span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p>All socket payloads are now encrypted end-to-end using a per-session symmetric key negotiated on connect via a server-side handshake. Encryption and decryption are handled transparently inside the SDK — no changes to how you call <code>sendMessage</code>, <code>socketEmit</code>, or any event listeners.</p>
+          <p><strong>No action required.</strong> Existing callers work without modification.</p>
+        </div>
+      </div>
+
+      <div class="wn-item" id="wn-112-3">
+        <div class="wn-item-header" onclick="toggleItem('wn-112-3')">
+          <span class="wn-tag fix">Fix</span>
+          <span class="wn-item-title">Disbanded groups now visible in read-only mode for removed members</span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p>When a group was disbanded (all members left or removed), removed participants had an inconsistent view — the conversation sometimes disappeared entirely before they could dismiss it. Removed participants now always see the conversation in read-only mode until they explicitly call <code>leave()</code> to hide it from their list.</p>
+        </div>
+      </div>
+
+      <div class="wn-item" id="wn-112-4">
+        <div class="wn-item-header" onclick="toggleItem('wn-112-4')">
+          <span class="wn-tag fix">Fix</span>
+          <span class="wn-item-title">Removed participant access hardened</span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p>Three access control gaps closed for removed users:</p>
+          <ul>
+            <li><strong>Message history capped at removal time</strong> — The REST message list API now applies a <code>createdAt ≤ removedAt</code> filter for removed participants. Messages sent after removal are no longer visible.</li>
+            <li><strong>Search, starred messages, and unread counts blocked</strong> — Removed users could previously search messages, view their starred messages, and fetch unread counts from conversations they were removed from. All three endpoints now check active membership before returning results.</li>
+            <li><strong>Socket and push already enforced</strong> — Real-time events and push notifications were already blocked at the socket room level (room kick on removal). No change here.</li>
+          </ul>
+          <p><strong>No client action required.</strong> These are server-side enforcement fixes.</p>
+        </div>
+      </div>
+
+      <div class="wn-item" id="wn-112-5">
+        <div class="wn-item-header" onclick="toggleItem('wn-112-5')">
+          <span class="wn-tag fix">Fix</span>
+          <span class="wn-item-title">Unread badge drops to zero immediately when admin removes a user</span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p>When an admin removed a user from a group, the removed user's unread badge stayed non-zero until they manually opened the conversation. The server now bulk-inserts read records for all unread messages in that conversation at the moment of removal, so the badge correctly drops to zero immediately.</p>
+          <p><strong>No client action required.</strong></p>
+        </div>
+      </div>
+
+      <div class="wn-item" id="wn-112-6">
+        <div class="wn-item-header" onclick="toggleItem('wn-112-6')">
+          <span class="wn-tag fix">Fix</span>
+          <span class="wn-item-title">Compression metadata now stored on the server</span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p>When a compressed image was uploaded via <code>uploadBatch</code>, the file record on the server silently dropped <code>compressed</code>, <code>originalSize</code>, and <code>compressionAlgorithm</code> due to DTO validation stripping unknown fields. These are now correctly persisted.</p>
+          <p><strong>No client action required.</strong> <code>uploadBatch</code> already sends this metadata — it will now be saved automatically.</p>
+        </div>
+      </div>
+
+      <div class="wn-item" id="wn-112-7">
+        <div class="wn-item-header" onclick="toggleItem('wn-112-7')">
+          <span class="wn-tag fix">Fix</span>
+          <span class="wn-item-title">Delete for me also removes the message from your starred list</span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p>Calling <code>deleteForMe</code> on a starred message hid it from the message list but left it in the starred messages list. The server now removes the star record at the same time as the delete-for-me record. The message no longer appears in <code>getStarredMessages</code> after being deleted for the requesting user.</p>
+          <p><strong>No client action required.</strong></p>
+        </div>
+      </div>
+
+    </div>
+  </div><!-- /.wn-version -->
+
+  <!-- ── v1.1.1 ── -->
+  <div class="wn-version" id="wn-111">
+    <div class="wn-header" onclick="toggleVersion('wn-111')">
+      <div class="wn-title">
+        <span class="wn-ver">v1.1.1</span>
+        <span class="wn-date">May 2026</span>
+      </div>
+      <span class="wn-chevron">▲</span>
+    </div>
+    <div class="wn-body">
+
+      <div class="wn-item" id="wn-111-1">
+        <div class="wn-item-header" onclick="toggleItem('wn-111-1')">
+          <span class="wn-tag new">New</span>
+          <span class="wn-item-title">Attachment snapshot on reply messages</span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p><code>replyTo</code> now includes an <code>attachmentSnapshot</code> field containing a snapshot of the first attachment from the quoted message: <code>type</code>, <code>filename</code>, <code>mimeType</code>, <code>size</code>, <code>duration</code>, <code>dimensions</code>, and a signed <code>url</code>.</p>
+          <p>The snapshot is stored at write time so reply bubbles can render the quoted attachment preview without fetching the original message. A new <code>ReplyAttachmentSnapshot</code> type is exported from the SDK.</p>
+        </div>
+      </div>
+
+      <div class="wn-item" id="wn-111-2">
+        <div class="wn-item-header" onclick="toggleItem('wn-111-2')">
+          <span class="wn-tag fix">Fix</span>
+          <span class="wn-item-title"><code>contentPreview</code> for multi-attachment replies</span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p>When replying to a message with multiple attachments, <code>replyTo.contentPreview</code> now reflects the full count: <code>"photo.jpg +2 more"</code>, <code>"3 Photos"</code>, <code>"3 Attachments"</code> (mixed types). Previously it always showed only the first filename regardless of how many attachments the quoted message had.</p>
+        </div>
+      </div>
+
+      <div class="wn-item" id="wn-111-3">
+        <div class="wn-item-header" onclick="toggleItem('wn-111-3')">
+          <span class="wn-tag fix">Fix</span>
+          <span class="wn-item-title">Pin, unpin, and unmute operations</span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p>Server-side issues causing pin, unpin, and unmute to fail in certain states are resolved. All three operations now complete reliably. <strong>No client action required.</strong></p>
+        </div>
+      </div>
+
+      <div class="wn-item" id="wn-111-4">
+        <div class="wn-item-header" onclick="toggleItem('wn-111-4')">
+          <span class="wn-tag fix">Fix</span>
+          <span class="wn-item-title">Various backend fixes</span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p>Stability and correctness improvements across multiple server-side paths. <strong>No client action required.</strong></p>
+        </div>
+      </div>
+
+    </div>
+  </div><!-- /.wn-version -->
+
+  <!-- ── v1.1.0 ── -->
+  <div class="wn-version" id="wn-110">
     <div class="wn-header" onclick="toggleVersion('wn-110')">
       <div class="wn-title">
         <span class="wn-ver">v1.1.0</span>
-        <span class="wn-badge current">Current</span>
         <span class="wn-date">May 2026</span>
       </div>
       <span class="wn-chevron">▲</span>
@@ -430,7 +592,7 @@ section.sec>h2:hover{color:#fff}
           <span class="wn-chevron-sm">▾</span>
         </div>
         <div class="wn-item-body">
-          <p>The <code>participant_left</code> socket event was only broadcast to the <code>conversation:&lt;id&gt;</code> room. Users only join that room when they actively open that specific conversation — so users on the conversation-list screen never received the event and saw a stale participant count. The server now also emits directly to each remaining participant's personal <code>user:&lt;tenantId&gt;:&lt;userId&gt;</code> room, skipping users already in the conversation room to avoid double-delivery.</p>
+          <p>The <code>participant_left</code> socket event was only broadcast to the <code>conversation:&lt;tenantId&gt;:&lt;id&gt;</code> room. Users only join that room when they actively open that specific conversation — so users on the conversation-list screen never received the event and saw a stale participant count. The server now also emits directly to each remaining participant's personal <code>user:&lt;tenantId&gt;:&lt;userId&gt;</code> room, skipping users already in the conversation room to avoid double-delivery.</p>
           <p><strong>Action required:</strong> None. Server-side fix only.</p>
         </div>
       </div>
@@ -457,6 +619,48 @@ section.sec>h2:hover{color:#fff}
         </div>
       </div>
 
+      <div class="wn-item" id="wn-109-7">
+        <div class="wn-item-header" onclick="toggleItem('wn-109-7')">
+          <span class="wn-tag fix">Fix</span>
+          <span class="wn-item-title">Removed user could re-enter conversation room via <code>join_room</code></span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p>The socket access check for <code>join_room</code> was missing the <code>isActive</code> participant check. A removed user whose client re-emitted <code>joinRoom</code> (e.g. on reconnect or by navigating back to the chat screen) would be silently re-admitted to the conversation room and continue receiving <code>new_message</code> events. The check now requires <code>isActive: true</code>, consistent with the write-access check.</p>
+          <p><strong>Action required:</strong> None. Server-side fix only.</p>
+        </div>
+      </div>
+
+      <div class="wn-item" id="wn-109-8">
+        <div class="wn-item-header" onclick="toggleItem('wn-109-8')">
+          <span class="wn-tag fix">Fix</span>
+          <span class="wn-item-title">Re-added user's conversation missing from list when they had previously deleted it</span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p>When a user deleted a conversation (<code>isHidden: true</code>), was then removed from the group, and later re-added by an admin, the conversation never reappeared in their list. The reactivation path now resets <code>isHidden</code> to <code>false</code> alongside <code>isActive</code>.</p>
+          <p>Additionally, the server now server-side joins the re-added user's active sockets into the conversation room and emits <code>conversation_created</code> to their personal room so the conversation appears immediately — no reconnect or <code>joinRoom</code> call needed.</p>
+          <p><strong>Action required:</strong> None. Server-side fix only. Existing <code>conversation_created → joinRoom</code> listeners remain safe (idempotent).</p>
+        </div>
+      </div>
+
+      <div class="wn-item" id="wn-109-9">
+        <div class="wn-item-header" onclick="toggleItem('wn-109-9')">
+          <span class="wn-tag new">New</span>
+          <span class="wn-item-title">Optional <code>role</code> parameter on <code>addParticipants</code></span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p><code>addParticipants</code> now accepts an optional <code>role</code> parameter (<code>'admin' | 'member'</code>, default <code>'member'</code>). This applies to both newly added users and previously removed users being re-added. A former admin who is re-added without specifying <code>role: 'admin'</code> will come back as a member — their previous role is never silently restored.</p>
+          <pre><code><span class="cm">// Default — added as member (backward compatible)</span>
+<span class="kw">await</span> conversationsApi.<span class="fn">addParticipants</span>(conversationId, [<span class="str">'user-3'</span>]);
+
+<span class="cm">// Explicitly add as admin</span>
+<span class="kw">await</span> conversationsApi.<span class="fn">addParticipants</span>(conversationId, [<span class="str">'user-3'</span>], <span class="str">'admin'</span>);</code></pre>
+          <p><strong>Action required:</strong> None for existing code — the parameter is optional and defaults to <code>'member'</code>. No call sites need updating unless you want to add members as admins directly.</p>
+        </div>
+      </div>
+
     </div>
   </div>
 
@@ -1175,7 +1379,7 @@ npx pod-install</code></pre>
       <tr><td><code>userId</code></td><td><code>string</code></td><td>External auth</td><td>Your system's user ID</td></tr>
       <tr><td><code>avatar.url</code></td><td><code>string</code></td><td>No</td><td>Avatar URL — pass <code>url</code> OR <code>base64</code>, not both</td></tr>
       <tr><td><code>avatar.base64</code></td><td><code>string</code></td><td>No</td><td>Raw base64 avatar string</td></tr>
-      <tr><td><code>encryptionMode</code></td><td><code>'none'|'server'</code></td><td>No</td><td>Defaults to <code>'none'</code></td></tr>
+      <tr><td><code>transitEncryption</code></td><td><code>boolean</code></td><td>No</td><td>Payload-level wire encryption: encrypts every HTTP request/response and socket event using ECDH key exchange + AES-256-GCM. Default: <code>true</code>. Server must have <code>TRANSIT_ENCRYPTION_ENABLED=true</code> (default). Safe to toggle anytime — wire-only, nothing stored. Set <code>false</code> for local development only.</td></tr>
       <tr><td><code>upload</code></td><td><code>UploadConfig</code></td><td>No</td><td>File size limits, allowed types, progress callback</td></tr>
     </tbody>
   </table>
@@ -1536,7 +1740,8 @@ chatClient.<span class="fn">disconnect</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>]);
+<span class="kw">await</span> conversationsApi.<span class="fn">addParticipants</span>(conversationId, [<span class="str">'user-3'</span>]);               <span class="cm">// added as member (default)</span>
+<span class="kw">await</span> conversationsApi.<span class="fn">addParticipants</span>(conversationId, [<span class="str">'user-3'</span>], <span class="str">'admin'</span>);  <span class="cm">// added as admin</span>
 <span class="kw">await</span> conversationsApi.<span class="fn">removeParticipant</span>(conversationId, <span class="str">'user-2'</span>);
 <span class="kw">await</span> conversationsApi.<span class="fn">updateParticipantRole</span>(conversationId, <span class="str">'user-1'</span>, <span class="str">'admin'</span>);
 
@@ -1582,16 +1787,15 @@ chatClient.<span class="fn">disconnect</span>();
 
   <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.
+    When the <strong>user is added to a conversation while their socket is already connected</strong>, the server now automatically joins their active sockets into the new room and emits <code>conversation_created</code> to their personal room. No <code>joinRoom</code> call is required — <code>new_message</code>, <code>typing_indicator</code>, and all other room events will arrive immediately.
+  </p>
+  <p>
+    Calling <code>joinRoom</code> on <code>conversation_created</code> is still safe (idempotent) and can be kept for defensive compatibility, but is no longer necessary:
   </p>
 
-  <pre><code><span class="cm">// Fires when you're added to a new or existing conversation at runtime</span>
+  <pre><code><span class="cm">// Optional — server already handles this automatically</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);
+  client.socket.emit.<span class="fn">joinRoom</span>(conv.id); <span class="cm">// safe no-op if already in room</span>
 });</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>
@@ -1622,9 +1826,9 @@ client.socket.<span class="fn">on</span>(<span class="str">'new_message'</span>,
   });
 });
 
-<span class="cm">// Only case where joinRoom is needed</span>
+<span class="cm">// Optional — server auto-joins the room, but this is safe to keep</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);
+  client.socket.emit.<span class="fn">joinRoom</span>(conv.id); <span class="cm">// idempotent no-op if already joined</span>
 });</code></pre>
   </div>
   <div data-p="node">
@@ -1635,6 +1839,7 @@ client.socket.<span class="fn">on</span>(<span class="str">'new_message'</span>,
   client.socket.emit.<span class="fn">markRead</span>(message.conversationId, message.id);
 });
 
+<span class="cm">// Optional — server auto-joins the room, but safe to keep</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>
@@ -1644,7 +1849,7 @@ client.socket.<span class="fn">on</span>(<span class="str">'conversation_created
     <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>When added to a conversation at runtime, the server now auto-joins the socket room and emits <code>conversation_created</code>. No <code>joinRoom</code> call needed, but safe to keep for compatibility.</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>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antzsoft/chat-core",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "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",