@antzsoft/chat-core 1.0.6 → 1.0.8

package/README.md

@@ -1122,6 +1122,166 @@ result.failed.forEach((f) => console.error('Failed:', f.filename, f.error));
 
 ---
 
+## File Compression
+
+Compression is optional and fully backward compatible. It runs entirely client-side before the upload starts — the server receives the already-compressed file with the correct size and MIME type.
+
+### How it works
+
+When `platformCompressFn` is provided and `compression.enabled` is `true` (the default when a compressor is supplied), `uploadBatch` compresses each file before requesting a presigned URL:
+
+1. Determine strategy per file (`image` → WebP/JPEG resize+encode, `gzip` → text/doc compression, `skip` → no-op)
+2. Run `platformCompressFn(file, compressionConfig)` — returns a `CompressedFile`
+3. If compressed result is **larger** than the original, the original is used instead (automatic fallback)
+4. Request presigned URL with the compressed size and MIME type
+5. Upload the compressed bytes
+6. Store `metadata.compressed`, `metadata.originalSize`, `metadata.compressionAlgorithm` on the file record
+
+### Strategy by file type
+
+| File type | Strategy | Algorithm | Notes |
+|-----------|----------|-----------|-------|
+| `image/jpeg`, `image/png`, `image/gif`, `image/bmp`, `image/tiff` | `image` | `webp` (web) / `jpeg` (RN) | Resize to `imageMaxDimension` first |
+| `image/webp` | `image` | `webp` | Re-encode at target quality |
+| `image/svg+xml` | `gzip` | `gzip` | SVG is XML text |
+| `text/plain`, `text/csv`, `text/markdown`, `application/json`, `text/xml`, `application/xml`, `text/yaml`, `application/rtf` | `gzip` | `gzip` | Only when `compressDocuments: true` |
+| `video/*`, `audio/*`, `application/pdf`, `application/zip`, Office formats (`.docx`, `.xlsx`, `.pptx`) | `skip` | `none` | Already compressed |
+
+### Configuration
+
+Pass `compression` and `platformCompressFn` in the config:
+
+```typescript
+import { AntzChatClient } from '@antzsoft/chat-core';
+
+const client = new AntzChatClient({
+  apiUrl: 'https://api.yourapp.com/api/v1',
+  authToken: 'your-token',
+  platformUploadFn: myUploadFn,
+  persistStorage: myStorage,
+
+  // Optional — omit to disable compression entirely
+  platformCompressFn: myCompressFn,
+  compression: {
+    enabled: true,             // default: true when platformCompressFn is provided
+    imageQuality: 0.85,        // 0–1, default: 0.85
+    imageMaxDimension: 1920,   // longest side cap in px, default: 1920
+    compressDocuments: true,   // gzip text/json/csv/xml/yaml, default: true
+  },
+});
+```
+
+### Opt out completely
+
+```typescript
+// Disable compression — files upload as-is
+const client = new AntzChatClient({
+  ...
+  compression: { enabled: false },
+});
+```
+
+### Implementing `platformCompressFn` for Node.js
+
+The web and RN SDKs provide their own compressors automatically. For Node.js / `AntzChatClient` direct usage, implement it with `sharp` and `zlib`:
+
+```typescript
+import sharp from 'sharp';
+import zlib from 'zlib';
+import { promisify } from 'util';
+import type { PlatformCompressFn } from '@antzsoft/chat-core';
+import { getCompressionStrategy } from '@antzsoft/chat-core';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as os from 'os';
+
+const gzip = promisify(zlib.gzip);
+
+export const nodeCompressFn: PlatformCompressFn = async (file, options) => {
+  const strategy = getCompressionStrategy(file.type, options);
+  const noop = { ...file, originalSize: file.size, compressed: false, compressionAlgorithm: 'none' as const };
+
+  if (strategy === 'image') {
+    try {
+      const buffer = await sharp(file.uri)
+        .resize({ width: options.imageMaxDimension, height: options.imageMaxDimension, fit: 'inside', withoutEnlargement: true })
+        .jpeg({ quality: Math.round(options.imageQuality * 100) })
+        .toBuffer();
+
+      if (buffer.length >= file.size) return noop;
+
+      const tmpPath = path.join(os.tmpdir(), `${Date.now()}.jpg`);
+      await fs.writeFile(tmpPath, buffer);
+
+      return {
+        uri: tmpPath,
+        name: file.name.replace(/\.[^.]+$/, '.jpg'),
+        type: 'image/jpeg',
+        size: buffer.length,
+        originalSize: file.size,
+        compressed: true,
+        compressionAlgorithm: 'jpeg' as const,
+      };
+    } catch {
+      return noop;
+    }
+  }
+
+  if (strategy === 'gzip') {
+    try {
+      const input = await fs.readFile(file.uri);
+      const compressed = await gzip(input);
+
+      if (compressed.length >= file.size) return noop;
+
+      const tmpPath = path.join(os.tmpdir(), `${Date.now()}.gz`);
+      await fs.writeFile(tmpPath, compressed);
+
+      return {
+        uri: tmpPath,
+        name: file.name + '.gz',
+        type: file.type,
+        size: compressed.length,
+        originalSize: file.size,
+        compressed: true,
+        compressionAlgorithm: 'gzip' as const,
+      };
+    } catch {
+      return noop;
+    }
+  }
+
+  return noop;
+};
+```
+
+Then pass it to the client:
+
+```typescript
+const client = new AntzChatClient({
+  apiUrl: 'https://api.yourapp.com/api/v1',
+  authToken: process.env.AUTH_TOKEN,
+  platformUploadFn: myUploadFn,
+  persistStorage: myStorage,
+  platformCompressFn: nodeCompressFn,
+  compression: { imageQuality: 0.85, imageMaxDimension: 1920 },
+});
+```
+
+### `CompressedFile` type
+
+```typescript
+interface CompressedFile extends UploadableFile {
+  originalSize: number;
+  compressed: boolean;
+  compressionAlgorithm: 'webp' | 'jpeg' | 'gzip' | 'none';
+}
+```
+
+The `CompressedFile` extends `UploadableFile` — it is a drop-in replacement everywhere `UploadableFile` is accepted.
+
+---
+
 ### Devices API (`devicesApi`)
 
 Used for push notification token registration. The SDK does not call this automatically — the host app is responsible for obtaining the device token from the OS and registering it.
