npm - @antzsoft/chat-core - Versions diffs - 1.0.6 → 1.0.8 - Mend

@antzsoft/chat-core 1.0.6 → 1.0.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/README.md +200 -3
package/dist/index.cjs +98 -7
package/dist/index.cjs.map +1 -1
package/dist/index.d.cts +63 -6
package/dist/index.d.ts +63 -6
package/dist/index.js +97 -7
package/dist/index.js.map +1 -1
package/docs/integration-guide.html +456 -9
package/package.json +1 -1

package/docs/integration-guide.html CHANGED Viewed

@@ -118,6 +118,29 @@ li{margin-bottom:4px;color:#c8d0e0}
 .badge.purple{color:var(--accent2);border-color:rgba(167,139,250,.4);background:rgba(167,139,250,.1)}
 .badge.green{color:var(--green);border-color:rgba(52,211,153,.4);background:rgba(52,211,153,.1)}
 .badge.orange{color:var(--yellow);border-color:rgba(251,191,36,.4);background:rgba(251,191,36,.1)}
+/* ── Section accordion ── */
+section.sec>h2{cursor:pointer;user-select:none;display:flex;align-items:center;justify-content:space-between;gap:10px}
+section.sec>h2 .sec-chevron{font-size:11px;color:var(--muted);transition:transform .22s;margin-left:auto;flex-shrink:0}
+section.sec.collapsed>h2 .sec-chevron{transform:rotate(180deg)}
+section.sec .sec-body{display:block}
+section.sec.collapsed .sec-body{display:none}
+section.sec>h2:hover{color:#fff}
+/* ── H3 sub-accordion inside sections ── */
+.sub-acc{border:1px solid var(--border);border-radius:var(--radius);margin:18px 0}
+.sub-acc-hdr{display:flex;align-items:center;justify-content:space-between;padding:10px 16px;cursor:pointer;user-select:none;background:var(--surface)}
+.sub-acc-hdr:hover{background:var(--surface2)}
+.sub-acc-hdr h3{margin:0;font-size:14px;font-weight:700;color:var(--accent2)}
+.sub-acc-hdr .sub-chev{font-size:10px;color:var(--muted);transition:transform .2s}
+.sub-acc.closed .sub-chev{transform:rotate(180deg)}
+.sub-acc-body{padding:4px 16px 14px}
+.sub-acc.closed .sub-acc-body{display:none}
+/* ── Go-to-top FAB ── */
+#gototop{position:fixed;bottom:28px;right:28px;width:42px;height:42px;border-radius:50%;background:var(--accent);color:#fff;border:none;cursor:pointer;display:flex;align-items:center;justify-content:center;font-size:18px;box-shadow:0 4px 18px rgba(108,140,255,.45);opacity:0;transform:translateY(12px);transition:opacity .22s,transform .22s;pointer-events:none;z-index:300}
+#gototop.show{opacity:1;transform:translateY(0);pointer-events:auto}
+#gototop:hover{background:var(--accent2);box-shadow:0 6px 24px rgba(167,139,250,.5)}
 </style>
 </head>
 <body>
@@ -132,7 +155,7 @@ li{margin-bottom:4px;color:#c8d0e0}
   <div class="section-label">What's New</div>
   <ul>
-    <li><a href="#whats-new">v1.0.6 Release Notes</a></li>
+    <li><a href="#whats-new">v1.0.8 Release Notes</a></li>
   </ul>
   <div class="section-label">Getting Started</div>
@@ -177,6 +200,7 @@ li{margin-bottom:4px;color:#c8d0e0}
   <div class="section-label">Files &amp; Advanced</div>
   <ul>
     <li><a href="#step-upload">16. Upload Files</a></li>
+    <li><a href="#step-compress">16.5 File Compression</a></li>
     <li data-nav="rn-web"><a href="#step-push">17. Push Notifications</a></li>
     <li><a href="#step-prefs">17.5 Notification Preferences</a></li>
     <li><a href="#step-example">18. Full Example</a></li>
@@ -218,12 +242,197 @@ li{margin-bottom:4px;color:#c8d0e0}
   <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.0.6 (current) ── -->
+  <!-- ── v1.0.8 (current) ── -->
+  <div class="wn-version open" id="wn-108">
+    <div class="wn-header" onclick="toggleVersion('wn-108')">
+      <div class="wn-title">
+        <span class="wn-ver">v1.0.8</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-108-1">
+        <div class="wn-item-header" onclick="toggleItem('wn-108-1')">
+          <span class="wn-tag new">New</span>
+          <span class="wn-item-title">File compression — client-side, before upload</span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p>Files are now compressed on the client before the presigned URL is requested. Images are resized and re-encoded (WebP on web, JPEG on RN). Text-based documents (JSON, CSV, XML, YAML, plain text, SVG) are gzip-compressed on web. Audio, video, PDF, ZIP, and Office formats are skipped — they are already compressed.</p>
+          <p>If the compressed result is larger than the original, the original is used automatically. Compression metadata (<code>compressed</code>, <code>originalSize</code>, <code>compressionAlgorithm</code>) is stored on the file record.</p>
+          <table>
+            <tr><th>Platform</th><th>Images</th><th>Text docs</th><th>Default state</th></tr>
+            <tr><td>Web</td><td>WebP via <code>canvas</code></td><td>gzip via <code>CompressionStream</code></td><td>On (no deps)</td></tr>
+            <tr><td>React Native</td><td>JPEG via <code>expo-image-manipulator</code></td><td>Skip</td><td>On when peer dep installed</td></tr>
+            <tr><td>Node.js</td><td>JPEG via <code>sharp</code> (optional)</td><td>gzip via <code>zlib</code></td><td>Off — supply <code>platformCompressFn</code> to enable</td></tr>
+          </table>
+          <p><strong>Action required:</strong> None for web or RN — compression works automatically. Node.js users who want compression must supply a <code>platformCompressFn</code> — see <a href="#step-compress">Step 16.5</a>. To disable: pass <code>compression: { enabled: false }</code>.</p>
+          <p class="wn-ref">→ <a href="#step-compress">Step 16.5 — File Compression</a></p>
+        </div>
+      </div>
+      <div class="wn-item" id="wn-108-2">
+        <div class="wn-item-header" onclick="toggleItem('wn-108-2')">
+          <span class="wn-tag fix">Fix</span>
+          <span class="wn-item-title">Removed members keep read-only access to conversation</span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p>Previously, removing a member from a conversation caused it to disappear from their conversation list entirely. They could no longer read history or see who was in the conversation.</p>
+          <p>Now, removed members:</p>
+          <ul>
+            <li>Still see the conversation in their list</li>
+            <li>Can read message history up to the point of removal</li>
+            <li>Are kicked from the socket room immediately — they receive no new real-time events</li>
+            <li>Cannot send, react, type, edit, or delete — <code>validateWriteAccess</code> blocks all write operations</li>
+          </ul>
+          <p>This is implemented via a new <code>isHidden</code> field on the <code>Participant</code> subdocument (schema change, server only). The conversation list filter now shows conversations where the user is not hidden, regardless of <code>isActive</code>.</p>
+          <p><strong>Action required:</strong> None. Behavior change is entirely server-side. SDK types and API calls are unchanged.</p>
+        </div>
+      </div>
+      <div class="wn-item" id="wn-108-3">
+        <div class="wn-item-header" onclick="toggleItem('wn-108-3')">
+          <span class="wn-tag fix">Fix</span>
+          <span class="wn-item-title">Admin delete is now hide-only — other participants unaffected</span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p>Previously, when an admin called <code>deleteConversation</code> it set <code>conversation.isActive = false</code>, making it disappear for <em>all</em> participants. This was wrong — only the admin who deleted it should lose access.</p>
+          <p>Now, <code>deleteConversation</code> sets <code>participant.isHidden = true</code> for the requesting user only. All other participants continue to see the conversation normally.</p>
+          <p><strong>Action required:</strong> None. Server-side change only.</p>
+        </div>
+      </div>
+      <div class="wn-item" id="wn-108-4">
+        <div class="wn-item-header" onclick="toggleItem('wn-108-4')">
+          <span class="wn-tag fix">Fix</span>
+          <span class="wn-item-title"><code>lastMessage.status</code> stuck as <code>deleted</code> after new messages</span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p>When a message was deleted, <code>lastMessage.status</code> on the conversation was set to <code>'deleted'</code>. Sending a new message afterwards never reset it — so the conversation list kept showing <code>deleted</code> as the last message state indefinitely.</p>
+          <p>Root cause: two separate code paths update <code>lastMessage</code> (REST and WebSocket) and neither was explicitly setting <code>status: 'active'</code> when writing a new message. Fixed in both paths.</p>
+          <p><strong>Action required:</strong> None. Server-side fix only.</p>
+        </div>
+      </div>
+      <div class="wn-item" id="wn-108-5">
+        <div class="wn-item-header" onclick="toggleItem('wn-108-5')">
+          <span class="wn-tag new">New</span>
+          <span class="wn-item-title"><code>duration</code> field in <code>SendMessageAttachment</code> for audio/video</span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p><code>SendMessageAttachment</code> now accepts an optional <code>duration</code> field (integer, seconds). Pass it when sending audio or video so receivers can render a player UI — e.g. show <code>0:30</code> before the file is loaded. The server stores and echoes this value in <code>new_message</code> and all message list responses.</p>
+          <pre><code><span class="kw">await</span> socketEmit.<span class="fn">sendMessage</span>({
+  conversationId, <span class="at">tempId</span>: <span class="fn">uuid</span>(),
+  <span class="at">attachments</span>: [{
+    <span class="at">fileId</span>: f.id, <span class="at">type</span>: <span class="str">'audio'</span>, <span class="at">url</span>: f.url,
+    <span class="at">filename</span>: f.filename, <span class="at">mimeType</span>: f.mimeType, <span class="at">size</span>: f.size,
+    <span class="at">duration</span>: recordingSeconds,  <span class="cm">// ← pass this</span>
+  }],
+});</code></pre>
+          <p><strong>Action required (React Native):</strong> Always pass <code>duration</code> when sending audio or video. Omitting it on RN causes receivers to get <code>undefined</code> duration, which crashes native audio player libraries that require an explicit value to initialize. Web is unaffected — browsers read duration natively from the audio stream.</p>
+          <p><strong>Action required (Web):</strong> None — recommended to pass for better UX (shows duration before file loads) but not required.</p>
+          <p class="wn-ref">→ <a href="#step-send">Step 9 — Sending Messages</a></p>
+        </div>
+      </div>
+    </div>
+  </div>
+  <!-- ── v1.0.7 ── -->
+  <div class="wn-version open" id="wn-107">
+    <div class="wn-header" onclick="toggleVersion('wn-107')">
+      <div class="wn-title">
+        <span class="wn-ver">v1.0.7</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-107-1">
+        <div class="wn-item-header" onclick="toggleItem('wn-107-1')">
+          <span class="wn-tag new">New</span>
+          <span class="wn-item-title"><code>deliveredTo</code> per-user delivery timestamps on all messages</span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p>All message responses (REST list, single fetch, send, edit, pin, star, search) now include a <code>deliveredTo</code> array alongside <code>readBy</code>, giving you per-user delivery timestamps for "message info" panels.</p>
+          <pre><code><span class="cm">// Message object — new fields</span>
+{
+  <span class="at">readBy</span>: [{ <span class="at">userId</span>: <span class="str">'user_2'</span>, <span class="at">readAt</span>: <span class="str">'2026-05-18T10:00:00.000Z'</span> }],
+  <span class="at">deliveredTo</span>: [{ <span class="at">userId</span>: <span class="str">'user_2'</span>, <span class="at">deliveredAt</span>: <span class="str">'2026-05-18T09:59:00.000Z'</span> }],
+}</code></pre>
+          <p>The <code>message_delivered</code> socket event payload has also changed — <code>deliveredTo</code> is now <code>Array&lt;{ userId, deliveredAt }&gt;</code> (top-level <code>deliveredAt</code> removed).</p>
+          <p><strong>Breaking change:</strong> <code>Message.readBy</code> type changed from <code>string[]</code> to <code>Array&lt;{ userId: string; readAt: string }&gt;</code>. Update any code reading <code>readBy</code> entries as plain strings.</p>
+          <p class="wn-ref">→ <a href="#step-realtime">Step 10 — Real-time Events</a> (<code>message_delivered</code> event)</p>
+        </div>
+      </div>
+      <div class="wn-item" id="wn-107-2">
+        <div class="wn-item-header" onclick="toggleItem('wn-107-2')">
+          <span class="wn-tag new">New</span>
+          <span class="wn-item-title">Audio attachment support for <code>.m4a</code> / <code>audio/x-m4a</code></span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p>The server now accepts <code>audio/m4a</code> and <code>audio/x-m4a</code> MIME types for audio attachments. Previously only <code>audio/mpeg</code>, <code>audio/ogg</code>, and <code>audio/wav</code> were accepted — uploads of <code>.m4a</code> files returned a <code>400</code> unsupported type error.</p>
+          <p><strong>Action required:</strong> No SDK change needed. If you were filtering <code>.m4a</code> files out in the client before upload, remove that restriction.</p>
+        </div>
+      </div>
+      <div class="wn-item" id="wn-107-3">
+        <div class="wn-item-header" onclick="toggleItem('wn-107-3')">
+          <span class="wn-tag new">New</span>
+          <span class="wn-item-title">Participant filter on <code>getMembers</code></span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p><code>getMembers</code> now accepts a <code>filter</code> parameter to control which participants are returned.</p>
+          <pre><code><span class="cm">// active only (default — same as before)</span>
+<span class="kw">await</span> conversationsApi.<span class="fn">getMembers</span>(conversationId);
+<span class="cm">// all participants including removed ones</span>
+<span class="kw">await</span> conversationsApi.<span class="fn">getMembers</span>(conversationId, { <span class="at">filter</span>: <span class="str">'all'</span> });
+<span class="cm">// only removed participants</span>
+<span class="kw">await</span> conversationsApi.<span class="fn">getMembers</span>(conversationId, { <span class="at">filter</span>: <span class="str">'deleted'</span> });</code></pre>
+          <p>Default is <code>'active'</code> — no behaviour change for existing callers.</p>
+          <p class="wn-ref">→ <a href="#step-convs">Step 6 — Conversations</a> (participants section)</p>
+        </div>
+      </div>
+      <div class="wn-item" id="wn-107-4">
+        <div class="wn-item-header" onclick="toggleItem('wn-107-4')">
+          <span class="wn-tag new">New</span>
+          <span class="wn-item-title">Message character limit — 10,000</span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p>Text message content is now capped at <strong>10,000 characters</strong>. Sending a message that exceeds this limit returns a <code>400</code> validation error.</p>
+          <p><strong>Action required:</strong> Add client-side length validation before send to give users immediate feedback rather than waiting for a server error.</p>
+          <pre><code><span class="kw">const</span> MAX_LENGTH = <span class="num">10000</span>;
+<span class="kw">if</span> (text.length > MAX_LENGTH) {
+  <span class="fn">showError</span>(<span class="str">`Message too long (${text.length}/${MAX_LENGTH})`</span>);
+  <span class="kw">return</span>;
+}</code></pre>
+        </div>
+      </div>
+    </div><!-- /.wn-body -->
+  </div><!-- /.wn-version -->
+  <!-- ── v1.0.6 ── -->
   <div class="wn-version" id="wn-106">
     <div class="wn-header" onclick="toggleVersion('wn-106')">
       <div class="wn-title">
         <span class="wn-ver">v1.0.6</span>
-        <span class="wn-badge current">Current</span>
         <span class="wn-date">May 2026</span>
       </div>
       <span class="wn-chevron">▲</span>
@@ -1320,7 +1529,13 @@ client.socket.<span class="fn">on</span>(<span class="str">'conversation_created
 <span class="kw">const</span> attachments = successful.<span class="fn">map</span>(f => ({
   <span class="at">fileId</span>: f.id, <span class="at">type</span>: f.type, <span class="at">url</span>: f.url, <span class="at">filename</span>: f.filename, <span class="at">mimeType</span>: f.mimeType, <span class="at">size</span>: f.size,
 }));
-<span class="kw">await</span> socketEmit.<span class="fn">sendMessage</span>({ conversationId, <span class="at">tempId</span>: <span class="fn">uuid</span>(), attachments });</code></pre>
+<span class="kw">await</span> socketEmit.<span class="fn">sendMessage</span>({ conversationId, <span class="at">tempId</span>: <span class="fn">uuid</span>(), attachments });
+<span class="cm">// Audio/video — always pass duration (seconds) so receivers can render a player UI</span>
+<span class="kw">await</span> socketEmit.<span class="fn">sendMessage</span>({
+  conversationId, <span class="at">tempId</span>: <span class="fn">uuid</span>(),
+  <span class="at">attachments</span>: [{ <span class="at">fileId</span>: f.id, <span class="at">type</span>: <span class="str">'audio'</span>, <span class="at">url</span>: f.url, <span class="at">filename</span>: f.filename, <span class="at">mimeType</span>: f.mimeType, <span class="at">size</span>: f.size, <span class="at">duration</span>: recordingSeconds }],
+});</code></pre>
 </section>
 <!-- ─── STEP 10: REAL-TIME ─────────────────────────────────────────────── -->
@@ -1442,12 +1657,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</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>
       </tr>
       <tr>
         <td><code>'messages_delivered'</code></td>
-        <td>Batch delivery catch-up when a recipient comes online</td>
+        <td>Batch delivery catch-up when a recipient comes online. Payload: <code>{ conversationId, messageIds[], deliveredTo: string, deliveredAt }</code></td>
         <td><strong>Chat detail screen</strong> — add on mount, remove on unmount.</td>
       </tr>
       <tr>
@@ -1781,6 +1996,8 @@ socket?.<span class="fn">on</span>(<span class="str">'read_receipt'</span>, ({ c
   <pre><code><span class="kw">const</span> attachments = successful.<span class="fn">map</span>(f => ({
   <span class="at">fileId</span>: f.id, <span class="at">type</span>: f.type, <span class="at">url</span>: f.url,
   <span class="at">filename</span>: f.filename, <span class="at">mimeType</span>: f.mimeType, <span class="at">size</span>: f.size,
+  <span class="cm">// For audio/video include duration (seconds) — required for receiver player UI</span>
+  ...(f.type === <span class="str">'audio'</span> || f.type === <span class="str">'video'</span> ? { <span class="at">duration</span>: knownDurationSeconds } : {}),
 }));
 <span class="kw">await</span> socketEmit.<span class="fn">sendMessage</span>({ conversationId, <span class="at">tempId</span>: <span class="fn">uuid</span>(), attachments });</code></pre>
@@ -1797,6 +2014,156 @@ socket?.<span class="fn">on</span>(<span class="str">'read_receipt'</span>, ({ c
 });</code></pre>
 </section>
+<!-- ─── STEP 16.5: COMPRESSION ───────────────────────────────────────── -->
+<section id="step-compress">
+  <h2><span class="step">STEP 16.5</span> File Compression</h2>
+  <p>Compression runs <strong>client-side before upload</strong> — the server receives the compressed file with the correct size and MIME type. It is optional and fully backward compatible. Omit <code>platformCompressFn</code> to keep the original behavior.</p>
+  <!-- ── REACT NATIVE ── -->
+  <div data-p="rn">
+    <div class="callout tip"><strong>Zero config for Expo</strong> Install <code>expo-image-manipulator</code> and compression works automatically. No other changes needed.</div>
+    <pre><code>npx expo install expo-image-manipulator</code></pre>
+    <p>Without <code>expo-image-manipulator</code> the SDK skips compression silently — files upload as-is.</p>
+    <h3>Default behavior</h3>
+    <pre><code><span class="cm">// AntzChatNavigator / AntzChatProvider — compression on by default, nothing to add</span>
+&lt;AntzChatNavigator config={{ <span class="at">apiUrl</span>: <span class="str">'...'</span> }} /&gt;
+<span class="cm">// AntzChatClient (headless) — pass rnCompressFn explicitly</span>
+<span class="kw">import</span> { AntzChatClient, rnUploadFn, rnPersistStorage, rnCompressFn } <span class="kw">from</span> <span class="str">'@antzsoft/chat-rn-sdk'</span>;
+<span class="kw">const</span> client = <span class="kw">new</span> <span class="fn">AntzChatClient</span>({
+  <span class="at">apiUrl</span>: <span class="str">'https://api.example.com/api/v1'</span>,
+  <span class="at">authToken</span>: token,
+  <span class="at">platformUploadFn</span>: rnUploadFn,
+  <span class="at">persistStorage</span>: rnPersistStorage,
+  <span class="at">platformCompressFn</span>: rnCompressFn,   <span class="cm">// add this for headless usage</span>
+});</code></pre>
+    <h3>Strategy by file type</h3>
+    <table>
+      <tr><th>File type</th><th>Strategy</th><th>Algorithm</th><th>Requires</th></tr>
+      <tr><td>JPEG, PNG, GIF, BMP, TIFF, WebP</td><td>Resize + re-encode</td><td>JPEG</td><td><code>expo-image-manipulator</code></td></tr>
+      <tr><td>Video, audio, PDF, ZIP, Office</td><td>Skip</td><td>—</td><td>—</td></tr>
+      <tr><td>Text, JSON, CSV, XML, YAML</td><td>Skip on RN</td><td>—</td><td>No <code>CompressionStream</code> in RN JS engine</td></tr>
+    </table>
+    <h3>Tune or disable</h3>
+    <pre><code><span class="cm">// Tune</span>
+&lt;AntzChatNavigator config={{ ..., <span class="at">compression</span>: { <span class="at">imageQuality</span>: <span class="num">0.75</span>, <span class="at">imageMaxDimension</span>: <span class="num">1280</span> } }} /&gt;
+<span class="cm">// Disable entirely</span>
+&lt;AntzChatNavigator config={{ ..., <span class="at">compression</span>: { <span class="at">enabled</span>: <span class="kw">false</span> } }} /&gt;</code></pre>
+  </div>
+  <!-- ── WEB ── -->
+  <div data-p="web">
+    <div class="callout tip"><strong>Zero config on Web</strong> <code>webCompressFn</code> is pre-wired automatically in <code>AntzChatProvider</code> / <code>AntzChat</code>. No extra packages — uses browser-native <code>canvas</code> and <code>CompressionStream</code>.</div>
+    <h3>Default behavior</h3>
+    <pre><code><span class="cm">// AntzChat / AntzChatProvider — compression on by default, nothing to add</span>
+&lt;AntzChat config={{ <span class="at">apiUrl</span>: <span class="str">'...'</span>, <span class="at">authToken</span>: <span class="str">'...'</span> }} /&gt;
+<span class="cm">// AntzChatClient (headless) — pass webCompressFn explicitly</span>
+<span class="kw">import</span> { AntzChatClient } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+<span class="kw">import</span> { webUploadFn, webPersistStorage, webCompressFn } <span class="kw">from</span> <span class="str">'@antzsoft/chat-web-sdk'</span>;
+<span class="kw">const</span> client = <span class="kw">new</span> <span class="fn">AntzChatClient</span>({
+  <span class="at">apiUrl</span>: <span class="str">'https://api.example.com/api/v1'</span>,
+  <span class="at">authToken</span>: token,
+  <span class="at">platformUploadFn</span>: webUploadFn,
+  <span class="at">persistStorage</span>: webPersistStorage,
+  <span class="at">platformCompressFn</span>: webCompressFn,   <span class="cm">// add this for headless usage</span>
+});</code></pre>
+    <h3>Strategy by file type</h3>
+    <table>
+      <tr><th>File type</th><th>Strategy</th><th>Algorithm</th><th>API used</th></tr>
+      <tr><td>JPEG, PNG, GIF, BMP, TIFF, WebP</td><td>Resize + re-encode</td><td>WebP</td><td><code>canvas.toBlob('image/webp')</code></td></tr>
+      <tr><td>SVG, JSON, CSV, plain text, XML, YAML, RTF, Markdown</td><td>Compress bytes</td><td>gzip</td><td><code>CompressionStream('gzip')</code></td></tr>
+      <tr><td>Video, audio, PDF, ZIP, Office</td><td>Skip</td><td>—</td><td>Already compressed</td></tr>
+    </table>
+    <h3>Tune or disable</h3>
+    <pre><code><span class="cm">// Tune</span>
+&lt;AntzChat config={{ ..., <span class="at">compression</span>: { <span class="at">imageQuality</span>: <span class="num">0.75</span>, <span class="at">imageMaxDimension</span>: <span class="num">1280</span>, <span class="at">compressDocuments</span>: <span class="kw">false</span> } }} /&gt;
+<span class="cm">// Disable entirely</span>
+&lt;AntzChat config={{ ..., <span class="at">compression</span>: { <span class="at">enabled</span>: <span class="kw">false</span> } }} /&gt;</code></pre>
+  </div>
+  <!-- ── NODE.JS ── -->
+  <div data-p="node">
+    <div class="callout info"><strong>Node.js</strong> No compressor is provided by default. Supply your own using <code>sharp</code> (images) and Node's built-in <code>zlib</code> (text/docs). Omit <code>platformCompressFn</code> to skip compression entirely.</div>
+    <h3>Install optional dep</h3>
+    <pre><code>npm install sharp   <span class="cm"># optional — only needed for image compression</span></code></pre>
+    <h3>Implementation</h3>
+    <pre><code><span class="kw">import</span> sharp <span class="kw">from</span> <span class="str">'sharp'</span>;
+<span class="kw">import</span> zlib <span class="kw">from</span> <span class="str">'zlib'</span>;
+<span class="kw">import</span> { promisify } <span class="kw">from</span> <span class="str">'util'</span>;
+<span class="kw">import</span> { writeFile, readFile } <span class="kw">from</span> <span class="str">'fs/promises'</span>;
+<span class="kw">import</span> { join } <span class="kw">from</span> <span class="str">'path'</span>;
+<span class="kw">import</span> { tmpdir } <span class="kw">from</span> <span class="str">'os'</span>;
+<span class="kw">import</span> { <span class="tp">PlatformCompressFn</span> } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+<span class="kw">import</span> { getCompressionStrategy } <span class="kw">from</span> <span class="str">'@antzsoft/chat-core'</span>;
+<span class="kw">const</span> gzip = <span class="fn">promisify</span>(zlib.gzip);
+<span class="kw">export const</span> nodeCompressFn: <span class="tp">PlatformCompressFn</span> = <span class="kw">async</span> (file, options) => {
+  <span class="kw">const</span> noop = { ...file, <span class="at">originalSize</span>: file.size, <span class="at">compressed</span>: <span class="kw">false</span>, <span class="at">compressionAlgorithm</span>: <span class="str">'none'</span> <span class="kw">as const</span> };
+  <span class="kw">const</span> strategy = <span class="fn">getCompressionStrategy</span>(file.type, options);
+  <span class="kw">if</span> (strategy === <span class="str">'image'</span>) {
+    <span class="kw">const</span> buf = <span class="kw">await</span> sharp(file.uri)
+      .<span class="fn">resize</span>({ <span class="at">width</span>: options.imageMaxDimension, <span class="at">height</span>: options.imageMaxDimension, <span class="at">fit</span>: <span class="str">'inside'</span>, <span class="at">withoutEnlargement</span>: <span class="kw">true</span> })
+      .<span class="fn">jpeg</span>({ <span class="at">quality</span>: <span class="fn">Math.round</span>(options.imageQuality * <span class="num">100</span>) })
+      .<span class="fn">toBuffer</span>();
+    <span class="kw">if</span> (buf.length >= file.size) <span class="kw">return</span> noop;
+    <span class="kw">const</span> tmp = <span class="fn">join</span>(<span class="fn">tmpdir</span>(), <span class="str">`</span><span class="num">${Date.now()}</span><span class="str">.jpg`</span>);
+    <span class="kw">await</span> <span class="fn">writeFile</span>(tmp, buf);
+    <span class="kw">return</span> { <span class="at">uri</span>: tmp, <span class="at">name</span>: file.name.<span class="fn">replace</span>(<span class="str">/\.[^.]+$/</span>, <span class="str">'.jpg'</span>), <span class="at">type</span>: <span class="str">'image/jpeg'</span>, <span class="at">size</span>: buf.length, <span class="at">originalSize</span>: file.size, <span class="at">compressed</span>: <span class="kw">true</span>, <span class="at">compressionAlgorithm</span>: <span class="str">'jpeg'</span> <span class="kw">as const</span> };
+  }
+  <span class="kw">if</span> (strategy === <span class="str">'gzip'</span>) {
+    <span class="kw">const</span> input = <span class="kw">await</span> <span class="fn">readFile</span>(file.uri);
+    <span class="kw">const</span> compressed = <span class="kw">await</span> <span class="fn">gzip</span>(input);
+    <span class="kw">if</span> (compressed.length >= file.size) <span class="kw">return</span> noop;
+    <span class="kw">const</span> tmp = <span class="fn">join</span>(<span class="fn">tmpdir</span>(), <span class="str">`</span><span class="num">${Date.now()}</span><span class="str">.gz`</span>);
+    <span class="kw">await</span> <span class="fn">writeFile</span>(tmp, compressed);
+    <span class="kw">return</span> { <span class="at">uri</span>: tmp, <span class="at">name</span>: file.name + <span class="str">'.gz'</span>, <span class="at">type</span>: file.type, <span class="at">size</span>: compressed.length, <span class="at">originalSize</span>: file.size, <span class="at">compressed</span>: <span class="kw">true</span>, <span class="at">compressionAlgorithm</span>: <span class="str">'gzip'</span> <span class="kw">as const</span> };
+  }
+  <span class="kw">return</span> noop;
+};</code></pre>
+    <h3>Wire it in</h3>
+    <pre><code><span class="kw">const</span> client = <span class="kw">new</span> <span class="fn">AntzChatClient</span>({
+  <span class="at">apiUrl</span>: <span class="str">'https://api.example.com/api/v1'</span>,
+  <span class="at">authToken</span>: process.env.<span class="at">AUTH_TOKEN</span>,
+  <span class="at">platformUploadFn</span>: myNodeUploadFn,
+  <span class="at">persistStorage</span>: myStorage,
+  <span class="at">platformCompressFn</span>: nodeCompressFn,
+  <span class="at">compression</span>: { <span class="at">imageQuality</span>: <span class="num">0.85</span>, <span class="at">imageMaxDimension</span>: <span class="num">1920</span> },
+});</code></pre>
+  </div>
+  <!-- ── SHARED: config reference ── -->
+  <h3>CompressionConfig reference</h3>
+  <table>
+    <tr><th>Field</th><th>Type</th><th>Default</th><th>Description</th></tr>
+    <tr><td><code>enabled</code></td><td><code>boolean</code></td><td><code>true</code> when <code>platformCompressFn</code> provided</td><td>Master switch</td></tr>
+    <tr><td><code>imageQuality</code></td><td><code>number</code> (0–1)</td><td><code>0.85</code></td><td>Encode quality for images</td></tr>
+    <tr><td><code>imageMaxDimension</code></td><td><code>number</code></td><td><code>1920</code></td><td>Longest side cap in px before encoding</td></tr>
+    <tr><td><code>compressDocuments</code></td><td><code>boolean</code></td><td><code>true</code></td><td>gzip text/JSON/CSV/XML/YAML/SVG/RTF (web only)</td></tr>
+  </table>
+  <div class="callout info"><strong>Automatic fallback</strong> If the compressed result is larger than the original, the SDK uploads the original automatically — no extra code needed.</div>
+</section>
 <!-- ─── STEP 17: PUSH (RN + WEB only) ────────────────────────────────── -->
 <section id="step-push" data-p="rn web">
   <h2><span class="step">STEP 17</span> Push Notifications</h2>
@@ -2546,6 +2913,9 @@ console.<span class="fn">log</span>(<span class="str">`${summary.totalUnread} un
 </main>
+<!-- ── Go-to-top FAB ── -->
+<button id="gototop" onclick="window.scrollTo({top:0,behavior:'smooth'})" title="Back to top">↑</button>
 <script>
 // ── State ────────────────────────────────────────────────────────────────
 let _platform = 'rn';
@@ -2632,10 +3002,87 @@ function toggleItem(id) {
   document.getElementById(id).classList.toggle('open');
 }
-// ── Progress bar ──────────────────────────────────────────────────────────
+// ── Progress bar + go-to-top FAB ─────────────────────────────────────────
+const _fab = document.getElementById('gototop');
 window.addEventListener('scroll', () => {
-  const el = document.getElementById('prog');
-  el.style.width = (window.scrollY / (document.body.scrollHeight - window.innerHeight) * 100) + '%';
+  const ratio = window.scrollY / (document.body.scrollHeight - window.innerHeight);
+  document.getElementById('prog').style.width = (ratio * 100) + '%';
+  _fab.classList.toggle('show', window.scrollY > 300);
+});
+// ── Section accordion ─────────────────────────────────────────────────────
+// Make every <section> (except #whats-new which has its own accordion) collapsible.
+// Wrap content below h2 in a .sec-body div and add a chevron to h2.
+document.querySelectorAll('section[id]').forEach(sec => {
+  if (sec.id === 'whats-new') return; // already has its own accordion
+  sec.classList.add('sec');
+  const h2 = sec.querySelector(':scope > h2');
+  if (!h2) return;
+  // Add chevron to h2
+  const chev = document.createElement('span');
+  chev.className = 'sec-chevron';
+  chev.textContent = '▲';
+  h2.appendChild(chev);
+  // Wrap all siblings after h2 into .sec-body
+  const body = document.createElement('div');
+  body.className = 'sec-body';
+  const siblings = [];
+  let node = h2.nextSibling;
+  while (node) { siblings.push(node); node = node.nextSibling; }
+  siblings.forEach(n => body.appendChild(n));
+  sec.appendChild(body);
+  // Toggle on h2 click
+  h2.addEventListener('click', () => sec.classList.toggle('collapsed'));
+});
+// ── H3 sub-accordion ─────────────────────────────────────────────────────
+// Wrap each h3 + its following siblings (until next h3/h2/section end) into
+// a collapsible .sub-acc block. Only applied inside .sec-body.
+document.querySelectorAll('.sec-body').forEach(body => {
+  const h3s = Array.from(body.querySelectorAll(':scope > h3'));
+  h3s.forEach(h3 => {
+    // Collect nodes that belong to this h3 (until next h3 or end)
+    const nodes = [];
+    let n = h3.nextSibling;
+    while (n && !(n.nodeType === 1 && (n.tagName === 'H3' || n.tagName === 'H2'))) {
+      nodes.push(n);
+      n = n.nextSibling;
+    }
+    if (!nodes.length) return; // h3 with no content — skip
+    // Build accordion shell
+    const acc = document.createElement('div');
+    acc.className = 'sub-acc';
+    const hdr = document.createElement('div');
+    hdr.className = 'sub-acc-hdr';
+    const title = document.createElement('h3');
+    title.innerHTML = h3.innerHTML;
+    const chev = document.createElement('span');
+    chev.className = 'sub-chev';
+    chev.textContent = '▲';
+    hdr.appendChild(title);
+    hdr.appendChild(chev);
+    const accBody = document.createElement('div');
+    accBody.className = 'sub-acc-body';
+    nodes.forEach(nd => accBody.appendChild(nd));
+    acc.appendChild(hdr);
+    acc.appendChild(accBody);
+    hdr.addEventListener('click', () => acc.classList.toggle('closed'));
+    // Replace original h3 with the accordion
+    h3.replaceWith(acc);
+  });
 });
 // ── Sidebar active link ───────────────────────────────────────────────────

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@antzsoft/chat-core",
-  "version": "1.0.6",
+  "version": "1.0.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",