@antzsoft/chat-core 1.2.4 → 1.2.6

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,197 @@ const config = await appConfigApi.get();
 
 ---
 
+## 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
@@ -2553,6 +2776,103 @@ document.querySelectorAll('[data-conv-id]').forEach((el) => {
 
 ## Changelog
 
+### 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.