@@ -1559,7 +1719,7 @@ Subscribe using `client.socket.on(event, handler)` (headless) or directly on the
 | `read_receipt` | `ReadReceiptEvent` | A user read messages in a conversation. | **Chat detail screen** (to update tick marks) + **app root** (to clear your own unread count when read on another device). |
 | `unread_count_changed` | `{ conversationId: string; unreadCount: number; userId: string }` | Your unread count changed for a conversation (fired to your personal room on all devices). | **App root / conversation list screen** — keep alive as long as the list is rendered. |
 | `message_ack` | `MessageAckEvent` | Server confirmation for a message you sent via socket (maps tempId to the real messageId). | **Chat detail screen** — add on mount, remove on unmount. |
-| `message_delivered` | `{ messageId: string; conversationId: string; deliveredAt: string }` | A single message you sent was delivered to all active recipients. | **Chat detail screen** — add on mount, remove on unmount. |
+| `message_delivered` | `MessageDeliveredEvent` | A single message you sent was delivered to all active recipients. | **Chat detail screen** — add on mount, remove on unmount. |
 | `messages_delivered` | `MessagesDeliveredEvent` | Batch delivery catch-up — fired when a recipient comes online and your pending messages are delivered. | **Chat detail screen** — add on mount, remove on unmount. |
 | `conversation_created` | `Conversation` | A new conversation was created (or you were added to one). | **App root** — call `joinRoom` here for the new conversation. Keep for full session. |
 | `conversation_updated` | `Conversation` | A conversation's last message or metadata changed — use this to update the conversation list. | **App root** — keep for full session. The server emits this for every message across all conversations; a global listener keeps the in-memory conversation list and unread badge always in sync. |
