@antzsoft/chat-core 1.0.3 → 1.0.4

package/README.md

@@ -787,7 +787,8 @@ import { conversationsApi } from '@antzsoft/chat-core';
 | `get` | `(conversationId: string) => Promise<Conversation>` | Fetch a single conversation. |
 | `createGroup` | `(data: CreateGroupData) => Promise<Conversation>` | Create a group conversation. |
 | `createDirect` | `(data: CreateDirectData) => Promise<Conversation>` | Start or retrieve a direct conversation with another user. |
-| `update` | `(conversationId: string, data: UpdateConversationData) => Promise<Conversation>` | Update group name, description, or icon. |
+| `update` | `(conversationId: string, data: UpdateConversationData) => Promise<Conversation>` | Update group name or description. |
+| `uploadIcon` | `(conversationId: string, file: File \| { uri: string; name: string; type: string }) => Promise<Conversation>` | Upload or replace the group icon (admin only). Deletes previous icon from storage. Returns conversation with fresh `iconUrl`. |
 | `delete` | `(conversationId: string) => Promise<void>` | Delete a conversation (admin only). |
 | `addParticipants` | `(conversationId: string, userIds: string[]) => Promise<Conversation>` | Add one or more participants. |
 | `removeParticipant` | `(conversationId: string, userId: string) => Promise<Conversation>` | Remove a participant. |
