@antzsoft/chat-core 1.1.2 → 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.2 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,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.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.2</span>
+        <span class="wn-ver">v1.1.3</span>
         <span class="wn-badge current">Current</span>
         <span class="wn-date">May 2026</span>
       </div>
@@ -254,6 +254,139 @@ section.sec>h2:hover{color:#fff}
     </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 +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>
@@ -1697,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> });
 
@@ -1735,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);
@@ -1745,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.2",
+  "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",