@antzsoft/chat-core 1.2.2 → 1.2.3

package/README.md

@@ -740,6 +740,7 @@ import { messagesApi } from '@antzsoft/chat-core';
 | `search` | `(params: SearchParams) => Promise<PaginatedResponse<Message>>` | Full-text message search. |
 | `getLastRead` | `(conversationId: string) => Promise<{ lastReadMessageId: string \| null; lastReadAt: string \| null }>` | Fetch the current user's last-read pointer for a conversation. Use on initial load; after that the store is kept live by socket events. |
 | `markAsRead` | `(conversationId: string, messageId?: string) => Promise<void>` | Mark messages as read via REST. |
+| `getReceipts` | `(messageId: string) => Promise<MessageReceiptsResponse>` | Fetch per-user read and delivery receipts for a single message, with resolved user profiles (name, avatar). Use as the initial load for a message info / "Read by" detail screen. |
 | `pin` | `(messageId: string) => Promise<Message>` | Pin a message. |
 | `unpin` | `(messageId: string) => Promise<Message>` | Unpin a message. |
 | `getPinned` | `(conversationId: string) => Promise<Message[]>` | List pinned messages in a conversation. |
@@ -1809,8 +1810,8 @@ 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` | `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. |
+| `message_delivered` | `MessageDeliveredEvent` | Fired to the sender each time a recipient receives a message — one event per recipient. Fires immediately at send time for online recipients, and again per recipient as offline recipients reconnect. Payload: `{ messageId, conversationId, deliveredTo: { userId, deliveredAt } }` | **Chat detail screen** — add on mount, remove on unmount. |
+| `messages_delivered` | `MessagesDeliveredEvent` | Batch delivery catch-up — fired to the sender when an offline recipient reconnects and all pending undelivered messages are marked delivered in bulk. Payload: `{ conversationId, messageIds[], deliveredTo: string, deliveredAt }` | **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. |
 | `conversation_deleted` | `{ conversationId: string }` | A conversation was deleted. | **App root / conversation list screen** — remove from state and navigate away if it was open. |
