@antzsoft/chat-core 1.2.1 → 1.2.3

package/docs/integration-guide.html

@@ -155,7 +155,7 @@ section.sec>h2:hover{color:#fff}
 
   <div class="section-label">What's New</div>
   <ul>
-    <li><a href="#whats-new">v1.2.0 Release Notes</a></li>
+    <li><a href="#whats-new">v1.2.3 Release Notes</a></li>
   </ul>
 
   <div class="section-label">Getting Started</div>
@@ -192,6 +192,7 @@ section.sec>h2:hover{color:#fff}
     <li><a href="#step-realtime">10. Real-time Events</a></li>
     <li><a href="#step-typing">11. Typing Indicators</a></li>
     <li><a href="#step-read">12. Read Receipts &amp; Last Seen</a></li>
+    <li><a href="#step-message-info">12b. Message Info Screen</a></li>
     <li><a href="#step-edit">13. Edit &amp; Delete</a></li>
     <li><a href="#step-search">14. Search Messages</a></li>
     <li><a href="#step-reactions">15. Reactions, Pin, Star</a></li>
@@ -242,16 +243,107 @@ 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.0 (current) ── -->
-  <div class="wn-version open" id="wn-120">
-    <div class="wn-header" onclick="toggleVersion('wn-120')">
+  <!-- ── v1.2.3 (current) ── -->
+  <div class="wn-version open" id="wn-123">
+    <div class="wn-header" onclick="toggleVersion('wn-123')">
       <div class="wn-title">
-        <span class="wn-ver">v1.2.0</span>
+        <span class="wn-ver">v1.2.3</span>
         <span class="wn-badge current">Current</span>
         <span class="wn-date">May 2026</span>
       </div>
       <span class="wn-chevron">▲</span>
     </div>
+    <div class="wn-body">
+
+      <div class="wn-item" id="wn-123-1">
+        <div class="wn-item-header" onclick="toggleItem('wn-123-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 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>
+        </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>
+          <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>
+        </div>
+      </div>
+
+      <div class="wn-item" id="wn-123-3">
+        <div class="wn-item-header" onclick="toggleItem('wn-123-3')">
+          <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-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>
+          <table>
+            <thead><tr><th>Viewer</th><th>Rendered text</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>
+            </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>
+          <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>
+          </ul>
+        </div>
+      </div>
+
+    </div>
+  </div><!-- /.wn-version -->
+
+  <!-- ── v1.2.0 ── -->
+  <div class="wn-version" id="wn-120">
+    <div class="wn-header" onclick="toggleVersion('wn-120')">
+      <div class="wn-title">
+        <span class="wn-ver">v1.2.0</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-120-1">
@@ -2641,12 +2733,12 @@ socket.<span class="fn">on</span>(<span class="str">'message_deleted'</span>, (e
       </tr>
       <tr>
         <td><code>'message_delivered'</code></td>
-        <td>A single message you sent was delivered to all active recipients. Payload: <code>{ messageId, conversationId, deliveredTo: Array&lt;{ userId, deliveredAt }&gt; }</code></td>
-        <td><strong>Chat detail screen</strong> — add on mount, remove on unmount.</td>
+        <td>Fired to the sender each time a recipient receives a message — <strong>one event per recipient</strong>. Fires at send time for online recipients, and again per recipient as offline recipients reconnect. Payload: <code>{ messageId, conversationId, deliveredTo: { userId, deliveredAt } }</code></td>
+        <td><strong>Chat detail screen / message info screen</strong> — add on mount, remove on unmount.</td>
       </tr>
       <tr>
         <td><code>'messages_delivered'</code></td>
-        <td>Batch delivery catch-up when a recipient comes online. Payload: <code>{ conversationId, messageIds[], deliveredTo: string, deliveredAt }</code></td>
+        <td>Batch delivery catch-up fired to the sender when an offline recipient reconnects and all pending messages are marked delivered in bulk. Payload: <code>{ conversationId, messageIds[], deliveredTo: string, deliveredAt }</code></td>
         <td><strong>Chat detail screen</strong> — add on mount, remove on unmount.</td>
       </tr>
       <tr>
@@ -2848,6 +2940,79 @@ socket?.<span class="fn">on</span>(<span class="str">'read_receipt'</span>, ({ c
   </table>
 </section>
 
+<!-- ─── STEP 12b: MESSAGE INFO SCREEN ────────────────────────────────── -->
+<section id="step-message-info">
+  <h2><span class="step">STEP 12b</span> Message Info Screen (Read by / Delivered to)</h2>
+
+  <p>The message info screen shows all group participants split into three buckets: <strong>Read by</strong>, <strong>Delivered to</strong>, and <strong>Sent to</strong> (not yet received). The list updates live as participants read or receive the message.</p>
+
+  <h3>Initial load</h3>
+  <p>Call <code>messagesApi.getReceipts(messageId)</code> on open. This returns <code>readBy[]</code> and <code>deliveredTo[]</code> with resolved user profiles — no secondary lookup needed.</p>
+
+  <pre><code><span class="kw">import</span> { messagesApi, conversationsApi } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+<span class="kw">import</span> <span class="tp">{ MessageReceiptsResponse }</span> <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+
+<span class="cm">// Fetch receipts + participants in parallel</span>
+<span class="kw">const</span> [receipts, conversation] = <span class="kw">await</span> Promise.<span class="fn">all</span>([
+  messagesApi.<span class="fn">getReceipts</span>(messageId),
+  conversationsApi.<span class="fn">get</span>(conversationId),
+]);
+
+<span class="kw">const</span> readByIds    = <span class="kw">new</span> <span class="fn">Set</span>(receipts.readBy.<span class="fn">map</span>(r => r.userId));
+<span class="kw">const</span> deliveredIds = <span class="kw">new</span> <span class="fn">Set</span>(receipts.deliveredTo.<span class="fn">map</span>(d => d.userId));
+
+<span class="kw">const</span> sentTo = conversation.participants
+  .<span class="fn">filter</span>(p => !readByIds.<span class="fn">has</span>(p.userId) && !deliveredIds.<span class="fn">has</span>(p.userId) && p.userId !== senderId)
+  .<span class="fn">map</span>(p => p.user);</code></pre>
+
+  <h3>Live updates</h3>
+  <p>Subscribe to <code>read_receipt</code> and <code>message_delivered</code> while the screen is open. Both fire per-person so the buckets update one entry at a time.</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</span> <span class="tp">{ ReadReceiptEvent, MessageDeliveredEvent }</span> <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+
+<span class="kw">const</span> socket = <span class="fn">tryGetSocket</span>();
+
+<span class="kw">function</span> <span class="fn">onReadReceipt</span>(evt: <span class="tp">ReadReceiptEvent</span>) {
+  <span class="kw">if</span> (!evt.updatedMessageIds?.<span class="fn">includes</span>(messageId)) <span class="kw">return</span>;
+  <span class="cm">// Move evt.userId from deliveredTo / sentTo → readBy</span>
+  <span class="fn">addToReadBy</span>({ userId: evt.userId, readAt: evt.readAt });
+  <span class="fn">removeFromDeliveredTo</span>(evt.userId);
+  <span class="fn">removeFromSentTo</span>(evt.userId);
+}
+
+<span class="kw">function</span> <span class="fn">onMessageDelivered</span>(evt: <span class="tp">MessageDeliveredEvent</span>) {
+  <span class="kw">if</span> (evt.messageId !== messageId) <span class="kw">return</span>;
+  <span class="cm">// Move evt.deliveredTo.userId from sentTo → deliveredTo</span>
+  <span class="fn">addToDeliveredTo</span>(evt.deliveredTo);
+  <span class="fn">removeFromSentTo</span>(evt.deliveredTo.userId);
+}
+
+socket?.<span class="fn">on</span>(<span class="str">'read_receipt'</span>, onReadReceipt);
+socket?.<span class="fn">on</span>(<span class="str">'message_delivered'</span>, onMessageDelivered);
+
+<span class="cm">// Clean up on screen close</span>
+<span class="kw">return</span> () => {
+  socket?.<span class="fn">off</span>(<span class="str">'read_receipt'</span>, onReadReceipt);
+  socket?.<span class="fn">off</span>(<span class="str">'message_delivered'</span>, onMessageDelivered);
+};</code></pre>
+
+  <div class="callout tip">
+    <strong>Three-bucket logic</strong> — All group participants minus the sender form the full list. <code>readBy</code> takes priority: once someone is in <code>readBy</code>, remove them from <code>deliveredTo</code> and <code>sentTo</code>. <code>deliveredTo</code> takes priority over <code>sentTo</code>. The <code>sentTo</code> bucket is always derived as the remainder.
+  </div>
+
+  <h4>Summary — what is automatic vs. what you do</h4>
+  <table>
+    <thead><tr><th>Action</th><th>Automatic?</th><th>What you do</th></tr></thead>
+    <tbody>
+      <tr><td>Initial receipt list with user profiles</td><td>❌ Manual</td><td>Call <code>messagesApi.getReceipts(messageId)</code> on screen open</td></tr>
+      <tr><td>Live read updates</td><td>❌ Manual</td><td>Listen to <code>read_receipt</code>, check <code>updatedMessageIds</code></td></tr>
+      <tr><td>Live delivery updates</td><td>❌ Manual</td><td>Listen to <code>message_delivered</code>, check <code>messageId</code></td></tr>
+      <tr><td>Participant list for "Sent to" bucket</td><td>❌ Manual</td><td>Fetch via <code>conversationsApi.get(conversationId)</code></td></tr>
+    </tbody>
+  </table>
+</section>
+
 <!-- ─── STEP 13: EDIT & DELETE ────────────────────────────────────────── -->
 <section id="step-edit">
   <h2><span class="step">STEP 13</span> Edit &amp; Delete Messages</h2>
@@ -3432,6 +3597,133 @@ self.<span class="fn">addEventListener</span>(<span class="str">'notificationcli
     simultaneously when a notification is triggered. Removing a token only deactivates that specific
     device; other devices continue to receive notifications.
   </p>
+
+  <!-- ── Notification payload + channel/category setup (RN only) ──────── -->
+  <div data-p="rn">
+    <h3>Handling incoming notifications</h3>
+
+    <h4>Notification payload</h4>
+    <p>
+      Every push notification the server sends includes <code>channelId</code> and <code>categoryId</code>
+      at the top level (read by the OS / Expo SDK) and mirrored inside the <code>data</code> object
+      (readable by your JS notification handler):
+    </p>
+    <pre><code>{
+  <span class="str">"title"</span>: <span class="str">"Alice replied to you"</span>,
+  <span class="str">"body"</span>:  <span class="str">"Sounds good!"</span>,
+  <span class="str">"priority"</span>:   <span class="str">"high"</span>,
+  <span class="str">"channelId"</span>:  <span class="str">"reply"</span>,
+  <span class="str">"categoryId"</span>: <span class="str">"reply"</span>,
+  <span class="str">"data"</span>: {
+    <span class="str">"event"</span>:               <span class="str">"reply"</span>,
+    <span class="str">"channelId"</span>:          <span class="str">"reply"</span>,
+    <span class="str">"categoryId"</span>:         <span class="str">"reply"</span>,
+    <span class="str">"conversation_id"</span>:    <span class="str">"..."</span>,
+    <span class="str">"message_id"</span>:         <span class="str">"..."</span>,
+    <span class="str">"original_message_id"</span>: <span class="str">"..."</span>,
+    <span class="str">"sender_id"</span>:          <span class="str">"..."</span>,
+    <span class="str">"sender_name"</span>:        <span class="str">"Alice"</span>
+  }
+}</code></pre>
+
+    <h4>Per-event channelId and categoryId</h4>
+    <table style="width:100%;border-collapse:collapse;font-size:13px;margin:12px 0">
+      <thead><tr style="border-bottom:1px solid var(--border)">
+        <th style="text-align:left;padding:6px 10px;color:var(--muted)">Event</th>
+        <th style="text-align:left;padding:6px 10px;color:var(--muted)">channelId</th>
+        <th style="text-align:left;padding:6px 10px;color:var(--muted)">categoryId</th>
+        <th style="text-align:left;padding:6px 10px;color:var(--muted)">Notes</th>
+      </tr></thead>
+      <tbody>
+        <tr style="border-bottom:1px solid var(--border)"><td style="padding:6px 10px"><code>dm_message</code></td><td style="padding:6px 10px"><code>messages</code></td><td style="padding:6px 10px"><code>message</code></td><td style="padding:6px 10px">Direct message</td></tr>
+        <tr style="border-bottom:1px solid var(--border)"><td style="padding:6px 10px"><code>group_message</code></td><td style="padding:6px 10px"><code>messages</code></td><td style="padding:6px 10px"><code>message</code></td><td style="padding:6px 10px">Group message</td></tr>
+        <tr style="border-bottom:1px solid var(--border)"><td style="padding:6px 10px"><code>mention</code></td><td style="padding:6px 10px"><code>messages</code></td><td style="padding:6px 10px"><code>message</code></td><td style="padding:6px 10px">Mentioned in a group</td></tr>
+        <tr style="border-bottom:1px solid var(--border)"><td style="padding:6px 10px"><code>reply</code></td><td style="padding:6px 10px"><code>reply</code></td><td style="padding:6px 10px"><code>reply</code></td><td style="padding:6px 10px">Reply to your message</td></tr>
+        <tr style="border-bottom:1px solid var(--border)"><td style="padding:6px 10px"><code>dm_reaction</code> / <code>group_reaction</code></td><td style="padding:6px 10px"><code>reactions</code></td><td style="padding:6px 10px"><code>reaction</code></td><td style="padding:6px 10px">Emoji reaction</td></tr>
+        <tr style="border-bottom:1px solid var(--border)"><td style="padding:6px 10px"><code>group_invite</code></td><td style="padding:6px 10px"><code>group_invites</code></td><td style="padding:6px 10px"><code>invite</code></td><td style="padding:6px 10px">Added to a group</td></tr>
+        <tr style="border-bottom:1px solid var(--border)"><td style="padding:6px 10px"><code>group_removed</code></td><td style="padding:6px 10px"><code>group_updates</code></td><td style="padding:6px 10px">—</td><td style="padding:6px 10px">Removed from a group</td></tr>
+        <tr style="border-bottom:1px solid var(--border)"><td style="padding:6px 10px"><code>group_role_changed</code></td><td style="padding:6px 10px"><code>group_updates</code></td><td style="padding:6px 10px">—</td><td style="padding:6px 10px">Role changed in a group</td></tr>
+        <tr><td style="padding:6px 10px"><code>message_edited</code> / <code>message_deleted</code></td><td style="padding:6px 10px"><code>silent</code></td><td style="padding:6px 10px">—</td><td style="padding:6px 10px">Silent background sync, no sound</td></tr>
+      </tbody>
+    </table>
+    <div class="callout tip">
+      <strong>channelId</strong> is Android-only (Android 8+) — controls sound, importance, and DND behaviour per channel.<br>
+      <strong>categoryId</strong> is iOS-only — links to interactive action buttons registered with <code>setNotificationCategoryAsync</code>.<br>
+      If the channel/category is not registered yet on the client, the OS falls back to default behaviour — notifications still arrive normally.
+    </div>
+
+    <h4>Android — register channels at app startup</h4>
+    <p>Create all channels unconditionally on every app launch, before the first notification arrives:</p>
+    <pre><code><span class="kw">import</span> * <span class="kw">as</span> Notifications <span class="kw">from</span> <span class="str">'expo-notifications'</span>;
+
+<span class="kw">async function</span> <span class="fn">setupNotificationChannels</span>() {
+  <span class="kw">await</span> Notifications.<span class="fn">setNotificationChannelAsync</span>(<span class="str">'messages'</span>, {
+    name: <span class="str">'Messages'</span>,
+    importance: Notifications.AndroidImportance.HIGH,
+    sound: <span class="str">'default'</span>,
+  });
+  <span class="kw">await</span> Notifications.<span class="fn">setNotificationChannelAsync</span>(<span class="str">'reply'</span>, {
+    name: <span class="str">'Replies'</span>,
+    importance: Notifications.AndroidImportance.HIGH,
+    sound: <span class="str">'default'</span>,
+  });
+  <span class="kw">await</span> Notifications.<span class="fn">setNotificationChannelAsync</span>(<span class="str">'reactions'</span>, {
+    name: <span class="str">'Reactions'</span>,
+    importance: Notifications.AndroidImportance.DEFAULT,
+  });
+  <span class="kw">await</span> Notifications.<span class="fn">setNotificationChannelAsync</span>(<span class="str">'group_invites'</span>, {
+    name: <span class="str">'Group Invites'</span>,
+    importance: Notifications.AndroidImportance.HIGH,
+    sound: <span class="str">'default'</span>,
+  });
+  <span class="kw">await</span> Notifications.<span class="fn">setNotificationChannelAsync</span>(<span class="str">'group_updates'</span>, {
+    name: <span class="str">'Group Updates'</span>,
+    importance: Notifications.AndroidImportance.LOW,
+  });
+  <span class="kw">await</span> Notifications.<span class="fn">setNotificationChannelAsync</span>(<span class="str">'silent'</span>, {
+    name: <span class="str">'Background Sync'</span>,
+    importance: Notifications.AndroidImportance.MIN,
+    sound: <span class="kw">undefined</span>,
+    enableVibrate: <span class="kw">false</span>,
+  });
+}</code></pre>
+
+    <h4>iOS — register categories with interactive actions</h4>
+    <p>Register categories before requesting push permission. The <code>reply</code> category adds a Reply button when the app is killed:</p>
+    <pre><code><span class="kw">import</span> * <span class="kw">as</span> Notifications <span class="kw">from</span> <span class="str">'expo-notifications'</span>;
+
+<span class="kw">async function</span> <span class="fn">setupNotificationCategories</span>() {
+  <span class="kw">await</span> Notifications.<span class="fn">setNotificationCategoryAsync</span>(<span class="str">'reply'</span>, [
+    {
+      identifier: <span class="str">'REPLY_ACTION'</span>,
+      buttonTitle: <span class="str">'Reply'</span>,
+      textInput: { submitButtonTitle: <span class="str">'Send'</span>, placeholder: <span class="str">'Type a reply...'</span> },
+    },
+  ]);
+  <span class="kw">await</span> Notifications.<span class="fn">setNotificationCategoryAsync</span>(<span class="str">'message'</span>, [
+    {
+      identifier: <span class="str">'REPLY_ACTION'</span>,
+      buttonTitle: <span class="str">'Reply'</span>,
+      textInput: { submitButtonTitle: <span class="str">'Send'</span>, placeholder: <span class="str">'Type a reply...'</span> },
+    },
+  ]);
+  <span class="kw">await</span> Notifications.<span class="fn">setNotificationCategoryAsync</span>(<span class="str">'reaction'</span>, []);
+  <span class="kw">await</span> Notifications.<span class="fn">setNotificationCategoryAsync</span>(<span class="str">'invite'</span>, []);
+}</code></pre>
+
+    <h4>Reading data in your notification handler</h4>
+    <p>Use <code>data.conversation_id</code> for deep-linking and <code>data.event</code> to distinguish notification types:</p>
+    <pre><code><span class="kw">import</span> * <span class="kw">as</span> Notifications <span class="kw">from</span> <span class="str">'expo-notifications'</span>;
+
+Notifications.<span class="fn">addNotificationResponseReceivedListener</span>((response) => {
+  <span class="kw">const</span> { event, conversation_id, channelId } =
+    response.notification.request.content.data;
+
+  <span class="kw">if</span> (conversation_id) {
+    navigation.<span class="fn">navigate</span>(<span class="str">'Chat'</span>, { conversationId: conversation_id });
+  }
+});</code></pre>
+  </div>
 </section>
 
 <!-- ─── STEP 17.5: NOTIFICATION PREFERENCES ──────────────────────────── -->

package/package.json

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