@antzsoft/chat-core 1.0.0

package/README.md

@@ -0,0 +1,1508 @@
+# @antzsoft/chat-core
+
+Platform-agnostic TypeScript core for Antz Chat — API client, Socket.IO wrapper, Zustand stores, and a headless client class that works in browser, React Native (Expo or bare), and Node.js.
+
+[![npm version](https://img.shields.io/npm/v/@antzsoft/chat-core)](https://www.npmjs.com/package/@antzsoft/chat-core)
+[![license](https://img.shields.io/npm/l/@antzsoft/chat-core)](./LICENSE)
+
+---
+
+## Overview
+
+`@antzsoft/chat-core` provides the shared foundation that both `@antzsoft/chat-web-sdk` and `@antzsoft/chat-rn-sdk` are built on. You can also use it directly when you need headless control — bot integrations, custom UIs, server-side tooling, or any environment that doesn't match the higher-level SDK's assumptions.
+
+**Key capabilities:**
+
+- Axios HTTP client with automatic token injection, refresh handling, and multi-tenant headers
+- Socket.IO wrapper with typed event emitters, ack-based operations, and connection-state management
+- Zustand auth store with platform-portable token persistence
+- Zustand chat store for UI state (active conversation, typing indicators, online presence, replies)
+- `AntzChatClient` — a single class that wires everything together for headless use
+- Full TypeScript types for all entities, API payloads, and socket events
+
+The package ships both ESM (`dist/index.js`) and CJS (`dist/index.cjs`) builds, plus `.d.ts` declarations.
+
+---
+
+## Installation
+
+```bash
+npm install @antzsoft/chat-core
+```
+
+`axios`, `socket.io-client`, and `zustand` are regular dependencies — they are bundled in the package and require no separate install. There are no peer dependencies.
+
+---
+
+## Using This SDK Independently (Custom UI)
+
+`@antzsoft/chat-core` is a **fully standalone SDK**. You do not need `@antzsoft/chat-web-sdk` or `@antzsoft/chat-rn-sdk` to build a complete chat app — those packages only add pre-built UI components. This package gives you everything needed to build your own UI on any platform.
+
+### What you get out of the box
+
+| Capability | What the SDK provides |
+|---|---|
+| Authentication | Login, register, logout, token refresh (automatic on 401) |
+| Conversations | List, create (group/DM), update, delete, mute, pin, leave, manage members |
+| Messages | Send, edit, delete, react, star, pin, search, paginate |
+| File uploads | Presigned URL pipeline — request URL → upload binary → confirm |
+| Real-time | Socket.IO wrapper — send/receive messages, typing, read receipts, presence |
+| State management | Zustand auth store (persisted) + chat store (typing users, online status, reply/edit state) |
+| Push notifications | Device token registration/removal API |
+| TypeScript | Full types for every entity, API payload, and socket event |
+
+### What you must provide
+
+The SDK has two required adapters that differ between platforms. You write them once — they are simple wrappers:
+
+#### 1. `persistStorage` — token persistence
+
+The SDK stores auth tokens under the key `"antz-chat-auth"` using this adapter. Tokens survive page reloads (web) or app restarts (RN) if you point it at a persistent store.
+
+**Why it's required:** The SDK is platform-agnostic — it can't assume `localStorage` exists (Node.js, RN) or `AsyncStorage` exists (web, Node.js). You tell it where to store tokens.
+
+```typescript
+// Browser — localStorage
+const persistStorage = {
+  getItem: (key: string) => localStorage.getItem(key),
+  setItem: (key: string, value: string) => localStorage.setItem(key, value),
+  removeItem: (key: string) => localStorage.removeItem(key),
+};
+
+// React Native — AsyncStorage
+import AsyncStorage from '@react-native-async-storage/async-storage';
+const persistStorage = {
+  getItem: (key: string) => AsyncStorage.getItem(key),
+  setItem: (key: string, value: string) => AsyncStorage.setItem(key, value),
+  removeItem: (key: string) => AsyncStorage.removeItem(key),
+};
+
+// Node.js / server — in-memory (tokens lost on restart, fine for bots)
+const _store: Record<string, string> = {};
+const persistStorage = {
+  getItem: (key: string) => _store[key] ?? null,
+  setItem: (key: string, value: string) => { _store[key] = value; },
+  removeItem: (key: string) => { delete _store[key]; },
+};
+```
+
+#### 2. `platformUploadFn` — binary file upload
+
+The SDK handles the full upload pipeline (requesting presigned URLs, confirming uploads) but delegates the actual binary transfer to this function. This is because the HTTP APIs differ between platforms — XHR on web, fetch/FileSystem on RN, fs on Node.js.
+
+**Why it's required:** Sending binary data to S3/GCS presigned URLs works differently on each platform. You provide the right implementation for your environment.
+
+```typescript
+// Browser — XHR with progress reporting
+const platformUploadFn = async (presigned, file, onProgress) => {
+  await new Promise<void>((resolve, reject) => {
+    const xhr = new XMLHttpRequest();
+    xhr.open(presigned.method, presigned.uploadUrl);
+    Object.entries(presigned.headers).forEach(([k, v]) => xhr.setRequestHeader(k, v));
+    xhr.upload.onprogress = (e) => onProgress?.(e.loaded / e.total);
+    xhr.onload = () => xhr.status < 400 ? resolve() : reject(new Error(`${xhr.status}`));
+    xhr.onerror = () => reject(new Error('Network error'));
+    if (presigned.method === 'PUT') {
+      fetch(file.uri).then(r => r.blob()).then(blob => xhr.send(blob));
+    } else {
+      const fd = new FormData();
+      Object.entries(presigned.fields ?? {}).forEach(([k, v]) => fd.append(k, v));
+      fetch(file.uri).then(r => r.blob()).then(blob => { fd.append('file', blob, file.name); xhr.send(fd); });
+    }
+  });
+};
+
+// React Native — fetch (works on Expo and bare RN)
+const platformUploadFn = async (presigned, file, onProgress) => {
+  onProgress?.(0);
+  const res = await fetch(presigned.uploadUrl, {
+    method: presigned.method,
+    headers: presigned.headers,
+    body: { uri: file.uri, name: file.name, type: file.type } as any,
+  });
+  if (!res.ok) throw new Error(`Upload failed: ${res.status}`);
+  onProgress?.(1);
+};
+
+// Node.js — fs + fetch (Node 18+)
+import { readFileSync } from 'fs';
+const platformUploadFn = async (presigned, file) => {
+  const body = readFileSync(file.uri.replace('file://', ''));
+  const res = await fetch(presigned.uploadUrl, {
+    method: presigned.method,
+    headers: presigned.headers,
+    body,
+  });
+  if (!res.ok) throw new Error(`Upload failed: ${res.status}`);
+};
+```
+
+> **Note:** If your app does not use file uploads at all, you can pass a no-op:
+> ```typescript
+> const platformUploadFn = async () => {};
+> ```
+
+### Minimum setup — 5 lines
+
+```typescript
+import { AntzChatClient } from '@antzsoft/chat-core';
+
+const client = new AntzChatClient({
+  apiUrl: 'https://your-server.com/api/v1',
+  persistStorage,    // your adapter from above
+  platformUploadFn,  // your adapter from above
+});
+
+await client.auth.login({ email: 'user@example.com', password: 'secret' });
+await client.connect(); // opens socket
+
+client.socket.on('new_message', (evt) => console.log(evt.message));
+client.socket.emit.joinRoom('your-conversation-id');
+```
+
+### Authentication options
+
+```typescript
+// Option 1 — SDK manages login/logout (built-in auth)
+await client.auth.login({ email, password });
+
+// Option 2 — pre-authenticated token from your own auth system
+const client = new AntzChatClient({ apiUrl, persistStorage, platformUploadFn, authToken: 'eyJ...' });
+
+// Option 3 — dynamic token provider (SSO, token rotation)
+const client = new AntzChatClient({
+  apiUrl, persistStorage, platformUploadFn,
+  authProvider: async () => {
+    const token = await yourApp.getAccessToken(); // your auth library
+    return token;
+  },
+});
+```
+
+### What you build yourself
+
+When using core SDK directly, you are responsible for building:
+- Your own UI components (conversation list, message bubbles, input box, etc.)
+- Wiring socket events to your UI state (the `useChatStore` Zustand store helps with this)
+- File picker integration (to produce `UploadableFile` objects for `uploadFiles`)
+
+The rest of this README documents all the APIs, stores, types, and socket events in full detail.
+
+---
+
+## Quick Start
+
+The fastest way to go headless: instantiate `AntzChatClient`, connect, and start listening.
+
+```typescript
+import {
+  AntzChatClient,
+  type AntzChatConfig,
+  type NewMessageEvent,
+} from '@antzsoft/chat-core';
+
+// Minimal localStorage adapter (browser)
+const localStorageAdapter = {
+  getItem: (key: string) => localStorage.getItem(key),
+  setItem: (key: string, value: string) => localStorage.setItem(key, value),
+  removeItem: (key: string) => localStorage.removeItem(key),
+};
+
+// Platform upload function (browser — XHR with progress)
+const platformUploadFn = async (presigned, file, onProgress) => {
+  await new Promise<void>((resolve, reject) => {
+    const xhr = new XMLHttpRequest();
+    xhr.open(presigned.method, presigned.uploadUrl);
+    Object.entries(presigned.headers).forEach(([k, v]) => xhr.setRequestHeader(k, v));
+    xhr.upload.onprogress = (e) => onProgress?.(e.loaded / e.total);
+    xhr.onload = () => (xhr.status < 400 ? resolve() : reject(new Error(`Upload failed: ${xhr.status}`)));
+    xhr.onerror = () => reject(new Error('Network error during upload'));
+    xhr.send(file.uri ? null : (file as any)); // blob or body per presigned.method
+  });
+};
+
+const config: AntzChatConfig = {
+  apiUrl: 'https://api.yourapp.com/api/v1',
+  persistStorage: localStorageAdapter,
+  platformUploadFn,
+};
+
+const client = new AntzChatClient(config);
+
+// Log in (stores tokens automatically)
+const { user, tokens } = await client.auth.login({ email: 'user@example.com', password: 'secret' });
+console.log('Logged in as', user.displayName);
+
+// Open a socket connection
+await client.connect();
+
+// Listen for incoming messages
+client.socket.on('new_message', (event: NewMessageEvent) => {
+  console.log('[new message]', event.message.content.text);
+});
+
+// Join a conversation room
+client.socket.emit.joinRoom('conv-123');
+
+// Send a message over the socket
+await client.socket.emit.sendMessage({
+  conversationId: 'conv-123',
+  text: 'Hello!',
+  tempId: crypto.randomUUID(),
+});
+
+// Or use the REST API directly
+const history = await client.messages.list('conv-123', { limit: 50 });
+console.log('Loaded', history.data.length, 'messages');
+
+// Clean up
+client.disconnect();
+```
+
+---
+
+## Configuration
+
+### `AntzChatConfig`
+
+```typescript
+interface AntzChatConfig {
+  /**
+   * Base URL for all REST API requests.
+   * Include the versioned path segment — e.g. "https://api.yourapp.com/api/v1".
+   * Required.
+   */
+  apiUrl: string;
+
+  /**
+   * Platform-specific function that performs the actual binary upload
+   * to a presigned URL. The core never touches binary data directly —
+   * it delegates to this function so the same codebase works on web and RN.
+   * Required.
+   */
+  platformUploadFn: PlatformUploadFn;
+
+  /**
+   * Key-value storage adapter for auth token persistence.
+   * Web: wrap localStorage. RN: wrap AsyncStorage.
+   * Required.
+   */
+  persistStorage: PersistStorage;
+
+  /**
+   * WebSocket server URL. Defaults to apiUrl with any "/api/vN" suffix stripped.
+   * The socket connects to "{socketUrl}/chat".
+   * Optional.
+   */
+  socketUrl?: string;
+
+  /**
+   * Static JWT. Pass when you have a token from outside the SDK
+   * (e.g. SSO flow completed by the host app). Skips the login step.
+   * Use this OR authProvider, not both.
+   * Optional.
+   */
+  authToken?: string;
+
+  /**
+   * Async function that returns a fresh access token. Called before every
+   * request and on socket reconnect. Preferred when the host app manages
+   * its own auth lifecycle.
+   * Optional.
+   */
+  authProvider?: () => Promise<string>;
+
+  /**
+   * Tenant identifier for multi-tenant backends.
+   * Sent as the "X-Tenant-ID" request header when provided.
+   * Optional.
+   */
+  tenantId?: string;
+
+  /**
+   * Encryption mode. Must match the server's ENCRYPTION_MODE env var.
+   * Default: 'none'.
+   */
+  encryptionMode?: 'none' | 'server';
+
+  /**
+   * Fine-grained upload constraints and callbacks.
+   * Optional — sensible defaults are applied for all sub-fields.
+   */
+  upload?: UploadConfig;
+}
+```
+
+### `PersistStorage`
+
+Supports both synchronous (localStorage) and asynchronous (AsyncStorage) storage backends.
+
+```typescript
+interface PersistStorage {
+  getItem(key: string): string | null | Promise<string | null>;
+  setItem(key: string, value: string): void | Promise<void>;
+  removeItem(key: string): void | Promise<void>;
+}
+```
+
+**Web (localStorage):**
+
+```typescript
+const persistStorage: PersistStorage = {
+  getItem: (key) => localStorage.getItem(key),
+  setItem: (key, value) => localStorage.setItem(key, value),
+  removeItem: (key) => localStorage.removeItem(key),
+};
+```
+
+**React Native (AsyncStorage):**
+
+```typescript
+import AsyncStorage from '@react-native-async-storage/async-storage';
+
+const persistStorage: PersistStorage = {
+  getItem: (key) => AsyncStorage.getItem(key),
+  setItem: (key, value) => AsyncStorage.setItem(key, value),
+  removeItem: (key) => AsyncStorage.removeItem(key),
+};
+```
+
+### `PlatformUploadFn`
+
+The core requests a presigned URL from the server, then hands the presigned response and the local file descriptor to this function. The function is responsible for the actual HTTP upload and for calling `onProgress` with a 0–1 fraction.
+
+```typescript
+type PlatformUploadFn = (
+  presigned: PresignedUrlResponse,
+  file: UploadableFile,
+  onProgress?: (pct: number) => void,
+) => Promise<void>;
+```
+
+**Web implementation (XHR):**
+
+```typescript
+const platformUploadFn: PlatformUploadFn = (presigned, file, onProgress) =>
+  new Promise((resolve, reject) => {
+    const xhr = new XMLHttpRequest();
+    xhr.open(presigned.method, presigned.uploadUrl);
+    Object.entries(presigned.headers).forEach(([k, v]) => xhr.setRequestHeader(k, v));
+    xhr.upload.onprogress = (e) => onProgress?.(e.loaded / e.total);
+    xhr.onload = () => (xhr.status < 400 ? resolve() : reject(new Error(`${xhr.status}`)));
+    xhr.onerror = () => reject(new Error('Network error'));
+
+    // For PUT: send the raw blob. For POST (S3-style): send FormData with fields.
+    if (presigned.method === 'PUT') {
+      fetch(file.uri)
+        .then((r) => r.blob())
+        .then((blob) => xhr.send(blob));
+    } else {
+      const fd = new FormData();
+      Object.entries(presigned.fields ?? {}).forEach(([k, v]) => fd.append(k, v));
+      fetch(file.uri)
+        .then((r) => r.blob())
+        .then((blob) => { fd.append('file', blob, file.name); xhr.send(fd); });
+    }
+  });
+```
+
+**React Native implementation (fetch):**
+
+```typescript
+import * as FileSystem from 'expo-file-system';
+
+const platformUploadFn: PlatformUploadFn = async (presigned, file, onProgress) => {
+  const callback = (progress: FileSystem.UploadProgressData) => {
+    onProgress?.(progress.totalBytesSent / progress.totalBytesExpectedToSend);
+  };
+
+  const uploadTask = FileSystem.createUploadTask(
+    presigned.uploadUrl,
+    file.uri,
+    {
+      httpMethod: presigned.method,
+      headers: presigned.headers,
+      uploadType: FileSystem.FileSystemUploadType.BINARY_CONTENT,
+    },
+    callback,
+  );
+
+  const result = await uploadTask.uploadAsync();
+  if (!result || result.status >= 400) {
+    throw new Error(`Upload failed: ${result?.status}`);
+  }
+};
+```
+
+### `UploadConfig`
+
+```typescript
+interface UploadConfig {
+  /**
+   * File size limits in MB. Pass a single number to apply uniformly,
+   * or per-type limits. Defaults: image 5, video 25, audio 10, document 10.
+   */
+  maxFileSizeMB?: number | {
+    image?: number;
+    video?: number;
+    audio?: number;
+    document?: number;
+    default?: number;
+  };
+
+  /** Max attachments per message. Default: 10. */
+  maxFilesPerMessage?: number;
+
+  /** Restrict which file categories are allowed. Default: all four. */
+  allowedTypes?: Array<'image' | 'video' | 'audio' | 'document'>;
+
+  /** Called when a file fails local validation or the upload itself fails. */
+  onUploadError?: (file: UploadableFile, error: Error) => void;
+
+  /** Called with 0–100 aggregate progress during a batch upload. */
+  onProgress?: (progress: number) => void;
+}
+```
+
+**Example with per-type limits:**
+
+```typescript
+const config: AntzChatConfig = {
+  apiUrl: 'https://api.yourapp.com/api/v1',
+  persistStorage,
+  platformUploadFn,
+  upload: {
+    maxFileSizeMB: { image: 10, video: 50, audio: 20, document: 25 },
+    maxFilesPerMessage: 5,
+    allowedTypes: ['image', 'document'],
+    onUploadError: (file, err) => console.error(`Failed to upload ${file.name}:`, err),
+    onProgress: (pct) => setUploadProgress(pct),
+  },
+};
+```
+
+---
+
+## API Reference
+
+### `AntzChatClient` (Headless)
+
+A single class that initializes the API client, auth store, and socket in one shot. Use this when you need direct programmatic control and don't want to wire the internals yourself.
+
+```typescript
+class AntzChatClient {
+  readonly auth: typeof authApi;
+  readonly messages: typeof messagesApi;
+  readonly conversations: typeof conversationsApi;
+  readonly storage: typeof storageApi;
+  readonly socket: {
+    emit: typeof socketEmit;
+    on(event: string, handler: (...args: unknown[]) => void): void;
+    off(event: string, handler: (...args: unknown[]) => void): void;
+  };
+
+  constructor(config: AntzChatConfig);
+
+  /** Connect the Socket.IO client. Resolves when the connection is established. */
+  connect(): Promise<void>;
+
+  /** Disconnect the Socket.IO client and clear the socket singleton. */
+  disconnect(): void;
+
+  /**
+   * High-level batch upload. Requests presigned URLs, delegates binary upload
+   * to the configured platformUploadFn, and confirms each upload with the server.
+   */
+  uploadFiles(files: UploadableFile[], conversationId?: string): Promise<BatchUploadResult>;
+}
+```
+
+**Usage:**
+
+```typescript
+const client = new AntzChatClient(config);
+
+// Option A — SDK manages auth
+await client.auth.login({ email: 'user@example.com', password: 'secret' });
+
+// Option B — pre-authenticated token in config
+// const client = new AntzChatClient({ ...config, authToken: 'eyJ...' });
+
+await client.connect();
+
+// Listen to socket events
+client.socket.on('new_message', (evt: NewMessageEvent) => handleMessage(evt));
+
+// Emit socket events
+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 msgs  = await client.messages.list('conv-abc', { limit: 50 });
+
+// Upload files
+const result = await client.uploadFiles(
+  [{ uri: 'blob:http://...', name: 'photo.jpg', type: 'image/jpeg', size: 204800 }],
+  'conv-abc',
+);
+console.log('Uploaded:', result.successful);
+console.log('Failed:', result.failed);
+
+client.disconnect();
+```
+
+---
+
+### Auth API (`authApi`)
+
+```typescript
+import { authApi } from '@antzsoft/chat-core';
+```
+
+| Method | Signature | Description |
+|---|---|---|
+| `login` | `(credentials: LoginCredentials) => Promise<AuthResponse>` | Authenticate with email + password. Returns user and tokens. |
+| `register` | `(data: RegisterData) => Promise<AuthResponse>` | Create a new account. |
+| `refresh` | `(refreshToken: string) => Promise<AuthTokens>` | Exchange a refresh token for new tokens. The HTTP client handles this automatically on 401 — call manually only if needed. |
+| `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. |
+
+```typescript
+// Login
+const { user, tokens } = await authApi.login({ email: 'user@example.com', password: 'secret' });
+
+// Register
+const { user } = await authApi.register({
+  email: 'new@example.com',
+  password: 'hunter2',
+  username: 'newuser',
+  displayName: 'New User',
+  tenantId: 'tenant-xyz',
+});
+
+// Logout
+await authApi.logout(tokens.refreshToken);
+```
+
+---
+
+### Messages API (`messagesApi`)
+
+```typescript
+import { messagesApi } from '@antzsoft/chat-core';
+```
+
+| Method | Signature | Description |
+|---|---|---|
+| `list` | `(conversationId: string, params?: ListMessagesParams) => Promise<CursorPaginatedResponse<Message>>` | Fetch messages with cursor pagination. |
+| `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. |
+| `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. |
+| `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. |
+
+```typescript
+interface ListMessagesParams {
+  cursor?: string;       // Opaque cursor for pagination
+  limit?: number;        // Default decided by server
+  direction?: 'before' | 'after';
+}
+
+interface SendData {
+  text?: string;
+  attachments?: SendMessageAttachment[];
+  replyTo?: string;      // messageId of the message being replied to
+  tempId?: string;       // Client-generated ID for optimistic UI
+  isEncrypted?: boolean;
+}
+
+interface SearchParams {
+  query: string;
+  conversationId?: string;
+  page?: number;
+  limit?: number;
+}
+```
+
+```typescript
+// Cursor-paginated message history
+const page1 = await messagesApi.list('conv-abc', { limit: 50 });
+if (page1.meta.hasMore && page1.meta.nextCursor) {
+  const page2 = await messagesApi.list('conv-abc', {
+    cursor: page1.meta.nextCursor,
+    direction: 'before',
+    limit: 50,
+  });
+}
+
+// Send with a reply reference
+await messagesApi.send('conv-abc', {
+  text: 'Good point!',
+  replyTo: 'msg-456',
+  tempId: crypto.randomUUID(),
+});
+
+// Search
+const results = await messagesApi.search({ query: 'deployment', conversationId: 'conv-abc' });
+```
+
+---
+
+### Conversations API (`conversationsApi`)
+
+```typescript
+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. |
+| `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. |
+| `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. |
+| `updateParticipantRole` | `(conversationId: string, userId: string, role: 'admin' \| 'member') => Promise<Conversation>` | Promote or demote a participant. |
+| `mute` | `(conversationId: string, mutedUntil?: string) => Promise<void>` | Mute notifications. Pass an ISO date string to mute until a specific time. |
+| `unmute` | `(conversationId: string) => Promise<void>` | Unmute a conversation. |
+| `pin` | `(conversationId: string) => Promise<void>` | Pin a conversation to the top of the list. |
+| `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 CreateGroupData {
+  name: string;
+  description?: string;
+  icon?: string;          // Emoji or short string used as the group avatar
+  participantIds: string[];
+}
+
+interface CreateDirectData {
+  userId: string;
+}
+
+interface UpdateConversationData {
+  name?: string;
+  description?: string;
+  icon?: string;
+}
+```
+
+```typescript
+// Create a group
+const group = await conversationsApi.createGroup({
+  name: 'Engineering',
+  participantIds: ['user-a', 'user-b', 'user-c'],
+});
+
+// Start a DM
+const dm = await conversationsApi.createDirect({ userId: 'user-b' });
+
+// Add members
+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);
+```
+
+---
+
+### Storage API (`storageApi` and `uploadBatch`)
+
+```typescript
+import { storageApi, uploadBatch } from '@antzsoft/chat-core';
+```
+
+**`storageApi` methods:**
+
+| Method | Signature | Description |
+|---|---|---|
+| `requestPresignedUrl` | `(payload: PresignedUrlRequest) => Promise<PresignedUrlResponse>` | Request a single presigned upload URL. |
+| `requestPresignedUrlBatch` | `(files: PresignedUrlRequest[]) => Promise<{ urls: PresignedUrlResponse[]; errors: Array<{ filename: string; error: string }> }>` | Batch presigned URL request. |
+| `confirmUpload` | `(fileId: string) => Promise<FileResponse>` | Confirm that a binary upload is complete. Required after every upload. |
+| `getFile` | `(fileId: string) => Promise<FileResponse>` | Fetch file metadata. |
+| `getFileUrl` | `(fileId: string, expiresIn?: number) => Promise<{ url: string; expiresAt: string }>` | Get a fresh signed URL for an already-uploaded file. |
+| `deleteFile` | `(fileId: string) => Promise<void>` | Delete a file. |
+| `getConversationFiles` | `(conversationId: string, params?: { page?: number; limit?: number; type?: FileType }) => Promise<PaginatedResponse<FileResponse>>` | List all files shared in a conversation. |
+| `getMyFiles` | `(params?: { page?: number; limit?: number }) => Promise<PaginatedResponse<FileResponse>>` | List files uploaded by the current user. |
+
+**`uploadBatch` — high-level helper:**
+
+```typescript
+function uploadBatch(
+  files: UploadableFile[],
+  platformUploadFn: PlatformUploadFn,
+  conversationId?: string,
+  onProgress?: (pct: number) => void,
+): Promise<BatchUploadResult>
+```
+
+Handles the full upload pipeline: batch presign → parallel binary upload → confirm each file. Returns `{ successful: FileResponse[]; failed: Array<{ filename: string; error: string }> }`.
+
+```typescript
+// Manual: get a presigned URL, upload, confirm
+const presigned = await storageApi.requestPresignedUrl({
+  filename: 'report.pdf',
+  mimeType: 'application/pdf',
+  size: 512000,
+  conversationId: 'conv-abc',
+});
+await platformUploadFn(presigned, file, (pct) => console.log(`${pct * 100}%`));
+const fileRecord = await storageApi.confirmUpload(presigned.fileId);
+
+// High-level: let uploadBatch handle everything
+const result = await uploadBatch(
+  files,
+  platformUploadFn,
+  'conv-abc',
+  (pct) => setProgress(pct),
+);
+result.successful.forEach((f) => console.log('Uploaded:', f.url));
+result.failed.forEach((f) => console.error('Failed:', f.filename, f.error));
+```
+
+---
+
+### Devices API (`devicesApi`)
+
+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.
+
+```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. |
+
+```typescript
+type RegisterDeviceTokenPayload =
+  | {
+      deviceId: string;        // Stable UUID — generate once and persist
+      platform: 'ios' | 'android' | 'web';
+      provider: 'expo' | 'fcm' | 'apns';
+      token: string;           // The OS-issued push token
+      userAgent?: string;
+    }
+  | {
+      deviceId: string;
+      platform: 'web';
+      provider: 'web-push';
+      endpoint: string;        // PushSubscription.endpoint
+      p256dh: string;          // base64url key 'p256dh'
+      auth: string;            // base64url key 'auth'
+      userAgent?: string;
+    };
+```
+
+```typescript
+// Mobile (Expo)
+import * as Notifications from 'expo-notifications';
+
+const { data: expoPushToken } = await Notifications.getExpoPushTokenAsync();
+await devicesApi.register({
+  deviceId: await getStableDeviceId(),  // from SecureStore
+  platform: 'ios',
+  provider: 'expo',
+  token: expoPushToken,
+});
+
+// On logout
+await devicesApi.remove(deviceId);
+```
+
+---
+
+### Socket
+
+#### Connection management
+
+```typescript
+import {
+  connectSocket,
+  disconnectSocket,
+  reconnectSocket,
+  getSocketStatus,
+  onSocketStatus,
+} from '@antzsoft/chat-core';
+import type { SocketStatus } from '@antzsoft/chat-core';
+```
+
+| Function | Signature | Description |
+|---|---|---|
+| `connectSocket` | `(config: ResolvedConfig, getToken: () => string \| null \| undefined) => Promise<Socket>` | Initialize and connect the Socket.IO client. No-ops if already connected. |
+| `disconnectSocket` | `() => void` | Disconnect and clear the socket singleton. |
+| `reconnectSocket` | `(token: string) => void` | Update the auth token on the existing socket and reconnect. |
+| `getSocketStatus` | `() => SocketStatus` | Synchronously read the current connection status. |
+| `onSocketStatus` | `(listener: (status: SocketStatus) => void) => () => void` | Subscribe to status changes. Returns an unsubscribe function. |
+
+```typescript
+type SocketStatus = 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'error';
+```
+
+```typescript
+const unsubscribe = onSocketStatus((status) => {
+  if (status === 'connected') console.log('Socket ready');
+  if (status === 'error') console.error('Socket error — check network');
+});
+
+// Later, if the host app refreshes its own token:
+reconnectSocket(newAccessToken);
+
+// Cleanup
+unsubscribe();
+disconnectSocket();
+```
+
+#### `socketEmit` — outbound events
+
+```typescript
+import { socketEmit } from '@antzsoft/chat-core';
+```
+
+All emit methods that have server responses use a 5-second ack timeout and return a rejected promise on timeout or when the socket is not connected. Fire-and-forget methods silently no-op when disconnected.
+
+| Method | Signature | Behavior |
+|---|---|---|
+| `joinRoom` | `(conversationId: string) => void` | Join a conversation room to receive its events. Fire-and-forget. |
+| `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. |
+| `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. |
+| `unpinMessage` | `(messageId: string) => Promise<unknown>` | Unpin a message. Ack-based. |
+| `typing` | `(conversationId: string, isTyping: boolean) => void` | Broadcast typing status. Fire-and-forget. |
+| `markRead` | `(conversationId: string, messageId?: string) => void` | Mark messages read. Fire-and-forget. |
+| `getOnlineUsers` | `(userIds: string[]) => Promise<string[]>` | Query which of the given user IDs are online. Returns the online subset. |
+| `getTypingUsers` | `(conversationId: string) => Promise<unknown>` | Fetch users currently typing in a conversation. Ack-based. |
+
+```typescript
+// Join before sending
+socketEmit.joinRoom('conv-abc');
+
+// Send a message
+await socketEmit.sendMessage({
+  conversationId: 'conv-abc',
+  text: 'Hello!',
+  tempId: crypto.randomUUID(),
+});
+
+// Typing indicator
+socketEmit.typing('conv-abc', true);
+// ... user stops typing
+socketEmit.typing('conv-abc', false);
+
+// Mark messages read
+socketEmit.markRead('conv-abc');            // mark all unread
+socketEmit.markRead('conv-abc', 'msg-99'); // mark up to a specific message
+
+// Check presence
+const onlineIds = await socketEmit.getOnlineUsers(['user-a', 'user-b', 'user-c']);
+console.log('Online:', onlineIds); // ['user-a', 'user-c']
+```
+
+#### Socket events to listen on
+
+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. |
+
+```typescript
+import type {
+  NewMessageEvent,
+  MessageUpdatedEvent,
+  MessageDeletedEvent,
+  ReactionUpdatedEvent,
+  TypingIndicatorEvent,
+  UserStatusEvent,
+  ReadReceiptEvent,
+  MessageAckEvent,
+  MessagesDeliveredEvent,
+} from '@antzsoft/chat-core';
+
+client.socket.on('new_message', (evt: NewMessageEvent) => {
+  appendMessage(evt.message);
+});
+
+client.socket.on('message_updated', (evt: MessageUpdatedEvent) => {
+  updateMessageText(evt.messageId, evt.text);
+});
+
+client.socket.on('message_deleted', (evt: MessageDeletedEvent) => {
+  removeMessage(evt.messageId);
+});
+
+client.socket.on('reaction_updated', (evt: ReactionUpdatedEvent) => {
+  setMessageReactions(evt.messageId, evt.reactions);
+});
+
+client.socket.on('typing_indicator', (evt: TypingIndicatorEvent) => {
+  if (evt.isTyping) {
+    showTyping(evt.conversationId, evt.displayName);
+  } else {
+    hideTyping(evt.conversationId, evt.userId);
+  }
+});
+
+client.socket.on('read_receipt', (evt: ReadReceiptEvent) => {
+  markMessagesRead(evt.fullyReadMessageIds ?? []);
+});
+
+client.socket.on('message_ack', (evt: MessageAckEvent) => {
+  // Replace optimistic message
+  confirmOptimisticMessage(evt.tempId, evt.messageId, evt.status);
+});
+```
+
+---
+
+### Auth Store
+
+The auth store is a Zustand store that persists user and token state through the configured `PersistStorage` adapter under the key `"antz-chat-auth"`.
+
+```typescript
+import { initAuthStore, getAuthStore, resetAuthStore } from '@antzsoft/chat-core';
+```
+
+| Function | Description |
+|---|---|
+| `initAuthStore(storage: PersistStorage)` | Initialize the auth store singleton. Idempotent — safe to call multiple times. Returns `{ useAuthStore, authTokenStore }`. |
+| `getAuthStore()` | Retrieve the singleton after initialization. Throws if called before `initAuthStore`. |
+| `resetAuthStore()` | Clear the singleton (for testing or SDK teardown). |
+
+#### `useAuthStore` — Zustand store
+
+```typescript
+interface AuthState {
+  user: User | null;
+  tokens: AuthTokens | null;
+  isAuthenticated: boolean;
+  isLoading: boolean;
+  /** True once persisted state has been rehydrated from storage. */
+  isHydrated: boolean;
+
+  setAuth(user: User, tokens: AuthTokens): void;
+  setTokens(tokens: AuthTokens): void;
+  setUser(user: User): void;
+  logout(): void;
+  setLoading(loading: boolean): void;
+  setHydrated(hydrated: boolean): void;
+}
+```
+
+```typescript
+// In a React component (web or RN)
+const { useAuthStore } = getAuthStore();
+const user = useAuthStore((s) => s.user);
+const isAuthenticated = useAuthStore((s) => s.isAuthenticated);
+
+// Outside React — read state directly
+const { useAuthStore } = getAuthStore();
+const currentUser = useAuthStore.getState().user;
+```
+
+#### `authTokenStore` — raw token operations
+
+Thin synchronous wrapper used internally by the API client and socket for token access.
+
+```typescript
+const { authTokenStore } = getAuthStore();
+
+authTokenStore.getAccessToken();    // string | null | undefined
+authTokenStore.getRefreshToken();   // string | null | undefined
+authTokenStore.setTokens(tokens);  // update stored tokens
+authTokenStore.clearTokens();      // clear tokens and log out
+```
+
+---
+
+### Chat Store (`useChatStore`)
+
+A non-persisted Zustand store for transient UI state. Import and use in any component or hook.
+
+```typescript
+import { useChatStore } from '@antzsoft/chat-core';
+```
+
+#### State
+
+| Field | Type | Description |
+|---|---|---|
+| `activeConversationId` | `string \| null` | The currently open conversation. |
+| `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. |
+| `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. |
+
+#### Actions
+
+| Action | Signature | Description |
+|---|---|---|
+| `setActiveConversation` | `(id: string \| null) => void` | Set active conversation; clears `replyingTo` and `editingMessage`. |
+| `setPendingTarget` | `(target: { conversationId: string; messageId: string } \| null) => void` | Set scroll target for deep links. |
+| `addTypingUser` | `(conversationId: string, user: TypingUser) => void` | Add or refresh a typing user. De-duplicates by userId. |
+| `removeTypingUser` | `(conversationId: string, userId: string) => void` | Remove a user from the typing list. |
+| `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. |
+| `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. |
+| `setSidebarOpen` | `(open: boolean) => void` | Set sidebar state explicitly. |
+| `toggleGroupInfo` | `() => void` | Toggle group info panel. |
+| `setGroupInfoOpen` | `(open: boolean) => void` | Set group info panel state explicitly. |
+
+```typescript
+// In a component
+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) {
+    addTypingUser(evt.conversationId, {
+      userId: evt.userId,
+      displayName: evt.displayName,
+      avatarUrl: evt.avatarUrl,
+    });
+  } else {
+    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);
+  }
+});
+```
+
+---
+
+## Data Types
+
+### `User`
+
+```typescript
+interface User {
+  id: string;
+  tenantId: string;
+  email: string;
+  username: string;
+  displayName: string;
+  avatarUrl?: string;
+  phone?: string;
+  status: 'online' | 'offline' | 'away';
+  lastSeenAt?: string;   // ISO 8601
+  createdAt: string;
+  updatedAt: string;
+}
+```
+
+### `AuthTokens`
+
+```typescript
+interface AuthTokens {
+  accessToken: string;
+  refreshToken: string;
+  tokenType: string;   // 'Bearer'
+  expiresIn: number;   // seconds
+}
+```
+
+### `Message`
+
+```typescript
+interface Message {
+  id: string;
+  tenantId: string;
+  conversationId: string;
+  senderId: string;
+  content: MessageContent;
+  replyTo?: MessageReplyReference;
+  reactions: MessageReaction[];
+  status: 'sent' | 'delivered' | 'read' | 'failed' | 'deleted';
+  deliveryStatus?: 'sending' | 'sent' | 'delivered' | 'read' | 'failed';
+  isEdited: boolean;
+  editedAt?: string;
+  isStarred?: boolean;
+  isPinned?: boolean;
+  pinnedBy?: string;
+  pinnedAt?: string;
+  uploadProgress?: number;   // 0–100, present on optimistic messages
+  sentAt: string;
+  createdAt: string;
+  sender?: User;
+  readBy?: string[];
+  isEncrypted?: boolean;
+  encryptionMode?: 'none' | 'server' | 'e2ee';
+  encryptedContent?: EncryptedContent;
+}
+```
+
+### `MessageContent`
+
+```typescript
+interface MessageContent {
+  type: 'text' | 'attachment' | 'system';
+  text?: string;
+  attachments?: Attachment[];
+}
+```
+
+### `MessageReaction`
+
+```typescript
+interface MessageReaction {
+  emoji: string;
+  userIds: string[];
+  count: number;
+}
+```
+
+### `MessageReplyReference`
+
+```typescript
+interface MessageReplyReference {
+  messageId?: string;
+  contentPreview?: string;
+  senderName?: string;
+  // Present on optimistic messages before server confirmation
+  id?: string;
+  content?: MessageContent;
+  sender?: Pick<User, 'displayName' | 'avatarUrl'>;
+}
+```
+
+### `Conversation`
+
+```typescript
+interface Conversation {
+  id: string;
+  tenantId: string;
+  conversationType: 'direct' | 'group';
+  name?: string;
+  description?: string;
+  icon?: string;
+  iconUrl?: string;
+  participants: Participant[];
+  participantCount?: number;
+  settings?: ConversationSettings;
+  lastMessage?: Message;
+  createdBy?: string;
+  isActive: boolean;
+  createdAt: string;
+  updatedAt: string;
+  unreadCount?: number;
+  isPinned?: boolean;
+  isMuted?: boolean;
+  mutedUntil?: string;
+  encryptionMode?: 'none' | 'server' | 'e2ee';
+  isEncryptionEnabled?: boolean;
+  encryptionKey?: string;
+}
+
+interface ConversationSettings {
+  onlyAdminsCanMessage?: boolean;
+  onlyAdminsCanAddMembers?: boolean;
+}
+```
+
+### `Participant`
+
+```typescript
+interface Participant {
+  userId: string;
+  role: 'admin' | 'member';
+  joinedAt: string;
+  isActive?: boolean;
+  user?: User;
+}
+```
+
+### `Attachment`
+
+```typescript
+interface Attachment {
+  id: string;
+  type: 'image' | 'video' | 'audio' | 'document';
+  url: string;
+  thumbnailUrl?: string;
+  filename: string;
+  mimeType: string;
+  size: number;                                // bytes
+  dimensions?: { width: number; height: number };
+  duration?: number;                           // seconds, for audio/video
+  isUploading?: boolean;
+  uploadProgress?: number;                     // 0–100
+}
+```
+
+### `UploadableFile`
+
+Platform-agnostic file descriptor. Web builds it from a `File` object; RN builds it from a document/image picker result.
+
+```typescript
+interface UploadableFile {
+  uri: string;    // blob URL on web, file:// URI on RN
+  name: string;
+  type: string;   // MIME type, e.g. "image/jpeg"
+  size: number;   // bytes
+}
+```
+
+### `SendMessagePayload`
+
+```typescript
+interface SendMessagePayload {
+  conversationId: string;
+  text?: string;
+  attachments?: SendMessageAttachment[];
+  replyTo?: string;           // messageId
+  tempId: string;             // client-generated; echoed back in message_ack
+  encryptedContent?: EncryptedContent;
+  isEncrypted?: boolean;
+}
+
+interface SendMessageAttachment {
+  fileId: string;
+  type: 'image' | 'video' | 'audio' | 'document';
+  url: string;
+  thumbnailUrl?: string;
+  filename: string;
+  mimeType: string;
+  size: number;
+}
+```
+
+### Socket event types
+
+```typescript
+interface NewMessageEvent {
+  tempId?: string;
+  senderName?: string;
+  senderAvatarUrl?: string;
+  message: Message;
+}
+
+interface MessageUpdatedEvent {
+  messageId: string;
+  conversationId: string;
+  text: string;
+  editedAt: string;
+}
+
+interface MessageDeletedEvent {
+  messageId: string;
+  conversationId: string;
+}
+
+interface ReactionUpdatedEvent {
+  messageId: string;
+  conversationId: string;
+  reactions: MessageReaction[];
+}
+
+interface TypingIndicatorEvent {
+  conversationId: string;
+  userId: string;
+  username: string;
+  displayName: string;
+  avatarUrl?: string;
+  isTyping: boolean;
+}
+
+interface UserStatusEvent {
+  userId: string;
+  status: 'online' | 'offline' | 'away';
+  lastSeenAt?: string;
+}
+
+interface ReadReceiptEvent {
+  conversationId: string;
+  messageId: string;
+  userId: string;
+  readAt: string;
+  updatedMessageIds?: string[];
+  fullyReadMessageIds?: string[];
+}
+
+interface MessageAckEvent {
+  tempId: string;      // the client-generated ID you sent
+  messageId: string;   // the server-assigned real ID
+  status: MessageStatus;
+}
+
+interface MessagesDeliveredEvent {
+  conversationId: string;
+  messageIds: string[];
+  deliveredTo: string;
+  deliveredAt: string;
+}
+```
+
+---
+
+## Building a Custom Integration
+
+This example shows a complete headless Node.js integration — useful for bots, message archiving, or any backend consumer that needs to interact with Antz Chat.
+
+```typescript
+// node-bot.ts
+import {
+  AntzChatClient,
+  type AntzChatConfig,
+  type NewMessageEvent,
+  type UploadableFile,
+} from '@antzsoft/chat-core';
+import { readFileSync } from 'fs';
+
+// ─── 1. In-memory storage adapter for Node.js ───────────────────────────────
+const _store: Record<string, string> = {};
+const nodeStorage = {
+  getItem: (key: string) => _store[key] ?? null,
+  setItem: (key: string, value: string) => { _store[key] = value; },
+  removeItem: (key: string) => { delete _store[key]; },
+};
+
+// ─── 2. Node.js upload adapter using fetch ──────────────────────────────────
+const nodePlatformUploadFn: AntzChatConfig['platformUploadFn'] = async (presigned, file) => {
+  const body = readFileSync(file.uri.replace('file://', ''));
+  const res = await fetch(presigned.uploadUrl, {
+    method: presigned.method,
+    headers: presigned.headers,
+    body,
+  });
+  if (!res.ok) throw new Error(`Upload failed: ${res.status}`);
+};
+
+// ─── 3. Initialize the client ───────────────────────────────────────────────
+const client = new AntzChatClient({
+  apiUrl: 'https://api.yourapp.com/api/v1',
+  persistStorage: nodeStorage,
+  platformUploadFn: nodePlatformUploadFn,
+  tenantId: 'tenant-xyz',
+});
+
+// ─── 4. Authenticate ────────────────────────────────────────────────────────
+await client.auth.login({ email: 'bot@yourapp.com', password: process.env.BOT_PASSWORD! });
+
+// ─── 5. Connect socket ──────────────────────────────────────────────────────
+await client.connect();
+
+// ─── 6. Fetch conversations and join all rooms ──────────────────────────────
+const { data: conversations } = await client.conversations.list({ limit: 100 });
+for (const conv of conversations) {
+  client.socket.emit.joinRoom(conv.id);
+}
+
+// ─── 7. Listen and respond to messages ──────────────────────────────────────
+client.socket.on('new_message', async (evt: NewMessageEvent) => {
+  const { message } = evt;
+
+  // Ignore messages sent by the bot itself
+  const me = await client.auth.getMe();
+  if (message.senderId === me.id) return;
+
+  const text = message.content.text?.toLowerCase() ?? '';
+
+  if (text.includes('ping')) {
+    await client.socket.emit.sendMessage({
+      conversationId: message.conversationId,
+      text: 'Pong!',
+      tempId: crypto.randomUUID(),
+    });
+  }
+
+  // Mark message as read
+  client.socket.emit.markRead(message.conversationId, message.id);
+});
+
+// ─── 8. Graceful shutdown ───────────────────────────────────────────────────
+process.on('SIGINT', () => {
+  client.disconnect();
+  process.exit(0);
+});
+```
+
+**Custom UI (no framework):**
+
+```typescript
+// custom-ui.ts — vanilla browser without the web SDK
+import {
+  AntzChatClient,
+  useChatStore,
+  type NewMessageEvent,
+} from '@antzsoft/chat-core';
+
+const client = new AntzChatClient({ apiUrl, persistStorage, platformUploadFn });
+
+await client.auth.login({ email, password });
+await client.connect();
+
+// Sync socket events into the chat store
+client.socket.on('new_message', (evt: NewMessageEvent) => {
+  renderMessage(evt.message);
+  client.socket.emit.markRead(evt.message.conversationId, evt.message.id);
+});
+
+// Use chatStore for local UI state
+const { setActiveConversation, setReplyingTo } = useChatStore.getState();
+
+document.querySelectorAll('[data-conv-id]').forEach((el) => {
+  el.addEventListener('click', () => {
+    const convId = el.getAttribute('data-conv-id')!;
+    setActiveConversation(convId);
+    client.socket.emit.joinRoom(convId);
+  });
+});
+```
+
+---
+
+## License
+
+MIT