@@ -1854,7 +2014,8 @@ interface Message {
   sentAt: string;
   createdAt: string;
   sender?: User;
-  readBy?: string[];
+  readBy?: Array<{ userId: string; readAt: string }>;
+  deliveredTo?: Array<{ userId: string; deliveredAt: string }>;
   isEncrypted?: boolean;
   encryptionMode?: 'none' | 'server' | 'e2ee';
   encryptedContent?: EncryptedContent;
@@ -1992,6 +2153,7 @@ interface SendMessageAttachment {
   filename: string;
   mimeType: string;
   size: number;
+  duration?: number;  // seconds — required for audio/video so receivers can render a player UI
 }
 ```
 
@@ -2053,10 +2215,16 @@ interface MessageAckEvent {
   status: MessageStatus;
 }
 
+interface MessageDeliveredEvent {
+  messageId: string;
+  conversationId: string;
+  deliveredTo: Array<{ userId: string; deliveredAt: string }>;
+}
+
 interface MessagesDeliveredEvent {
   conversationId: string;
   messageIds: string[];
-  deliveredTo: string;
+  deliveredTo: string;   // single userId (batch catch-up per recipient)
   deliveredAt: string;
 }
 ```
@@ -2180,6 +2348,35 @@ document.querySelectorAll('[data-conv-id]').forEach((el) => {
 
 ---
 
+## Changelog
+
+### v1.0.8
+- **`duration` field in `SendMessageAttachment`** — Pass `duration` (seconds) when sending audio or video. Server now stores and returns it in `new_message` and message list responses. **Action required (RN):** Omitting it on React Native can crash native audio player libraries on the receiver side; always pass it for audio/video. Web is unaffected.
+- **File compression** — `uploadBatch` now accepts optional `platformCompressFn` + `compressionConfig` args. Fully backward compatible — existing callers unchanged. Web/RN SDKs wire this in automatically; Node.js users can supply `nodeCompressFn` manually. No action required unless opting in on Node.
+- **Removed members keep read-only access** — Server behavior change. Removed participants stay in their conversation list and can read history but cannot write. Socket room membership ends immediately on removal. **No SDK change required.**
+- **Admin delete is hide-only** — Server behavior change. Deleting a conversation sets `isHidden` for the requester only; other participants are unaffected. **No SDK change required.**
+- **Fix: `lastMessage.status` stuck as `deleted`** — Server now explicitly resets `status: 'active'` on both REST and WebSocket paths when a new message is sent. **No client action required.**
+- **Fix: `duration` stored from sender payload** — `SendMessageAttachment.duration` is now persisted and echoed back. The `SendMessageAttachment` interface in this package is unchanged (field was already present as optional).
+
+### v1.0.7
+- **`deliveredTo` per-user delivery timestamps** — All message responses now include `deliveredTo: Array<{ userId, deliveredAt }>` alongside `readBy`. The `Message` type updated: `readBy` changed from `string[]` to `Array<{ userId, readAt }>`. The `message_delivered` socket event payload changed from `{ deliveredTo: string[], deliveredAt }` to `{ deliveredTo: Array<{ userId, deliveredAt }> }`.
+- **Audio support for `.m4a` / `audio/x-m4a`** — `audio/m4a` and `audio/x-m4a` MIME types are now accepted for audio attachments.
+- **Participant filter on `getMembers`** — `getMembers(conversationId, { filter: 'active' | 'deleted' | 'all' })` defaults to `'active'`. Use `'all'` to include removed participants, `'deleted'` to list only removed ones.
+- **Message character limit: 10,000** — Text messages are capped at 10,000 characters. Sending beyond this returns a `400` validation error.
+
+### v1.0.6
+- `externalId` on all user responses
+- Single unified User List API (`usersApi.list()`)
+- Single unified Conversation List API (`conversationsApi.list()`)
+- Fix: attachment last-message content preview
+- Fix: avatar upload via `AntzChatClient`
+- Fix: `client.connect()` on React Native
+- Group icon — create & update
+- Scroll to first unread message
+- Push notifications — device token registration (RN & Web)
+
+---
+
 ## License
 
 MIT

package/dist/index.cjs

@@ -102,6 +102,7 @@ __export(src_exports, {
   disconnectSocket: () => disconnectSocket,
   getApiClient: () => getApiClient,
   getAuthStore: () => getAuthStore,
+  getCompressionStrategy: () => getCompressionStrategy,
   getSocket: () => getSocket,
   getSocketStatus: () => getSocketStatus,
   initApiClient: () => initApiClient,
@@ -168,6 +169,13 @@ function resolveConfig(config) {
       onProgress: config.upload?.onProgress
     },
     platformUploadFn: config.platformUploadFn,
+    platformCompressFn: config.platformCompressFn,
+    compression: {
+      enabled: config.compression?.enabled ?? config.platformCompressFn != null,
+      imageQuality: config.compression?.imageQuality ?? 0.85,
+      imageMaxDimension: config.compression?.imageMaxDimension ?? 1920,
+      compressDocuments: config.compression?.compressDocuments ?? true
+    },
     persistStorage: config.persistStorage,
     messagePageSize: config.messagePageSize ?? 40,
     starredMessagePageSize: config.starredMessagePageSize ?? 30,
@@ -175,6 +183,68 @@ function resolveConfig(config) {
   };
 }
 
+// src/compression/compress.ts
+var GZIP_MIME_TYPES = /* @__PURE__ */ new Set([
+  "text/plain",
+  "text/csv",
+  "text/markdown",
+  "text/x-markdown",
+  "text/xml",
+  "application/xml",
+  "text/yaml",
+  "text/x-yaml",
+  "application/x-yaml",
+  "application/rtf",
+  "text/rtf",
+  "application/json",
+  "image/svg+xml"
+]);
+var IMAGE_MIME_TYPES = /* @__PURE__ */ new Set([
+  "image/jpeg",
+  "image/png",
+  "image/gif",
+  "image/webp",
+  "image/bmp",
+  "image/tiff"
+]);
+var SKIP_MIME_TYPES = /* @__PURE__ */ new Set([
+  "video/mp4",
+  "video/webm",
+  "video/quicktime",
+  "audio/mpeg",
+  "audio/wav",
+  "audio/ogg",
+  "audio/webm",
+  "audio/mp4",
+  "application/zip",
+  "application/pdf",
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  "application/vnd.openxmlformats-officedocument.presentationml.presentation"
+]);
+function getCompressionStrategy(mimeType, config) {
+  if (SKIP_MIME_TYPES.has(mimeType)) return "skip";
+  if (IMAGE_MIME_TYPES.has(mimeType)) return "image";
+  if (config.compressDocuments && GZIP_MIME_TYPES.has(mimeType)) return "gzip";
+  return "skip";
+}
+async function compressFile(file, platformCompressFn, config) {
+  const noop = {
+    ...file,
+    originalSize: file.size,
+    compressed: false,
+    compressionAlgorithm: "none"
+  };
+  if (!config.enabled || !platformCompressFn) return noop;
+  const strategy = getCompressionStrategy(file.type, config);
+  if (strategy === "skip") return noop;
+  try {
+    return await platformCompressFn(file, config);
+  } catch {
+    return noop;
+  }
+}
+
 // src/api/client.ts
 var import_axios = __toESM(require("axios"), 1);
 var _tokenStore = null;
@@ -491,8 +561,11 @@ var conversationsApi = {
   async leave(conversationId) {
     await getApiClient().delete(`/conversations/${conversationId}/leave`);
   },
-  async getMembers(conversationId) {
-    const { data } = await getApiClient().get(`/conversations/${conversationId}/participants`);
+  async getMembers(conversationId, filter) {
+    const { data } = await getApiClient().get(
+      `/conversations/${conversationId}/participants`,
+      filter ? { params: { filter } } : void 0
+    );
     return data;
   },
   /**
@@ -568,12 +641,22 @@ var storageApi = {
     return data;
   }
 };
-async function uploadBatch(files, platformUploadFn, conversationId, onProgress) {
-  const requests = files.map((f) => ({
+async function uploadBatch(files, platformUploadFn, conversationId, onProgress, platformCompressFn, compressionConfig) {
+  const compressedFiles = await Promise.all(
+    files.map((f) => compressFile(f, platformCompressFn, compressionConfig ?? { enabled: false, imageQuality: 0.85, imageMaxDimension: 1920, compressDocuments: true }))
+  );
+  const requests = compressedFiles.map((f) => ({
     filename: f.name,
     mimeType: f.type,
     size: f.size,
-    conversationId
+    conversationId,
+    ...f.compressed && {
+      metadata: {
+        compressed: true,
+        originalSize: f.originalSize,
+        compressionAlgorithm: f.compressionAlgorithm
+      }
+    }
   }));
   const { urls, errors: requestErrors } = await storageApi.requestPresignedUrlBatch(requests);
   const progressMap = {};
@@ -587,7 +670,7 @@ async function uploadBatch(files, platformUploadFn, conversationId, onProgress)
   const failed = [...requestErrors];
   await Promise.all(
     urls.map(async (presigned, idx) => {
-      const file = files[idx];
+      const file = compressedFiles[idx];
       progressMap[idx] = 0;
       try {
         await platformUploadFn(presigned, file, (pct) => {
@@ -982,7 +1065,14 @@ var AntzChatClient = class {
     disconnectSocket();
   }
   uploadFiles(files, conversationId) {
-    return uploadBatch(files, this._config.platformUploadFn, conversationId, this._config.upload.onProgress);
+    return uploadBatch(
+      files,
+      this._config.platformUploadFn,
+      conversationId,
+      this._config.upload.onProgress,
+      this._config.platformCompressFn,
+      this._config.compression
+    );
   }
   async uploadIcon(conversationId, file) {
     const result = await this.uploadFiles([file], conversationId);
@@ -1002,6 +1092,7 @@ var AntzChatClient = class {
   disconnectSocket,
   getApiClient,
   getAuthStore,
+  getCompressionStrategy,
   getSocket,
   getSocketStatus,
   initApiClient,