@antzsoft/chat-core 1.1.2 → 1.1.4

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.2 Release Notes</a></li>
+    <li><a href="#whats-new">v1.1.4 Release Notes</a></li>
   </ul>
 
   <div class="section-label">Getting Started</div>
@@ -242,11 +242,11 @@ 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.2 (current) ── -->
-  <div class="wn-version open" id="wn-112">
-    <div class="wn-header" onclick="toggleVersion('wn-112')">
+  <!-- ── v1.1.4 (current) ── -->
+  <div class="wn-version open" id="wn-114">
+    <div class="wn-header" onclick="toggleVersion('wn-114')">
       <div class="wn-title">
-        <span class="wn-ver">v1.1.2</span>
+        <span class="wn-ver">v1.1.4</span>
         <span class="wn-badge current">Current</span>
         <span class="wn-date">May 2026</span>
       </div>
@@ -254,6 +254,179 @@ section.sec>h2:hover{color:#fff}
     </div>
     <div class="wn-body">
 
+      <div class="wn-item" id="wn-114-1">
+        <div class="wn-item-header" onclick="toggleItem('wn-114-1')">
+          <span class="wn-tag fix">Fix</span>
+          <span class="wn-item-title">Socket ack timeout eliminated for rapid or large messages</span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p>Sending many messages in quick succession — especially long text messages or in group chats with online recipients — could trigger a <code>Socket ack timeout: send_message</code> error on the client, even though the messages were delivered successfully. The root cause was that the server was performing delivery tracking, room broadcasts, and push notifications synchronously before returning the socket acknowledgement, which could exceed the 5-second ack window.</p>
+          <p>The server now returns the ack immediately after the message is written to the database. All subsequent work (delivery status tracking, <code>new_message</code> broadcast to recipients, push notifications) runs in the background. <strong>No behaviour change is visible to users</strong> — delivery ticks, message broadcasts, and push notifications all still fire; they just no longer block the ack.</p>
+          <p>No SDK or integration changes required. This fix is a server-side change paired with a client-side queue improvement (see below).</p>
+        </div>
+      </div>
+
+      <div class="wn-item" id="wn-114-2">
+        <div class="wn-item-header" onclick="toggleItem('wn-114-2')">
+          <span class="wn-tag fix">Fix</span>
+          <span class="wn-item-title">Per-conversation send queue — parallel sends across conversations</span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p>The SDK's internal <code>send_message</code> queue was previously shared across all conversations. This meant that sending messages in Conversation A would block outgoing messages in Conversation B until each ack completed, even though the two conversations are fully independent.</p>
+          <p>The queue is now keyed per <code>conversationId</code>. Messages within the same conversation are still serialised (guaranteeing order), but messages across different conversations are sent in parallel. The <code>QUEUE_MAX_SIZE</code> limit of 100 pending messages also now applies per conversation rather than globally.</p>
+          <p>No integration changes required. This is an internal SDK improvement in <code>@antzsoft/chat-core</code>.</p>
+        </div>
+      </div>
+
+    </div>
+  </div><!-- /.wn-version -->
+
+  <!-- ── v1.1.3 ── -->
+  <div class="wn-version" 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-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>
@@ -942,17 +1115,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>
@@ -1697,6 +1874,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> });
 
@@ -1735,8 +1923,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);
@@ -1745,11 +1940,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.2",
+  "version": "1.1.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",