@antzsoft/chat-core 1.0.2 → 1.0.4

package/README.md

@@ -525,28 +525,61 @@ const client = new AntzChatClient({
 });
 ```
 
-### Avatar for non-builtin modes
+### Avatar
 
-Pass the user's profile picture on init. The server fetches the URL (or decodes the base64), validates it (supported formats: JPEG, PNG, GIF, WebP; max **5 MB** by default), uploads it to its own storage, and serves it back as a **15-minute signed URL**. SHA-256 hash deduplication ensures the image is only re-uploaded when it actually changes — repeat connections are a no-op.
+There are three ways to set or update a user's avatar:
 
-Server-side size limit is configurable via `AVATAR_MAX_SIZE` (bytes):
+#### 1. Config — on init (any mode)
 
-```env
-AVATAR_MAX_SIZE=5242880    # 5 MB default — change to any value in bytes
-```
+Pass the avatar when constructing `AntzChatClient`. The server fetches the URL (or decodes the base64), validates, uploads to its own storage, and deduplicates by SHA-256 hash — repeat connections are a no-op.
 
 ```typescript
 const client = new AntzChatClient({
   // ...
   avatar: {
-    url: 'https://cdn.yoursystem.com/avatars/user-58.jpg',  // server fetches this
+    url: 'https://cdn.yoursystem.com/avatars/user-58.jpg',
     // OR
-    // base64: 'data:image/jpeg;base64,...',                // server decodes this
+    // base64: 'data:image/jpeg;base64,...',
   },
 });
 ```
 
-If the client doesn't provide an avatar — nothing breaks. The user simply has no profile picture until one is provided.
+#### 2. `client.auth.syncAvatar()` — post-init update (any mode)
+
+Call this any time after init to push a new avatar from a URL or base64 string. Use this when the avatar changes after the client is already running — for example when the user updates their profile in your external system.
+
+```typescript
+// From a URL
+await client.auth.syncAvatar({ url: 'https://cdn.example.com/new-avatar.jpg' });
+
+// From base64
+await client.auth.syncAvatar({ base64: 'data:image/jpeg;base64,...' });
+```
+
+#### 3. `client.auth.uploadAvatar()` — file upload (builtin mode only)
+
+Use when the user picks a file from their device. Sends as multipart to `PUT /users/me/avatar`.
+
+```typescript
+const file = input.files[0]; // File from <input type="file">
+const { avatarUrl } = await client.auth.uploadAvatar(file);
+```
+
+**Which to use:**
+
+| Scenario | Method |
+|---|---|
+| Avatar known at init and won't change | `AntzChatConfig.avatar` |
+| Avatar URL changes at runtime | `client.auth.syncAvatar({ url })` |
+| User picks a file to upload (builtin mode) | `client.auth.uploadAvatar(file)` |
+
+Supported formats: JPEG, PNG, GIF, WebP — max **5 MB** by default. Server-side limit is configurable:
+
+```env
+AVATAR_MAX_SIZE=5242880    # 5 MB default — change to any value in bytes
+```
+
+If no avatar is provided — nothing breaks. The user simply has no profile picture until one is set.
 
 ---
 
@@ -605,7 +638,7 @@ client.socket.emit.joinRoom('conv-abc');
 await client.socket.emit.sendMessage({ conversationId: 'conv-abc', text: 'Hi', tempId: 'tmp-1' });
 
 // REST calls
-const convs = await client.conversations.list({ page: 1, limit: 20 });
+const convs = await client.conversations.list(); // returns all conversations
 const msgs  = await client.messages.list('conv-abc', { limit: 50 });
 
 // Upload files
@@ -654,6 +687,15 @@ const { user } = await authApi.register({
 
 // Logout
 await authApi.logout(tokens.refreshToken);
+
+// Upload avatar (builtin mode — user picks a file)
+const { avatarUrl } = await authApi.uploadAvatar(file);
+
+// Sync avatar from URL (any mode — use when avatar changes after init)
+const { avatarUrl } = await authApi.syncAvatar({ url: 'https://cdn.example.com/avatar.jpg' });
+
+// Sync avatar from base64 (any mode)
+const { avatarUrl } = await authApi.syncAvatar({ base64: 'data:image/jpeg;base64,...' });
 ```
 
 ---
@@ -670,18 +712,22 @@ import { messagesApi } from '@antzsoft/chat-core';
 | `get` | `(messageId: string) => Promise<Message>` | Fetch a single message. |
 | `send` | `(conversationId: string, payload: SendData) => Promise<Message>` | Send a message via REST (use `socketEmit.sendMessage` for real-time delivery). |
 | `update` | `(messageId: string, text: string) => Promise<Message>` | Edit message text. |
-| `delete` | `(messageId: string) => Promise<void>` | Delete a message. |
+| `delete` | `(messageId: string) => Promise<void>` | Delete a message for everyone (own message within window, or admin). |
+| `deleteForMe` | `(messageId: string) => Promise<void>` | Hide a message for the current user only — other participants are unaffected. |
 | `addReaction` | `(messageId: string, emoji: string) => Promise<Message>` | Add an emoji reaction. |
 | `removeReaction` | `(messageId: string, emoji: string) => Promise<Message>` | Remove an emoji reaction. |
 | `star` | `(messageId: string) => Promise<void>` | Star a message. |
 | `unstar` | `(messageId: string) => Promise<void>` | Unstar a message. |
 | `getStarred` | `(params?: { page?: number; limit?: number; conversationId?: string }) => Promise<PaginatedResponse<Message>>` | List starred messages. |
 | `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. |
 | `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. |
 
+> **Delete permissions** — `delete()` (for everyone) requires either: the message belongs to the current user AND was sent within the delete window, OR the current user is a group admin. The server default window is **1800 s (30 min)** when `conversation.settings.messageConfig.deleteWindowSeconds` is not set. DMs have no admin role — only the sender can delete for everyone in a DM. `deleteForMe()` is always allowed for any message. See the [integration guide — Edit & Delete section](docs/integration-guide.html#step-edit) for a ready-to-use `getDeleteOptions()` helper.
+
 ```typescript
 interface ListMessagesParams {
   cursor?: string;       // Opaque cursor for pagination
@@ -737,11 +783,12 @@ import { conversationsApi } from '@antzsoft/chat-core';
 
 | Method | Signature | Description |
 |---|---|---|
-| `list` | `(params?: { page?: number; limit?: number }) => Promise<PaginatedResponse<Conversation>>` | List all conversations the current user is part of. |
+| `list` | `(params?: ConversationListParams) => Promise<PaginatedResponse<Conversation>>` | List conversations with optional server-side filters. |
 | `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. |
@@ -752,13 +799,37 @@ import { conversationsApi } from '@antzsoft/chat-core';
 | `unpin` | `(conversationId: string) => Promise<void>` | Unpin a conversation. |
 | `leave` | `(conversationId: string) => Promise<void>` | Leave a group conversation. |
 | `getMembers` | `(conversationId: string) => Promise<User[]>` | Fetch full user profiles for all participants. |
-| `searchUsers` | `(query: string) => Promise<User[]>` | Search users by name or email (for adding to conversations). |
+
+```typescript
+interface ConversationListParams {
+  /** Omit both page and limit to receive all results in one response */
+  page?: number;
+  limit?: number;
+  /** Filter by conversation type */
+  type?: 'direct' | 'group';
+  /** Only pinned (true) or unpinned (false) conversations */
+  isPinned?: boolean;
+  /** Only muted (true) or unmuted (false) conversations */
+  isMuted?: boolean;
+  /** Only conversations with at least one unread message */
+  hasUnread?: boolean;
+  /** Search by group name / description — uses the server-side text index */
+  search?: string;
+  /** Filter by the current user's role in the conversation */
+  role?: 'admin' | 'member';
+  /** Filter by whether the last message has attachments */
+  hasAttachments?: boolean;
+  /** Filter by last message attachment type */
+  attachmentType?: 'image' | 'video' | 'document' | 'audio';
+  /** Filter by notification enabled/disabled for the current user */
+  notificationsEnabled?: boolean;
+}
+```
 
 ```typescript
 interface CreateGroupData {
   name: string;
   description?: string;
-  icon?: string;          // Emoji or short string used as the group avatar
   participantIds: string[];
 }
 
@@ -769,10 +840,39 @@ interface CreateDirectData {
 interface UpdateConversationData {
   name?: string;
   description?: string;
-  icon?: string;
 }
 ```
 
+```typescript
+// All conversations (no page/limit = server returns everything)
+const { data } = await conversationsApi.list();
+
+// Filter by type
+const groups = await conversationsApi.list({ type: 'group' });
+const dms    = await conversationsApi.list({ type: 'direct' });
+
+// Filter pinned / muted / unread
+const pinned  = await conversationsApi.list({ isPinned: true });
+const muted   = await conversationsApi.list({ isMuted: true });
+const unread  = await conversationsApi.list({ hasUnread: true });
+
+// Text search (uses server-side MongoDB text index on name + description)
+const results = await conversationsApi.list({ search: 'design' });
+
+// Filter by current user's role
+const adminConvs = await conversationsApi.list({ role: 'admin' });
+
+// Combine filters — pinned group conversations with unread messages
+const urgent = await conversationsApi.list({
+  type: 'group',
+  isPinned: true,
+  hasUnread: true,
+});
+
+// Explicit pagination (pass page + limit to opt in)
+const page1 = await conversationsApi.list({ page: 1, limit: 20 });
+```
+
 ```typescript
 // Create a group
 const group = await conversationsApi.createGroup({
@@ -789,8 +889,93 @@ await conversationsApi.addParticipants(group.id, ['user-d', 'user-e']);
 // Mute for 8 hours
 const mutedUntil = new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString();
 await conversationsApi.mute(group.id, mutedUntil);
+
+// ── Unread counts ──────────────────────────────────────────────────────────
+
+// Total unread across all conversations + per-conversation breakdown
+const summary = await conversationsApi.getUnreadSummary();
+// summary.totalUnread          → 12
+// summary.byConversation       → [{ conversationId, unreadCount }, ...]
+
+// Unread count for one specific conversation
+const { unreadCount } = await conversationsApi.getUnreadCount(conversationId);
+```
+
+#### When to call unread APIs vs relying on socket
+
+The socket keeps unread counts live while the app is connected. The REST APIs are the **source of truth** for everything else:
+
+| Situation | What to do |
+|---|---|
+| App cold start | Call `getUnreadSummary()` — hydrate local state before socket connects |
+| App comes to foreground | Call `getUnreadSummary()` — catch up on anything received while socket was down |
+| Socket reconnects after drop | Call `getUnreadSummary()` — reconcile any drift during the outage |
+| Push notification opens a specific chat | Call `getUnreadCount(conversationId)` — refresh just that conversation |
+| User is actively chatting (socket connected) | Use `unreadCount` from `conversationsApi.list()` or the `conversation_updated` socket event — no need to poll REST |
+
+#### Socket events for real-time unread updates
+
+```typescript
+import { tryGetSocket } from '@antzsoft/chat-core';
+
+const socket = tryGetSocket();
+
+// Fires when a new message arrives — updates unreadCount for that conversation
+socket?.on('conversation_updated', ({ conversationId, unreadCount }) => {
+  // unreadCount is calculated server-side from the DB — always accurate
+});
+
+// Fires when YOU mark a conversation as read — resets unreadCount to 0
+// Also fires on your OTHER devices (same user, different session)
+socket?.on('unread_count_changed', ({ conversationId, unreadCount }) => {
+  // unreadCount is 0 here — conversation was just read
+});
 ```
 
+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`)
@@ -853,19 +1038,21 @@ result.failed.forEach((f) => console.error('Failed:', f.filename, f.error));
 
 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.
 
+The server stores one token document per physical device in `chat_device_tokens`. A single user can have multiple active tokens (phone + tablet + browser) — the server delivers push to all of them simultaneously.
+
 ```typescript
 import { devicesApi } from '@antzsoft/chat-core';
 ```
 
 | Method | Signature | Description |
 |---|---|---|
-| `register` | `(payload: RegisterDeviceTokenPayload) => Promise<void>` | Register or refresh a push token. Upserts by `deviceId`. |
-| `remove` | `(deviceId: string) => Promise<void>` | Remove a device token. Call this on logout to stop push delivery. |
+| `register` | `(payload: RegisterDeviceTokenPayload) => Promise<void>` | Register or refresh a push token. Upserts by `deviceId` — safe to call on every app launch. |
+| `remove` | `(deviceId: string) => Promise<void>` | Deactivate a device token. Call on logout or when the user disables notifications. |
 
 ```typescript
 type RegisterDeviceTokenPayload =
   | {
-      deviceId: string;        // Stable UUID — generate once and persist
+      deviceId: string;        // Stable UUID — generate once on install, persist, never regenerate
       platform: 'ios' | 'android' | 'web';
       provider: 'expo' | 'fcm' | 'apns';
       token: string;           // The OS-issued push token
@@ -882,20 +1069,239 @@ type RegisterDeviceTokenPayload =
     };
 ```
 
+#### The `deviceId` rule
+
+`deviceId` must be a **stable UUID that persists across app restarts**. Generate it once on first install and store it in `SecureStore` / `AsyncStorage` (mobile) or `localStorage` (web). If you lose it, the old token becomes an orphan in the server DB and the user may receive duplicate notifications until the stale token expires.
+
+#### When to call `register()`
+
+**Mobile:** Call on every app launch after authentication. Expo and FCM can silently rotate tokens after OS upgrades or reinstalls. Calling on every launch ensures the server always has the current token — the upsert is a no-op if the token hasn't changed.
+
+**Web:** Call on app init if a subscription already exists (to refresh `lastUsedAt` and catch silent endpoint rotation), and again when the user explicitly enables notifications.
+
+#### When to call `remove()`
+
+Call on logout, or when the user disables push in your settings UI. This sets the token to inactive on the server — push stops immediately for that device. Other devices belonging to the same user are unaffected.
+
 ```typescript
-// Mobile (Expo)
+// ── Mobile (Expo) ──────────────────────────────────────────────────────────
 import * as Notifications from 'expo-notifications';
+import * as Device from 'expo-device';
+import * as SecureStore from 'expo-secure-store';
+import * as Crypto from 'expo-crypto';
+
+async function getStableDeviceId(): Promise<string> {
+  const existing = await SecureStore.getItemAsync('chat-device-id');
+  if (existing) return existing;
+  const id = Crypto.randomUUID();
+  await SecureStore.setItemAsync('chat-device-id', id);
+  return id;
+}
+
+// Call after every login / on every app launch after auth
+async function registerPushToken(): Promise<void> {
+  if (!Device.isDevice) return; // simulators cannot receive push
+  const { status } = await Notifications.requestPermissionsAsync();
+  if (status !== 'granted') return;
+  const { data: token } = await Notifications.getExpoPushTokenAsync();
+  await devicesApi.register({
+    deviceId: await getStableDeviceId(),
+    platform: Device.osName === 'iOS' ? 'ios' : 'android',
+    provider: 'expo',
+    token,
+  });
+}
+
+// On logout
+await devicesApi.remove(await getStableDeviceId());
+
+// ── Mobile (FCM — direct Firebase, no Expo) ────────────────────────────────
+import messaging from '@react-native-firebase/messaging';
 
-const { data: expoPushToken } = await Notifications.getExpoPushTokenAsync();
 await devicesApi.register({
-  deviceId: await getStableDeviceId(),  // from SecureStore
-  platform: 'ios',
-  provider: 'expo',
-  token: expoPushToken,
+  deviceId: await getStableDeviceId(),
+  platform: 'android',
+  provider: 'fcm',
+  token: await messaging().getToken(),
 });
 
-// On logout
-await devicesApi.remove(deviceId);
+// FCM tokens can rotate — re-register on rotation
+messaging().onTokenRefresh(async (newToken) => {
+  await devicesApi.register({
+    deviceId: await getStableDeviceId(),
+    platform: 'android',
+    provider: 'fcm',
+    token: newToken,
+  });
+});
+
+// ── Web (VAPID) ────────────────────────────────────────────────────────────
+function getStableDeviceId(): string {
+  let id = localStorage.getItem('chat-device-id');
+  if (!id) { id = crypto.randomUUID(); localStorage.setItem('chat-device-id', id); }
+  return id;
+}
+
+function subToPayload(sub: PushSubscription, deviceId: string) {
+  const b64 = (buf: ArrayBuffer | null) =>
+    buf ? btoa(String.fromCharCode(...new Uint8Array(buf))) : '';
+  return {
+    deviceId, platform: 'web' as const, provider: 'web-push' as const,
+    endpoint: sub.endpoint,
+    p256dh: b64(sub.getKey('p256dh')),
+    auth: b64(sub.getKey('auth')),
+  };
+}
+
+// On app init after login — re-registers any existing subscription
+async function syncPushSubscription(): Promise<void> {
+  if (!('serviceWorker' in navigator) || Notification.permission !== 'granted') return;
+  const reg = await navigator.serviceWorker.ready;
+  const existing = await reg.pushManager.getSubscription();
+  if (existing) await devicesApi.register(subToPayload(existing, getStableDeviceId()));
+}
+
+// When user clicks "Enable notifications"
+async function enablePushNotifications(): Promise<void> {
+  const permission = await Notification.requestPermission();
+  if (permission !== 'granted') return;
+  const reg = await navigator.serviceWorker.ready;
+  const sub = await reg.pushManager.subscribe({
+    userVisibleOnly: true,
+    applicationServerKey: YOUR_VAPID_PUBLIC_KEY,
+  });
+  await devicesApi.register(subToPayload(sub, getStableDeviceId()));
+}
+
+// On logout or "Disable notifications"
+async function disablePushNotifications(): Promise<void> {
+  const reg = await navigator.serviceWorker.ready;
+  const sub = await reg.pushManager.getSubscription();
+  if (sub) await sub.unsubscribe();
+  await devicesApi.remove(getStableDeviceId());
+}
+```
+
+#### Token lifecycle
+
+| Event | Action |
+|---|---|
+| App launch after login (mobile) | Call `register()` — upsert handles token rotation automatically |
+| App init after login (web, subscription exists) | Call `syncPushSubscription()` — refreshes `lastUsedAt`, catches silent endpoint rotation |
+| User enables notifications (web) | Call `enablePushNotifications()` — requests permission, subscribes, registers |
+| User logs out (any platform) | Call `remove(deviceId)` |
+| FCM / Expo token rotates | Call `register()` again with new token — upsert updates the existing record |
+| Notification engine gets `DeviceNotRegistered` from Expo/FCM/VAPID | Engine auto-marks token inactive — no action needed in app |
+
+---
+
+### Notification Preferences (`usersApi.updatePreferences` / `usersApi.getPreferences`)
+
+Notification preferences are stored per user in `chat_user_prefs` on the server. A preferences record with all defaults is created automatically when a device token is first registered — so this API is always available after push registration.
+
+All fields are optional on update — only send what changed. Any future preference field is added to this same collection and the same API; no new endpoints needed.
+
+```typescript
+import { usersApi } from '@antzsoft/chat-core';
+import type { UserPreferences } from '@antzsoft/chat-core';
+```
+
+| Method | Description |
+|---|---|
+| `getPreferences()` | Fetch current preferences. Returns `null` if no record exists (all defaults apply). |
+| `updatePreferences(prefs)` | Partial update — only fields you pass are changed. |
+
+```typescript
+// Fetch current preferences
+const prefs = await usersApi.getPreferences();
+// prefs is null if no record yet (all defaults apply — everything enabled, quietHours off)
+
+// Disable reaction notifications
+await usersApi.updatePreferences({ notifyOnReaction: false });
+
+// Hide message content from notification body
+await usersApi.updatePreferences({ messagePreview: false });
+
+// Enable quiet hours (no push 23:00–07:00 IST)
+await usersApi.updatePreferences({
+  quietHours: { enabled: true, start: '23:00', end: '07:00', timezone: 'Asia/Kolkata' },
+});
+
+// Turn off all notifications (master switch)
+await usersApi.updatePreferences({ notificationsEnabled: false });
+```
+
+#### `UserPreferences` type
+
+```typescript
+interface UserPreferences {
+  /** Master switch — false disables all push. Default: true */
+  notificationsEnabled?: boolean;
+
+  /** Play sound with notifications. Default: true */
+  soundEnabled?: boolean;
+
+  /** Show message text in notification body.
+   *  false = show "New message" only (privacy mode). Default: true */
+  messagePreview?: boolean;
+
+  /** Notify when @mentioned in a group. Default: true */
+  notifyOnMention?: boolean;
+
+  /** Notify when someone reacts to your message. Default: true */
+  notifyOnReaction?: boolean;
+
+  /** Notify when added to a group. Default: true */
+  notifyOnGroupInvite?: boolean;
+
+  /** Quiet hours — no push delivered during this window. Default: disabled */
+  quietHours?: {
+    enabled: boolean;
+    start: string;    // HH:MM — e.g. "22:00"
+    end: string;      // HH:MM — e.g. "08:00"
+    timezone: string; // IANA — e.g. "Asia/Kolkata"
+  };
+}
+```
+
+#### Adding future preferences
+
+Add the new field to the server schema (`user-prefs.schema.ts`) and to the `UserPreferences` interface above. The same `updatePreferences()` / `getPreferences()` API handles it — no new endpoints, no new collections.
+
+---
+
+### Users API (`usersApi`)
+
+User data is served directly from the chat server's MongoDB shadow records — no external user-service call is made. Shadow records are kept warm by the server's background sync job (runs on startup and periodically).
+
+```typescript
+import { usersApi } from '@antzsoft/chat-core';
+```
+
+| Method | Signature | Description |
+|---|---|---|
+| `list` | `(params?: { query?: string; page?: number; limit?: number }) => Promise<PaginatedResponse<User>>` | List users, optionally filtered by a search query. Omit `page`/`limit` for all results. |
+| `getById` | `(userId: string) => Promise<User>` | Fetch a single user by their chat system ID. |
+| `getLastSeen` | `(userId: string) => Promise<{ lastSeenAt: string \| null }>` | Fetch a user's last-seen timestamp. Use on initial load; after that the store is kept live by `user_offline` socket events. |
+
+All methods return `User` objects that include `externalId` for non-builtin modes.
+
+```typescript
+// All users (no page/limit = server returns everything)
+const { data } = await usersApi.list();
+
+// Search by name / username / email
+const { data: results } = await usersApi.list({ query: 'john' });
+
+// Paginated (opt in by passing page + limit)
+const { data, meta } = await usersApi.list({ page: 1, limit: 20 });
+
+// Search + paginated
+const { data: results } = await usersApi.list({ query: 'john', page: 1, limit: 10 });
+
+// Get a specific user
+const user = await usersApi.getById('64abc...');
+console.log(user.displayName, user.externalId);
 ```
 
 ---
@@ -941,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
@@ -955,7 +1415,8 @@ 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. 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. |
 | `pinMessage` | `(messageId: string) => Promise<unknown>` | Pin a message. Ack-based. |
@@ -994,20 +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. |
-| `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 {
@@ -1134,11 +1604,20 @@ import { useChatStore } from '@antzsoft/chat-core';
 | `pendingTarget` | `{ conversationId: string; messageId: string } \| null` | Scroll-to target for deep-linked messages. |
 | `typingUsers` | `Record<string, TypingUser[]>` | Map of conversationId → users currently typing. |
 | `onlineUsers` | `string[]` | Array of user IDs currently online. |
+| `lastRead` | `Record<string, LastReadEntry>` | Map of conversationId → `{ messageId, readAt }` — the current user's last-read pointer per conversation. Hydrated by `read_receipt` socket events automatically. |
+| `lastSeen` | `Record<string, string>` | Map of userId → ISO timestamp — each user's last-seen time. Hydrated by `user_offline` socket events automatically. |
 | `replyingTo` | `Message \| null` | Message being replied to in the composer. |
 | `editingMessage` | `Message \| null` | Message being edited in the composer. |
 | `isSidebarOpen` | `boolean` | Conversation list sidebar visibility. |
 | `isGroupInfoOpen` | `boolean` | Group info panel visibility. |
 
+```typescript
+interface LastReadEntry {
+  messageId: string;
+  readAt: string; // ISO 8601
+}
+```
+
 #### Actions
 
 | Action | Signature | Description |
@@ -1150,6 +1629,8 @@ import { useChatStore } from '@antzsoft/chat-core';
 | `setUserOnline` | `(userId: string) => void` | Mark a user as online. |
 | `setUserOffline` | `(userId: string) => void` | Mark a user as offline. |
 | `setOnlineUsers` | `(userIds: string[]) => void` | Replace the full online users list. |
+| `setLastRead` | `(conversationId: string, messageId: string, readAt: string) => void` | Update the last-read pointer for a conversation. Called automatically by the `read_receipt` socket listener — only call manually to seed state on initial load. |
+| `setLastSeen` | `(userId: string, lastSeenAt: string) => void` | Update a user's last-seen timestamp. Called automatically by the `user_offline` socket listener — only call manually to seed state on initial load. |
 | `setReplyingTo` | `(message: Message \| null) => void` | Set reply context; clears `editingMessage`. |
 | `setEditingMessage` | `(message: Message \| null) => void` | Set edit context; clears `replyingTo`. |
 | `toggleSidebar` | `() => void` | Toggle sidebar open/closed. |
@@ -1157,15 +1638,61 @@ import { useChatStore } from '@antzsoft/chat-core';
 | `toggleGroupInfo` | `() => void` | Toggle group info panel. |
 | `setGroupInfoOpen` | `(open: boolean) => void` | Set group info panel state explicitly. |
 
+#### Automatic socket wiring
+
+The socket listeners for `read_receipt`, `user_online`, and `user_offline` are wired automatically inside `connectSocket`. You do not need to subscribe to these events yourself — `lastRead` and `lastSeen` in the store are kept up to date as long as the socket is connected.
+
+#### Seeding state on initial load
+
+The store starts empty. On first render, fetch the initial values from the API and seed the store:
+
+```typescript
+import { messagesApi, usersApi, useChatStore, type LastReadEntry } from '@antzsoft/chat-core';
+
+// Seed last-read for the active conversation when it opens
+const conversationId = 'conv-abc';
+const { lastReadMessageId, lastReadAt } = await messagesApi.getLastRead(conversationId);
+if (lastReadMessageId && lastReadAt) {
+  useChatStore.getState().setLastRead(conversationId, lastReadMessageId, lastReadAt);
+}
+
+// Seed last-seen for a specific user (e.g. in a DM header)
+const { lastSeenAt } = await usersApi.getLastSeen('user-xyz');
+if (lastSeenAt) {
+  useChatStore.getState().setLastSeen('user-xyz', lastSeenAt);
+}
+```
+
+After seeding, socket events keep the store live — no further fetches are needed.
+
+#### Reading state in components
+
 ```typescript
-// In a component
+import { useChatStore, type LastReadEntry } from '@antzsoft/chat-core';
+
+// Last-read pointer for the open conversation
+const lastRead: LastReadEntry | undefined = useChatStore(
+  (s) => s.lastRead['conv-abc'],
+);
+// lastRead.messageId — scroll here on open
+// lastRead.readAt    — "read up to" timestamp
+
+// Last-seen for a user (e.g. "Last seen 5 minutes ago" in a DM)
+const lastSeenAt: string | undefined = useChatStore(
+  (s) => s.lastSeen['user-xyz'],
+);
+
+// Online presence
+const isOnline = useChatStore((s) => s.onlineUsers.includes('user-xyz'));
+```
+
+```typescript
+// Typing indicator wiring (still manual — not auto-wired)
 const activeId = useChatStore((s) => s.activeConversationId);
 const typingInActive = useChatStore((s) =>
   activeId ? (s.typingUsers[activeId] ?? []) : [],
 );
-const { setActiveConversation, setReplyingTo } = useChatStore.getState();
 
-// Wire typing indicator events
 client.socket.on('typing_indicator', (evt: TypingIndicatorEvent) => {
   const { addTypingUser, removeTypingUser } = useChatStore.getState();
   if (evt.isTyping) {
@@ -1178,16 +1705,6 @@ client.socket.on('typing_indicator', (evt: TypingIndicatorEvent) => {
     removeTypingUser(evt.conversationId, evt.userId);
   }
 });
-
-// Wire user status events
-client.socket.on('user_status', (evt: UserStatusEvent) => {
-  const { setUserOnline, setUserOffline } = useChatStore.getState();
-  if (evt.status === 'online') {
-    setUserOnline(evt.userId);
-  } else {
-    setUserOffline(evt.userId);
-  }
-});
 ```
 
 ---
@@ -1199,6 +1716,7 @@ client.socket.on('user_status', (evt: UserStatusEvent) => {
 ```typescript
 interface User {
   id: string;
+  externalId?: string;   // external system user ID (non-builtin modes only)
   tenantId: string;
   email: string;
   username: string;
@@ -1298,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;