@antzsoft/chat-core 1.1.1 → 1.1.3

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.3 Release Notes</a></li>
   </ul>
 
   <div class="section-label">Getting Started</div>
@@ -242,12 +242,307 @@ 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.3 (current) ── -->
+  <div class="wn-version open" id="wn-113">
+    <div class="wn-header" onclick="toggleVersion('wn-113')">
+      <div class="wn-title">
+        <span class="wn-ver">v1.1.3</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-113-1">
+        <div class="wn-item-header" onclick="toggleItem('wn-113-1')">
+          <span class="wn-tag new">New</span>
+          <span class="wn-item-title">usersApi.updateProfile() — self-user profile update</span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p>The self user can now update their own profile (name, email, phone) instantly without waiting for the 2-hour background sync cycle.</p>
+          <pre><code><span class="kw">await</span> usersApi.<span class="fn">updateProfile</span>({ firstName: <span class="str">'Jane'</span>, lastName: <span class="str">'Smith'</span>, email: <span class="str">'jane@example.com'</span> });</code></pre>
+          <p><strong>Admin-updated fields (firstName, lastName) via external identity provider:</strong> the chat module will reflect those changes either on the next 2-hour sync or the next time the app initialises the chat client. Webhook-based instant sync will be introduced in a future release.</p>
+          <p class="wn-ref">→ <a href="#users-api">Users API</a> for the full reference</p>
+        </div>
+      </div>
+
+      <div class="wn-item" id="wn-113-2">
+        <div class="wn-item-header" onclick="toggleItem('wn-113-2')">
+          <span class="wn-tag new">New</span>
+          <span class="wn-item-title">Group icon — remove support</span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p>Admins can now remove a group icon in addition to setting or replacing one. Tapping the new <strong>✕</strong> button (top-right of the group avatar in Group Info) clears the icon immediately — the asset is deleted from storage and the conversation reverts to its initials avatar.</p>
+          <pre><code><span class="cm">// Remove icon — admin only</span>
+<span class="kw">const</span> updated = <span class="kw">await</span> conversationsApi.<span class="fn">removeIcon</span>(groupId);
+<span class="cm">// updated.iconUrl === undefined</span></code></pre>
+          <p>Like upload, remove is admin-only; non-admins receive <code>403 Forbidden</code>. No icon is ever left orphaned in storage.</p>
+          <p class="wn-ref">→ <a href="#step-convs">Step 6 — Conversations</a> (group icon section) for the full pipeline</p>
+        </div>
+      </div>
+
+      <div class="wn-item" id="wn-113-3">
+        <div class="wn-item-header" onclick="toggleItem('wn-113-3')">
+          <span class="wn-tag new">New</span>
+          <span class="wn-item-title">Leave / Delete / Exit — WhatsApp-style behavior</span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p><code>leave(id)</code> exits a group but keeps it in the list (read-only). <code>leave(id, true)</code> exits and removes it atomically. <code>delete(id)</code> hides any conversation from the caller's list — no longer admin-only, works for DMs ("Delete Chat") and already-exited groups ("Delete Group"). When the last admin exits, the server auto-promotes the longest-standing member instead of returning <code>400</code>.</p>
+          <p class="wn-ref">→ <a href="#step-convs">Step 6 — Conversations</a> for code examples</p>
+        </div>
+      </div>
+
+      <div class="wn-item" id="wn-113-4">
+        <div class="wn-item-header" onclick="toggleItem('wn-113-4')">
+          <span class="wn-tag new">New</span>
+          <span class="wn-item-title">Message visibility windows — gap messages hidden after re-add</span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p>Messages sent while a user was not a member (gap periods) are now always hidden. Re-adding after a plain exit preserves prior history; re-adding after "Exit and Delete" shows only messages from the re-add point. DM "Delete Chat" also resets the window — when the other party messages again, only new messages are visible. No client changes required.</p>
+        </div>
+      </div>
+
+      <div class="wn-item" id="wn-113-5">
+        <div class="wn-item-header" onclick="toggleItem('wn-113-5')">
+          <span class="wn-tag new">New</span>
+          <span class="wn-item-title">useConversations() — leaveGroup, leaveAndDeleteGroup, deleteConversation</span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p>Three new mutations added to <code>useConversations()</code> in both web and RN SDKs: <code>leaveGroup</code>, <code>leaveAndDeleteGroup</code>, and <code>deleteConversation</code> (RN) / <code>deleteGroup</code> (web). Cache is updated optimistically — no manual invalidation needed.</p>
+        </div>
+      </div>
+
+    </div>
+  </div><!-- /.wn-version -->
+
+  <!-- ── v1.1.2 ── -->
+  <div class="wn-version" 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-date">May 2026</span>
+      </div>
+      <span class="wn-chevron">▾</span>
+    </div>
+    <div class="wn-body">
+
+      <div class="wn-item" id="wn-112-0a">
+        <div class="wn-item-header" onclick="toggleItem('wn-112-0a')">
+          <span class="wn-tag new">New</span>
+          <span class="wn-item-title">usersApi.updateProfile() — immediate profile update</span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p>A new <code>usersApi.updateProfile(payload)</code> method lets the host app push profile field changes to the chat server immediately — without waiting for the next background sync cycle.</p>
+          <p>This is especially useful in <strong>non-builtin (external/SSO) modes</strong>: when the user updates their name or email in the main identity provider, the host app can call <code>updateProfile()</code> so the chat UI reflects the change right away rather than waiting up to 2 hours for the next cron sync.</p>
+          <pre><code><span class="kw">import</span> { usersApi } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+
+<span class="kw">await</span> usersApi.<span class="fn">updateProfile</span>({
+  firstName:   <span class="str">'Jane'</span>,
+  lastName:    <span class="str">'Smith'</span>,
+  email:       <span class="str">'jane@example.com'</span>,
+  displayName: <span class="str">'Jane S.'</span>,   <span class="cm">// optional</span>
+  phone:       <span class="str">'+919900000000'</span>,
+});</code></pre>
+          <table>
+            <tr><th>Field</th><th>Builtin</th><th>Non-builtin</th></tr>
+            <tr><td><code>firstName</code>, <code>lastName</code>, <code>email</code></td><td>Written directly</td><td>Written immediately; may be overwritten on next sync if user-service returns different values</td></tr>
+            <tr><td><code>displayName</code>, <code>phone</code></td><td>Written directly</td><td>Written immediately</td></tr>
+            <tr><td><code>username</code>, <code>status</code></td><td colspan="2">Not allowed</td></tr>
+          </table>
+          <p><strong>Uniqueness:</strong> <code>email</code> and <code>phone</code> must each be unique within the tenant. A <code>409 Conflict</code> is returned if another user already holds the same value.</p>
+          <p class="wn-ref">→ <a href="#users-api">Users API</a> for the full reference</p>
+        </div>
+      </div>
+
+      <div class="wn-item" id="wn-112-0b">
+        <div class="wn-item-header" onclick="toggleItem('wn-112-0b')">
+          <span class="wn-tag new">New</span>
+          <span class="wn-item-title">On-connect per-user profile sync</span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p>In non-builtin modes, <code>AntzChatClient.connect()</code> now triggers a fire-and-forget background sync of the current user's profile from the upstream user-service if the shadow record hasn't been synced in the last 6 hours.</p>
+          <p>Previously only the 2-hour bulk cron kept shadow records up to date. Now profile fields (<code>firstName</code>, <code>lastName</code>, <code>displayName</code>, <code>email</code>, <code>username</code>, <code>phone</code>, <code>status</code>) are refreshed on every fresh SDK initialisation, providing near-immediate consistency for users who reconnect after a period of inactivity.</p>
+          <p><strong>No client action required.</strong> This is handled automatically inside <code>connect()</code>.</p>
+        </div>
+      </div>
+
+      <div class="wn-item" id="wn-112-0c">
+        <div class="wn-item-header" onclick="toggleItem('wn-112-0c')">
+          <span class="wn-tag new">New</span>
+          <span class="wn-item-title">Phone number uniqueness enforced per tenant</span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p><code>phone</code> is now unique within a tenant — the same phone number cannot be registered to two different users under the same tenant. A <code>409 Conflict</code> is returned on registration or profile update if the number is already in use.</p>
+          <p>Same-phone across different tenants is still allowed (a user can have the same phone in tenant A and tenant B).</p>
+          <p><strong>No client action required</strong> for existing data. New uniqueness is enforced at write time only.</p>
+        </div>
+      </div>
+
+      <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 +725,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>
@@ -780,17 +1075,21 @@ section.sec>h2:hover{color:#fff}
       <div class="wn-item" id="wn-106-7">
         <div class="wn-item-header" onclick="toggleItem('wn-106-7')">
           <span class="wn-tag new">New</span>
-          <span class="wn-item-title">Group icon — create &amp; update</span>
+          <span class="wn-item-title">Group icon — create, update &amp; remove</span>
           <span class="wn-chevron-sm">▾</span>
         </div>
         <div class="wn-item-body">
-          <p>Group conversations now support a custom icon. Admins can set or replace it at any time. The icon is stored server-side and a fresh signed URL is returned on every conversation response.</p>
+          <p>Group conversations now support a custom icon. Admins can set, replace, or remove it at any time. The icon is stored server-side and a fresh signed URL is returned on every conversation response.</p>
           <pre><code><span class="cm">// Upload icon — admin only</span>
 <span class="kw">const</span> updated = <span class="kw">await</span> client.<span class="fn">uploadIcon</span>(groupId, {
   <span class="at">uri</span>: file.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="at">size</span>: file.size,
 });
-<span class="cm">// updated.iconUrl → fresh signed URL</span></code></pre>
-          <p>Non-admins receive <code>403 Forbidden</code>. The URL is never stored in the DB — regenerated from <code>iconMeta.storageKey</code> on every response. Replacing an icon automatically deletes the previous one.</p>
+<span class="cm">// updated.iconUrl → fresh signed URL</span>
+
+<span class="cm">// Remove icon — admin only</span>
+<span class="kw">const</span> noIcon = <span class="kw">await</span> conversationsApi.<span class="fn">removeIcon</span>(groupId);
+<span class="cm">// noIcon.iconUrl === undefined</span></code></pre>
+          <p>Non-admins receive <code>403 Forbidden</code> on both operations. The URL is never stored in the DB — regenerated from <code>iconMeta.storageKey</code> on every response. Replacing or removing an icon automatically deletes the previous asset from storage.</p>
           <p class="wn-ref">→ <a href="#step-convs">Step 6 — Conversations</a> (group icon section) for the full upload pipeline</p>
         </div>
       </div>
@@ -1217,7 +1516,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>
@@ -1535,6 +1834,17 @@ chatClient.<span class="fn">disconnect</span>();
 <span class="cm">// Search users by name / username / email</span>
 <span class="kw">const</span> { data: results } = <span class="kw">await</span> usersApi.<span class="fn">list</span>({ <span class="at">query</span>: <span class="str">'john'</span> });
 
+<span class="cm">// Update current user's profile — works in both builtin and non-builtin modes.</span>
+<span class="cm">// In non-builtin modes use this to push a change immediately without waiting</span>
+<span class="cm">// for the next 2-hour background sync from the upstream user-service.</span>
+<span class="kw">await</span> usersApi.<span class="fn">updateProfile</span>({
+  firstName:   <span class="str">'Jane'</span>,
+  lastName:    <span class="str">'Smith'</span>,
+  email:       <span class="str">'jane@example.com'</span>,  <span class="cm">// 409 if taken by another user in this tenant</span>
+  displayName: <span class="str">'Jane S.'</span>,
+  phone:       <span class="str">'+919900000000'</span>,      <span class="cm">// 409 if taken by another user in this tenant</span>
+});
+
 <span class="cm">// Create DM — returns existing if already exists</span>
 <span class="kw">const</span> dm = <span class="kw">await</span> conversationsApi.<span class="fn">createDirect</span>({ <span class="at">userId</span>: <span class="str">'target-user-id'</span> });
 
@@ -1573,8 +1883,15 @@ chatClient.<span class="fn">disconnect</span>();
 <span class="cm">// - iconMeta = { storageKey, provider, bucket, mimeType, size } embedded in conversation doc</span>
 <span class="cm">// - Non-admins get 403 Forbidden at server level</span>
 
+<span class="cm">// Remove the group icon (admin only)</span>
+<span class="cm">// Deletes asset from storage + clears iconMeta. Returns conversation with iconUrl: undefined.</span>
+<span class="kw">const</span> noIcon = <span class="kw">await</span> conversationsApi.<span class="fn">removeIcon</span>(group.id);
+<span class="cm">// → DELETE /conversations/:id/icon</span>
+<span class="cm">//   Server: validateAdmin() → deleteByKey(iconMeta.storageKey) → $unset iconMeta</span>
+<span class="cm">//   noIcon.iconUrl === undefined</span>
+
 <span class="cm">// Web/RN SDK components (GroupInfoPanel, NewChatModal, ChatHeader) handle this automatically.</span>
-<span class="cm">// Camera button shown only to admins. No code needed in your app.</span>
+<span class="cm">// Camera button + remove (✕) button shown only to admins. No code needed in your app.</span>
 
 <span class="cm">// Participants</span>
 <span class="kw">const</span> members = <span class="kw">await</span> conversationsApi.<span class="fn">getMembers</span>(conversationId);
@@ -1583,11 +1900,34 @@ chatClient.<span class="fn">disconnect</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>);
 
