@antzsoft/chat-core 1.2.6 → 1.2.7

package/README.md

@@ -1701,6 +1701,173 @@ 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.
@@ -2050,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. |
@@ -2063,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. |
 
@@ -2073,6 +2241,7 @@ import type {
   MessageUpdatedEvent,
   MessageDeletedEvent,
   ReactionUpdatedEvent,
+  MessageStarUpdatedEvent,
   TypingIndicatorEvent,
   UserStatusEvent,
   ReadReceiptEvent,
@@ -2096,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);
@@ -2776,6 +2950,16 @@ 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.

package/dist/index.cjs

@@ -142,6 +142,7 @@ __export(src_exports, {
   setTransitSession: () => setTransitSession,
   socketEmit: () => socketEmit,
   storageApi: () => storageApi,
+  syncApi: () => syncApi,
   tryGetSocket: () => tryGetSocket,
   uploadBatch: () => uploadBatch,
   useChatStore: () => useChatStore,
@@ -840,6 +841,30 @@ var authApi = {
   }
 };
 
+// src/api/sync.ts
+var syncApi = {
+  /**
+   * Cross-conversation delta sync — call on every socket reconnect.
+   * `since` is the ISO timestamp returned as `syncedAt` from the previous call.
+   * Returns `stale: true` (with empty arrays) when the gap exceeds 60 days —
+   * the app should mark all conversations `needs_refresh` and lazy-sync on open.
+   */
+  pull(since) {
+    return getApiClient().get("/sync", { params: { since } }).then((r) => r.data);
+  },
+  /**
+   * Per-conversation delta sync — call when a conversation has `needs_refresh = true`
+   * or on fresh install (omit `since` to receive the full message history).
+   * Covers messages, deletedForMe, full reaction state, stars, participant changes,
+   * and read receipts — everything needed to make local SQLite authoritative.
+   */
+  pullConversation(conversationId, since) {
+    return getApiClient().get(`/conversations/${conversationId}/sync`, {
+      params: since ? { since } : {}
+    }).then((r) => r.data);
+  }
+};
+
 // src/api/app-config.ts
 var appConfigApi = {
   async get() {
@@ -1974,6 +1999,7 @@ var AntzChatClient = class {
   setTransitSession,
   socketEmit,
   storageApi,
+  syncApi,
   tryGetSocket,
   uploadBatch,
   useChatStore,