@@ -829,7 +830,6 @@ interface ConversationListParams {
 interface CreateGroupData {
   name: string;
   description?: string;
-  icon?: string;          // Emoji or short string used as the group avatar
   participantIds: string[];
 }
 
@@ -840,7 +840,6 @@ interface CreateDirectData {
 interface UpdateConversationData {
   name?: string;
   description?: string;
-  icon?: string;
 }
 ```
 
@@ -935,6 +934,48 @@ socket?.on('unread_count_changed', ({ conversationId, unreadCount }) => {
 
 Both events are emitted to the user's **private room** (`user:{tenantId}:{userId}`) so every connected device of the same user receives them simultaneously. This is how reading on your phone automatically clears the badge on your browser tab.
 
+#### Chat icon badge — complete pattern (headless / custom UI)
+
+When building a custom UI using `chat-core` directly (no web/RN SDK), maintain your own unread state and update it on socket events:
+
+```typescript
+import { conversationsApi, tryGetSocket } from '@antzsoft/chat-core';
+
+// 1. Cold start — fetch accurate counts from DB
+const summary = await conversationsApi.getUnreadSummary();
+let totalUnread = summary.totalUnread;
+updateBadge(totalUnread); // your UI function
+
+// 2. While socket is connected — update on every event
+const socket = tryGetSocket();
+
+socket?.on('conversation_updated', ({ conversationId, unreadCount }) => {
+  // Server sends accurate DB count per conversation — recalculate total
+  summary.byConversation = summary.byConversation
+    .filter(c => c.conversationId !== conversationId)
+    .concat({ conversationId, unreadCount });
+  totalUnread = summary.byConversation.reduce((s, c) => s + c.unreadCount, 0);
+  updateBadge(totalUnread);
+});
+
+socket?.on('unread_count_changed', ({ conversationId }) => {
+  // User read a conversation — clear it from the map
+  summary.byConversation = summary.byConversation
+    .filter(c => c.conversationId !== conversationId);
+  totalUnread = summary.byConversation.reduce((s, c) => s + c.unreadCount, 0);
+  updateBadge(totalUnread);
+});
+
+// 3. On foreground / socket reconnect — resync from DB
+async function onForeground() {
+  const fresh = await conversationsApi.getUnreadSummary();
+  totalUnread = fresh.totalUnread;
+  updateBadge(totalUnread);
+}
+```
+
+> **Using `@antzsoft/chat-web-sdk` or `@antzsoft/chat-rn-sdk`?** You don't need any of this — `useConversations()` handles socket subscriptions internally. Just sum `conversations.reduce((s, c) => s + (c.unreadCount ?? 0), 0)` and it updates automatically.
+
 ---
 
 ### Storage API (`storageApi` and `uploadBatch`)
@@ -1306,6 +1347,60 @@ unsubscribe();
 disconnectSocket();
 ```
 
+#### Room membership — auto-join and `joinRoom`
+
+**On every socket connection, the server automatically joins the user into all their existing conversation rooms.** No client action is needed. The moment `client.connect()` resolves, the user is already subscribed to real-time events for every conversation they belong to.
+
+This means:
+- You do **not** need to call `joinRoom` when opening a chat screen.
+- `new_message`, `typing_indicator`, `read_receipt`, and all other conversation events are received for all conversations from the moment the socket connects.
+- Calling `joinRoom` on an already-joined room is safe (idempotent) but causes an unnecessary DB access check — avoid it in hot paths.
+
+**When to call `joinRoom`:**
+
+There is only one real use case — when the **user is added to a conversation while their socket is already connected** (either someone created a new group and added them, or they were added to an existing group). The server does not auto-join the user's socket to the new room — it only emits `conversation_created` to the user's personal room. The client must call `joinRoom` in response, otherwise the socket will not receive any `new_message`, `typing_indicator`, or other room events for that conversation.
+
+```typescript
+client.socket.on('conversation_created', (conv) => {
+  // Fires when you're added to a new or existing conversation at runtime
+  client.socket.emit.joinRoom(conv.id);
+});
+```
+
+**Where to add the `new_message` listener:**
+
+Register it **once at app root level**, right after `client.connect()`. A single listener handles messages from all conversations — use `message.conversationId` to route to the right place. Never add it inside a screen or component.
+
+```typescript
+await client.connect();
+
+client.socket.on('new_message', (event: NewMessageEvent) => {
+  const { message } = event;
+
+  // Update the open chat view if this conversation is active
+  if (message.conversationId === activeConversationId) {
+    appendMessageToView(message);
+  }
+
+  // Always update the conversation list (last message + unread badge)
+  updateConversationList(message.conversationId, {
+    lastMessage: message,
+    // Don't increment unread if the user sent it or is currently viewing that chat
+    incrementUnread: message.conversationId !== activeConversationId
+                     && message.senderId !== currentUserId,
+  });
+});
+
+// Only case where joinRoom is needed — new conversation created at runtime
+client.socket.on('conversation_created', (conv) => {
+  client.socket.emit.joinRoom(conv.id);
+});
+```
+
+**`leaveRoom`** is only needed if you want to intentionally stop receiving events for a room the user is still a member of (e.g. archiving client-side). It is not needed when navigating away from a screen.
+
+---
+
 #### `socketEmit` — outbound events
 
 ```typescript
@@ -1320,7 +1415,7 @@ All emit methods that have server responses use a 5-second ack timeout and retur
 | `leaveRoom` | `(conversationId: string) => void` | Leave a conversation room. Fire-and-forget. |
 | `sendMessage` | `(payload: SendMessagePayload) => Promise<unknown>` | Send a message. Ack-based. |
 | `updateMessage` | `(messageId: string, text: string) => Promise<unknown>` | Edit a message. Ack-based. |
-| `deleteMessage` | `(messageId: string) => Promise<unknown>` | Delete a message for everyone (own message within window, or admin). Ack-based. |
+| `deleteMessage` | `(messageId: string) => Promise<unknown>` | Delete a message for everyone. Own messages must be within the delete window (default 30 min); group admins can delete any message with no time restriction. Ack-based. |
 | `deleteMessageForMe` | `(messageId: string) => Promise<unknown>` | Hide a message for the current user only. Ack-based. |
 | `addReaction` | `(messageId: string, emoji: string) => Promise<unknown>` | Add a reaction. Ack-based. |
 | `removeReaction` | `(messageId: string, emoji: string) => Promise<unknown>` | Remove a reaction. Ack-based. |
@@ -1360,21 +1455,29 @@ console.log('Online:', onlineIds); // ['user-a', 'user-c']
 
 Subscribe using `client.socket.on(event, handler)` (headless) or directly on the Socket.IO socket via `getSocket().on(event, handler)`.
 
-| Event | Payload type | Description |
-|---|---|---|
-| `new_message` | `NewMessageEvent` | A new message was sent to a room you've joined. |
-| `message_updated` | `MessageUpdatedEvent` | A message was edited. |
-| `message_deleted` | `MessageDeletedEvent` | A message was deleted for everyone. |
-| `message_deleted_for_me` | `{ messageId: string }` | A message was hidden for the current user only (fired only to that user). |
-| `reaction_updated` | `ReactionUpdatedEvent` | Reactions on a message changed (full reaction array). |
-| `typing_indicator` | `TypingIndicatorEvent` | A user started or stopped typing. |
-| `user_status` | `UserStatusEvent` | A user's online/offline/away status changed. |
-| `read_receipt` | `ReadReceiptEvent` | A user read messages in a conversation. |
-| `message_ack` | `MessageAckEvent` | Server confirmation for a message you sent via socket (maps tempId to the real messageId). |
-| `messages_delivered` | `MessagesDeliveredEvent` | Messages you sent were delivered to a recipient. |
-| `conversation_created` | `Conversation` | A new conversation was created (or you were added to one). |
-| `conversation_updated` | `Conversation` | A conversation's metadata was changed. |
-| `conversation_deleted` | `{ conversationId: string }` | A conversation was deleted. |
+| Event | Payload type | Description | Where to listen / unlisten |
+|---|---|---|---|
+| `new_message` | `NewMessageEvent` | New message in any of the user's conversations — all rooms are auto-joined on connect. | **App root** after `client.connect()`. Never remove — must stay alive for the full app session to keep the conversation list and unread badges up to date. |
+| `message_updated` | `MessageUpdatedEvent` | A message was edited. | **Chat detail screen** — add on mount, remove on unmount. |
+| `message_deleted` | `MessageDeletedEvent` | A message was deleted for everyone. | **Chat detail screen** — add on mount, remove on unmount. |
+| `message_deleted_for_me` | `{ messageId: string; conversationId: string }` | A message was hidden for the current user only (fired only to that user's socket). | **Chat detail screen** — add on mount, remove on unmount. |
+| `reaction_updated` | `ReactionUpdatedEvent` | Reactions on a message changed (full reaction array). | **Chat detail screen** — add on mount, remove on unmount. |
+| `message_pin_updated` | `{ messageId: string; conversationId: string; isPinned: boolean; pinnedBy?: string; pinnedAt?: string }` | A message was pinned or unpinned. | **Chat detail screen** — add on mount, remove on unmount. |
+| `typing_indicator` | `TypingIndicatorEvent` | A user started or stopped typing. | **Chat detail screen** — add on mount, remove on unmount. |
+| `user_online` | `{ userId: string }` | A participant came online — auto-updates `useChatStore.onlineUsers`. | **App root** — drives online indicators everywhere. Keep for full session. |
+| `user_offline` | `{ userId: string; lastSeen: string }` | A participant went offline — auto-updates `useChatStore.lastSeen`. | **App root** — drives online indicators and last-seen everywhere. Keep for full session. |
+| `user_status` | `UserStatusEvent` | Global presence broadcast (online/offline/away) to all connected clients. | **App root** — keep for full session. |
+| `online_users` | `string[]` | Full list of online user IDs — sent on initial room join. | **App root** — keep for full session. |
+| `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. |
+| `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. |
+| `conversation_deleted` | `{ conversationId: string }` | A conversation was deleted. | **App root / conversation list screen** — remove from state and navigate away if it was open. |
+| `participant_joined` | `{ conversationId: string; userId: string; displayName: string; addedBy: string }` | A new participant was added to a group conversation. | **Chat detail screen** — add on mount, remove on unmount. |
+| `participant_left` | `{ conversationId: string; userId: string; displayName: string; removedBy?: string }` | A participant left or was removed from a group conversation. | **Chat detail screen** — add on mount, remove on unmount. |
 
 ```typescript
 import type {
@@ -1713,8 +1816,7 @@ interface Conversation {
   conversationType: 'direct' | 'group';
   name?: string;
   description?: string;
-  icon?: string;
-  iconUrl?: string;
+  iconUrl?: string;  // Fresh signed URL generated on each response — never stored directly
   participants: Participant[];
   participantCount?: number;
   settings?: ConversationSettings;

package/dist/index.cjs

@@ -514,6 +514,26 @@ var conversationsApi = {
   async getUnreadSummary() {
     const { data } = await getApiClient().get("/conversations/unread");
     return data;
+  },
+  /**
+   * Upload or replace the group icon (admin only).
+   * Accepts a File (web) or { uri, name, type } object (React Native).
+   * The server stores the image in its own storage, deletes the previous icon,
+   * and returns a fresh signed iconUrl on every subsequent response.
+   */
+  async uploadIcon(conversationId, file) {
+    const formData = new FormData();
+    if (file instanceof File) {
+      formData.append("icon", file);
+    } else {
+      formData.append("icon", { uri: file.uri, name: file.name, type: file.type });
+    }
+    const { data } = await getApiClient().put(
+      `/conversations/${conversationId}/icon`,
+      formData,
+      { headers: { "Content-Type": "multipart/form-data" } }
+    );
+    return normalizeConversation(data);
   }
 };