@antzsoft/chat-core 1.2.5 → 1.2.7

package/README.md

@@ -1104,6 +1104,38 @@ async function onForeground() {
 
 > **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.
 
+#### Clear / Delete Chat (v1.2.6+)
+
+`conversationsApi.delete(conversationId)` hides a conversation from the caller's list. Any participant can call it — no admin role required. Other participants are completely unaffected.
+
+| Scenario | Call | Effect |
+|---|---|---|
+| **Delete Chat** (DM) | `conversationsApi.delete(id)` | Hides DM, wipes periods. Re-opens with new history only when other party messages. |
+| **Exit Group** | `conversationsApi.leave(id)` | Caller inactive, stays in list read-only. Auto-promotes admin if needed. |
+| **Exit and Delete** | `conversationsApi.leave(id, true)` | Atomic exit + hide. Periods wiped. No race window. |
+| **Delete Group** (post-exit) | `conversationsApi.delete(id)` | Hides already-exited group entry. Others unaffected. |
+
+```typescript
+// Delete Chat — DM
+await conversationsApi.delete(dmConversationId);
+
+// Exit Group
+await conversationsApi.leave(groupId);
+
+// Exit and Delete (atomic — one write)
+await conversationsApi.leave(groupId, true);
+
+// Listen for confirmation on the caller's own sockets
+socket.on('conversation_deleted', ({ conversationId }) => {
+  removeFromConversationList(conversationId);
+  if (activeConversationId === conversationId) navigateBackToList();
+});
+```
+
+**Message history after re-add:** if the user left with `delete()` or `leave(true)`, membership periods are wiped — only messages from the re-add point are visible. Plain `leave()` preserves prior history windows.
+
+**Web/RN SDK hooks expose named mutations:** `leaveGroup`, `leaveAndDeleteGroup`, `deleteGroup` (web) / `deleteConversation` (RN) — cache updated optimistically, no manual invalidation needed.
+
 ---
 
 ### Storage API (`storageApi` and `uploadBatch`)
@@ -1669,6 +1701,364 @@ const config = await appConfigApi.get();
 
 ---
 
+### Sync API (`syncApi`)
+
+> **v1.2.7+** — Mobile (React Native) only. Web SDK uses React Query cache invalidation on reconnect — no sync calls needed.
+
+```typescript
+import { syncApi } from '@antzsoft/chat-core';
+import type {
+  CrossConversationSyncResponse,
+  ConversationSyncResponse,
+} from '@antzsoft/chat-core';
+```
+
+| Method | Signature | Description |
+|---|---|---|
+| `pull` | `(since: string) => Promise<CrossConversationSyncResponse>` | Cross-conversation delta sync. Call on every socket reconnect. `since` is the `syncedAt` value returned by the previous call (server clock — avoids client clock skew). |
+| `pullConversation` | `(conversationId: string, since?: string) => Promise<ConversationSyncResponse>` | Per-conversation delta sync. Call when a conversation has `needs_refresh = true`, or omit `since` on fresh install to receive full history. |
+
+#### When to call each
+
+| Situation | Call |
+|---|---|
+| Socket reconnects (within stale threshold) | `syncApi.pull(lastSyncedAt)` — returns all cross-conversation changes |
+| Socket reconnects (gap > stale threshold) | `pull()` returns `stale: true` — mark all conversations `needs_refresh`, lazy-sync on open |
+| User opens a stale conversation | `syncApi.pullConversation(convId, lastSyncedAt)` — returns full delta for that conversation |
+| Fresh install / first open | `syncApi.pullConversation(convId)` — omit `since` to receive full history |
+
+#### `CrossConversationSyncResponse`
+
+Returned by `syncApi.pull(since)`. Does **not** include reactions or stars — those are per-conversation and returned by `pullConversation`.
+
+```typescript
+interface CrossConversationSyncResponse {
+  syncedAt: string;      // server-stamped ISO timestamp — store as new lastSyncedAt
+  stale: boolean;        // true when gap > CHAT_SYNC_STALE_DAYS (default 30) — app should lazy-sync on open
+  messages: Message[];   // edits, deletes, pins, unpins — any message with updatedAt > since
+  deletedForMe: SyncDeletedForMe[];
+  participantChanges: SyncParticipantChange[];
+  readReceipts: SyncReadReceipt[];
+}
+
+interface SyncDeletedForMe {
+  messageId: string;
+  conversationId: string;
+  deletedAt: string | null;
+}
+
+interface SyncParticipantChange {
+  conversationId: string;
+  userId: string;
+  role: string;
+  isActive: boolean;       // false = removed
+  isMuted: boolean;
+  mutedUntil: string | null;
+  updatedAt: string | null;
+}
+
+interface SyncReadReceipt {
+  messageId: string;
+  conversationId: string;
+  userId: string;
+  readAt: string | null;
+}
+```
+
+#### `ConversationSyncResponse`
+
+Returned by `syncApi.pullConversation(convId, since?)`. Includes everything needed to make local SQLite authoritative for that conversation.
+
+```typescript
+interface ConversationSyncResponse {
+  syncedAt: string;
+  messages: Message[];          // updatedAt > since — edits, deletes, pins
+  deletedForMe: SyncDeletedForMe[];
+  reactions: SyncReactions;     // full current state for messages with reactedAt > since
+  stars: SyncStarEntry[];       // updatedAt > since; isActive: false = unstarred
+  participantChanges: SyncParticipantChange[];
+  readReceipts: SyncReadReceipt[];
+}
+
+// keyed by messageId — full current emoji counts (not delta)
+type SyncReactions = Record<string, MessageReaction[]>;
+
+interface SyncStarEntry {
+  messageId: string;
+  conversationId: string;
+  isActive: boolean;   // true = starred, false = unstarred (soft-deleted)
+  updatedAt: string | null;
+}
+```
+
+#### What each field covers
+
+| Field | What changed events it captures |
+|---|---|
+| `messages` | Edits (`isEdited: true`), deletes (`status: "deleted"`), pins / unpins (`isPinned`) |
+| `deletedForMe` | Messages this user hid for themselves only — remove from local DB |
+| `reactions` | Full current emoji counts for any message that had reaction activity. Upsert as ground truth — never merge |
+| `stars` | `isActive: true` = starred, `isActive: false` = unstarred — delete local star record when false |
+| `participantChanges` | Role changes, mute/unmute, removals (`isActive: false`) |
+| `readReceipts` | Read receipts received since `since` |
+
+#### Stale handling
+
+When `pull()` returns `stale: true`, the server returns no data — it would be too large to return everything. The stale threshold defaults to **30 days** and is controlled by the `CHAT_SYNC_STALE_DAYS` server environment variable. The correct pattern:
+
+```typescript
+const result = await syncApi.pull(lastSyncedAt);
+
+if (result.stale) {
+  // Store new cursor so next reconnect uses the server's timestamp, not the old one
+  await AsyncStorage.setItem('@antz_last_synced_at', result.syncedAt);
+  // Mark every conversation needs_refresh in your local SQLite
+  await db.execute('UPDATE conversations SET needs_refresh = 1');
+  // Lazy-sync — call pullConversation when the user actually opens each conversation
+} else {
+  await AsyncStorage.setItem('@antz_last_synced_at', result.syncedAt);
+  await mergeSyncDeltaIntoSQLite(result);
+}
+```
+
+#### RN SDK — built-in hooks
+
+When using `@antzsoft/chat-rn-sdk`, use the pre-built hooks instead of calling `syncApi` directly:
+
+```typescript
+import { useSync, useConversationSync } from '@antzsoft/chat-rn-sdk';
+
+// In your root provider — auto-triggers on every socket reconnect
+useSync({
+  onSync: async (data) => {
+    // data is CrossConversationSyncResponse
+    await mergeSyncDeltaIntoSQLite(data);
+  },
+  onStale: async () => {
+    // Gap > stale threshold — mark all conversations needs_refresh
+    await db.execute('UPDATE conversations SET needs_refresh = 1');
+  },
+});
+
+// In your conversation screen — call when needs_refresh is true
+const { isSyncing, sync } = useConversationSync(conversationId);
+
+useEffect(() => {
+  if (needsRefresh) {
+    sync().then((data) => {
+      if (data) upsertConversationDeltaToSQLite(data);
+      clearNeedsRefresh(conversationId);
+    });
+  }
+}, [conversationId, needsRefresh]);
+```
+
+#### Full event coverage
+
+| Event | `pull()` | `pullConversation()` |
+|---|---|---|
+| Message edited | ✅ | ✅ |
+| Message deleted (everyone) | ✅ | ✅ |
+| Message deleted for me | ✅ | ✅ |
+| Message pinned / unpinned | ✅ | ✅ |
+| Reaction added / removed | — | ✅ full current state |
+| Star / unstar | — | ✅ with `isActive` |
+| Read receipt | ✅ | ✅ |
+| Role change / mute / removal | ✅ | ✅ |
+
+---
+
+## Error Handling
+
+All SDK errors — whether from REST calls, socket operations, or internal state — are instances of `AntzChatError` or one of its subclasses. Every error carries a machine-readable `code`, a human-readable `message`, a `retryable` boolean, and an optional `context` object with extra diagnostics.
+
+### Error classes
+
+| Class | When thrown | `retryable` |
+|---|---|---|
+| `AntzChatAuthError` | 401 after token refresh also fails, or no refresh token exists | `false` |
+| `AntzChatValidationError` | 400 / 422 — bad input, validation failure | `false` |
+| `AntzChatPermissionError` | 403 — insufficient permissions | `false` |
+| `AntzChatNetworkError` | Network failure, timeout, socket disconnect, queue overflow | `true` |
+| `AntzChatServerError` | 5xx or unexpected server errors | `true` |
+| `AntzChatError` (base) | Transit config mismatch, unknown errors | varies |
+
+All classes extend the native `Error` class, so existing `catch (err)` blocks continue to work unchanged.
+
+### Error codes
+
+Switch on `err.code` for fine-grained handling:
+
+| Code | Class | Source |
+|---|---|---|
+| `SESSION_EXPIRED` | `AntzChatAuthError` | 401, no prior retry |
+| `AUTH_FAILED` | `AntzChatAuthError` | 401 after token refresh also failed |
+| `PERMISSION_DENIED` | `AntzChatPermissionError` | 403 |
+| `VALIDATION_ERROR` | `AntzChatValidationError` | 400 / 422 |
+| `NOT_FOUND` | `AntzChatServerError` | 404 |
+| `RATE_LIMITED` | `AntzChatNetworkError` | 429 |
+| `NETWORK_ERROR` | `AntzChatNetworkError` | No response / connection failure |
+| `SOCKET_TIMEOUT` | `AntzChatNetworkError` | ACK timeout (5 s) or reconnect timeout (15 s) |
+| `SOCKET_NOT_CONNECTED` | `AntzChatNetworkError` | Socket not up when an ack-required emit fires |
+| `SEND_QUEUE_FULL` | `AntzChatNetworkError` | Per-conversation queue > 100 pending messages |
+| `MESSAGE_DROPPED` | `AntzChatNetworkError` | Message waited > 30 s in queue before socket ready |
+| `TRANSIT_MISMATCH` | `AntzChatError` | SDK and server transit-encryption config differ |
+| `SERVER_ERROR` | `AntzChatServerError` | 5xx or unrecognised HTTP error |
+
+### Imports
+
+```typescript
+import {
+  AntzChatError,
+  AntzChatAuthError,
+  AntzChatValidationError,
+  AntzChatNetworkError,
+  AntzChatPermissionError,
+  AntzChatServerError,
+} from '@antzsoft/chat-core';
+```
+
+### Usage patterns
+
+#### instanceof branching
+
+```typescript
+import {
+  AntzChatAuthError,
+  AntzChatValidationError,
+  AntzChatNetworkError,
+  AntzChatPermissionError,
+  AntzChatServerError,
+} from '@antzsoft/chat-core';
+
+try {
+  await authApi.login({ email, password });
+} catch (err) {
+  if (err instanceof AntzChatAuthError)        showLoginError(err.message);
+  else if (err instanceof AntzChatValidationError) showFieldErrors(err.fields ?? [err.message]);
+  else if (err instanceof AntzChatPermissionError) showPermissionDenied();
+  else if (err instanceof AntzChatNetworkError && err.retryable) scheduleRetry();
+  else if (err instanceof AntzChatServerError) logAndShowGenericError(err);
+  else throw err; // unknown — re-throw
+}
+```
+
+#### code switching (fine-grained)
+
+```typescript
+import { AntzChatError } from '@antzsoft/chat-core';
+
+try {
+  await socketEmit.sendMessage(payload);
+} catch (err) {
+  if (!(err instanceof AntzChatError)) throw err;
+  switch (err.code) {
+    case 'SESSION_EXPIRED':       redirectToLogin();                           break;
+    case 'SEND_QUEUE_FULL':       showToast('Too many messages in flight');    break;
+    case 'MESSAGE_DROPPED':       showToast('Message timed out — try again');  break;
+    case 'SOCKET_TIMEOUT':
+    case 'SOCKET_NOT_CONNECTED':  showOfflineBanner();                         break;
+    case 'PERMISSION_DENIED':     showToast('You cannot send here');           break;
+    default:                      console.error(err.code, err.message, err.context);
+  }
+}
+```
+
+#### retryable flag
+
+```typescript
+import { AntzChatError } from '@antzsoft/chat-core';
+
+async function sendWithRetry(payload, maxAttempts = 3) {
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await socketEmit.sendMessage(payload);
+    } catch (err) {
+      if (err instanceof AntzChatError && err.retryable && attempt < maxAttempts) {
+        await new Promise(r => setTimeout(r, attempt * 1000)); // back-off
+        continue;
+      }
+      throw err;
+    }
+  }
+}
+```
+
+#### AntzChatValidationError — field errors
+
+When the server returns `message` as a string array (e.g. class-validator errors), `AntzChatValidationError.fields` is populated with the individual messages:
+
+```typescript
+import { AntzChatValidationError } from '@antzsoft/chat-core';
+
+try {
+  await authApi.register(payload);
+} catch (err) {
+  if (err instanceof AntzChatValidationError) {
+    console.log(err.message);  // "email must be a valid email; password is too short"
+    console.log(err.fields);   // ["email must be a valid email", "password is too short"]
+  }
+}
+```
+
+#### Transit encryption mismatch
+
+If the SDK and server have mismatched `transitEncryption` settings, `connectSocket` throws a non-retryable `AntzChatError` with code `TRANSIT_MISMATCH` before any socket is created:
+
+```typescript
+import { AntzChatError } from '@antzsoft/chat-core';
+
+try {
+  await client.connect();
+} catch (err) {
+  if (err instanceof AntzChatError && err.code === 'TRANSIT_MISMATCH') {
+    console.error('Config mismatch:', err.message, err.context);
+    // err.context = { sdkEnabled: true, serverEnabled: false }
+  }
+}
+```
+
+### What stays silent (by design)
+
+These three cases intentionally do not throw:
+
+| Situation | Reason |
+|---|---|
+| `socketEmit.typing()` / `socketEmit.markRead()` — socket not connected | Best-effort only; callers must not be forced to wrap them |
+| Transit session timeout (5 s) — server event not received | SDK degrades gracefully to unencrypted mode and continues |
+| `usersApi.getPreferences()` failure | Returns `null`; preferences are non-critical and defaults apply |
+
+### Error context
+
+Every `AntzChatError` carries a `context` object with extra diagnostics. It is safe to log but never needed for control flow:
+
+```typescript
+catch (err) {
+  if (err instanceof AntzChatError) {
+    // context contains: httpStatus, path, serverError, axiosCode, event, decryptionFailed, etc.
+    console.error('[AntzChat]', err.name, err.code, err.message, err.context);
+  }
+}
+```
+
+If transit decryption fails for an error response body, `context.decryptionFailed = true` is set and the generic HTTP-status-based class is still returned — no unhandled exception.
+
+### normalizeAxiosError
+
+If you make raw axios calls through `getApiClient()` and want the same normalisation:
+
+```typescript
+import { getApiClient, normalizeAxiosError, AntzChatError } from '@antzsoft/chat-core';
+
+try {
+  const { data } = await getApiClient().get('/some/endpoint');
+} catch (err) {
+  throw normalizeAxiosError(err); // always returns AntzChatError (or subclass)
+}
+```
+
+---
+
 ### Socket
 
 #### Connection management
@@ -1827,6 +2217,7 @@ Subscribe using `client.socket.on(event, handler)` (headless) or directly on the
 | `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_star_updated` | `MessageStarUpdatedEvent` | A message was starred or unstarred by the current user on another device. Fired only to the acting user's personal room — other participants never receive it. `isStarred: true` = starred, `isStarred: false` = unstarred. | **App root** (to sync star state across all open chat screens and the starred messages list). Keep for full session. |
 | `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. |
@@ -1840,7 +2231,7 @@ Subscribe using `client.socket.on(event, handler)` (headless) or directly on the
 | `messages_delivered` | `MessagesDeliveredEvent` | Batch delivery catch-up — fired to the sender when an offline recipient reconnects and all pending undelivered messages are marked delivered in bulk. Payload: `{ conversationId, messageIds[], deliveredTo: string, deliveredAt }` | **Chat detail screen** — add on mount, remove on unmount. |
 | `conversation_created` | `Conversation` | A new conversation was created (or you were added to one). | **App root** — call `joinRoom` here for the new conversation. Keep for full session. |
 | `conversation_updated` | `Conversation` | A conversation's last message or metadata changed — use this to update the conversation list. | **App root** — keep for full session. The server emits this for every message across all conversations; a global listener keeps the in-memory conversation list and unread badge always in sync. |
-| `conversation_deleted` | `{ conversationId: string }` | A conversation was deleted. | **App root / conversation list screen** — remove from state and navigate away if it was open. |
+| `conversation_deleted` | `{ conversationId: string }` | Emitted **only to the acting user's own sockets** when they: (1) self-delete/hide a conversation via `delete()`, (2) exit+delete a group via `leave(id, true)`, or (3) hide an already-exited group via `delete()`. Other participants never receive this event. | **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. |
 
@@ -1850,6 +2241,7 @@ import type {
   MessageUpdatedEvent,
   MessageDeletedEvent,
   ReactionUpdatedEvent,
+  MessageStarUpdatedEvent,
   TypingIndicatorEvent,
   UserStatusEvent,
   ReadReceiptEvent,
@@ -1873,6 +2265,11 @@ client.socket.on('reaction_updated', (evt: ReactionUpdatedEvent) => {
   setMessageReactions(evt.messageId, evt.reactions);
 });
 
+client.socket.on('message_star_updated', (evt: MessageStarUpdatedEvent) => {
+  // Fires on your other devices when you star/unstar on one device
+  updateMessageStarState(evt.messageId, evt.isStarred);
+});
+
 client.socket.on('typing_indicator', (evt: TypingIndicatorEvent) => {
   if (evt.isTyping) {
     showTyping(evt.conversationId, evt.displayName);
@@ -2553,6 +2950,113 @@ document.querySelectorAll('[data-conv-id]').forEach((el) => {
 
 ## Changelog
 
+### v1.2.7
+- **New: `syncApi` — offline delta sync for mobile** — Two new REST endpoints let the mobile app pull all changes since a given timestamp without a full refetch. Call `syncApi.pull(since)` on every socket reconnect to get cross-conversation deltas; call `syncApi.pullConversation(convId, since?)` when opening a stale conversation (or on fresh install with no `since`). When the gap exceeds the stale threshold (default 30 days, env: `CHAT_SYNC_STALE_DAYS`) the server sets `stale: true` and returns no data — the app lazy-syncs each conversation as the user opens it. See [`syncApi`](#sync-api-syncapi) for full reference.
+- **New: `message_star_updated` socket event — real-time star sync across devices** — When the current user stars or unstars a message, the server now emits `message_star_updated` to their personal socket room. All other connected devices of the same user receive the event and update their local message cache automatically — no refetch needed. Payload: `{ messageId: string; conversationId: string; isStarred: boolean }`. New exported type: `MessageStarUpdatedEvent`. Web and RN `SocketProvider` handle this event internally.
+- **New: Soft-delete for unstar — offline sync support** — Unstar is no longer a hard delete on `chat_message_stars`. The record is now soft-deleted (`isActive: false`, `unstarredAt` timestamp set) so delta sync queries (`updatedAt > since`) can detect both star and unstar events. All `getStarredMessages` queries filter `isActive: true` — no visible behaviour change.
+- **New: `updatedAt` on `chat_conversation_participants`** — Participant documents now carry `updatedAt` (Mongoose timestamps). Enables delta sync queries to detect mute, pin, role, and removal changes since a given timestamp.
+- **New: Sync indexes** — Five new MongoDB indexes added: `{ conversationId, updatedAt }` on `chat_messages`, `{ userId, tenantId, updatedAt }` on `chat_conversation_participants`, `{ userId, tenantId, updatedAt }` on `chat_message_stars`, `{ conversationId, reactedAt }` on `chat_message_reactions`, `{ conversationId, readAt }` on `chat_message_reads`. Added idempotently at startup — no manual migration needed.
+- **Migrations 003 & 004** — `003_backfill_participant_updatedAt`: sets `updatedAt = joinedAt` on all existing participant documents. `004_backfill_star_isActive`: sets `isActive: true` on all existing star records. Both run automatically on first deploy and are idempotent.
+- **New exported types:** `CrossConversationSyncResponse`, `ConversationSyncResponse`, `SyncReadReceipt`, `SyncDeletedForMe`, `SyncParticipantChange`, `SyncStarEntry`, `SyncReactions`.
+- **No breaking changes** — all additions are purely additive. Existing API contracts, socket events, and type shapes are unchanged.
+
+### v1.2.6
+
+- **New: Clear / Delete Chat — hide any conversation without affecting other participants** — `conversationsApi.delete(conversationId)` is now available to any participant (no admin role required) on both DMs and groups. It hides the conversation from the caller's list only; all other participants are unaffected.
+
+  | Scenario | Call | Effect |
+  |---|---|---|
+  | **Delete Chat** (DM) | `conversationsApi.delete(id)` | Hidden from list, periods wiped. Re-opens with new history only when other party messages. |
+  | **Exit Group** | `conversationsApi.leave(id)` | Caller inactive, stays read-only. Server auto-promotes admin if needed. |
+  | **Exit and Delete** | `conversationsApi.leave(id, true)` | Atomic exit + hide. Periods wiped. |
+  | **Delete Group** (post-exit) | `conversationsApi.delete(id)` | Hides the already-exited entry. Others unaffected. |
+
+  ```typescript
+  // Delete a DM ("Delete Chat")
+  await conversationsApi.delete(dmConversationId);
+
+  // Exit and Delete a group
+  await conversationsApi.leave(groupId, true);
+
+  // Socket event fired to the caller's own sockets
+  socket.on('conversation_deleted', ({ conversationId }) => {
+    removeFromList(conversationId);
+    if (activeConversationId === conversationId) navigateBackToList();
+  });
+  ```
+
+  **Web SDK (`useConversations`):** `leaveGroup` / `leaveAndDeleteGroup` / `deleteGroup` mutations — optimistic cache update, no manual invalidation needed.  
+  **RN SDK (`useConversations`):** `leaveGroup` / `leaveAndDeleteGroup` / `deleteConversation` mutations — same behaviour.
+
+  **Message history after re-add:** periods wiped on `delete()` / `leave(true)` — only messages from the re-add point onwards visible on rejoin. Plain `leave()` without delete preserves prior history windows.
+
+- **New: Inactive & Reactivate user — server-enforced deactivation and fresh-start reactivation** — When a user account is set to `inactive` (self-service builtin, or external user-service sync), the server applies "self-left + delete" atomically across all surfaces:
+
+  | Action | Effect |
+  |---|---|
+  | Refresh tokens | All revoked — no new access tokens |
+  | Device tokens | All disabled — push stops immediately |
+  | Redis caches | `chatuser:`, `shadow:builtin:`, `shadow:<tenant>:` busted atomically |
+  | Groups | `participant_left` to remaining members, admin auto-promoted, periods wiped |
+  | DMs | Hidden silently, periods wiped |
+  | Live socket | Force-disconnected, `user_offline` broadcast fires |
+  | Socket cache-hit (non-builtin) | DB status re-checked on every connect — no 5-min bypass |
+  | `addParticipants` / `createGroup` | Inactive IDs silently filtered before insert |
+  | Blocked users list | Deactivated accounts excluded automatically |
+
+  **On reactivation:** device tokens re-enabled, user cache busted, conversation list intentionally empty (fresh start). DMs reopen when other party messages — new history only.
+
+  **SDK resilience (v1.2.6+):** RN `SocketProvider` retries token refresh up to 5× on `connect_error` auth failures before stopping. Web `SocketProvider` calls `logout()` after 5 retries — shows login screen instead of frozen stale UI.
+
+  **No integration changes required.** Clients receive standard `participant_left` / `user_offline` events. See [Step 6b — Inactive Users](docs/integration-guide.html#step-inactive-user) for the complete client-side handling pattern.
+
+- **New: Removed/left users see frozen group state — name, icon, description, and member list as of exit time** — Group conversations now serve a historically accurate snapshot to removed or self-exited users instead of live data. The `name`, `description`, `iconUrl`, and `participantCount` fields are frozen at the moment the user left. The `participants` array reflects who was in the group at that exact time (not the current active members). No integration changes required — the response shape is identical; values are simply frozen for inactive participants. Existing code that filters `participants` by `p.isActive !== false` continues to work correctly. Use `conversation.participantCount` (not `participants.length`) for member count display.
+
+- **New: Structured error layer — `AntzChatError` class hierarchy** — All SDK errors (REST and socket) are now instances of typed error classes instead of raw `AxiosError` objects or plain `Error` strings. Each error carries a machine-readable `code`, `retryable` boolean, and diagnostic `context` object.
+
+  Five subclasses cover every failure category:
+
+  | Class | Codes | Source |
+  |---|---|---|
+  | `AntzChatAuthError` | `SESSION_EXPIRED`, `AUTH_FAILED` | 401 |
+  | `AntzChatValidationError` | `VALIDATION_ERROR` | 400 / 422; `.fields` array for multi-field errors |
+  | `AntzChatPermissionError` | `PERMISSION_DENIED` | 403 |
+  | `AntzChatNetworkError` | `NETWORK_ERROR`, `SOCKET_TIMEOUT`, `SOCKET_NOT_CONNECTED`, `SEND_QUEUE_FULL`, `MESSAGE_DROPPED`, `RATE_LIMITED` | Network, socket, queue |
+  | `AntzChatServerError` | `SERVER_ERROR`, `NOT_FOUND` | 5xx, 404 |
+
+  Transit-encrypted error bodies are decrypted before normalisation. If decryption fails, `context.decryptionFailed = true` is set and the error class is still determined correctly from the HTTP status code.
+
+  **Backward compatible — no integration changes required.** All new classes extend native `Error` so existing `catch (err)` blocks work unchanged. Opt into typed handling by importing the classes:
+
+  ```typescript
+  import { AntzChatAuthError, AntzChatNetworkError } from '@antzsoft/chat-core';
+
+  try {
+    await authApi.login(credentials);
+  } catch (err) {
+    if (err instanceof AntzChatAuthError)       redirectToLogin();
+    else if (err instanceof AntzChatNetworkError && err.retryable) retry();
+  }
+  ```
+
+  See [Error Handling](#error-handling) for full reference.
+
+### v1.2.5
+
+- **New: Transit session decoupled from socket — `createRestTransitSession()` exported** — Previously the transit encryption session was established exclusively via the socket ECDH handshake. The session key was unavailable until the socket connected, blocking encrypted HTTP requests that needed to fire before the socket (e.g. notification action replies when the app is killed). A new `POST /crypto/session` REST endpoint performs the full ECDH exchange over HTTP. `createRestTransitSession(apiUrl)` is exported from the core SDK; the axios client uses it automatically when a session is needed before the socket is ready. **No integration changes required** for standard SDK usage.
+
+  ```typescript
+  import { createRestTransitSession } from '@antzsoft/chat-core';
+  // RN / Hermes — uses @noble/curves + @noble/ciphers
+  import { rnCreateRestTransitSession } from '@antzsoft/chat-rn-sdk';
+
+  // In a background notification reply handler (app killed, no socket):
+  const session = await rnCreateRestTransitSession('https://api.yourapp.com/api/v1');
+  // session.sessionId + session.sessionKey ready for encrypting REST calls manually
+  ```
+
+- **New: `rnCreateRestTransitSession()` exported from `@antzsoft/chat-rn-sdk`** — Hermes-compatible wrapper using `@noble/curves` (X25519) and `@noble/ciphers` (AES-256-GCM). Use in background notification reply handlers when the main app is not running and no socket can be established.
+
 ### v1.2.4
 - **New: Chunked multipart upload for files ≥ 10 MB (S3 and local)** — Files at or above 10 MB on S3 now use the S3 multipart upload protocol (`CreateMultipartUpload` → parallel `UploadPart` per 10 MB chunk → `CompleteMultipartUpload`) instead of a single presigned POST. Benefits: resumable on network failure, parallel part uploads (max 3 concurrent), no single-request timeout risk, supports files up to 5 TB. Files below 10 MB continue to use the existing single-part presigned POST flow unchanged. Local provider also uses chunked multipart for files ≥ 10 MB (parts land in a staging directory, assembled on complete). Azure is unaffected (stays presigned PUT). **No integration changes required for Web and RN SDK users** — `webUploadPartFn` and `rnUploadPartFn` are wired in automatically. Node.js / custom integrators must supply `platformUploadPartFn` to `uploadBatch` to enable chunked uploads; without it the multipart path is skipped and files fail if they exceed the S3 single-PUT limit.
 - **New: `storageApi.completeMultipartUpload(fileId, uploadId, parts)`** — Completes an in-progress S3 multipart upload, assembling all parts and transitioning the file record to active. Called automatically by `uploadBatch` — only needed for custom manual upload flows.