@antzsoft/chat-core 1.0.3 → 1.0.5

package/README.md

@@ -614,6 +614,13 @@ class AntzChatClient {
    * to the configured platformUploadFn, and confirms each upload with the server.
    */
   uploadFiles(files: UploadableFile[], conversationId?: string): Promise<BatchUploadResult>;
+
+  /**
+   * Upload or replace the group icon (admin only).
+   * Internally calls uploadFiles() to upload the file, then sets the icon on the conversation.
+   * Same presigned URL pipeline as message attachments — platformUploadFn is handled automatically.
+   */
+  uploadIcon(conversationId: string, file: UploadableFile): Promise<Conversation>;
 }
 ```
 
@@ -773,6 +780,56 @@ await messagesApi.send('conv-abc', {
 const results = await messagesApi.search({ query: 'deployment', conversationId: 'conv-abc' });
 ```
 
+#### Jump to first unread message
+
+Use `direction: 'after'` with the user's `lastReadMessageId` as the cursor to fetch only the unread messages. This powers a scroll-to-first-unread experience with an "↑ Unread messages" divider.
+
+```typescript
+import { messagesApi, useChatStore } from '@antzsoft/chat-core';
+
+// 1. Get the last-read pointer and seed the store
+const { lastReadMessageId, lastReadAt } = await messagesApi.getLastRead(conversationId);
+
+if (lastReadMessageId && lastReadAt) {
+  useChatStore.getState().setLastRead(conversationId, lastReadMessageId, lastReadAt);
+
+  // 2. Fetch all messages AFTER the last-read message — these are unread
+  const { data: unreadMessages, meta } = await messagesApi.list(conversationId, {
+    cursor: lastReadMessageId,
+    direction: 'after',
+    limit: 50,
+  });
+
+  // unreadMessages[0] is the first unread — scroll the list to this item
+  // meta.hasMore = true means there are more than 50 unread messages
+  if (unreadMessages.length > 0) {
+    scrollToMessage(unreadMessages[0].id);
+  }
+} else {
+  // No prior read state — load latest messages normally
+  const { data: messages } = await messagesApi.list(conversationId, { limit: 30 });
+}
+```
+
+Render the divider in your message list by checking `useChatStore.lastRead[conversationId]`:
+
+```typescript
+const lastRead = useChatStore((s) => s.lastRead[conversationId]);
+
+function MessageRow({ message, prevMessage }) {
+  // Insert divider between the last-read message and the next one
+  const isFirstUnread = lastRead && prevMessage?.id === lastRead.messageId;
+  return (
+    <>
+      {isFirstUnread && <UnreadDivider />}
+      <MessageBubble message={message} />
+    </>
+  );
+}
+```
+
+After the user reads the messages, call `socketEmit.markRead(conversationId)` (see [Read Receipts](#chat-store-usechatstore)) to update the server and broadcast the receipt to other participants.
+
 ---
 
 ### Conversations API (`conversationsApi`)
@@ -787,7 +844,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, fileId: string) => Promise<Conversation>` | Set the group icon from an already-uploaded file (admin only). Call `client.uploadFiles()` first to get the `fileId`, then pass it here. Server copies `storageKey` into `conversation.iconMeta`, deletes the `chat_files` record, and returns the conversation with a 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 +887,6 @@ interface ConversationListParams {
 interface CreateGroupData {
   name: string;
   description?: string;
-  icon?: string;          // Emoji or short string used as the group avatar
   participantIds: string[];
 }
 
@@ -840,7 +897,6 @@ interface CreateDirectData {
 interface UpdateConversationData {
   name?: string;
   description?: string;
-  icon?: string;
 }
 ```
 
@@ -884,6 +940,37 @@ const group = await conversationsApi.createGroup({
 // Start a DM
 const dm = await conversationsApi.createDirect({ userId: 'user-b' });
 
+// ── Group icon ────────────────────────────────────────────────────────────────
+// Upload or replace the group icon (admin only).
+// Uses the SAME presigned URL pipeline as message attachments — platformUploadFn
+// is handled automatically from config, you never pass it explicitly.
+// Always call AFTER createGroup — the group must exist first.
+
+// Using AntzChatClient (headless) — one call, same as client.uploadFiles()
+const updated = await client.uploadIcon(group.id, {
+  uri: 'blob:http://...',   // URL.createObjectURL(file) on web, file URI on RN
+  name: 'icon.jpg',
+  type: 'image/jpeg',
+  size: file.size,
+});
+console.log(updated.iconUrl); // fresh signed URL, regenerated on every response
+
+// What client.uploadIcon() does internally (same as attachment upload):
+// 1. uploadFiles([file], conversationId)
+//      → POST /storage/presigned-url   (creates temp chat_files record)
+//      → platformUploadFn uploads binary directly to S3/Azure/local
+//      → POST /storage/confirm/:fileId  (marks chat_files active)
+// 2. conversationsApi.uploadIcon(conversationId, fileId)
+//      → PUT /conversations/:id/icon { fileId }
+//         Server: validateAdmin() → copy storageKey into conversation.iconMeta
+//                → delete chat_files record (it was only a transport vehicle)
+//                → return conversation with fresh iconUrl
+
+// iconUrl behaviour:
+// - Never stored in DB — regenerated fresh from iconMeta.storageKey on every response
+// - Previous icon deleted from storage automatically on replace
+// - Non-admins get 403 Forbidden
+
 // Add members
 await conversationsApi.addParticipants(group.id, ['user-d', 'user-e']);
 
@@ -935,6 +1022,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 +1435,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 +1503,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 +1543,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 {
@@ -1541,7 +1732,7 @@ The socket listeners for `read_receipt`, `user_online`, and `user_offline` are w
 
 #### Seeding state on initial load
 
-The store starts empty. On first render, fetch the initial values from the API and seed the store:
+The store starts empty. On first render, fetch the initial values from the API and seed the store. Once seeded, `lastReadMessageId` can also be used as a cursor to [jump to the first unread message](#jump-to-first-unread-message) using `messagesApi.list()` with `direction: 'after'`.
 
 ```typescript
 import { messagesApi, usersApi, useChatStore, type LastReadEntry } from '@antzsoft/chat-core';
@@ -1713,8 +1904,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,18 @@ var conversationsApi = {
   async getUnreadSummary() {
     const { data } = await getApiClient().get("/conversations/unread");
     return data;
+  },
+  /**
+   * Set the group icon from an already-uploaded file (admin only).
+   * The fileId comes from uploadBatch() / client.uploadFiles() — same as attachments.
+   * Server copies storageKey into conversation.iconMeta and deletes the chat_files record.
+   */
+  async uploadIcon(conversationId, fileId) {
+    const { data } = await getApiClient().put(
+      `/conversations/${conversationId}/icon`,
+      { fileId }
+    );
+    return normalizeConversation(data);
   }
 };
 
@@ -972,6 +984,12 @@ var AntzChatClient = class {
   uploadFiles(files, conversationId) {
     return uploadBatch(files, this._config.platformUploadFn, conversationId, this._config.upload.onProgress);
   }
+  async uploadIcon(conversationId, file) {
+    const result = await this.uploadFiles([file], conversationId);
+    const fileId = result.successful[0]?.id;
+    if (!fileId) throw new Error("Icon upload failed");
+    return conversationsApi.uploadIcon(conversationId, fileId);
+  }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {