@antzsoft/chat-core 1.0.0 → 1.0.3

package/README.md

@@ -325,6 +325,27 @@ interface AntzChatConfig {
    */
   encryptionMode?: 'none' | 'server';
 
+  /**
+   * The user's ID in the external auth system.
+   * Required for non-builtin authentication modes (antz, external, wso2).
+   * Sent as the "x-user-id" request header when provided.
+   * Optional.
+   */
+  userId?: string;
+
+  /**
+   * Optional profile picture for non-builtin authentication modes.
+   * Supply a publicly accessible URL or a base64-encoded data URI.
+   * The server fetches/decodes the image, stores it in its own storage,
+   * and serves back a 15-minute signed URL. Hash-based deduplication means
+   * repeat connections with the same image are a no-op.
+   * Optional.
+   */
+  avatar?: {
+    url?: string;
+    base64?: string;
+  };
+
   /**
    * Fine-grained upload constraints and callbacks.
    * Optional — sensible defaults are applied for all sub-fields.
@@ -483,6 +504,85 @@ const config: AntzChatConfig = {
 
 ---
 
+## Non-Builtin Authentication (antz / external / wso2)
+
+When the Antz Chat server runs in `antz`, `external`, or `wso2` mode, authentication is handled by an external system. The SDK must pass three things on every request:
+
+| Config field | HTTP header | When required |
+|---|---|---|
+| `authToken` or `authProvider` | `Authorization: Bearer <token>` | Always |
+| `userId` | `x-user-id` | Non-builtin modes |
+| `tenantId` | `X-Tenant-ID` | Non-builtin modes |
+
+```typescript
+const client = new AntzChatClient({
+  apiUrl: 'https://api.yourapp.com/api/v1',
+  persistStorage,
+  platformUploadFn,
+  authToken: 'jwt-from-your-auth-system',
+  userId: '58',           // the user's ID in your external system
+  tenantId: '11',         // your tenant/zoo/org ID
+});
+```
+
+### Avatar
+
+There are three ways to set or update a user's avatar:
+
+#### 1. Config — on init (any mode)
+
+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',
+    // OR
+    // base64: 'data:image/jpeg;base64,...',
+  },
+});
+```
+
+#### 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.
+
+---
+
 ## API Reference
 
 ### `AntzChatClient` (Headless)
@@ -538,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
@@ -568,6 +668,8 @@ import { authApi } from '@antzsoft/chat-core';
 | `logout` | `(refreshToken?: string) => Promise<void>` | Invalidate the current session. |
 | `logoutAll` | `() => Promise<void>` | Invalidate all sessions for the current user. |
 | `getMe` | `() => Promise<User>` | Fetch the current user's profile. |
+| `uploadAvatar` | `(file: File \| Blob, mimeType?: string) => Promise<{ avatarUrl: string }>` | Multipart avatar upload for builtin auth mode. |
+| `syncAvatar` | `(source: { url?: string; base64?: string }) => Promise<{ avatarUrl: string }>` | Sync avatar from a URL or base64 string — for non-builtin modes or post-init updates. |
 
 ```typescript
 // Login
@@ -578,12 +680,22 @@ const { user } = await authApi.register({
   email: 'new@example.com',
   password: 'hunter2',
   username: 'newuser',
-  displayName: 'New User',
+  firstName: 'New',
+  lastName: 'User',
   tenantId: 'tenant-xyz',
 });
 
 // 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,...' });
 ```
 
 ---
@@ -600,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
@@ -667,7 +783,7 @@ 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. |
@@ -682,7 +798,32 @@ 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 {
@@ -703,6 +844,36 @@ interface UpdateConversationData {
 }
 ```
 
+```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({
@@ -719,8 +890,51 @@ 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.
+
 ---
 
 ### Storage API (`storageApi` and `uploadBatch`)
@@ -783,19 +997,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
@@ -812,20 +1028,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);
 ```
 
 ---
@@ -885,7 +1320,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 message within window, or admin). 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. |
@@ -928,7 +1364,8 @@ Subscribe using `client.socket.on(event, handler)` (headless) or directly on the
 |---|---|---|
 | `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. |
+| `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. |
@@ -1064,11 +1501,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 |
@@ -1080,6 +1526,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. |
@@ -1087,15 +1535,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
-// In a component
+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
+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) {
@@ -1108,16 +1602,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);
-  }
-});
 ```
 
 ---
@@ -1129,10 +1613,13 @@ 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;
   displayName: string;
+  firstName?: string;
+  lastName?: string;
   avatarUrl?: string;
   phone?: string;
   status: 'online' | 'offline' | 'away';