@antzsoft/chat-core 1.2.6 → 1.2.8

package/dist/internal.d.ts

@@ -1,4 +1,4 @@
-export { ad as uploadBatchWithSlots } from './storage-CctLCOnZ.js';
+export { al as uploadBatchWithSlots } from './storage-CW70b4vi.js';
 
 declare function generateUUID(): string;
 

package/dist/{storage-CctLCOnZ.d.cts → storage-CW70b4vi.d.cts}

@@ -359,6 +359,11 @@ interface ReactionUpdatedEvent {
     reactions: MessageReaction[];
     lastReaction: LastReaction | null;
 }
+interface MessageStarUpdatedEvent {
+    messageId: string;
+    conversationId: string;
+    isStarred: boolean;
+}
 interface TypingIndicatorEvent {
     conversationId: string;
     userId: string;
@@ -413,6 +418,53 @@ interface MessagesDeliveredEvent {
     deliveredTo: string;
     deliveredAt: string;
 }
+interface SyncReadReceipt {
+    messageId: string;
+    conversationId: string;
+    userId: string;
+    readAt: string | null;
+}
+interface SyncDeletedForMe {
+    messageId: string;
+    conversationId: string;
+    deletedAt: string | null;
+}
+interface SyncParticipantChange {
+    conversationId: string;
+    userId: string;
+    role: string;
+    isActive: boolean;
+    isMuted: boolean;
+    mutedUntil: string | null;
+    updatedAt: string | null;
+}
+interface SyncStarEntry {
+    messageId: string;
+    conversationId: string;
+    /** true = starred, false = unstarred (soft-deleted) */
+    isActive: boolean;
+    updatedAt: string | null;
+}
+/** Full current reaction state keyed by messageId. Only message IDs with activity since `since` are included. */
+type SyncReactions = Record<string, MessageReaction[]>;
+interface CrossConversationSyncResponse {
+    syncedAt: string;
+    /** When true the gap exceeds 60 days — app should mark all conversations needs_refresh and lazy-sync on open */
+    stale: boolean;
+    messages: Message[];
+    deletedForMe: SyncDeletedForMe[];
+    participantChanges: SyncParticipantChange[];
+    readReceipts: SyncReadReceipt[];
+}
+interface ConversationSyncResponse {
+    syncedAt: string;
+    messages: Message[];
+    deletedForMe: SyncDeletedForMe[];
+    reactions: SyncReactions;
+    stars: SyncStarEntry[];
+    participantChanges: SyncParticipantChange[];
+    readReceipts: SyncReadReceipt[];
+}
 interface SendMessageAttachment {
     fileId: string;
     type: FileType;
@@ -707,4 +759,4 @@ declare function uploadBatchWithSlots(files: UploadableFile[], platformUploadFn:
     slotToFile: Map<string, FileResponse>;
 }>;
 
-export { type QuietHours as $, type AuthResponse as A, type BatchUploadResult as B, type CursorPaginatedResponse as C, type MessageContent as D, type MessageDeletedEvent as E, type FileResponse as F, type MessageDeletedForMeEvent as G, type MessageDeliveredEvent as H, type MessageMetadata as I, type MessageReaction as J, type MessageReceiptEntry as K, type LoginCredentials as L, type Message as M, type MessageReplyReference as N, type MessageUpdatedEvent as O, type PaginatedResponse as P, type MessagesDeliveredEvent as Q, type ResolvedCompressionConfig as R, type SendMessagePayload as S, type MultipartPartUrl as T, type User as U, type MultipartUploadInfo as V, type NewMessageEvent as W, type OptimisticAttachment as X, type PlatformCompressFn as Y, type PlatformUploadFn as Z, type PlatformUploadPartFn as _, type RegisterData as a, type ReactionUpdatedEvent as a0, type ReadReceiptEvent as a1, type ReplyAttachmentSnapshot as a2, type ResolvedFileSizeLimits as a3, type SendMessageAttachment as a4, type SystemMessageMetadata as a5, type TypingIndicatorEvent as a6, type UploadConfig as a7, type UploadProgress as a8, type UserStatusEvent as a9, resolveConfig as aa, storageApi as ab, uploadBatch as ac, uploadBatchWithSlots as ad, type AuthTokens as b, type AppConfig as c, type MessageReceiptsResponse as d, type ConversationListParams as e, type Conversation as f, type Participant as g, type ConversationUnreadCount as h, type UnreadSummary as i, type UserPreferences as j, type ResolvedConfig as k, type PersistStorage as l, type PresignedUrlRequest as m, type PresignedUrlResponse as n, type CompletedPart as o, type FileType as p, type AntzChatConfig as q, type UploadableFile as r, type Attachment as s, type CompressedFile as t, type CompressionAlgorithm as u, type CompressionConfig as v, type ConversationType as w, type FileSizeLimits as x, type LastReaction as y, type MessageAckEvent as z };
+export { type PlatformCompressFn as $, type AuthResponse as A, type BatchUploadResult as B, type CrossConversationSyncResponse as C, type LastReaction as D, type MessageAckEvent as E, type FileResponse as F, type MessageContent as G, type MessageDeletedEvent as H, type MessageDeletedForMeEvent as I, type MessageDeliveredEvent as J, type MessageMetadata as K, type LoginCredentials as L, type Message as M, type MessageReaction as N, type MessageReceiptEntry as O, type PaginatedResponse as P, type MessageReplyReference as Q, type ResolvedCompressionConfig as R, type SendMessagePayload as S, type MessageStarUpdatedEvent as T, type User as U, type MessageUpdatedEvent as V, type MessagesDeliveredEvent as W, type MultipartPartUrl as X, type MultipartUploadInfo as Y, type NewMessageEvent as Z, type OptimisticAttachment as _, type RegisterData as a, type PlatformUploadFn as a0, type PlatformUploadPartFn as a1, type QuietHours as a2, type ReactionUpdatedEvent as a3, type ReadReceiptEvent as a4, type ReplyAttachmentSnapshot as a5, type ResolvedFileSizeLimits as a6, type SendMessageAttachment as a7, type SyncDeletedForMe as a8, type SyncParticipantChange as a9, type SyncReactions as aa, type SyncReadReceipt as ab, type SyncStarEntry as ac, type SystemMessageMetadata as ad, type TypingIndicatorEvent as ae, type UploadConfig as af, type UploadProgress as ag, type UserStatusEvent as ah, resolveConfig as ai, storageApi as aj, uploadBatch as ak, uploadBatchWithSlots as al, type AuthTokens as b, type ConversationSyncResponse as c, type AppConfig as d, type CursorPaginatedResponse as e, type MessageReceiptsResponse as f, type ConversationListParams as g, type Conversation as h, type Participant as i, type ConversationUnreadCount as j, type UnreadSummary as k, type UserPreferences as l, type ResolvedConfig as m, type PersistStorage as n, type PresignedUrlRequest as o, type PresignedUrlResponse as p, type CompletedPart as q, type FileType as r, type AntzChatConfig as s, type UploadableFile as t, type Attachment as u, type CompressedFile as v, type CompressionAlgorithm as w, type CompressionConfig as x, type ConversationType as y, type FileSizeLimits as z };

package/dist/{storage-CctLCOnZ.d.ts → storage-CW70b4vi.d.ts}

@@ -359,6 +359,11 @@ interface ReactionUpdatedEvent {
     reactions: MessageReaction[];
     lastReaction: LastReaction | null;
 }
+interface MessageStarUpdatedEvent {
+    messageId: string;
+    conversationId: string;
+    isStarred: boolean;
+}
 interface TypingIndicatorEvent {
     conversationId: string;
     userId: string;
@@ -413,6 +418,53 @@ interface MessagesDeliveredEvent {
     deliveredTo: string;
     deliveredAt: string;
 }
+interface SyncReadReceipt {
+    messageId: string;
+    conversationId: string;
+    userId: string;
+    readAt: string | null;
+}
+interface SyncDeletedForMe {
+    messageId: string;
+    conversationId: string;
+    deletedAt: string | null;
+}
+interface SyncParticipantChange {
+    conversationId: string;
+    userId: string;
+    role: string;
+    isActive: boolean;
+    isMuted: boolean;
+    mutedUntil: string | null;
+    updatedAt: string | null;
+}
+interface SyncStarEntry {
+    messageId: string;
+    conversationId: string;
+    /** true = starred, false = unstarred (soft-deleted) */
+    isActive: boolean;
+    updatedAt: string | null;
+}
+/** Full current reaction state keyed by messageId. Only message IDs with activity since `since` are included. */
+type SyncReactions = Record<string, MessageReaction[]>;
+interface CrossConversationSyncResponse {
+    syncedAt: string;
+    /** When true the gap exceeds 60 days — app should mark all conversations needs_refresh and lazy-sync on open */
+    stale: boolean;
+    messages: Message[];
+    deletedForMe: SyncDeletedForMe[];
+    participantChanges: SyncParticipantChange[];
+    readReceipts: SyncReadReceipt[];
+}
+interface ConversationSyncResponse {
+    syncedAt: string;
+    messages: Message[];
+    deletedForMe: SyncDeletedForMe[];
+    reactions: SyncReactions;
+    stars: SyncStarEntry[];
+    participantChanges: SyncParticipantChange[];
+    readReceipts: SyncReadReceipt[];
+}
 interface SendMessageAttachment {
     fileId: string;
     type: FileType;
@@ -707,4 +759,4 @@ declare function uploadBatchWithSlots(files: UploadableFile[], platformUploadFn:
     slotToFile: Map<string, FileResponse>;
 }>;
 
-export { type QuietHours as $, type AuthResponse as A, type BatchUploadResult as B, type CursorPaginatedResponse as C, type MessageContent as D, type MessageDeletedEvent as E, type FileResponse as F, type MessageDeletedForMeEvent as G, type MessageDeliveredEvent as H, type MessageMetadata as I, type MessageReaction as J, type MessageReceiptEntry as K, type LoginCredentials as L, type Message as M, type MessageReplyReference as N, type MessageUpdatedEvent as O, type PaginatedResponse as P, type MessagesDeliveredEvent as Q, type ResolvedCompressionConfig as R, type SendMessagePayload as S, type MultipartPartUrl as T, type User as U, type MultipartUploadInfo as V, type NewMessageEvent as W, type OptimisticAttachment as X, type PlatformCompressFn as Y, type PlatformUploadFn as Z, type PlatformUploadPartFn as _, type RegisterData as a, type ReactionUpdatedEvent as a0, type ReadReceiptEvent as a1, type ReplyAttachmentSnapshot as a2, type ResolvedFileSizeLimits as a3, type SendMessageAttachment as a4, type SystemMessageMetadata as a5, type TypingIndicatorEvent as a6, type UploadConfig as a7, type UploadProgress as a8, type UserStatusEvent as a9, resolveConfig as aa, storageApi as ab, uploadBatch as ac, uploadBatchWithSlots as ad, type AuthTokens as b, type AppConfig as c, type MessageReceiptsResponse as d, type ConversationListParams as e, type Conversation as f, type Participant as g, type ConversationUnreadCount as h, type UnreadSummary as i, type UserPreferences as j, type ResolvedConfig as k, type PersistStorage as l, type PresignedUrlRequest as m, type PresignedUrlResponse as n, type CompletedPart as o, type FileType as p, type AntzChatConfig as q, type UploadableFile as r, type Attachment as s, type CompressedFile as t, type CompressionAlgorithm as u, type CompressionConfig as v, type ConversationType as w, type FileSizeLimits as x, type LastReaction as y, type MessageAckEvent as z };
+export { type PlatformCompressFn as $, type AuthResponse as A, type BatchUploadResult as B, type CrossConversationSyncResponse as C, type LastReaction as D, type MessageAckEvent as E, type FileResponse as F, type MessageContent as G, type MessageDeletedEvent as H, type MessageDeletedForMeEvent as I, type MessageDeliveredEvent as J, type MessageMetadata as K, type LoginCredentials as L, type Message as M, type MessageReaction as N, type MessageReceiptEntry as O, type PaginatedResponse as P, type MessageReplyReference as Q, type ResolvedCompressionConfig as R, type SendMessagePayload as S, type MessageStarUpdatedEvent as T, type User as U, type MessageUpdatedEvent as V, type MessagesDeliveredEvent as W, type MultipartPartUrl as X, type MultipartUploadInfo as Y, type NewMessageEvent as Z, type OptimisticAttachment as _, type RegisterData as a, type PlatformUploadFn as a0, type PlatformUploadPartFn as a1, type QuietHours as a2, type ReactionUpdatedEvent as a3, type ReadReceiptEvent as a4, type ReplyAttachmentSnapshot as a5, type ResolvedFileSizeLimits as a6, type SendMessageAttachment as a7, type SyncDeletedForMe as a8, type SyncParticipantChange as a9, type SyncReactions as aa, type SyncReadReceipt as ab, type SyncStarEntry as ac, type SystemMessageMetadata as ad, type TypingIndicatorEvent as ae, type UploadConfig as af, type UploadProgress as ag, type UserStatusEvent as ah, resolveConfig as ai, storageApi as aj, uploadBatch as ak, uploadBatchWithSlots as al, type AuthTokens as b, type ConversationSyncResponse as c, type AppConfig as d, type CursorPaginatedResponse as e, type MessageReceiptsResponse as f, type ConversationListParams as g, type Conversation as h, type Participant as i, type ConversationUnreadCount as j, type UnreadSummary as k, type UserPreferences as l, type ResolvedConfig as m, type PersistStorage as n, type PresignedUrlRequest as o, type PresignedUrlResponse as p, type CompletedPart as q, type FileType as r, type AntzChatConfig as s, type UploadableFile as t, type Attachment as u, type CompressedFile as v, type CompressionAlgorithm as w, type CompressionConfig as x, type ConversationType as y, type FileSizeLimits as z };

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.6 Release Notes</a></li>
+    <li><a href="#whats-new">v1.2.8 Release Notes</a></li>
   </ul>
 
   <div class="section-label">Getting Started</div>
@@ -250,16 +250,248 @@ 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.6 (current) ── -->
-  <div class="wn-version open" id="wn-126">
-    <div class="wn-header" onclick="toggleVersion('wn-126')">
+  <!-- ── v1.2.8 (current) ── -->
+  <div class="wn-version open" id="wn-128">
+    <div class="wn-header" onclick="toggleVersion('wn-128')">
       <div class="wn-title">
-        <span class="wn-ver">v1.2.6</span>
+        <span class="wn-ver">v1.2.8</span>
         <span class="wn-badge current">Current</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-128-delivery-status">
+        <div class="wn-item-header" onclick="toggleItem('wn-128-delivery-status')">
+          <span class="wn-tag new">New</span>
+          <span class="wn-item-title"><code>deliveryStatus</code> on <code>Conversation.lastMessage</code> — tick state in conversation list</span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p>The conversation list API (<code>GET /conversations</code>) and the <code>conversation_updated</code> socket event now include <code>deliveryStatus</code> on the <code>lastMessage</code> object. This is the tick state of the last message as seen by the sender — stored directly on the conversation document and kept current by the server on every read and delivery event.</p>
+
+          <table>
+            <thead><tr><th>Value</th><th>Meaning</th></tr></thead>
+            <tbody>
+              <tr><td><code>'sent'</code></td><td>Message written to the server — not yet delivered to all recipients</td></tr>
+              <tr><td><code>'delivered'</code></td><td>All active recipients have received the message on at least one device</td></tr>
+              <tr><td><code>'read'</code></td><td>All active recipients have opened and read the message</td></tr>
+            </tbody>
+          </table>
+
+          <p><strong>Usage — rendering tick marks in a conversation list (custom UI):</strong></p>
+          <pre><code><span class="kw">const</span> { data: conversations } = <span class="kw">await</span> conversationsApi.<span class="fn">list</span>();
+
+<span class="kw">for</span> (<span class="kw">const</span> conv <span class="kw">of</span> conversations) {
+  <span class="kw">const</span> lm = conv.lastMessage;
+  <span class="kw">if</span> (!lm) <span class="kw">continue</span>;
+
+  <span class="cm">// Only show ticks on messages sent by the current user</span>
+  <span class="kw">const</span> isMyMessage = lm.senderId === currentUserId;
+  <span class="kw">if</span> (!isMyMessage) <span class="kw">continue</span>;
+
+  <span class="cm">// deliveryStatus: 'sent' | 'delivered' | 'read'</span>
+  <span class="fn">renderTick</span>(conv.id, lm.deliveryStatus ?? <span class="str">'sent'</span>);
+}</code></pre>
+
+          <p><strong>Live updates</strong> — the existing <code>read_receipt</code> socket event continues to carry real-time tick updates while a conversation room is open. <code>deliveryStatus</code> on <code>lastMessage</code> is the cold-start / list-load source of truth; socket events keep it live after that.</p>
+
+          <p><strong>Server-side changes:</strong></p>
+          <ul>
+            <li><code>lastMessage.deliveryStatus</code> is set to <code>'sent'</code> when a new message is written</li>
+            <li>Promoted to <code>'delivered'</code> when all active recipients have a delivery record for that message</li>
+            <li>Promoted to <code>'read'</code> when <code>fullyReadMessageIds</code> includes the last message (i.e. all active recipients have read it)</li>
+            <li>Status never demotes — a conditional update ensures it only advances: <code>sent → delivered → read</code></li>
+          </ul>
+
+          <p><strong>Migration</strong> — existing conversations are backfilled automatically by <code>005_backfill_last_message_delivery_status</code> on first deploy. It queries <code>chat_message_reads</code> and <code>chat_message_deliveries</code> to compute the correct status for each conversation's current last message. No manual step required.</p>
+
+          <p><strong>Backward compatibility</strong> — <code>deliveryStatus</code> defaults to <code>'sent'</code> when absent (<code>lm.deliveryStatus ?? 'sent'</code>). The field was already defined as optional on the <code>Message</code> type — it is now also populated on the <code>lastMessage</code> snapshot. No breaking changes.</p>
+        </div>
+      </div>
+
+    </div>
+  </div><!-- /.wn-version -->
+
+  <!-- ── v1.2.7 ── -->
+  <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.7</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-127-starsynce">
+        <div class="wn-item-header" onclick="toggleItem('wn-127-starsynce')">
+          <span class="wn-tag new">New</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>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>Field</th><th>Type</th><th>Description</th></tr></thead>
+            <tbody>
+              <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>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-127-softustar">
+        <div class="wn-item-header" onclick="toggleItem('wn-127-softustar')">
+          <span class="wn-tag new">New</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>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-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>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>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 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>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-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>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><!-- /.wn-version -->
+
+  <!-- ── 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.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-126-clearchat">
@@ -280,7 +512,7 @@ section.sec>h2:hover{color:#fff}
             </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 to the caller's own sockets when <code>delete()</code> is called — remove the conversation from local state and navigate away if it was open. Other participants do not receive this event.</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>
@@ -393,7 +625,7 @@ section.sec>h2:hover{color:#fff}
   <button class="wn-history-btn" onclick="openVersionHistory()">
     <span class="wn-history-icon">⏱</span>
     View version history
-    <span class="wn-history-count">19 older versions</span>
+    <span class="wn-history-count">20 older versions</span>
   </button>
 
 </section>
@@ -3166,7 +3398,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>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antzsoft/chat-core",
-  "version": "1.2.6",
+  "version": "1.2.8",
   "description": "Platform-agnostic core for Antz Chat — API, socket, stores, types. Works in browser, React Native (Expo or bare), and Node.js.",
   "author": "Antz",
   "license": "MIT",