@@ -2090,6 +2091,7 @@ interface Message {
   conversationId: string;
   senderId: string;
   content: MessageContent;
+  metadata?: MessageMetadata;
   replyTo?: MessageReplyReference;
   reactions: MessageReaction[];
   status: 'sent' | 'delivered' | 'read' | 'failed' | 'deleted';
@@ -2109,6 +2111,80 @@ interface Message {
 }
 ```
 
+### `MessageMetadata`
+
+Present on all messages. For system messages, the actor/target fields power viewer-aware text resolution inside the SDK — `content.text` is already resolved by the time the message reaches your code.
+
+```typescript
+interface MessageMetadata {
+  type: string;
+  hasAttachments: boolean;
+  containsLink: boolean;
+  // System messages only
+  systemOperationType?: string;  // 'group_created' | 'user_added' | 'user_removed' | 'user_left' | 'admin_promoted' | 'admin_demoted' | 'group_updated'
+  actorUserId?: string;          // ID of the user who performed the action
+  actorUserName?: string;        // Display name of the actor
+  targetUserId?: string;         // ID of the user the action was performed on
+  targetUserName?: string;       // Display name of the target
+}
+```
+
+### `resolveSystemMessageText`
+
+A pure utility function exported from the package for advanced use cases. The SDK calls this automatically inside `messagesApi.list()` — you only need it if you process raw messages outside the SDK pipeline (e.g. a custom socket handler with `AntzChatClient`).
+
+```typescript
+import { resolveSystemMessageText } from '@antzsoft/chat-core';
+
+client.socket.on('new_message', (event: NewMessageEvent) => {
+  const message = event.message;
+  if (message.content.type === 'system') {
+    const currentUserId = getAuthStore().useAuthStore.getState().user?.id ?? '';
+    message.content.text = resolveSystemMessageText(message, currentUserId);
+  }
+  appendMessageToView(message);
+});
+```
+
+**Viewer-aware output for `user_removed` (currentUserId = Anil's ID):**
+
+| Viewer | `content.text` after resolution |
+|--------|--------------------------------|
+| Anil (actor) | `"You removed Ajay Antony"` |
+| Ajay (target) | `"Anil Rathod removed you"` |
+| Saket (bystander) | `"Anil Rathod removed Ajay Antony"` |
+
+The function falls back to the raw `content.text` from the server if `metadata.actorUserId` is absent (old server compatibility).
+
+### `MessageReceiptsResponse`
+
+Returned by `messagesApi.getReceipts()`. Use as the initial load for a "Read by / Delivered to" detail screen. User profiles (name, avatar) are resolved server-side so no secondary lookup is needed.
+
+```typescript
+interface MessageReceiptEntry {
+  userId: string;
+  displayName: string;
+  avatarUrl?: string;
+}
+
+interface MessageReceiptsResponse {
+  messageId: string;
+  readBy: Array<MessageReceiptEntry & { readAt: string }>;
+  deliveredTo: Array<MessageReceiptEntry & { deliveredAt: string }>;
+}
+```
+
+```typescript
+// Initial load for the detail screen
+const receipts = await messagesApi.getReceipts(messageId);
+
+// receipts.readBy      → participants who have read the message (with timestamps)
+// receipts.deliveredTo → participants who received it but haven't read it yet
+// "Sent to" bucket     → conversation.participants minus the above two sets
+```
+
+---
+
 ### `MessageContent`
 
 ```typescript
@@ -2451,6 +2527,10 @@ document.querySelectorAll('[data-conv-id]').forEach((el) => {
 
 ## Changelog
 
+### v1.2.3
+- **New: `messagesApi.getReceipts(messageId)` — message info screen API** — New `GET /messages/:id/receipts` endpoint returns per-user read and delivery receipts for a single message with resolved user profiles (name, avatar) included. Use as the initial data load for a "Read by / Delivered to" detail screen — no secondary user lookup needed. Returns `{ messageId, readBy: [{ userId, displayName, avatarUrl, readAt }], deliveredTo: [{ userId, displayName, avatarUrl, deliveredAt }] }`. New exported types: `MessageReceiptsResponse`, `MessageReceiptEntry`.
+- **Fix: `message_delivered` now fires per recipient, not all-or-nothing** — Previously the server only emitted `message_delivered` to the sender when every recipient was online simultaneously at send time. It now fires once per online recipient at send time. The `deliveredTo` field is now a single `{ userId, deliveredAt }` object (previously an array of all recipients). This matches how `read_receipt` works and enables the delivery section of a message info screen to update live one entry at a time. **Backward compatible** — existing handlers only read `event.messageId` to update the tick mark and are unaffected.
+
 ### v1.2.0
 - **Fix: `getSocket()` and `tryGetSocket()` now return the transit-aware proxy** — Previously these functions returned the raw Socket.IO socket, bypassing the `secureOn` decryption wrapper. Any integrator calling `getSocket().on('new_message', ...)` or `tryGetSocket().on(...)` directly would receive raw encrypted envelopes (`{v:1, iv:..., ct:...}`) instead of decrypted payloads. Both functions now return the same secure proxy that `connectSocket()` returns — all `.on()` calls automatically decrypt via transit when enabled. **No integration changes required — existing code that uses `getSocket()` or `tryGetSocket()` will now transparently receive decrypted data.**
 

package/dist/index.cjs

@@ -35,12 +35,12 @@ var chat_store_exports = {};
 __export(chat_store_exports, {
   useChatStore: () => useChatStore
 });
-var import_zustand, useChatStore;
+var import_zustand2, useChatStore;
 var init_chat_store = __esm({
   "src/stores/chat.store.ts"() {
     "use strict";
-    import_zustand = require("zustand");
-    useChatStore = (0, import_zustand.create)((set) => ({
+    import_zustand2 = require("zustand");
+    useChatStore = (0, import_zustand2.create)((set) => ({
       activeConversationId: null,
       pendingTarget: null,
       typingUsers: {},
@@ -119,6 +119,7 @@ __export(src_exports, {
   refreshSocketAuth: () => refreshSocketAuth,
   resetAuthStore: () => resetAuthStore,
   resolveConfig: () => resolveConfig,
+  resolveSystemMessageText: () => resolveSystemMessageText,
   setApiClientInstance: () => setApiClientInstance,
   setTransitSession: () => setTransitSession,
   socketEmit: () => socketEmit,
@@ -574,6 +575,123 @@ var appConfigApi = {
   }
 };
 
+// src/stores/auth.store.ts
+var import_zustand = require("zustand");
+var import_middleware = require("zustand/middleware");
+function createAuthStore(storage) {
+  if (!storage) throw new Error("[AntzChat] createAuthStore requires a valid PersistStorage \u2014 received undefined. Make sure the SDK config is fully resolved before initializing the store.");
+  const ref = { store: null };
+  const store = (0, import_zustand.create)()(
+    (0, import_middleware.persist)(
+      (set) => ({
+        user: null,
+        tokens: null,
+        isAuthenticated: false,
+        isLoading: false,
+        isHydrated: false,
+        setAuth: (user, tokens) => set({ user, tokens, isAuthenticated: true, isLoading: false }),
+        setTokens: (tokens) => set({ tokens }),
+        setUser: (user) => set({ user }),
+        logout: () => set({ user: null, tokens: null, isAuthenticated: false, isLoading: false }),
+        setLoading: (isLoading) => set({ isLoading }),
+        setHydrated: (isHydrated) => set({ isHydrated })
+      }),
+      {
+        name: "antz-chat-auth",
+        storage: {
+          getItem: (name) => {
+            const result = storage.getItem(name);
+            if (result instanceof Promise) {
+              return result.then((str) => str ? JSON.parse(str) : null);
+            }
+            return result ? JSON.parse(result) : null;
+          },
+          setItem: (name, value) => {
+            storage.setItem(name, JSON.stringify(value));
+          },
+          removeItem: (name) => storage.removeItem(name)
+        },
+        partialize: (state) => ({
+          user: state.user,
+          tokens: state.tokens,
+          isAuthenticated: state.isAuthenticated
+        }),
+        onRehydrateStorage: () => (state, error) => {
+          if (error) {
+            console.warn("[AntzChat] Auth store rehydration failed:", error);
+          }
+          ref.store?.setState({ isHydrated: true });
+        }
+      }
+    )
+  );
+  ref.store = store;
+  if (!store.getState().isHydrated) {
+    const hydrationTimeout = setTimeout(() => {
+      if (!store.getState().isHydrated) {
+        store.setState({ isHydrated: true });
+      }
+    }, 3e3);
+    const unsub = store.subscribe((s) => {
+      if (s.isHydrated) {
+        clearTimeout(hydrationTimeout);
+        unsub();
+      }
+    });
+  }
+  const tokenStore = {
+    getAccessToken: () => store.getState().tokens?.accessToken,
+    getRefreshToken: () => store.getState().tokens?.refreshToken,
+    setTokens: (tokens) => store.getState().setTokens(tokens),
+    clearTokens: () => store.getState().logout()
+  };
+  return { useAuthStore: store, authTokenStore: tokenStore };
+}
+var _authStore = null;
+function initAuthStore(storage) {
+  if (!_authStore) {
+    _authStore = createAuthStore(storage);
+  }
+  return _authStore;
+}
+function getAuthStore() {
+  if (!_authStore) throw new Error("[AntzChat] Auth store not initialized. Call initAuthStore first.");
+  return _authStore;
+}
+function resetAuthStore() {
+  _authStore = null;
+}
+
+// src/utils/resolveSystemMessageText.ts
+function resolveSystemMessageText(message, currentUserId) {
+  const m = message.metadata;
+  if (!m?.systemOperationType || !m.actorUserId) {
+    return message.content.text ?? "";
+  }
+  const iActor = m.actorUserId === currentUserId;
+  const iTarget = m.targetUserId === currentUserId;
+  const actor = iActor ? "You" : m.actorUserName ?? "Someone";
+  const target = iTarget ? "you" : m.targetUserName ?? "a member";
+  switch (m.systemOperationType) {
+    case "group_created":
+      return iActor ? "You created the group" : `${actor} created the group`;
+    case "user_added":
+      return iActor ? `You added ${target}` : `${actor} added ${target}`;
+    case "user_removed":
+      return iActor ? `You removed ${target}` : `${actor} removed ${target}`;
+    case "user_left":
+      return iActor ? "You left the group" : `${actor} left the group`;
+    case "admin_promoted":
+      return iActor ? `You made ${target} an admin` : `${actor} made ${target} an admin`;
+    case "admin_demoted":
+      return iActor ? `You removed ${target} as admin` : `${actor} removed ${target} as admin`;
+    case "group_updated":
+      return iActor ? "You updated the group" : `${actor} updated the group`;
+    default:
+      return message.content.text ?? "";
+  }
+}
+
 // src/api/messages.ts
 var messagesApi = {
   async list(conversationId, params = {}) {
@@ -586,7 +704,14 @@ var messagesApi = {
       `/conversations/${conversationId}/messages`,
       { params: serverParams }
     );
-    return data;
+    const currentUserId = getAuthStore().useAuthStore.getState().user?.id;
+    if (!currentUserId) return data;
+    return {
+      ...data,
+      data: data.data.map(
+        (m) => m.content.type === "system" ? { ...m, content: { ...m.content, text: resolveSystemMessageText(m, currentUserId) } } : m
+      )
+    };
   },
   async get(messageId) {
     const { data } = await getApiClient().get(`/messages/${messageId}`);
@@ -653,6 +778,10 @@ var messagesApi = {
   async getPinned(conversationId) {
     const { data } = await getApiClient().get(`/conversations/${conversationId}/pinned-messages`);
     return data;
+  },
+  async getReceipts(messageId) {
+    const { data } = await getApiClient().get(`/messages/${messageId}/receipts`);
+    return data;
   }
 };
 
@@ -1500,93 +1629,6 @@ var socketEmit = {
   }
 };
 
-// src/stores/auth.store.ts
-var import_zustand2 = require("zustand");
-var import_middleware = require("zustand/middleware");
-function createAuthStore(storage) {
-  if (!storage) throw new Error("[AntzChat] createAuthStore requires a valid PersistStorage \u2014 received undefined. Make sure the SDK config is fully resolved before initializing the store.");
-  const ref = { store: null };
-  const store = (0, import_zustand2.create)()(
-    (0, import_middleware.persist)(
-      (set) => ({
-        user: null,
-        tokens: null,
-        isAuthenticated: false,
-        isLoading: false,
-        isHydrated: false,
-        setAuth: (user, tokens) => set({ user, tokens, isAuthenticated: true, isLoading: false }),
-        setTokens: (tokens) => set({ tokens }),
-        setUser: (user) => set({ user }),
-        logout: () => set({ user: null, tokens: null, isAuthenticated: false, isLoading: false }),
-        setLoading: (isLoading) => set({ isLoading }),
-        setHydrated: (isHydrated) => set({ isHydrated })
-      }),
-      {
-        name: "antz-chat-auth",
-        storage: {
-          getItem: (name) => {
-            const result = storage.getItem(name);
-            if (result instanceof Promise) {
-              return result.then((str) => str ? JSON.parse(str) : null);
-            }
-            return result ? JSON.parse(result) : null;
-          },
-          setItem: (name, value) => {
-            storage.setItem(name, JSON.stringify(value));
-          },
-          removeItem: (name) => storage.removeItem(name)
-        },
-        partialize: (state) => ({
-          user: state.user,
-          tokens: state.tokens,
-          isAuthenticated: state.isAuthenticated
-        }),
-        onRehydrateStorage: () => (state, error) => {
-          if (error) {
-            console.warn("[AntzChat] Auth store rehydration failed:", error);
-          }
-          ref.store?.setState({ isHydrated: true });
-        }
-      }
-    )
-  );
-  ref.store = store;
-  if (!store.getState().isHydrated) {
-    const hydrationTimeout = setTimeout(() => {
-      if (!store.getState().isHydrated) {
-        store.setState({ isHydrated: true });
-      }
-    }, 3e3);
-    const unsub = store.subscribe((s) => {
-      if (s.isHydrated) {
-        clearTimeout(hydrationTimeout);
-        unsub();
-      }
-    });
-  }
-  const tokenStore = {
-    getAccessToken: () => store.getState().tokens?.accessToken,
-    getRefreshToken: () => store.getState().tokens?.refreshToken,
-    setTokens: (tokens) => store.getState().setTokens(tokens),
-    clearTokens: () => store.getState().logout()
-  };
-  return { useAuthStore: store, authTokenStore: tokenStore };
-}
-var _authStore = null;
-function initAuthStore(storage) {
-  if (!_authStore) {
-    _authStore = createAuthStore(storage);
-  }
-  return _authStore;
-}
-function getAuthStore() {
-  if (!_authStore) throw new Error("[AntzChat] Auth store not initialized. Call initAuthStore first.");
-  return _authStore;
-}
-function resetAuthStore() {
-  _authStore = null;
-}
-
 // src/index.ts
 init_chat_store();
 
@@ -1663,6 +1705,7 @@ var AntzChatClient = class {
   refreshSocketAuth,
   resetAuthStore,
   resolveConfig,
+  resolveSystemMessageText,
   setApiClientInstance,
   setTransitSession,
   socketEmit,