@antzsoft/chat-core 1.2.5 → 1.2.7

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.2.4 Release Notes</a></li>
+    <li><a href="#whats-new">v1.2.7 Release Notes</a></li>
   </ul>
 
   <div class="section-label">Getting Started</div>
@@ -182,6 +182,8 @@ section.sec>h2:hover{color:#fff}
   <div class="section-label">Conversations</div>
   <ul>
     <li><a href="#step-convs">6. Conversations</a></li>
+    <li><a href="#step-inactive-user">6b. Inactive Users</a></li>
+    <li><a href="#step-clear-chat">6c. Clear / Delete Chat</a></li>
     <li><a href="#step-rooms">7. Join &amp; Leave Room</a></li>
   </ul>
 
@@ -207,6 +209,11 @@ section.sec>h2:hover{color:#fff}
     <li><a href="#step-example">18. Full Example</a></li>
     <li><a href="#step-unread">19. Unread Counts</a></li>
   </ul>
+
+  <div class="section-label">Error Handling</div>
+  <ul>
+    <li><a href="#step-errors">20. Error Handling</a></li>
+  </ul>
 </nav>
 
 <!-- ══ MAIN ═════════════════════════════════════════════════════════════ -->
@@ -243,189 +250,308 @@ 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.2.4 (current) ── -->
-  <div class="wn-version open" id="wn-124">
-    <div class="wn-header" onclick="toggleVersion('wn-124')">
+  <!-- ── v1.2.7 (current) ── -->
+  <div class="wn-version open" id="wn-127">
+    <div class="wn-header" onclick="toggleVersion('wn-127')">
       <div class="wn-title">
-        <span class="wn-ver">v1.2.4</span>
+        <span class="wn-ver">v1.2.7</span>
         <span class="wn-badge current">Current</span>
-        <span class="wn-date">May 2026</span>
+        <span class="wn-date">June 2026</span>
       </div>
       <span class="wn-chevron">▲</span>
     </div>
     <div class="wn-body">
 
-      <div class="wn-item" id="wn-124-mp1">
-        <div class="wn-item-header" onclick="toggleItem('wn-124-mp1')">
+      <div class="wn-item" id="wn-127-starsynce">
+        <div class="wn-item-header" onclick="toggleItem('wn-127-starsynce')">
           <span class="wn-tag new">New</span>
-          <span class="wn-item-title">Chunked multipart upload for files ≥ 10 MB (S3 and local)</span>
+          <span class="wn-item-title">Real-time star sync across devices — <code>message_star_updated</code> socket event</span>
           <span class="wn-chevron-sm">▾</span>
         </div>
         <div class="wn-item-body">
-          <p>Files at or above <strong>10 MB</strong> on S3 and local storage now use chunked multipart upload instead of a single presigned POST. The SDK splits the file into 10 MB chunks, uploads up to 3 parts in parallel, then completes the upload server-side.</p>
-          <p><strong>What changes per provider:</strong></p>
+          <p>When the current user stars or unstars a message on one device, the server now emits <code>message_star_updated</code> to their personal socket room. All other connected devices of the same user receive the event and update their message cache automatically — no refetch, no polling.</p>
           <table>
-            <thead><tr><th>Provider</th><th>File &lt; 10 MB</th><th>File ≥ 10 MB</th></tr></thead>
+            <thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead>
             <tbody>
-              <tr><td>AWS S3</td><td>Presigned POST (unchanged)</td><td><strong>New:</strong> chunked multipart — N presigned PUT URLs (one per part) → <code>CompleteMultipartUpload</code></td></tr>
-              <tr><td>Local (same-server / mount)</td><td>Presigned POST (unchanged)</td><td><strong>New:</strong> chunked multipart — N signed PUT URLs (one per part) → <code>POST /storage/multipart/complete/:fileId</code> assembles parts on disk</td></tr>
-              <tr><td>Azure Blob Storage</td><td>Presigned PUT (unchanged)</td><td>Presigned PUT (unchanged)</td></tr>
+              <tr><td><code>messageId</code></td><td><code>string</code></td><td>ID of the starred/unstarred message</td></tr>
+              <tr><td><code>conversationId</code></td><td><code>string</code></td><td>Conversation the message belongs to</td></tr>
+              <tr><td><code>isStarred</code></td><td><code>boolean</code></td><td><code>true</code> = starred, <code>false</code> = unstarred</td></tr>
             </tbody>
           </table>
-          <p><strong>Benefits at 50 MB+:</strong> resumes from last completed part on network failure, parallel throughput, no single-request timeout, supports files up to 5 TB.</p>
-          <p><strong>No integration changes required</strong> for Web SDK (<code>@antzsoft/chat-web-sdk</code>) and RN SDK (<code>@antzsoft/chat-rn-sdk</code>) users — <code>webUploadPartFn</code> and <code>rnUploadPartFn</code> are wired in automatically. Node.js / custom integrators must pass <code>platformUploadPartFn</code> to <code>uploadBatch</code> to enable chunked uploads.</p>
-          <p class="wn-ref">→ <a href="#step-upload">Step 16 — Upload Files</a></p>
+          <p>The event is emitted <strong>only to the acting user's own sockets</strong> — other participants never see it. Stars are personal bookmarks, not shared state.</p>
+          <pre><code><span class="kw">import</span> { tryGetSocket } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+<span class="kw">import type</span> { MessageStarUpdatedEvent } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+
+<span class="cm">// Register at app root — fires when you star/unstar on any other device</span>
+<span class="kw">const</span> socket = tryGetSocket();
+socket?.<span class="fn">on</span>(<span class="str">'message_star_updated'</span>, (evt: MessageStarUpdatedEvent) =&gt; {
+  <span class="cm">// Update the open chat view for the affected conversation</span>
+  updateMessageStarState(evt.messageId, evt.isStarred);
+
+  <span class="cm">// Optionally invalidate the starred messages list if it's open</span>
+  <span class="kw">if</span> (!evt.isStarred) removeFromStarredList(evt.messageId);
+});</code></pre>
+          <p><strong>Web and RN SDK users:</strong> both <code>SocketProvider</code> implementations handle this event internally and patch the React Query cache automatically. No code changes needed in the host app.</p>
+          <p><strong>No integration changes required</strong> for SDK users. Core SDK direct users should add the listener above at app root level.</p>
         </div>
       </div>
 
-      <div class="wn-item" id="wn-124-mp2">
-        <div class="wn-item-header" onclick="toggleItem('wn-124-mp2')">
+      <div class="wn-item" id="wn-127-softustar">
+        <div class="wn-item-header" onclick="toggleItem('wn-127-softustar')">
           <span class="wn-tag new">New</span>
-          <span class="wn-item-title"><code>storageApi.completeMultipartUpload()</code> · <code>PlatformUploadPartFn</code> type · <code>CompletedPart</code> / <code>MultipartUploadInfo</code> types</span>
+          <span class="wn-item-title">Soft-delete unstar + sync indexes — foundation for offline delta sync</span>
           <span class="wn-chevron-sm">▾</span>
         </div>
         <div class="wn-item-body">
-          <p><code>storageApi.completeMultipartUpload(fileId, uploadId, parts)</code> is called automatically by <code>uploadBatch</code> — only needed in custom manual upload flows. It assembles S3 parts and transitions the file record to active in one round-trip (replaces the separate <code>confirmUpload</code> call for the multipart path).</p>
-          <p><code>PlatformUploadPartFn</code> is the new platform adapter type: <code>(uploadUrl: string, blob: Blob | ArrayBuffer, onProgress?) =&gt; Promise&lt;string&gt;</code> — returns the ETag S3 sends back for the part. Exported from <code>@antzsoft/chat-core</code>.</p>
-          <p>New exported types: <code>MultipartUploadInfo</code>, <code>MultipartPartUrl</code>, <code>CompletedPart</code>.</p>
+          <p>Three server-side changes lay the groundwork for efficient offline delta sync in the mobile app:</p>
+          <ul>
+            <li><strong>Unstar is now a soft delete</strong> — <code>chat_message_stars</code> records are no longer hard-deleted when a user unstars. The record is updated to <code>isActive: false</code> with an <code>unstarredAt</code> timestamp. A sync query using <code>updatedAt &gt; since</code> can now detect both star and unstar events from a single collection scan. <code>getStarredMessages</code> filters <code>isActive: true</code> so visible behaviour is unchanged.</li>
+            <li><strong><code>updatedAt</code> on participant documents</strong> — <code>chat_conversation_participants</code> now carries <code>updatedAt</code> (Mongoose timestamps). Mute, pin, role change, and removal all bump this field, making the full participant state syncable via timestamp-based delta queries.</li>
+            <li><strong>New sync indexes</strong> — Three compound indexes added at startup (idempotent, no manual step needed):
+              <ul>
+                <li><code>{ conversationId, updatedAt }</code> on <code>chat_messages</code> — fetch all messages in a conversation mutated after a timestamp</li>
+                <li><code>{ userId, tenantId, updatedAt }</code> on <code>chat_conversation_participants</code> — fetch all participant records for a user mutated after a timestamp</li>
+                <li><code>{ userId, tenantId, updatedAt }</code> on <code>chat_message_stars</code> — fetch all star/unstar records for a user mutated after a timestamp</li>
+              </ul>
+            </li>
+          </ul>
+          <p><strong>Migrations 003 &amp; 004</strong> run automatically on first deploy:</p>
+          <ul>
+            <li><code>003_backfill_participant_updatedAt</code> — sets <code>updatedAt = joinedAt</code> on all existing participant documents that predate the schema change</li>
+            <li><code>004_backfill_star_isActive</code> — sets <code>isActive: true</code> on all existing star records (all surviving records represent active stars — hard-deleted unstar records no longer exist in the DB)</li>
+          </ul>
+          <p><strong>No integration changes required.</strong> All changes are server-side. The <code>getStarredMessages</code> API contract is unchanged.</p>
         </div>
       </div>
 
-
-      <div class="wn-item" id="wn-124-1">
-        <div class="wn-item-header" onclick="toggleItem('wn-124-1')">
-          <span class="wn-tag improvement">Improvement</span>
-          <span class="wn-item-title">S3 and local storage uploads now use presigned POST multipart — file bytes never touch the chat server</span>
+      <div class="wn-item" id="wn-127-crossconv-sync">
+        <div class="wn-item-header" onclick="toggleItem('wn-127-crossconv-sync')">
+          <span class="wn-tag new">New</span>
+          <span class="wn-item-title">Offline delta sync — <code>GET /sync</code> cross-conversation reconnect sync</span>
           <span class="wn-chevron-sm">▾</span>
         </div>
         <div class="wn-item-body">
-          <p>File uploads to S3 and the local storage provider now use <strong>presigned POST</strong> (AWS POST policy / HMAC-signed form fields) instead of presigned PUT. The client sends a <code>multipart/form-data</code> request directly to the storage endpoint — S3 or the chat server's own <code>/storage/files/upload</code> endpoint — with the signed fields embedded in the form body. No file bytes pass through the chat server.</p>
-          <p><strong>What changed per provider:</strong></p>
+          <p>Mobile apps can now catch up on all missed changes in a single HTTP request after a socket reconnect. <code>GET /sync?since=&lt;ISO timestamp&gt;</code> returns every cross-conversation delta since the cursor — edits, deletes, pins, participant changes, read receipts, and messages deleted-for-me — across all conversations the user belongs to.</p>
           <table>
-            <thead><tr><th>Provider</th><th>Upload method</th><th>Change</th></tr></thead>
+            <thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead>
             <tbody>
-              <tr><td>AWS S3</td><td>Presigned POST (multipart/form-data)</td><td>Changed from presigned PUT → POST. AWS signs a policy; client POSTs a FormData with all fields + file.</td></tr>
-              <tr><td>Local (same-server / mount)</td><td>Presigned POST (multipart/form-data)</td><td>HMAC-signed fields now go in the form body (not query string) — WAF-friendly.</td></tr>
-              <tr><td>Azure Blob Storage</td><td>Presigned PUT (SAS token)</td><td>Unchanged — Azure has no form-based upload API.</td></tr>
+              <tr><td><code>syncedAt</code></td><td><code>string</code></td><td>Server-stamped ISO timestamp — store as the new <code>since</code> cursor. Always use server clock to avoid client clock skew.</td></tr>
+              <tr><td><code>stale</code></td><td><code>boolean</code></td><td><code>true</code> when gap exceeds the stale threshold (default 30 days, configurable via <code>CHAT_SYNC_STALE_DAYS</code> env var). No data returned — mark all conversations <code>needs_refresh</code> and lazy-sync on open.</td></tr>
+              <tr><td><code>messages</code></td><td><code>Message[]</code></td><td>Messages with <code>updatedAt &gt; since</code> — covers edits, deletes, pins, unpins. Excludes messages deleted-for-me (those are in <code>deletedForMe</code>).</td></tr>
+              <tr><td><code>deletedForMe</code></td><td><code>SyncDeletedForMe[]</code></td><td>Messages this user hid for themselves — remove from local DB.</td></tr>
+              <tr><td><code>participantChanges</code></td><td><code>SyncParticipantChange[]</code></td><td>Role changes, mute/unmute, removals (<code>isActive: false</code>) across all conversations.</td></tr>
+              <tr><td><code>readReceipts</code></td><td><code>SyncReadReceipt[]</code></td><td>Read receipts received since <code>since</code>.</td></tr>
             </tbody>
           </table>
-          <p><strong>How the SDK handles both paths:</strong> The <code>PresignedUrlResponse</code> carries <code>method: 'POST'</code> and a <code>fields</code> object for S3/local. Your <code>platformUploadFn</code> should branch on this:</p>
-          <pre><code><span class="cm">// S3 / local → multipart FormData (method: 'POST', fields present)</span>
-<span class="cm">// Azure      → raw PUT body      (method: 'PUT',  no fields)</span>
-<span class="kw">if</span> (presigned.method === <span class="str">'POST'</span> &amp;&amp; presigned.fields) {
-  <span class="kw">const</span> fd = <span class="kw">new</span> <span class="fn">FormData</span>();
-  Object.<span class="fn">entries</span>(presigned.fields).<span class="fn">forEach</span>(([k, v]) => fd.<span class="fn">append</span>(k, v));
-  fd.<span class="fn">append</span>(<span class="str">'file'</span>, blob, file.name); <span class="cm">// file must be last</span>
-  xhr.<span class="fn">send</span>(fd);
-} <span class="kw">else</span> {
-  xhr.<span class="fn">send</span>(blob); <span class="cm">// Azure PUT</span>
-}</code></pre>
-          <p><strong>No integration changes required.</strong> Both the web SDK and RN SDK already implement this branching. If you are using the recommended <code>platformUploadFn</code> from Step 1 of this guide, it already handles both paths correctly. Only custom <code>platformUploadFn</code> implementations that unconditionally used <code>presigned.method</code> as PUT need updating — see the updated examples in <a href="#step1">Step 1</a>.</p>
-          <p class="wn-ref">→ <a href="#step1">Step 1 — platformUploadFn examples</a> · <a href="#step-upload">Step 16 — Upload Files</a></p>
+          <p><strong>Stale handling</strong> — when <code>stale: true</code> the server still returns the new <code>syncedAt</code> cursor. Save it and mark every conversation <code>needs_refresh = true</code> in local SQLite; open <code>GET /conversations/:id/sync</code> lazily when the user navigates to each conversation.</p>
+          <pre><code><span class="kw">import</span> { syncApi } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+
+<span class="cm">// Using @antzsoft/chat-rn-sdk built-in hook (recommended for RN)</span>
+<span class="kw">import</span> { useSync } <span class="kw">from</span> <span class="str">'@antzsoft/chat-rn-sdk'</span>;
+
+useSync({
+  onSync: <span class="kw">async</span> (data) =&gt; {
+    <span class="cm">// data: CrossConversationSyncResponse</span>
+    <span class="kw">await</span> mergeSyncDeltaIntoSQLite(data);
+  },
+  onStale: <span class="kw">async</span> () =&gt; {
+    <span class="cm">// Gap > stale threshold (default 30 days) — lazy-sync per conversation on open</span>
+    <span class="kw">await</span> db.execute(<span class="str">'UPDATE conversations SET needs_refresh = 1'</span>);
+  },
+});
+
+<span class="cm">// Or call syncApi directly (custom integration)</span>
+<span class="kw">const</span> result = <span class="kw">await</span> syncApi.<span class="fn">pull</span>(lastSyncedAt);
+<span class="kw">await</span> AsyncStorage.<span class="fn">setItem</span>(<span class="str">'@antz_last_synced_at'</span>, result.syncedAt);
+<span class="kw">if</span> (result.stale) markAllNeedsRefresh();
+<span class="kw">else</span> mergeSyncDeltaIntoSQLite(result);</code></pre>
+          <p><strong>Does not include reactions or stars</strong> — these are per-conversation and returned by <code>GET /conversations/:id/sync</code>.</p>
+          <p><strong>Web SDK users:</strong> the web SDK uses React Query cache invalidation on reconnect — no sync call needed. <code>syncApi</code> is intended for mobile (React Native) only.</p>
         </div>
       </div>
 
-      <div class="wn-item" id="wn-124-2">
-        <div class="wn-item-header" onclick="toggleItem('wn-124-2')">
-          <span class="wn-tag fix">Fix</span>
-          <span class="wn-item-title"><code>POST /storage/files/upload</code> returns <code>403</code> when transit encryption is enabled</span>
+      <div class="wn-item" id="wn-127-conv-sync">
+        <div class="wn-item-header" onclick="toggleItem('wn-127-conv-sync')">
+          <span class="wn-tag new">New</span>
+          <span class="wn-item-title">Offline delta sync — <code>GET /conversations/:id/sync</code> per-conversation full delta</span>
           <span class="wn-chevron-sm">▾</span>
         </div>
         <div class="wn-item-body">
-          <p>The local-storage direct upload endpoint (<code>POST /storage/files/upload</code>) was missing the <code>@PreTransit()</code> decorator. With <code>transitEncryption: true</code>, the <code>TransitEnforceGuard</code> rejected every upload request with <code>403 Transit encryption required</code>.</p>
-          <p><strong>Why this endpoint is pre-transit:</strong> The client uploads directly via XHR/fetch — not through the Axios client — so no <code>x-transit-session</code> header is ever present on this request. Auth is the HMAC signature embedded in the <code>multipart/form-data</code> fields (<code>token</code>, <code>ts</code>) which the server validates independently.</p>
-          <p><strong>No integration changes required.</strong> This fix unblocks uploads on deployments with <code>transitEncryption: true</code>. No client-side changes needed.</p>
+          <p>Returns the complete delta for a single conversation, including reactions and stars. Call this when a conversation is marked <code>needs_refresh</code> (gap exceeded the stale threshold) or when a fresh-install user opens a conversation for the first time (omit <code>since</code> to receive the full history).</p>
+          <table>
+            <thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead>
+            <tbody>
+              <tr><td><code>syncedAt</code></td><td><code>string</code></td><td>Server-stamped cursor — update <code>lastSyncedAt</code> after upsert.</td></tr>
+              <tr><td><code>messages</code></td><td><code>Message[]</code></td><td>All messages with <code>updatedAt &gt; since</code>. On fresh install (<code>since</code> omitted), returns all messages.</td></tr>
+              <tr><td><code>deletedForMe</code></td><td><code>SyncDeletedForMe[]</code></td><td>Messages deleted for this user — remove from local DB.</td></tr>
+              <tr><td><code>reactions</code></td><td><code>SyncReactions</code></td><td>Full current emoji counts for every message that had reaction activity since <code>since</code>. <strong>Always upsert as ground truth</strong> — reactions are hard-deleted so delta is not safe.</td></tr>
+              <tr><td><code>stars</code></td><td><code>SyncStarEntry[]</code></td><td><code>isActive: true</code> = starred, <code>isActive: false</code> = unstarred (soft-delete). Delete local star record when <code>false</code>.</td></tr>
+              <tr><td><code>participantChanges</code></td><td><code>SyncParticipantChange[]</code></td><td>Role changes, mutes, removals for this conversation.</td></tr>
+              <tr><td><code>readReceipts</code></td><td><code>SyncReadReceipt[]</code></td><td>Read receipts received since <code>since</code>.</td></tr>
+            </tbody>
+          </table>
+          <p><strong>Reactions are always returned as full current state</strong> for the affected messages — not as a delta. Because reaction removes are hard-deleted (no timestamp trace), a delta is impossible. Upsert the reaction counts returned and discard any locally cached state for those message IDs.</p>
+          <pre><code><span class="kw">import</span> { useConversationSync } <span class="kw">from</span> <span class="str">'@antzsoft/chat-rn-sdk'</span>;
+
+<span class="cm">// In your conversation screen</span>
+<span class="kw">const</span> { isSyncing, sync } = <span class="fn">useConversationSync</span>(conversationId);
+
+<span class="cm">// Trigger when conversation is marked stale</span>
+<span class="fn">useEffect</span>(() =&gt; {
+  <span class="kw">if</span> (needsRefresh) {
+    <span class="fn">sync</span>().then((data) =&gt; {
+      <span class="kw">if</span> (data) upsertConversationDeltaToSQLite(data);
+      clearNeedsRefresh(conversationId);
+    });
+  }
+}, [conversationId, needsRefresh]);
+
+<span class="cm">// Fresh install — omit since to get full history</span>
+<span class="kw">const</span> { sync: fullSync } = <span class="fn">useConversationSync</span>(conversationId, { skipSince: <span class="kw">true</span> });
+
+<span class="cm">// Or call syncApi directly</span>
+<span class="kw">const</span> result = <span class="kw">await</span> syncApi.<span class="fn">pullConversation</span>(conversationId, lastSyncedAt);
+<span class="kw">await</span> upsertConversationDeltaToSQLite(result);</code></pre>
+          <p><strong>Authorization</strong> — server verifies the caller is an active participant. Non-participants receive <code>403 Forbidden</code>.</p>
+          <p><strong>No integration changes required</strong> for web or existing RN users. RN apps that want offline sync should add <code>useSync</code> at the root provider level and <code>useConversationSync</code> in each conversation screen. See the <a href="#syncApi">Sync API reference</a> in the README for type signatures and full usage examples.</p>
         </div>
       </div>
 
     </div>
-  </div>
+  </div><!-- /.wn-version -->
 
-  <!-- ── v1.2.3 ── -->
-  <div class="wn-version" id="wn-123">
-    <div class="wn-header" onclick="toggleVersion('wn-123')">
+  <!-- ── v1.2.6 ── -->
+  <div class="wn-version" id="wn-126">
+    <div class="wn-header" onclick="toggleVersion('wn-126')">
       <div class="wn-title">
-        <span class="wn-ver">v1.2.3</span>
-        <span class="wn-date">May 2026</span>
+        <span class="wn-ver">v1.2.6</span>
+        <span class="wn-date">June 2026</span>
       </div>
       <span class="wn-chevron">▼</span>
     </div>
     <div class="wn-body">
 
-      <div class="wn-item" id="wn-123-1">
-        <div class="wn-item-header" onclick="toggleItem('wn-123-1')">
+      <div class="wn-item" id="wn-126-clearchat">
+        <div class="wn-item-header" onclick="toggleItem('wn-126-clearchat')">
           <span class="wn-tag new">New</span>
-          <span class="wn-item-title"><code>messagesApi.getReceipts(messageId)</code> — per-user read &amp; delivery receipt detail</span>
+          <span class="wn-item-title">Clear / Delete Chat — hide any conversation from your list without affecting other participants</span>
           <span class="wn-chevron-sm">▾</span>
         </div>
         <div class="wn-item-body">
-          <p>New endpoint <code>GET /messages/:id/receipts</code> returns the full read and delivery receipt list for a single message, with user profiles (name, avatar) resolved server-side. Designed as the initial load for a "Read by / Delivered to" message info screen.</p>
-          <p>Response shape:</p>
-          <pre><code>{
-  messageId: string,
-  readBy:     [{ userId, displayName, avatarUrl, readAt }],
-  deliveredTo: [{ userId, displayName, avatarUrl, deliveredAt }]
-}</code></pre>
-          <p>No secondary user lookup needed — profiles are included. The "Sent to" bucket (not yet delivered) is derived client-side by subtracting <code>readBy</code> and <code>deliveredTo</code> user IDs from the conversation participant list.</p>
-          <p class="wn-ref">→ <a href="#step-message-info">Step 12b — Message Info Screen</a> for the complete pattern including live updates.</p>
+          <p><code>conversationsApi.delete(conversationId)</code> is now available to <strong>any participant</strong> on both DMs and groups — no admin role required. It hides the conversation from the caller's list only; all other participants are completely unaffected.</p>
+          <table>
+            <thead><tr><th>Scenario</th><th>What to call</th><th>Effect</th></tr></thead>
+            <tbody>
+              <tr><td><strong>Delete Chat</strong> (DM)</td><td><code>conversationsApi.delete(id)</code></td><td>Conversation hidden from caller's list. Membership periods wiped — if the other person messages again, the chat reappears showing only messages from the reappearance point onwards.</td></tr>
+              <tr><td><strong>Exit Group</strong></td><td><code>conversationsApi.leave(id)</code></td><td>Caller becomes inactive participant, stays in list as read-only. Server auto-promotes another admin if caller was the only admin.</td></tr>
+              <tr><td><strong>Exit and Delete Group</strong></td><td><code>conversationsApi.leave(id, true)</code></td><td>Atomic: exit the group + hide from list in one write. Membership periods wiped. No race window between the two operations.</td></tr>
+              <tr><td><strong>Delete Group</strong> (after exit)</td><td><code>conversationsApi.delete(id)</code></td><td>Hides the already-exited group from caller's list. Other participants unaffected.</td></tr>
+            </tbody>
+          </table>
+          <p><strong>Message history after re-add / reappear:</strong> Membership periods are wiped on "Delete Chat" and "Exit and Delete". When the caller is re-added to a group or the other party messages in a DM, only messages from that point onwards are visible — no prior history leaks through.</p>
+          <p><strong>Socket event:</strong> <code>conversation_deleted</code> is emitted <strong>only to the acting user's own sockets</strong> in three cases: (1) <code>delete()</code> — self-delete/hide a DM or group, (2) <code>leave(id, true)</code> — exit and delete a group atomically, (3) <code>delete()</code> called on an already-exited group. In all cases, remove the conversation from local state and navigate away if it was open. Other participants never receive this event.</p>
+          <pre><code><span class="kw">import</span> { conversationsApi } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+
+<span class="cm">// ── DM: "Delete Chat" ─────────────────────────────────────────────────</span>
+<span class="kw">await</span> conversationsApi.<span class="fn">delete</span>(dmConversationId);
+<span class="cm">// → Caller's list: conversation hidden</span>
+<span class="cm">// → Other participant: unaffected</span>
+<span class="cm">// → Re-open trigger: other party sends a message → reappears with new history only</span>
+
+<span class="cm">// ── Group: "Exit Group" (stay in list read-only) ──────────────────────</span>
+<span class="kw">await</span> conversationsApi.<span class="fn">leave</span>(groupId);
+
+<span class="cm">// ── Group: "Exit and Delete" (leave + hide atomically) ───────────────</span>
+<span class="kw">await</span> conversationsApi.<span class="fn">leave</span>(groupId, <span class="kw">true</span>);
+
+<span class="cm">// ── Group: "Delete Group" (already exited, now hiding the entry) ──────</span>
+<span class="kw">await</span> conversationsApi.<span class="fn">delete</span>(groupId);</code></pre>
+          <p><strong>Web / RN SDK hooks:</strong> <code>useConversations()</code> exposes these as named mutations — <code>leaveGroup</code>, <code>leaveAndDeleteGroup</code>, and <code>deleteConversation</code> (RN) / <code>deleteGroup</code> (web). The cache is updated optimistically; no manual invalidation needed.</p>
+          <p class="wn-ref">→ <a href="#step-clear-chat">Step 6c — Clear / Delete Chat</a> for the full pattern with socket handling and Web/RN SDK examples.</p>
         </div>
       </div>
 
-      <div class="wn-item" id="wn-123-2">
-        <div class="wn-item-header" onclick="toggleItem('wn-123-2')">
-          <span class="wn-tag fix">Fix</span>
-          <span class="wn-item-title"><code>message_delivered</code> now fires per recipient, not all-or-nothing</span>
+      <div class="wn-item" id="wn-126-inactive">
+        <div class="wn-item-header" onclick="toggleItem('wn-126-inactive')">
+          <span class="wn-tag new">New</span>
+          <span class="wn-item-title">Inactive &amp; reactivate user — server-enforced deactivation and fresh-start reactivation</span>
           <span class="wn-chevron-sm">▾</span>
         </div>
         <div class="wn-item-body">
-          <p>Previously <code>message_delivered</code> only fired to the sender when <em>all</em> recipients were online at the moment of sending — if even one recipient was offline, the sender received no delivery event at all until every recipient came online simultaneously (which often never happens in large groups).</p>
-          <p>The server now fires <code>message_delivered</code> once per online recipient at send time. The payload's <code>deliveredTo</code> field is now a single object <code>{ userId, deliveredAt }</code> (previously an array) — one event per person, matching how <code>read_receipt</code> works.</p>
-          <p>This means the delivery section of a message info screen builds up live one entry at a time, exactly as WhatsApp does.</p>
-          <p><strong>Backward compatible</strong> — existing <code>message_delivered</code> handlers in both the web and RN SDKs only read <code>event.messageId</code> to update the tick mark and are unaffected by the <code>deliveredTo</code> shape change. The event fires more frequently (good — more accurate delivery feedback) but the existing handler logic is identical.</p>
-          <p class="wn-ref">→ <a href="#step-message-info">Step 12b — Message Info Screen</a> · <a href="#step-realtime">Step 10 — Real-time Events</a></p>
+          <p>When a user account is set to <code>inactive</code> (self-service in builtin mode, or via external user-service sync in non-builtin modes), the server applies full <strong>"self-left + delete"</strong> semantics atomically:</p>
+          <table>
+            <thead><tr><th>Action</th><th>Effect</th></tr></thead>
+            <tbody>
+              <tr><td>Refresh tokens</td><td>All revoked — no new access tokens can be issued</td></tr>
+              <tr><td>Device tokens</td><td>All disabled — push notifications stop immediately</td></tr>
+              <tr><td>Redis caches</td><td><code>chatuser:</code>, <code>shadow:builtin:</code>, <code>shadow:&lt;tenant&gt;:</code> busted atomically — no 5-min window</td></tr>
+              <tr><td>Group conversations</td><td><code>participant_left</code> fires to remaining members, admin auto-promoted, periods wiped</td></tr>
+              <tr><td>DM conversations</td><td>Hidden silently — periods wiped, no event emitted</td></tr>
+              <tr><td>Live socket</td><td>Force-disconnected — <code>user_offline</code> broadcast fires automatically</td></tr>
+              <tr><td>Socket auth cache-hit</td><td>Non-builtin shadow cache hit now re-checks DB status — no 5-min bypass window</td></tr>
+              <tr><td>addParticipants / createGroup</td><td>Inactive user IDs silently filtered before insert</td></tr>
+              <tr><td>Blocked users list</td><td>Deactivated users excluded automatically</td></tr>
+            </tbody>
+          </table>
+          <p><strong>On reactivation:</strong> device tokens re-enabled, user cache busted, conversation list intentionally empty — fresh start. DMs reopen when the other party messages, showing only messages from that point.</p>
+          <p><strong>SDK resilience:</strong> RN <code>SocketProvider</code> retries token refresh up to 5× on <code>connect_error</code> auth failures. Web <code>SocketProvider</code> calls <code>logout()</code> after 5 failed retries instead of silently freezing.</p>
+          <p><strong>No integration changes required</strong> — server-side only. Clients receive standard <code>participant_left</code> / <code>user_offline</code> events.</p>
+          <p class="wn-ref">→ <a href="#step-inactive-user">Step 6b — Inactive Users</a> for client-side handling: UI states, 401 enforcement, socket reconnect, and reactivation behaviour.</p>
         </div>
       </div>
 
-      <div class="wn-item" id="wn-123-3">
-        <div class="wn-item-header" onclick="toggleItem('wn-123-3')">
+      <div class="wn-item" id="wn-126-frozengroup">
+        <div class="wn-item-header" onclick="toggleItem('wn-126-frozengroup')">
           <span class="wn-tag new">New</span>
-          <span class="wn-item-title">Viewer-aware system message text — SDK resolves "You", "you", or full names automatically</span>
+          <span class="wn-item-title">Removed/left users see frozen group state — name, icon, description, and member list as of exit time</span>
           <span class="wn-chevron-sm">▾</span>
         </div>
         <div class="wn-item-body">
-          <p>System messages (member added/removed, admin promoted/demoted, group created/updated) now render differently depending on who is reading them — matching WhatsApp behaviour.</p>
+          <p>Group conversations now serve a historically accurate snapshot to removed or self-exited users instead of live data. Every field a removed user sees is frozen at the moment they left:</p>
           <table>
-            <thead><tr><th>Viewer</th><th>Rendered text</th></tr></thead>
+            <thead><tr><th>Field</th><th>Active member</th><th>Removed / left member</th></tr></thead>
             <tbody>
-              <tr><td>Actor (Anil removed Ajay)</td><td>"You removed Ajay Antony"</td></tr>
-              <tr><td>Target (Ajay was removed)</td><td>"Anil Rathod removed you"</td></tr>
-              <tr><td>Bystander (Saket)</td><td>"Anil Rathod removed Ajay Antony"</td></tr>
+              <tr><td><code>name</code></td><td>Live group name</td><td>Frozen at exit time</td></tr>
+              <tr><td><code>description</code></td><td>Live description</td><td>Frozen at exit time</td></tr>
+              <tr><td><code>iconUrl</code></td><td>Live icon</td><td>Frozen at exit time</td></tr>
+              <tr><td><code>participantCount</code></td><td>Current active count</td><td>Count at exit time</td></tr>
+              <tr><td><code>participants</code> array</td><td>Current active members</td><td>Members present at exit time</td></tr>
+              <tr><td><code>lastMessage</code></td><td>Live last message</td><td>Frozen at exit time (unchanged)</td></tr>
             </tbody>
           </table>
-          <p><strong>How it works:</strong> The server stores the neutral third-person form in <code>content.text</code> (used for push notifications and exports) and sends structured <code>actorUserId</code>, <code>actorUserName</code>, <code>targetUserId</code>, <code>targetUserName</code> fields in the message <code>metadata</code>. The SDK's <code>messagesApi.list()</code> applies <code>resolveSystemMessageText()</code> in-memory before returning messages — <code>content.text</code> is already correct by the time it reaches your UI. No frontend logic changes needed.</p>
-          <p><strong>Socket path:</strong> For raw <code>new_message</code> socket events handled outside the SDK pipeline (e.g. <code>AntzChatClient</code> headless usage), call <code>resolveSystemMessageText(message, currentUserId)</code> manually:</p>
-          <pre><code>import { resolveSystemMessageText, getAuthStore } from '@antzsoft/chat-core';
-
-client.socket.on('new_message', (event) => {
-  const message = event.message;
-  if (message.content.type === 'system') {
-    const uid = getAuthStore().useAuthStore.getState().user?.id ?? '';
-    message.content.text = resolveSystemMessageText(message, uid);
-  }
-  appendMessageToView(message);
-});</code></pre>
-          <p><strong>Backward compatible:</strong></p>
-          <ul>
-            <li>Old SDK + new server: <code>actorUserId</code> fields ignored, raw <code>content.text</code> displayed — degrades gracefully.</li>
-            <li>New SDK + old server: <code>actorUserId</code> absent, guard fires, raw <code>content.text</code> returned unchanged.</li>
-          </ul>
-          <p>Applies to: <code>group_created</code>, <code>user_added</code>, <code>user_removed</code>, <code>user_left</code>, <code>admin_promoted</code>, <code>admin_demoted</code>, <code>group_updated</code>.</p>
-          <p><strong>Also fixed in this release:</strong></p>
+          <p><strong>No integration changes required.</strong> The response shape is identical — field names and types are unchanged. Values are simply frozen for inactive participants. Existing code that filters participants by <code>p.isActive !== false</code> continues to work correctly since all members in a removed user's snapshot have <code>isActive: true</code> (they were active at that time).</p>
+          <p><strong>One recommendation:</strong> use <code>conversation.participantCount</code> (the server-provided field) for member count display rather than <code>conversation.participants.length</code> — the two are kept in sync by the server and <code>participantCount</code> is always the accurate value for both active and removed users.</p>
+          <p><strong>On re-add:</strong> all frozen snapshots are cleared automatically. The re-added user immediately sees live group data — current name, icon, description, and active member list.</p>
+        </div>
+      </div>
+
+      <div class="wn-item" id="wn-126-errors">
+        <div class="wn-item-header" onclick="toggleItem('wn-126-errors')">
+          <span class="wn-tag new">New</span>
+          <span class="wn-item-title">Structured error layer — typed error classes with codes, retryable flag, and context</span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p>All SDK errors — REST failures, socket timeouts, queue overflows, and transit mismatches — are now instances of typed error classes instead of raw <code>AxiosError</code> objects or plain <code>Error</code> strings. Every error carries:</p>
           <ul>
-            <li><code>group_updated</code> system message text now includes the actor name ("Anil changed the group name to 'X'" instead of the previous "Group name changed to 'X'").</li>
-            <li>Push notification body for <code>admin_demoted</code> corrected from "made you member" to "removed you as admin".</li>
-            <li>Removed users who are offline at the time of removal now receive a push notification ("Anil Rathod removed you from the group") since the socket event cannot reach them.</li>
+            <li><code>code</code> — machine-readable string (e.g. <code>SESSION_EXPIRED</code>, <code>SEND_QUEUE_FULL</code>)</li>
+            <li><code>retryable</code> — <code>true</code> when the operation is safe to retry (network errors, 5xx, rate limiting)</li>
+            <li><code>context</code> — diagnostic object (HTTP status, server path, axios code, <code>decryptionFailed</code> flag, etc.)</li>
           </ul>
+          <table>
+            <thead><tr><th>Class</th><th>Codes</th><th>Source</th></tr></thead>
+            <tbody>
+              <tr><td><code>AntzChatAuthError</code></td><td><code>SESSION_EXPIRED</code>, <code>AUTH_FAILED</code></td><td>HTTP 401</td></tr>
+              <tr><td><code>AntzChatValidationError</code></td><td><code>VALIDATION_ERROR</code></td><td>HTTP 400 / 422. <code>.fields</code> array for multi-field errors</td></tr>
+              <tr><td><code>AntzChatPermissionError</code></td><td><code>PERMISSION_DENIED</code></td><td>HTTP 403</td></tr>
+              <tr><td><code>AntzChatNetworkError</code></td><td><code>NETWORK_ERROR</code>, <code>RATE_LIMITED</code>, <code>SOCKET_TIMEOUT</code>, <code>SOCKET_NOT_CONNECTED</code>, <code>SEND_QUEUE_FULL</code>, <code>MESSAGE_DROPPED</code></td><td>Network, socket, queue</td></tr>
+              <tr><td><code>AntzChatServerError</code></td><td><code>SERVER_ERROR</code>, <code>NOT_FOUND</code></td><td>HTTP 5xx, 404</td></tr>
+              <tr><td><code>AntzChatError</code> (base)</td><td><code>TRANSIT_MISMATCH</code></td><td>SDK/server encryption config mismatch</td></tr>
+            </tbody>
+          </table>
+          <p>Transit-encrypted error bodies are decrypted before normalisation. If decryption itself fails, <code>context.decryptionFailed = true</code> is set and the class is still determined correctly from the HTTP status code.</p>
+          <p><strong>Backward compatible — no integration changes required.</strong> All classes extend native <code>Error</code> so existing <code>catch (err)</code> blocks work unchanged.</p>
+          <p class="wn-ref">→ <a href="#step-errors">Step 20 — Error Handling</a> for full usage patterns, code reference, and platform-specific examples.</p>
         </div>
       </div>
 
@@ -436,7 +562,7 @@ client.socket.on('new_message', (event) => {
   <button class="wn-history-btn" onclick="openVersionHistory()">
     <span class="wn-history-icon">⏱</span>
     View version history
-    <span class="wn-history-count">15 older versions</span>
+    <span class="wn-history-count">20 older versions</span>
   </button>
 
 </section>
@@ -453,6 +579,137 @@ client.socket.on('new_message', (event) => {
     </div>
     <div class="vh-body">
 
+  <!-- ── v1.2.5 ── -->
+  <div class="wn-version" id="wn-125">
+    <div class="wn-header" onclick="toggleVersion('wn-125')">
+      <div class="wn-title">
+        <span class="wn-ver">v1.2.5</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-125-transit">
+        <div class="wn-item-header" onclick="toggleItem('wn-125-transit')">
+          <span class="wn-tag new">New</span>
+          <span class="wn-item-title">Transit session decoupled from socket — <code>createRestTransitSession()</code> and <code>rnCreateRestTransitSession()</code></span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p>Previously the transit encryption session was established exclusively via the socket ECDH handshake. The session key was unavailable until the socket connected, blocking encrypted HTTP requests that needed to fire before the socket — for example, notification reply handlers when the app is killed.</p>
+          <p>A new <code>POST /crypto/session</code> REST endpoint establishes a full ECDH session over HTTP. <code>createRestTransitSession(apiUrl)</code> performs the exchange and returns <code>{ sessionId, sessionKey }</code> so any REST call can be encrypted without a socket connection. The axios client uses this path automatically when a transit session is needed before the socket is ready.</p>
+          <p><code>rnCreateRestTransitSession(apiUrl)</code> is exported from <code>@antzsoft/chat-rn-sdk</code> — a Hermes-compatible wrapper using <code>@noble/curves</code> (X25519) and <code>@noble/ciphers</code> (AES-256-GCM). Use it in background notification reply handlers when the main app is not running:</p>
+          <pre><code><span class="kw">import</span> { createRestTransitSession } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+<span class="kw">import</span> { rnCreateRestTransitSession } <span class="kw">from</span> <span class="str">'@antzsoft/chat-rn-sdk'</span>; <span class="cm">// RN / Hermes</span>
+
+<span class="cm">// In a background notification reply handler (app killed, no socket):</span>
+<span class="kw">const</span> session = <span class="kw">await</span> <span class="fn">rnCreateRestTransitSession</span>(<span class="str">'https://api.yourapp.com/api/v1'</span>);
+<span class="cm">// Use session.sessionId + session.sessionKey to encrypt REST calls manually.</span>
+<span class="cm">// Normal SDK usage: fully automatic — no code changes needed.</span></code></pre>
+          <p><strong>No integration changes required</strong> for standard SDK usage.</p>
+        </div>
+      </div>
+
+    </div>
+  </div><!-- /.wn-version -->
+
+  <!-- ── v1.2.4 ── -->
+  <div class="wn-version" id="wn-124">
+    <div class="wn-header" onclick="toggleVersion('wn-124')">
+      <div class="wn-title">
+        <span class="wn-ver">v1.2.4</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-124h-mp1">
+        <div class="wn-item-header" onclick="toggleItem('wn-124h-mp1')">
+          <span class="wn-tag new">New</span>
+          <span class="wn-item-title">Chunked multipart upload for files ≥ 10 MB (S3 and local)</span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p>Files ≥ 10 MB on S3 and local storage now use S3 multipart upload (10 MB parts, up to 3 parallel, <code>CompleteMultipartUpload</code>). Benefits: resumable, parallel throughput, no single-request timeout, up to 5 TB. Files below 10 MB and Azure are unchanged.</p>
+          <p><strong>No integration changes required</strong> for Web and RN SDK users — <code>webUploadPartFn</code> / <code>rnUploadPartFn</code> wired automatically. Node.js integrators must supply <code>platformUploadPartFn</code> to <code>uploadBatch</code>.</p>
+        </div>
+      </div>
+
+      <div class="wn-item" id="wn-124h-1">
+        <div class="wn-item-header" onclick="toggleItem('wn-124h-1')">
+          <span class="wn-tag improvement">Improvement</span>
+          <span class="wn-item-title">S3 and local uploads now use presigned POST — file bytes never touch the chat server</span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p>S3 and local uploads changed from presigned PUT to presigned POST (AWS policy / HMAC-signed fields). Bytes upload directly client-to-storage. Azure unchanged. <code>platformUploadFn</code> already branches on <code>method === 'POST' &amp;&amp; presigned.fields</code> — no changes needed.</p>
+        </div>
+      </div>
+
+      <div class="wn-item" id="wn-124h-2">
+        <div class="wn-item-header" onclick="toggleItem('wn-124h-2')">
+          <span class="wn-tag fix">Fix</span>
+          <span class="wn-item-title"><code>POST /storage/files/upload</code> returns 403 when transit encryption is enabled</span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p>The local-storage direct upload endpoint was missing <code>@PreTransit()</code>. XHR/fetch uploads never carry <code>x-transit-session</code> — the decorator marks the endpoint reachable without a transit session. Fixed. <strong>No integration changes required.</strong></p>
+        </div>
+      </div>
+
+    </div>
+  </div><!-- /.wn-version -->
+
+  <!-- ── v1.2.3 ── -->
+  <div class="wn-version" id="wn-123">
+    <div class="wn-header" onclick="toggleVersion('wn-123')">
+      <div class="wn-title">
+        <span class="wn-ver">v1.2.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-123h-1">
+        <div class="wn-item-header" onclick="toggleItem('wn-123h-1')">
+          <span class="wn-tag new">New</span>
+          <span class="wn-item-title"><code>messagesApi.getReceipts(messageId)</code> — per-user read &amp; delivery receipt detail</span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p>New <code>GET /messages/:id/receipts</code> returns the full read/delivery receipt list with resolved user profiles. Use as the initial load for a "Read by / Delivered to" message info screen — no secondary user lookup needed.</p>
+          <p class="wn-ref">→ <a href="#step-message-info">Step 12b — Message Info Screen</a></p>
+        </div>
+      </div>
+
+      <div class="wn-item" id="wn-123h-2">
+        <div class="wn-item-header" onclick="toggleItem('wn-123h-2')">
+          <span class="wn-tag fix">Fix</span>
+          <span class="wn-item-title"><code>message_delivered</code> now fires per recipient, not all-or-nothing</span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p>Server now fires once per online recipient. <code>deliveredTo</code> is a single <code>{ userId, deliveredAt }</code> object (was an array). Backward compatible — existing handlers only read <code>event.messageId</code>.</p>
+        </div>
+      </div>
+
+      <div class="wn-item" id="wn-123h-3">
+        <div class="wn-item-header" onclick="toggleItem('wn-123h-3')">
+          <span class="wn-tag new">New</span>
+          <span class="wn-item-title">Viewer-aware system message text — SDK resolves "You" / full names automatically</span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p>System messages render differently per viewer (actor / target / bystander) — matching WhatsApp behaviour. <code>content.text</code> resolved by <code>messagesApi.list()</code> before reaching your UI. Raw socket events: call <code>resolveSystemMessageText(message, currentUserId)</code> manually.</p>
+        </div>
+      </div>
+
+    </div>
+  </div><!-- /.wn-version -->
+
   <!-- ── v1.2.0 ── -->
   <div class="wn-version" id="wn-120">
     <div class="wn-header" onclick="toggleVersion('wn-120')">
@@ -2564,6 +2821,176 @@ chatClient.<span class="fn">disconnect</span>();
   </div>
 </section>
 
+<!-- ─── STEP 6b: INACTIVE USERS ────────────────────────────────────────── -->
+<section id="step-inactive-user">
+  <h2><span class="step">STEP 6b</span> Inactive Users — Handling Deactivated Accounts</h2>
+
+  <div class="callout info"><strong>New in v1.2.6</strong> — When a user's account is deactivated server-side, the server applies full "self-left + delete" semantics automatically. This section explains what your client receives and how to handle each case.</div>
+
+  <h3>What the server does on deactivation (automatic)</h3>
+  <p>No client action triggers this — it is driven entirely server-side when <code>user.status</code> changes to <code>inactive</code>:</p>
+  <table>
+    <thead><tr><th>Step</th><th>What happens</th><th>Client impact</th></tr></thead>
+    <tbody>
+      <tr><td>1</td><td>All refresh tokens revoked</td><td>Next <code>/auth/refresh</code> call → <code>401 Unauthorized</code></td></tr>
+      <tr><td>2</td><td>All device tokens disabled</td><td>Push notifications stop immediately — no action needed in app</td></tr>
+      <tr><td>3</td><td>All Redis auth caches busted</td><td>Next HTTP request or socket connect → <code>401 Unauthorized</code> immediately (no 5-min cache window)</td></tr>
+      <tr><td>4</td><td>All group conversations: <code>leave(hideAfterLeave=true)</code></td><td><code>participant_left</code> event fires to remaining members — update your member list</td></tr>
+      <tr><td>5</td><td>All DM conversations: hidden + periods wiped silently</td><td>No event — the conversation disappears from the list on next fetch</td></tr>
+      <tr><td>6</td><td>Live socket force-disconnected</td><td><code>disconnect</code> event fires on the deactivated user's socket; <code>user_offline</code> broadcast fires to all parties</td></tr>
+    </tbody>
+  </table>
+
+  <h3>What your app receives when a user in a conversation is deactivated</h3>
+  <p>When someone <em>else</em> in a conversation is deactivated, your app receives standard events — no special handling needed:</p>
+  <pre><code><span class="cm">// Standard events you already handle — no changes needed</span>
+socket.<span class="fn">on</span>(<span class="str">'participant_left'</span>, (event) => {
+  <span class="cm">// event.userId = deactivated user's ID</span>
+  <span class="cm">// Remove them from the group member list, update participant count</span>
+  <span class="fn">removeParticipant</span>(event.conversationId, event.userId);
+});
+
+socket.<span class="fn">on</span>(<span class="str">'user_offline'</span>, (event) => {
+  <span class="cm">// Standard presence update — deactivated users are offline</span>
+  useChatStore.<span class="fn">getState</span>().<span class="fn">setUserOffline</span>(event.userId);
+});</code></pre>
+
+  <h3>What your app receives when the CURRENT USER is deactivated</h3>
+  <p>The deactivated user's socket is force-disconnected. On RN, the <code>connect_error</code> handler (new in v1.2.6) retries up to 5 times; each attempt gets a <code>401 Unauthorized</code>. After all retries fail, the socket stays disconnected. On Web, after 5 retries the SDK calls <code>logout()</code> automatically and shows the login screen.</p>
+
+  <pre><code><span class="cm">// RN — the connect_error handler is built into SocketProvider (v1.2.6+)</span>
+<span class="cm">// No changes needed. After 5 retries, socket stays disconnected.</span>
+<span class="cm">// The conversation list goes empty on the next authenticated fetch (returns 401).</span>
+
+<span class="cm">// Web — SocketProvider calls logout() after 5 retries (v1.2.6+)</span>
+<span class="cm">// builtInAuth: true → login screen shown automatically</span>
+<span class="cm">// builtInAuth: false → handle via your own auth flow:</span>
+
+<span class="kw">import</span> { getAuthStore } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+
+<span class="kw">const</span> { useAuthStore } = <span class="fn">getAuthStore</span>();
+useAuthStore.<span class="fn">subscribe</span>((state) => {
+  <span class="kw">if</span> (!state.isAuthenticated) {
+    <span class="cm">// User was logged out — navigate to your own login screen</span>
+    router.<span class="fn">push</span>(<span class="str">'/login'</span>);
+  }
+});</code></pre>
+
+  <h3>Handling 401 on HTTP calls after deactivation</h3>
+  <p>The axios interceptor in <code>@antzsoft/chat-core</code> already handles this — on <code>401</code> it attempts a token refresh. If the refresh also returns <code>401</code> (because refresh tokens are all revoked), <code>clearTokens()</code> is called and the error is re-thrown. Handle it at the call site:</p>
+  <pre><code><span class="kw">try</span> {
+  <span class="kw">const</span> { data } = <span class="kw">await</span> conversationsApi.<span class="fn">list</span>();
+} <span class="kw">catch</span> (err: <span class="kw">any</span>) {
+  <span class="kw">if</span> (err?.response?.status === <span class="num">401</span>) {
+    <span class="cm">// Session permanently invalid — navigate to login</span>
+    router.<span class="fn">push</span>(<span class="str">'/login'</span>);
+  }
+}</code></pre>
+
+  <h3>Conversation list after deactivation</h3>
+  <p>All participant records are set to <code>isHidden: true</code> with membership periods wiped. <code>conversationsApi.list()</code> returns an empty array — your UI renders an empty state automatically with no special handling.</p>
+
+  <h3>On reactivation — fresh start</h3>
+  <p>The reactivated user starts with an empty conversation list. They must log in again (refresh tokens were revoked). Once logged in:</p>
+  <ul>
+    <li>Device tokens are re-enabled automatically — push notifications resume</li>
+    <li>Conversation list is empty — groups must be re-added by an admin; DMs reopen automatically when the other person sends a new message (only messages from the reopen point are visible)</li>
+    <li>User search and listing immediately shows the reactivated user (cache busted on reactivation)</li>
+  </ul>
+
+  <div class="callout tip"><strong>No client code changes required</strong> — all behaviour described here is handled by existing SDK event handlers and the HTTP interceptor. This step documents what to expect so you can test and verify each state in your app.</div>
+</section>
+
+<!-- ─── STEP 6c: CLEAR / DELETE CHAT ─────────────────────────────────────── -->
+<section id="step-clear-chat">
+  <h2><span class="step">STEP 6c</span> Clear / Delete Chat</h2>
+
+  <div class="callout info"><strong>New in v1.2.6</strong> — <code>conversationsApi.delete()</code> is now available to <strong>any participant</strong> on both DMs and group conversations, with no admin role required. It hides the conversation from the caller's list only — all other participants are completely unaffected.</div>
+
+  <h3>Conversation lifecycle actions</h3>
+
+  <table>
+    <thead><tr><th>Action</th><th>API call</th><th>Caller result</th><th>Others</th></tr></thead>
+    <tbody>
+      <tr><td><strong>Delete Chat</strong> (DM)</td><td><code>conversationsApi.delete(id)</code></td><td>Conversation hidden, periods wiped</td><td>Unaffected</td></tr>
+      <tr><td><strong>Exit Group</strong></td><td><code>conversationsApi.leave(id)</code></td><td>Inactive, stays read-only</td><td>Auto-promote if last admin</td></tr>
+      <tr><td><strong>Exit and Delete</strong></td><td><code>conversationsApi.leave(id, true)</code></td><td>Left + hidden atomically, periods wiped</td><td>Auto-promote if last admin</td></tr>
+      <tr><td><strong>Delete Group</strong> (post-exit)</td><td><code>conversationsApi.delete(id)</code></td><td>Already-exited group hidden</td><td>Unaffected</td></tr>
+    </tbody>
+  </table>
+
+  <h3>Clear Chat (DM)</h3>
+
+  <p>Calling <code>delete()</code> on a DM hides it from the caller's list and wipes their membership periods. The other participant's view is unchanged.</p>
+
+  <p><strong>Re-open behaviour:</strong> when the other participant sends a new message after the DM was deleted, the conversation reappears in the caller's list with only messages from the re-open point visible — no prior history leaks through (membership periods were wiped at delete time).</p>
+
+  <pre><code><span class="kw">import</span> { conversationsApi } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+
+<span class="cm">// Delete a DM from the caller's list</span>
+<span class="kw">await</span> conversationsApi.<span class="fn">delete</span>(dmConversationId);
+
+<span class="cm">// Listen for the server confirmation on the caller's own sockets</span>
+socket.<span class="fn">on</span>(<span class="str">'conversation_deleted'</span>, ({ conversationId }) => {
+  removeFromList(conversationId);   <span class="cm">// remove from local state</span>
+  <span class="kw">if</span> (activeConversationId === conversationId) {
+    navigateBackToList();           <span class="cm">// navigate away if currently open</span>
+  }
+});</code></pre>
+
+  <h3>Exit Group / Exit and Delete</h3>
+
+  <p><code>leave(id)</code> exits the group but keeps it in the conversation list as read-only — the caller can still read history but cannot send messages. <code>leave(id, true)</code> exits and hides it atomically in a single server write.</p>
+
+  <p>When the caller is the <strong>only admin</strong>, the server automatically promotes the longest-standing active member to admin before completing the exit — no client action required.</p>
+
+  <pre><code><span class="cm">// Exit Group — stay in list (read-only)</span>
+<span class="kw">await</span> conversationsApi.<span class="fn">leave</span>(groupId);
+
+<span class="cm">// Exit and Delete — leave + hide atomically (one write, no race)</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 entry from the list</span>
+<span class="kw">await</span> conversationsApi.<span class="fn">delete</span>(groupId);</code></pre>
+
+  <h3>Message history after re-add</h3>
+  <table>
+    <thead><tr><th>How the user left</th><th>Re-add behaviour</th></tr></thead>
+    <tbody>
+      <tr><td>Plain <code>leave()</code> — was not hidden</td><td>Prior history visible from the old membership periods. New period appended.</td></tr>
+      <tr><td><code>leave(true)</code> or <code>delete()</code> — periods wiped</td><td>Only messages from the re-add point onwards visible — fresh window.</td></tr>
+    </tbody>
+  </table>
+
+  <h3>Web SDK — <code>useConversations()</code> mutations</h3>
+
+  <pre><code><span class="kw">import</span> { useConversations } <span class="kw">from</span> <span class="str">'@antzsoft/chat-web-sdk'</span>;
+
+<span class="kw">const</span> {
+  leaveGroup,           <span class="cm">// leave(id)         — exit, stay in list</span>
+  leaveAndDeleteGroup,  <span class="cm">// leave(id, true)   — exit + hide atomically</span>
+  deleteGroup,          <span class="cm">// delete(id)        — hide DM or already-exited group</span>
+} = <span class="fn">useConversations</span>();
+
+<span class="cm">// Optimistic cache update — no manual invalidation needed</span>
+<span class="kw">await</span> leaveAndDeleteGroup.<span class="fn">mutateAsync</span>(groupId);</code></pre>
+
+  <h3>RN SDK — <code>useConversations()</code> mutations</h3>
+
+  <pre><code><span class="kw">import</span> { useConversations } <span class="kw">from</span> <span class="str">'@antzsoft/chat-rn-sdk'</span>;
+
+<span class="kw">const</span> {
+  leaveGroup,           <span class="cm">// leave(id)         — exit, stay in list</span>
+  leaveAndDeleteGroup,  <span class="cm">// leave(id, true)   — exit + hide atomically</span>
+  deleteConversation,   <span class="cm">// delete(id)        — hide DM or already-exited group</span>
+} = <span class="fn">useConversations</span>();
+
+<span class="cm">// Long-press action in conversation list:</span>
+<span class="kw">await</span> deleteConversation.<span class="fn">mutateAsync</span>(dmConversationId);</code></pre>
+
+  <div class="callout tip"><strong>Headless / custom UI</strong> — use <code>conversationsApi.leave()</code> and <code>conversationsApi.delete()</code> directly and update your local conversation list state on the <code>conversation_deleted</code> socket event.</div>
+</section>
+
 <!-- ─── STEP 7: ROOMS ──────────────────────────────────────────────────── -->
 <section id="step-rooms">
   <h2><span class="step">STEP 7</span> Rooms — Auto-join, <code>joinRoom</code>, and <code>new_message</code></h2>
@@ -2908,7 +3335,7 @@ socket.<span class="fn">on</span>(<span class="str">'message_deleted'</span>, (e
       </tr>
       <tr>
         <td><code>'conversation_deleted'</code></td>
-        <td>A conversation was deleted</td>
+        <td>Emitted only to the acting user's own sockets on: self-delete (<code>delete()</code>), exit+delete (<code>leave(id, true)</code>), or hide-after-exit (<code>delete()</code> on an already-exited group). Other participants never receive this event.</td>
         <td><strong>App root / conversation list screen</strong> — remove the conversation from state and navigate away if it was open.</td>
       </tr>
       <tr>
@@ -4342,6 +4769,453 @@ console.<span class="fn">log</span>(<span class="str">`${summary.totalUnread} un
   </div>
 </section>
 
+<!-- ─── STEP 20: ERROR HANDLING ─────────────────────────────────────────── -->
+<section id="step-errors">
+  <h2>20. Error Handling</h2>
+  <p>Every error thrown by the SDK — REST calls, socket operations, transit mismatches, and queue overflows — is an instance of a typed <code>AntzChatError</code> subclass. Each carries a <strong>machine-readable <code>code</code></strong>, a <strong><code>retryable</code> boolean</strong>, and a diagnostic <strong><code>context</code> object</strong>.</p>
+
+  <h3>Error classes</h3>
+  <table>
+    <thead><tr><th>Class</th><th>Codes</th><th><code>retryable</code></th><th>Typical cause</th></tr></thead>
+    <tbody>
+      <tr><td><code>AntzChatAuthError</code></td><td><code>SESSION_EXPIRED</code>, <code>AUTH_FAILED</code></td><td>false</td><td>HTTP 401 — expired/missing token; refresh also failed</td></tr>
+      <tr><td><code>AntzChatValidationError</code></td><td><code>VALIDATION_ERROR</code></td><td>false</td><td>HTTP 400/422 — bad input. <code>.fields</code> array for multi-field server errors</td></tr>
+      <tr><td><code>AntzChatPermissionError</code></td><td><code>PERMISSION_DENIED</code></td><td>false</td><td>HTTP 403 — insufficient role</td></tr>
+      <tr><td><code>AntzChatNetworkError</code></td><td><code>NETWORK_ERROR</code>, <code>RATE_LIMITED</code>, <code>SOCKET_TIMEOUT</code>, <code>SOCKET_NOT_CONNECTED</code>, <code>SEND_QUEUE_FULL</code>, <code>MESSAGE_DROPPED</code></td><td>true</td><td>Network failure, socket disconnect, queue overflow</td></tr>
+      <tr><td><code>AntzChatServerError</code></td><td><code>SERVER_ERROR</code>, <code>NOT_FOUND</code></td><td>true</td><td>HTTP 5xx, 404</td></tr>
+      <tr><td><code>AntzChatError</code> (base)</td><td><code>TRANSIT_MISMATCH</code>, <code>UNKNOWN_ERROR</code></td><td>false</td><td>Transit config mismatch, unknown errors</td></tr>
+    </tbody>
+  </table>
+
+  <h3>Error code reference</h3>
+  <table>
+    <thead><tr><th>Code</th><th>Class</th><th>When</th></tr></thead>
+    <tbody>
+      <tr><td><code>SESSION_EXPIRED</code></td><td><code>AntzChatAuthError</code></td><td>401 with no prior refresh attempt</td></tr>
+      <tr><td><code>AUTH_FAILED</code></td><td><code>AntzChatAuthError</code></td><td>401 after token refresh also failed</td></tr>
+      <tr><td><code>PERMISSION_DENIED</code></td><td><code>AntzChatPermissionError</code></td><td>403</td></tr>
+      <tr><td><code>VALIDATION_ERROR</code></td><td><code>AntzChatValidationError</code></td><td>400 / 422</td></tr>
+      <tr><td><code>NOT_FOUND</code></td><td><code>AntzChatServerError</code></td><td>404</td></tr>
+      <tr><td><code>RATE_LIMITED</code></td><td><code>AntzChatNetworkError</code></td><td>429</td></tr>
+      <tr><td><code>NETWORK_ERROR</code></td><td><code>AntzChatNetworkError</code></td><td>No response / connection failure</td></tr>
+      <tr><td><code>SOCKET_TIMEOUT</code></td><td><code>AntzChatNetworkError</code></td><td>Socket ACK not received within 5 s; reconnect not achieved within 15 s</td></tr>
+      <tr><td><code>SOCKET_NOT_CONNECTED</code></td><td><code>AntzChatNetworkError</code></td><td>Ack-required emit called when socket is down</td></tr>
+      <tr><td><code>SEND_QUEUE_FULL</code></td><td><code>AntzChatNetworkError</code></td><td>Per-conversation queue exceeds 100 pending messages</td></tr>
+      <tr><td><code>MESSAGE_DROPPED</code></td><td><code>AntzChatNetworkError</code></td><td>Message waited &gt; 30 s in queue before the socket became ready</td></tr>
+      <tr><td><code>TRANSIT_MISMATCH</code></td><td><code>AntzChatError</code></td><td>SDK has <code>transitEncryption</code> set opposite to the server</td></tr>
+      <tr><td><code>SERVER_ERROR</code></td><td><code>AntzChatServerError</code></td><td>5xx or any other unrecognised HTTP status</td></tr>
+    </tbody>
+  </table>
+
+  <!-- ── Import ── -->
+  <h3>Import</h3>
+
+  <div data-p="rn">
+    <pre><code><span class="kw">import</span> {
+  AntzChatError,
+  AntzChatAuthError,
+  AntzChatValidationError,
+  AntzChatNetworkError,
+  AntzChatPermissionError,
+  AntzChatServerError,
+} <span class="kw">from</span> <span class="str">'@antzsoft/chat-rn-sdk'</span>; <span class="cm">// re-exports everything from @antzsoft/chat-core</span></code></pre>
+  </div>
+
+  <div data-p="web">
+    <pre><code><span class="kw">import</span> {
+  AntzChatError,
+  AntzChatAuthError,
+  AntzChatValidationError,
+  AntzChatNetworkError,
+  AntzChatPermissionError,
+  AntzChatServerError,
+} <span class="kw">from</span> <span class="str">'@antzsoft/chat-web-sdk'</span>; <span class="cm">// re-exports everything from @antzsoft/chat-core</span></code></pre>
+  </div>
+
+  <div data-p="node">
+    <pre><code><span class="kw">import</span> {
+  AntzChatError,
+  AntzChatAuthError,
+  AntzChatValidationError,
+  AntzChatNetworkError,
+  AntzChatPermissionError,
+  AntzChatServerError,
+} <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;</code></pre>
+  </div>
+
+  <!-- ── Pattern 1: instanceof ── -->
+  <h3>Pattern 1 — instanceof branching</h3>
+  <p>Use when each error category needs a different UI response.</p>
+
+  <div data-p="rn">
+    <pre><code><span class="kw">import</span> { Alert } <span class="kw">from</span> <span class="str">'react-native'</span>;
+<span class="kw">import</span> {
+  AntzChatAuthError, AntzChatValidationError,
+  AntzChatPermissionError, AntzChatNetworkError,
+} <span class="kw">from</span> <span class="str">'@antzsoft/chat-rn-sdk'</span>;
+
+<span class="kw">try</span> {
+  <span class="kw">await</span> authApi.<span class="fn">login</span>({ email, password });
+} <span class="kw">catch</span> (err) {
+  <span class="kw">if</span> (err <span class="kw">instanceof</span> AntzChatAuthError)
+    Alert.<span class="fn">alert</span>(<span class="str">'Login failed'</span>, err.message);
+  <span class="kw">else if</span> (err <span class="kw">instanceof</span> AntzChatValidationError)
+    Alert.<span class="fn">alert</span>(<span class="str">'Invalid input'</span>, err.fields?.<span class="fn">join</span>(<span class="str">'\n'</span>) ?? err.message);
+  <span class="kw">else if</span> (err <span class="kw">instanceof</span> AntzChatPermissionError)
+    Alert.<span class="fn">alert</span>(<span class="str">'Not allowed'</span>, err.message);
+  <span class="kw">else if</span> (err <span class="kw">instanceof</span> AntzChatNetworkError && err.retryable)
+    <span class="fn">scheduleRetry</span>();
+  <span class="kw">else throw</span> err;
+}</code></pre>
+  </div>
+
+  <div data-p="web">
+    <pre><code><span class="kw">import</span> {
+  AntzChatAuthError, AntzChatValidationError,
+  AntzChatPermissionError, AntzChatNetworkError,
+} <span class="kw">from</span> <span class="str">'@antzsoft/chat-web-sdk'</span>;
+
+<span class="kw">try</span> {
+  <span class="kw">await</span> authApi.<span class="fn">login</span>({ email, password });
+} <span class="kw">catch</span> (err) {
+  <span class="kw">if</span> (err <span class="kw">instanceof</span> AntzChatAuthError)
+    setLoginError(err.message);
+  <span class="kw">else if</span> (err <span class="kw">instanceof</span> AntzChatValidationError)
+    err.fields?.<span class="fn">forEach</span>(msg => <span class="fn">addFormError</span>(msg));
+  <span class="kw">else if</span> (err <span class="kw">instanceof</span> AntzChatPermissionError)
+    toast.<span class="fn">error</span>(err.message);
+  <span class="kw">else if</span> (err <span class="kw">instanceof</span> AntzChatNetworkError && err.retryable)
+    <span class="fn">showOfflineBanner</span>();
+  <span class="kw">else throw</span> err;
+}</code></pre>
+  </div>
+
+  <div data-p="node">
+    <pre><code><span class="kw">import</span> {
+  AntzChatAuthError, AntzChatValidationError,
+  AntzChatNetworkError, AntzChatServerError,
+} <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+
+<span class="kw">try</span> {
+  <span class="kw">await</span> client.auth.<span class="fn">login</span>({ email, password });
+} <span class="kw">catch</span> (err) {
+  <span class="kw">if</span> (err <span class="kw">instanceof</span> AntzChatAuthError) {
+    console.<span class="fn">error</span>(<span class="str">'Auth failed:'</span>, err.message); process.<span class="fn">exit</span>(<span class="num">1</span>);
+  } <span class="kw">else if</span> (err <span class="kw">instanceof</span> AntzChatValidationError) {
+    console.<span class="fn">error</span>(<span class="str">'Bad input:'</span>, err.fields ?? err.message);
+  } <span class="kw">else if</span> (err <span class="kw">instanceof</span> AntzChatNetworkError && err.retryable) {
+    <span class="fn">scheduleRetry</span>();
+  } <span class="kw">else if</span> (err <span class="kw">instanceof</span> AntzChatServerError) {
+    console.<span class="fn">error</span>(<span class="str">`Server error ${err.httpStatus}:`</span>, err.message);
+  } <span class="kw">else throw</span> err;
+}</code></pre>
+  </div>
+
+  <!-- ── Pattern 2: code switch ── -->
+  <h3>Pattern 2 — code switch (fine-grained)</h3>
+  <p>Use when different codes within the same class need different handling.</p>
+
+  <div data-p="rn">
+    <pre><code><span class="kw">import</span> { AntzChatError } <span class="kw">from</span> <span class="str">'@antzsoft/chat-rn-sdk'</span>;
+
+<span class="kw">try</span> {
+  <span class="kw">await</span> socketEmit.<span class="fn">sendMessage</span>(payload);
+} <span class="kw">catch</span> (err) {
+  <span class="kw">if</span> (!(err <span class="kw">instanceof</span> AntzChatError)) <span class="kw">throw</span> err;
+  <span class="kw">switch</span> (err.code) {
+    <span class="kw">case</span> <span class="str">'SESSION_EXPIRED'</span>:       navigation.<span class="fn">navigate</span>(<span class="str">'Auth'</span>);                     <span class="kw">break</span>;
+    <span class="kw">case</span> <span class="str">'SEND_QUEUE_FULL'</span>:       <span class="fn">showToast</span>(<span class="str">'Too many messages in flight'</span>);         <span class="kw">break</span>;
+    <span class="kw">case</span> <span class="str">'MESSAGE_DROPPED'</span>:       <span class="fn">showToast</span>(<span class="str">'Message timed out — try again'</span>);       <span class="kw">break</span>;
+    <span class="kw">case</span> <span class="str">'SOCKET_TIMEOUT'</span>:
+    <span class="kw">case</span> <span class="str">'SOCKET_NOT_CONNECTED'</span>:  <span class="fn">showOfflineBanner</span>();                             <span class="kw">break</span>;
+    <span class="kw">case</span> <span class="str">'PERMISSION_DENIED'</span>:     <span class="fn">showToast</span>(<span class="str">'You cannot send here'</span>);               <span class="kw">break</span>;
+    <span class="kw">default</span>:                      console.<span class="fn">error</span>(err.code, err.message, err.context);
+  }
+}</code></pre>
+  </div>
+
+  <div data-p="web">
+    <pre><code><span class="kw">import</span> { AntzChatError } <span class="kw">from</span> <span class="str">'@antzsoft/chat-web-sdk'</span>;
+
+<span class="kw">try</span> {
+  <span class="kw">await</span> socketEmit.<span class="fn">sendMessage</span>(payload);
+} <span class="kw">catch</span> (err) {
+  <span class="kw">if</span> (!(err <span class="kw">instanceof</span> AntzChatError)) <span class="kw">throw</span> err;
+  <span class="kw">switch</span> (err.code) {
+    <span class="kw">case</span> <span class="str">'SESSION_EXPIRED'</span>:       router.<span class="fn">push</span>(<span class="str">'/login'</span>);                           <span class="kw">break</span>;
+    <span class="kw">case</span> <span class="str">'SEND_QUEUE_FULL'</span>:       toast.<span class="fn">warning</span>(<span class="str">'Too many messages in flight'</span>);      <span class="kw">break</span>;
+    <span class="kw">case</span> <span class="str">'MESSAGE_DROPPED'</span>:       toast.<span class="fn">warning</span>(<span class="str">'Message timed out — try again'</span>);    <span class="kw">break</span>;
+    <span class="kw">case</span> <span class="str">'SOCKET_TIMEOUT'</span>:
+    <span class="kw">case</span> <span class="str">'SOCKET_NOT_CONNECTED'</span>:  <span class="fn">showOfflineBanner</span>();                             <span class="kw">break</span>;
+    <span class="kw">case</span> <span class="str">'PERMISSION_DENIED'</span>:     toast.<span class="fn">error</span>(<span class="str">'You cannot send here'</span>);              <span class="kw">break</span>;
+    <span class="kw">default</span>:                      console.<span class="fn">error</span>(err.code, err.message, err.context);
+  }
+}</code></pre>
+  </div>
+
+  <div data-p="node">
+    <pre><code><span class="kw">import</span> { AntzChatError } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+
+<span class="kw">try</span> {
+  <span class="kw">await</span> client.socket.emit.<span class="fn">sendMessage</span>(payload);
+} <span class="kw">catch</span> (err) {
+  <span class="kw">if</span> (!(err <span class="kw">instanceof</span> AntzChatError)) <span class="kw">throw</span> err;
+  <span class="kw">switch</span> (err.code) {
+    <span class="kw">case</span> <span class="str">'SESSION_EXPIRED'</span>:       console.<span class="fn">error</span>(<span class="str">'Token expired — re-authenticate'</span>);   <span class="kw">break</span>;
+    <span class="kw">case</span> <span class="str">'SEND_QUEUE_FULL'</span>:       console.<span class="fn">warn</span>(<span class="str">'Queue full — slow down sends'</span>);         <span class="kw">break</span>;
+    <span class="kw">case</span> <span class="str">'MESSAGE_DROPPED'</span>:       console.<span class="fn">warn</span>(<span class="str">'Message dropped — socket was down'</span>);    <span class="kw">break</span>;
+    <span class="kw">case</span> <span class="str">'SOCKET_TIMEOUT'</span>:
+    <span class="kw">case</span> <span class="str">'SOCKET_NOT_CONNECTED'</span>:  console.<span class="fn">warn</span>(<span class="str">'Socket offline'</span>, err.context);          <span class="kw">break</span>;
+    <span class="kw">default</span>:                      console.<span class="fn">error</span>(err.code, err.message, err.context);
+  }
+}</code></pre>
+  </div>
+
+  <!-- ── Pattern 3: retryable ── -->
+  <h3>Pattern 3 — retryable flag with back-off</h3>
+  <p><code>retryable === true</code> on <code>AntzChatNetworkError</code> and <code>AntzChatServerError</code> — safe to retry automatically.</p>
+
+  <div data-p="rn">
+    <pre><code><span class="kw">import</span> { AntzChatError } <span class="kw">from</span> <span class="str">'@antzsoft/chat-rn-sdk'</span>;
+
+<span class="kw">async function</span> <span class="fn">sendWithRetry</span>(payload, maxAttempts = <span class="num">3</span>) {
+  <span class="kw">for</span> (<span class="kw">let</span> attempt = <span class="num">1</span>; attempt &lt;= maxAttempts; attempt++) {
+    <span class="kw">try</span> {
+      <span class="kw">return await</span> socketEmit.<span class="fn">sendMessage</span>(payload);
+    } <span class="kw">catch</span> (err) {
+      <span class="kw">if</span> (err <span class="kw">instanceof</span> AntzChatError && err.retryable && attempt &lt; maxAttempts) {
+        <span class="kw">await new</span> <span class="fn">Promise</span>(r => <span class="fn">setTimeout</span>(r, attempt * <span class="num">1500</span>));
+        <span class="kw">continue</span>;
+      }
+      <span class="kw">throw</span> err;
+    }
+  }
+}</code></pre>
+  </div>
+
+  <div data-p="web">
+    <pre><code><span class="kw">import</span> { AntzChatError } <span class="kw">from</span> <span class="str">'@antzsoft/chat-web-sdk'</span>;
+
+<span class="kw">async function</span> <span class="fn">fetchWithRetry</span>&lt;T&gt;(fn: () =&gt; Promise&lt;T&gt;, maxAttempts = <span class="num">3</span>): Promise&lt;T&gt; {
+  <span class="kw">for</span> (<span class="kw">let</span> i = <span class="num">1</span>; i &lt;= maxAttempts; i++) {
+    <span class="kw">try</span> {
+      <span class="kw">return await</span> <span class="fn">fn</span>();
+    } <span class="kw">catch</span> (err) {
+      <span class="kw">if</span> (err <span class="kw">instanceof</span> AntzChatError && err.retryable && i &lt; maxAttempts) {
+        <span class="kw">await new</span> <span class="fn">Promise</span>(r => <span class="fn">setTimeout</span>(r, i * <span class="num">1000</span>));
+        <span class="kw">continue</span>;
+      }
+      <span class="kw">throw</span> err;
+    }
+  }
+  <span class="kw">throw new</span> <span class="fn">Error</span>(<span class="str">'unreachable'</span>);
+}
+
+<span class="cm">// Usage</span>
+<span class="kw">const</span> messages = <span class="kw">await</span> <span class="fn">fetchWithRetry</span>(() => messagesApi.<span class="fn">list</span>(conversationId));</code></pre>
+  </div>
+
+  <div data-p="node">
+    <pre><code><span class="kw">import</span> { AntzChatError } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+
+<span class="kw">async function</span> <span class="fn">withRetry</span>&lt;T&gt;(fn: () =&gt; Promise&lt;T&gt;, maxAttempts = <span class="num">3</span>): Promise&lt;T&gt; {
+  <span class="kw">for</span> (<span class="kw">let</span> i = <span class="num">1</span>; i &lt;= maxAttempts; i++) {
+    <span class="kw">try</span> {
+      <span class="kw">return await</span> <span class="fn">fn</span>();
+    } <span class="kw">catch</span> (err) {
+      <span class="kw">if</span> (err <span class="kw">instanceof</span> AntzChatError && err.retryable && i &lt; maxAttempts) {
+        <span class="kw">await new</span> <span class="fn">Promise</span>(r => <span class="fn">setTimeout</span>(r, i * <span class="num">1000</span>));
+        <span class="kw">continue</span>;
+      }
+      <span class="kw">throw</span> err;
+    }
+  }
+  <span class="kw">throw new</span> <span class="fn">Error</span>(<span class="str">'unreachable'</span>);
+}
+
+<span class="cm">// Usage — bot polling messages with automatic retry</span>
+<span class="kw">const</span> history = <span class="kw">await</span> <span class="fn">withRetry</span>(() => client.messages.<span class="fn">list</span>(conversationId));</code></pre>
+  </div>
+
+  <!-- ── Pattern 4: validation fields ── -->
+  <h3>Pattern 4 — <code>AntzChatValidationError</code> field errors</h3>
+  <p>When the server returns a <code>string[]</code> message (class-validator errors), <code>.fields</code> is populated:</p>
+
+  <div data-p="rn">
+    <pre><code><span class="kw">import</span> { AntzChatValidationError } <span class="kw">from</span> <span class="str">'@antzsoft/chat-rn-sdk'</span>;
+
+<span class="kw">try</span> {
+  <span class="kw">await</span> authApi.<span class="fn">register</span>(payload);
+} <span class="kw">catch</span> (err) {
+  <span class="kw">if</span> (err <span class="kw">instanceof</span> AntzChatValidationError) {
+    <span class="cm">// err.message → "email must be a valid email; password is too short"</span>
+    <span class="cm">// err.fields  → ["email must be a valid email", "password is too short"]</span>
+    Alert.<span class="fn">alert</span>(<span class="str">'Registration failed'</span>, err.fields?.<span class="fn">join</span>(<span class="str">'\n'</span>) ?? err.message);
+  }
+}</code></pre>
+  </div>
+
+  <div data-p="web">
+    <pre><code><span class="kw">import</span> { AntzChatValidationError } <span class="kw">from</span> <span class="str">'@antzsoft/chat-web-sdk'</span>;
+
+<span class="kw">try</span> {
+  <span class="kw">await</span> authApi.<span class="fn">register</span>(payload);
+} <span class="kw">catch</span> (err) {
+  <span class="kw">if</span> (err <span class="kw">instanceof</span> AntzChatValidationError) {
+    <span class="cm">// err.fields → ["email must be a valid email", "password is too short"]</span>
+    err.fields?.<span class="fn">forEach</span>(msg => <span class="fn">addFormError</span>(msg));
+    <span class="cm">// or show a single joined message:</span>
+    <span class="fn">setError</span>(err.message); <span class="cm">// "email must be a valid email; password is too short"</span>
+  }
+}</code></pre>
+  </div>
+
+  <div data-p="node">
+    <pre><code><span class="kw">import</span> { AntzChatValidationError } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+
+<span class="kw">try</span> {
+  <span class="kw">await</span> client.auth.<span class="fn">register</span>(payload);
+} <span class="kw">catch</span> (err) {
+  <span class="kw">if</span> (err <span class="kw">instanceof</span> AntzChatValidationError) {
+    console.<span class="fn">error</span>(<span class="str">'Validation errors:'</span>, err.fields ?? err.message);
+    <span class="cm">// err.fields → ["email must be a valid email", "password is too short"]</span>
+  }
+}</code></pre>
+  </div>
+
+  <!-- ── Pattern 5: transit mismatch ── -->
+  <h3>Pattern 5 — transit mismatch on connect</h3>
+  <p>Thrown before the socket is created when the SDK and server have mismatched <code>transitEncryption</code> settings:</p>
+
+  <div data-p="rn">
+    <pre><code><span class="kw">import</span> { AntzChatError } <span class="kw">from</span> <span class="str">'@antzsoft/chat-rn-sdk'</span>;
+
+<span class="kw">try</span> {
+  <span class="kw">await</span> connectSocket(config, getToken);
+} <span class="kw">catch</span> (err) {
+  <span class="kw">if</span> (err <span class="kw">instanceof</span> AntzChatError && err.code === <span class="str">'TRANSIT_MISMATCH'</span>) {
+    <span class="cm">// err.context = { sdkEnabled: true, serverEnabled: false }</span>
+    console.<span class="fn">error</span>(<span class="str">'Transit config mismatch:'</span>, err.message, err.context);
+    Alert.<span class="fn">alert</span>(<span class="str">'Config error'</span>, err.message);
+  }
+}</code></pre>
+  </div>
+
+  <div data-p="web">
+    <pre><code><span class="kw">import</span> { AntzChatError } <span class="kw">from</span> <span class="str">'@antzsoft/chat-web-sdk'</span>;
+
+<span class="kw">try</span> {
+  <span class="kw">await</span> connectSocket(config, getToken);
+} <span class="kw">catch</span> (err) {
+  <span class="kw">if</span> (err <span class="kw">instanceof</span> AntzChatError && err.code === <span class="str">'TRANSIT_MISMATCH'</span>) {
+    <span class="cm">// err.context = { sdkEnabled: false, serverEnabled: true }</span>
+    console.<span class="fn">error</span>(<span class="str">'Transit config mismatch:'</span>, err.message, err.context);
+  }
+}</code></pre>
+  </div>
+
+  <div data-p="node">
+    <pre><code><span class="kw">import</span> { AntzChatError } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+
+<span class="kw">try</span> {
+  <span class="kw">await</span> client.<span class="fn">connect</span>();
+} <span class="kw">catch</span> (err) {
+  <span class="kw">if</span> (err <span class="kw">instanceof</span> AntzChatError && err.code === <span class="str">'TRANSIT_MISMATCH'</span>) {
+    <span class="cm">// err.context = { sdkEnabled, serverEnabled }</span>
+    console.<span class="fn">error</span>(<span class="str">'Transit config mismatch:'</span>, err.message, err.context);
+    process.<span class="fn">exit</span>(<span class="num">1</span>);
+  }
+}</code></pre>
+  </div>
+
+  <!-- ── Logging with context ── -->
+  <h3>Logging with context</h3>
+  <p><code>context</code> is safe to log but never needed for control flow. When transit decryption fails for an error body, <code>context.decryptionFailed = true</code> is set and the HTTP-status-based class is still returned correctly:</p>
+
+  <div data-p="rn">
+    <pre><code><span class="kw">import</span> { AntzChatError } <span class="kw">from</span> <span class="str">'@antzsoft/chat-rn-sdk'</span>;
+
+<span class="kw">catch</span> (err) {
+  <span class="kw">if</span> (err <span class="kw">instanceof</span> AntzChatError) {
+    <span class="cm">// context may contain: httpStatus, path, serverError, axiosCode,</span>
+    <span class="cm">// event, conversationId, decryptionFailed, sdkEnabled, serverEnabled</span>
+    console.<span class="fn">error</span>(<span class="str">'[AntzChat]'</span>, err.name, err.code, err.message, err.context);
+  }
+}</code></pre>
+  </div>
+
+  <div data-p="web">
+    <pre><code><span class="kw">import</span> { AntzChatError } <span class="kw">from</span> <span class="str">'@antzsoft/chat-web-sdk'</span>;
+
+<span class="kw">catch</span> (err) {
+  <span class="kw">if</span> (err <span class="kw">instanceof</span> AntzChatError) {
+    <span class="cm">// context may contain: httpStatus, path, serverError, axiosCode,</span>
+    <span class="cm">// event, conversationId, decryptionFailed, sdkEnabled, serverEnabled</span>
+    console.<span class="fn">error</span>(<span class="str">'[AntzChat]'</span>, err.name, err.code, err.message, err.context);
+  }
+}</code></pre>
+  </div>
+
+  <div data-p="node">
+    <pre><code><span class="kw">import</span> { AntzChatError } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+
+<span class="kw">catch</span> (err) {
+  <span class="kw">if</span> (err <span class="kw">instanceof</span> AntzChatError) {
+    <span class="cm">// context may contain: httpStatus, path, serverError, axiosCode,</span>
+    <span class="cm">// event, conversationId, decryptionFailed, sdkEnabled, serverEnabled</span>
+    console.<span class="fn">error</span>(<span class="str">'[AntzChat]'</span>, err.name, err.code, err.message, err.context);
+  }
+}</code></pre>
+  </div>
+
+  <!-- ── What stays silent ── -->
+  <h3>What stays silent — by design</h3>
+  <table>
+    <thead><tr><th>Call</th><th>Behaviour</th><th>Reason</th></tr></thead>
+    <tbody>
+      <tr><td><code>socketEmit.typing()</code></td><td>Silently no-ops when socket is down</td><td>Best-effort — callers must never be forced to wrap typing events</td></tr>
+      <tr><td><code>socketEmit.markRead()</code></td><td>Silently no-ops when socket is down</td><td>Best-effort — read marking is not critical-path</td></tr>
+      <tr><td>Transit session timeout (5 s)</td><td>SDK degrades to unencrypted mode and continues</td><td>Graceful degradation — hard-failing would break auth entirely</td></tr>
+      <tr><td><code>usersApi.getPreferences()</code></td><td>Returns <code>null</code> on any error</td><td>Preferences are non-critical — defaults apply when absent</td></tr>
+    </tbody>
+  </table>
+
+  <!-- ── normalizeAxiosError ── -->
+  <h3><code>normalizeAxiosError</code></h3>
+  <p>If you make raw axios calls through <code>getApiClient()</code> and want the same normalisation pipeline:</p>
+
+  <div data-p="rn">
+    <pre><code><span class="kw">import</span> { getApiClient, normalizeAxiosError, AntzChatError } <span class="kw">from</span> <span class="str">'@antzsoft/chat-rn-sdk'</span>;
+
+<span class="kw">try</span> {
+  <span class="kw">const</span> { data } = <span class="kw">await</span> <span class="fn">getApiClient</span>().<span class="fn">get</span>(<span class="str">'/some/endpoint'</span>);
+} <span class="kw">catch</span> (err) {
+  <span class="kw">throw</span> <span class="fn">normalizeAxiosError</span>(err); <span class="cm">// always returns AntzChatError or subclass</span>
+}</code></pre>
+  </div>
+
+  <div data-p="web">
+    <pre><code><span class="kw">import</span> { getApiClient, normalizeAxiosError, AntzChatError } <span class="kw">from</span> <span class="str">'@antzsoft/chat-web-sdk'</span>;
+
+<span class="kw">try</span> {
+  <span class="kw">const</span> { data } = <span class="kw">await</span> <span class="fn">getApiClient</span>().<span class="fn">get</span>(<span class="str">'/some/endpoint'</span>);
+} <span class="kw">catch</span> (err) {
+  <span class="kw">throw</span> <span class="fn">normalizeAxiosError</span>(err); <span class="cm">// always returns AntzChatError or subclass</span>
+}</code></pre>
+  </div>
+
+  <div data-p="node">
+    <pre><code><span class="kw">import</span> { getApiClient, normalizeAxiosError, AntzChatError } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+
+<span class="kw">try</span> {
+  <span class="kw">const</span> { data } = <span class="kw">await</span> <span class="fn">getApiClient</span>().<span class="fn">get</span>(<span class="str">'/some/endpoint'</span>);
+} <span class="kw">catch</span> (err) {
+  <span class="kw">throw</span> <span class="fn">normalizeAxiosError</span>(err); <span class="cm">// always returns AntzChatError or subclass</span>
+}</code></pre>
+  </div>
+
+</section>
+
 </main>
 
 <!-- ── Go-to-top FAB ── -->