-<span class="cm">// Pin · Mute · Leave · Delete</span>
+<span class="cm">// Pin · Mute</span>
 <span class="kw">await</span> conversationsApi.<span class="fn">pin</span>(conversationId);   <span class="cm">// 400 if already at 5 pinned</span>
 <span class="kw">await</span> conversationsApi.<span class="fn">mute</span>(conversationId, <span class="str">'2025-12-31T23:59:59Z'</span>); <span class="cm">// omit date = indefinite</span>
-<span class="kw">await</span> conversationsApi.<span class="fn">leave</span>(conversationId);
-<span class="kw">await</span> conversationsApi.<span class="fn">delete</span>(conversationId); <span class="cm">// admin only</span></code></pre>
+
+<span class="cm">// ── 1:1 Chat ──────────────────────────────────────────────────────────────────</span>
+<span class="cm">// "Delete Chat" — hides from caller's list only. Other participant unaffected.</span>
+<span class="cm">// If the other person messages again the chat reappears, showing only new messages.</span>
+<span class="kw">await</span> conversationsApi.<span class="fn">delete</span>(dmConversationId);
+
+<span class="cm">// ── Group Chat ─────────────────────────────────────────────────────────────────</span>
+<span class="cm">// "Exit Group" — leave but keep in list (read-only). Auto-promotes if last admin.</span>
+<span class="kw">await</span> conversationsApi.<span class="fn">leave</span>(groupId);
+
+<span class="cm">// "Exit and Delete" — leave + remove from list atomically.</span>
+<span class="kw">await</span> conversationsApi.<span class="fn">leave</span>(groupId, <span class="kw">true</span>);
+
+<span class="cm">// "Delete Group" — hide an already-exited group from the list. Any participant.</span>
+<span class="kw">await</span> conversationsApi.<span class="fn">delete</span>(groupId);</code></pre>
+
+  <div class="callout info">
+    <strong>Leave / Delete semantics</strong>
+    <ul style="margin:8px 0 0;padding-left:20px;line-height:1.7">
+      <li><strong>Exit Group</strong> — <code>leave(id)</code>. Caller becomes inactive, stays in list read-only. If the caller is the only admin, the server auto-promotes the longest-standing active member before completing the exit.</li>
+      <li><strong>Exit and Delete</strong> — <code>leave(id, true)</code>. Atomic: exit + hide from list in one server write. No race window.</li>
+      <li><strong>Delete Group</strong> (after exit) — <code>delete(id)</code>. Caller must already be inactive. Hides from their list only. Any participant, no admin role required.</li>
+      <li><strong>Delete Chat</strong> (1:1) — <code>delete(id)</code>. Hides from caller's list. DMs have no admin concept. When the other participant messages again, the chat reappears for the caller with only new messages visible.</li>
+    </ul>
+  </div>
 
   <div class="callout info">
     <strong>Pin limit — max 5</strong> — The server enforces a maximum of 5 pinned conversations per user. Attempting to pin a 6th returns <code>400 Bad Request</code>. Gate your UI before calling the API:

package/package.json

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