@antzsoft/chat-core 1.3.2 → 1.3.3

package/README.md

@@ -759,6 +759,7 @@ import { messagesApi } from '@antzsoft/chat-core';
 | `getLastRead` | `(conversationId: string) => Promise<{ lastReadMessageId: string \| null; lastReadAt: string \| null }>` | Fetch the current user's last-read pointer for a conversation. Use on initial load; after that the store is kept live by socket events. |
 | `markAsRead` | `(conversationId: string, messageId?: string) => Promise<void>` | Mark messages as read via REST. |
 | `getReceipts` | `(messageId: string) => Promise<MessageReceiptsResponse>` | Fetch per-user read and delivery receipts for a single message, with resolved user profiles (name, avatar). Use as the initial load for a message info / "Read by" detail screen. |
+| `getReactions` | `(messageId: string) => Promise<MessageReactionsResponse>` | Fetch the full reaction breakdown for a single message — grouped by emoji with per-user details and `didIReact`. Use for a reactions detail sheet. |
 | `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. |
@@ -1710,13 +1711,14 @@ import { syncApi } from '@antzsoft/chat-core';
 import type {
   CrossConversationSyncResponse,
   ConversationSyncResponse,
+  SyncDeliveredReceipt,
 } 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. |
+| `pullConversation` | `(conversationId: string, opts?: { since?: string; afterSeq?: number; beforeSeq?: number }) => Promise<ConversationSyncResponse>` | Per-conversation sync. Prefer `afterSeq` (forward catch-up) or `beforeSeq` (backward scroll). Falls back to `since` timestamp for older servers. |
 
 #### When to call each
 
@@ -1724,21 +1726,26 @@ import type {
 |---|---|
 | 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 |
+| User opens a stale conversation (catch-up) | `syncApi.pullConversation(convId, { afterSeq: lastKnownSeq })` |
+| User scrolls back into unloaded history | `syncApi.pullConversation(convId, { beforeSeq: oldestLocalSeq })` |
+| Resume interrupted sync | Pass the `nextSeq` from the previous page as the same cursor type |
+| First sync / old server | `syncApi.pullConversation(convId, { since: lastSyncedAt })` |
 
 #### `CrossConversationSyncResponse`
 
-Returned by `syncApi.pull(since)`. Does **not** include reactions or stars — those are per-conversation and returned by `pullConversation`.
+Returned by `syncApi.pull(since)`. As of v1.3.1, also includes `reactions` and `stars`.
 
 ```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
+  syncedAt: string;              // server-stamped ISO timestamp — store as new lastSyncedAt
+  stale: boolean;                // true when gap > CHAT_SYNC_STALE_DAYS (default 30)
+  messages: Message[];           // edits, deletes, pins, unpins — any message with updatedAt > since
   deletedForMe: SyncDeletedForMe[];
   participantChanges: SyncParticipantChange[];
   readReceipts: SyncReadReceipt[];
+  deliveredReceipts: SyncDeliveredReceipt[];  // delivery receipts since `since`
+  reactions: SyncReactions;      // v1.3.1+ — full current state for messages with reaction activity
+  stars: SyncStarEntry[];        // v1.3.1+ — star/unstar records since `since`
 }
 
 interface SyncDeletedForMe {
@@ -1763,25 +1770,44 @@ interface SyncReadReceipt {
   userId: string;
   readAt: string | null;
 }
+
+interface SyncDeliveredReceipt {
+  messageId: string;
+  conversationId: string;
+  userId: string;
+  deliveredAt: string | null;
+}
 ```
 
 #### `ConversationSyncResponse`
 
-Returned by `syncApi.pullConversation(convId, since?)`. Includes everything needed to make local SQLite authoritative for that conversation.
+Returned by `syncApi.pullConversation(convId, opts?)`. Supports seq-based pagination in both directions — call repeatedly following `hasMore` / `nextSeq` until `hasMore` is `false`.
 
 ```typescript
 interface ConversationSyncResponse {
   syncedAt: string;
-  messages: Message[];          // updatedAt > since — edits, deletes, pins
+  /** Cursor for the next page — pass as afterSeq or beforeSeq matching what you sent */
+  nextSeq?: number;
+  /** True when more pages are available — call again with nextSeq as the same cursor type */
+  hasMore?: boolean;
+  messages: Message[];
   deletedForMe: SyncDeletedForMe[];
-  reactions: SyncReactions;     // full current state for messages with reactedAt > since
-  stars: SyncStarEntry[];       // updatedAt > since; isActive: false = unstarred
+  reactions: SyncReactions;                    // full current state for affected messages
+  stars: SyncStarEntry[];                      // isActive: false = unstarred
   participantChanges: SyncParticipantChange[];
   readReceipts: SyncReadReceipt[];
+  deliveredReceipts: SyncDeliveredReceipt[];
 }
 
-// keyed by messageId — full current emoji counts (not delta)
-type SyncReactions = Record<string, MessageReaction[]>;
+// keyed by messageId — bounded shape: emoji, count, didIReact only (v1.3.2+)
+// Full user list: call messagesApi.getReactions(messageId) on demand
+type SyncReactions = Record<string, SyncReactionEntry[]>;
+
+interface SyncReactionEntry {
+  emoji: string;
+  count: number;
+  didIReact: boolean;  // true when the calling user has reacted with this emoji
+}
 
 interface SyncStarEntry {
   messageId: string;
@@ -1791,16 +1817,50 @@ interface SyncStarEntry {
 }
 ```
 
+#### Seq-based pagination
+
+`pullConversation` supports two directions. Always upsert each page to SQLite before requesting the next — this gives the user visible messages immediately and provides a safe resume point.
+
+**Forward (catch-up) — oldest → newest:**
+```typescript
+// Use Conversation.lastSeq from the conversation list as the starting cursor
+let afterSeq = conversation.lastSeq ?? 0;
+
+while (true) {
+  const res = await syncApi.pullConversation(conversationId, { afterSeq });
+  await upsertPageToSQLite(res);
+  if (!res.hasMore || res.nextSeq == null) break;
+  afterSeq = res.nextSeq;
+}
+```
+
+**Backward (scroll-back) — newest → oldest:**
+```typescript
+let beforeSeq: number | null = null; // null = start from the latest messages
+
+while (true) {
+  const res = await syncApi.pullConversation(conversationId,
+    beforeSeq != null ? { beforeSeq } : undefined,
+  );
+  await upsertPageToSQLite(res);
+  if (!res.hasMore || res.nextSeq == null) break;
+  beforeSeq = res.nextSeq;
+}
+```
+
+The built-in `SyncService.syncConversation()` in the RN app uses the backward direction and handles the loop, cancellation on unmount, and cursor persistence automatically.
+
 #### 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` |
+| Field | `pull()` | `pullConversation()` | What it captures |
+|---|---|---|---|
+| `messages` | ✅ | ✅ | Edits, deletes, pins/unpins. Each message includes `metadata`, `sender`, and signed attachment `url`s |
+| `deletedForMe` | ✅ | ✅ | Messages this user hid — remove from local DB |
+| `reactions` | ✅ v1.3.1 | ✅ | Full current `{ emoji, count, didIReact }` for affected messages. **Replace, never merge** |
+| `stars` | ✅ v1.3.1 | ✅ | `isActive: false` = unstarred — delete local star record |
+| `participantChanges` | ✅ | ✅ | Role changes, mute/unmute, removals (`isActive: false`) |
+| `readReceipts` | ✅ | ✅ | Read receipts — merge into `msg.readBy[]`, recompute status |
+| `deliveredReceipts` | ✅ | ✅ | Delivery receipts — merge into `msg.deliveredTo[]`, recompute status |
 
 #### Stale handling
 
@@ -1861,9 +1921,10 @@ useEffect(() => {
 | Message deleted (everyone) | ✅ | ✅ |
 | Message deleted for me | ✅ | ✅ |
 | Message pinned / unpinned | ✅ | ✅ |
-| Reaction added / removed | — | ✅ full current state |
-| Star / unstar | — | ✅ with `isActive` |
+| Reaction added / removed | ✅ v1.3.1+ | ✅ |
+| Star / unstar | ✅ v1.3.1+ | ✅ with `isActive` |
 | Read receipt | ✅ | ✅ |
+| Delivery receipt | ✅ | ✅ |
 | Role change / mute / removal | ✅ | ✅ |
 
 ---
@@ -2532,6 +2593,7 @@ interface Message {
   pinnedBy?: string;
   pinnedAt?: string;
   uploadProgress?: number;   // 0–100, present on optimistic messages
+  seq?: number;              // v1.3.0+ — monotonic per-conversation counter; use as afterSeq cursor
   sentAt: string;
   createdAt: string;
   sender?: User;
@@ -2614,6 +2676,41 @@ const receipts = await messagesApi.getReceipts(messageId);
 
 ---
 
+### `MessageReactionsResponse`
+
+Returned by `messagesApi.getReactions()`. Use as the data source for a reactions detail sheet (list of who reacted with each emoji).
+
+```typescript
+interface ReactionUser {
+  userId: string;
+  displayName: string;
+  avatarUrl?: string;
+}
+
+interface ReactionGroup {
+  emoji: string;
+  userIds: string[];      // all user IDs who reacted with this emoji
+  count: number;
+  users: ReactionUser[];  // resolved displayName + avatarUrl
+}
+
+interface MessageReactionsResponse {
+  messageId: string;
+  reactions: ReactionGroup[];
+}
+```
+
+```typescript
+// Load reaction breakdown for a detail sheet
+const data = await messagesApi.getReactions(messageId);
+for (const group of data.reactions) {
+  // group.emoji, group.count, group.users (with displayName + avatarUrl)
+  renderReactionSheet(group);
+}
+```
+
+---
+
 ### `MessageContent`
 
 ```typescript
@@ -2819,6 +2916,7 @@ interface MessageAckEvent {
   tempId: string;      // the client-generated ID you sent
   messageId: string;   // the server-assigned real ID
   status: MessageStatus;
+  seq?: number;        // v1.3.0+ — seq assigned by the server; persist as last known seq for this conversation
 }
 
 interface MessageDeliveredEvent {
@@ -2956,6 +3054,153 @@ document.querySelectorAll('[data-conv-id]').forEach((el) => {
 
 ## Changelog
 
+### v1.3.3
+
+- **New: `metadata` and `sender` fields in all sync message responses** — Messages returned by all three sync paths (`crossConversationSync`, `conversationSync`, `conversationSyncBySeq`) now include `metadata` (system message metadata — `actorUserId`, `targetUserId`, `action`) and `sender` (displayName, avatarUrl snapshot at send time). Both fields were already optional on the core SDK `Message` type so no SDK type changes were required. Previously absent from sync responses, meaning system message text could not be rendered and sender avatars were blank after an offline sync. The server batch-fetches sender profiles in a single `findByIds` call per sync request — one extra DB round trip per sync, not one per message. **No integration changes required.**
+
+### v1.3.2
+
+- **New: Bounded sync reaction payloads — `SyncReactionEntry` type replaces `MessageReaction[]`** — Previously, `SyncReactions` (the `reactions` field in `ConversationSyncResponse` and `CrossConversationSyncResponse`) was `Record<string, MessageReaction[]>` where `MessageReaction.userIds` was an unbounded string array. On high-traffic messages with hundreds of reactions, this could blow past the 4 MB adaptive page limit. The type is now `Record<string, SyncReactionEntry[]>` where each entry carries only `emoji`, `count`, and `didIReact` (whether the calling user reacted). Full user lists are fetched on demand via `messagesApi.getReactions()`. **Sync payload size is now O(messages × emojis) regardless of reaction count.**
+
+  ```typescript
+  // Old shape (removed)
+  // reactions: Record<string, MessageReaction[]>   // MessageReaction had userIds: string[]
+
+  // New shape
+  interface SyncReactionEntry {
+    emoji: string;
+    count: number;
+    didIReact: boolean;  // true when the calling user has reacted with this emoji
+  }
+  type SyncReactions = Record<string, SyncReactionEntry[]>;  // keyed by messageId
+  ```
+
+  **Migration** — clients reading `reactions[msgId][n].userIds` must switch to `reactions[msgId][n].count` and `didIReact`. For a full user list (e.g. "Who reacted" sheet), call `messagesApi.getReactions(messageId)`.
+
+- **New: `messagesApi.getReactions(messageId)` — reactions detail sheet API** — New `POST /messages/:id/reactions/list` endpoint (GET mirror also available) returns the full per-emoji breakdown for a single message: counts, all reacting user IDs, and resolved user profiles. Use as the data source for a "Who reacted" bottom sheet. **New exported types: `MessageReactionsResponse`, `ReactionGroup`, `ReactionUser`.**
+
+  ```typescript
+  interface ReactionGroup {
+    emoji: string;
+    userIds: string[];      // all user IDs who reacted with this emoji
+    count: number;
+    users: ReactionUser[];  // resolved displayName + avatarUrl for each userId
+  }
+
+  interface MessageReactionsResponse {
+    messageId: string;
+    reactions: ReactionGroup[];
+  }
+  ```
+
+- **Improvement: Adaptive page-halving in `conversationSyncBySeq`** — The seq-based sync endpoint now estimates response size before returning and halves the page limit (min 25) when the estimated payload would exceed 4 MB. Triggered only for pathological cases (message with hundreds of reactions). `SYNC_PAGE_LIMIT` reduced from 200 to 100. **No integration changes required.**
+
+- **No breaking changes** — `SyncReactions` shape change is the only client-visible change; see migration note above.
+
+### v1.3.1
+
+- **New: Bidirectional seq pagination in `conversationSyncBySeq`** — The per-conversation seq-based sync endpoint now supports both directions:
+
+  | Direction | Param | Order | Use case |
+  |---|---|---|---|
+  | Forward (default) | `afterSeq` | oldest → newest | catch-up / sync on reconnect |
+  | Backward | `beforeSeq` | newest → oldest | scroll-back / load older history |
+
+  Pass `beforeSeq` (exclusive upper bound) to page backward. The server validates mutual exclusivity — passing both is a `400 Bad Request`. The `nextSeq` in the response is the cursor for the next page in the same direction.
+
+  ```typescript
+  // Forward catch-up (default behavior, unchanged)
+  const res = await syncApi.pullConversation(conversationId, { afterSeq: lastKnownSeq });
+
+  // Backward scroll (new)
+  const res = await syncApi.pullConversation(conversationId, { beforeSeq: oldestLocalSeq });
+  if (res.hasMore) {
+    const nextPage = await syncApi.pullConversation(conversationId, { beforeSeq: res.nextSeq! });
+  }
+  ```
+
+- **New: `reactions` and `stars` in `CrossConversationSyncResponse`** — `syncApi.pull(since)` now returns `reactions: SyncReactions` and `stars: SyncStarEntry[]` alongside the existing fields. These were previously only available from `pullConversation`. Cross-conversation catch-up now covers the full delta including reaction and star changes since the cursor.
+
+  ```typescript
+  // CrossConversationSyncResponse now includes:
+  reactions: SyncReactions;     // full current state for messages with reaction activity > since
+  stars: SyncStarEntry[];       // star/unstar records since since; isActive: false = unstarred
+  ```
+
+  **Shape consistency** — stale responses and empty-conversations early returns now also include `reactions: {}` and `stars: []` so the response shape is always uniform.
+
+- **New: `useConversationSync` direction option (RN SDK)** — The `@antzsoft/chat-rn-sdk` `useConversationSync` hook accepts a `direction` option (`'forward' | 'backward'`, default `'forward'`). Pass `direction: 'backward'` with `beforeSeq` to trigger a scroll-back page load. The hook automatically uses the stored seq cursor for forward syncs.
+
+- **No breaking changes** — `pullConversation` opts are additive. `CrossConversationSyncResponse` gains two new fields that clients should merge the same way as `ConversationSyncResponse`.
+
+### v1.3.0
+
+- **New: `seq` and `lastSeq` — per-conversation monotonic message sequence numbers** — Every message now carries a `seq` field: a per-conversation monotonically increasing integer assigned at send time. The server maintains an atomic Redis counter per conversation (`chat:seq:{conversationId}`), flushed to MongoDB every 60 s. `seq` appears on all message responses (REST and socket), on `Message.seq`, and on the `MessageAckEvent.seq` field.
+
+  `Conversation.lastSeq` is the highest `seq` seen in that conversation — returned by all conversation list/get endpoints and updated on every `conversation_updated` socket event via the new `ConversationUpdatedEvent.lastSeq` field. Use it as the `afterSeq` cursor for `pullConversation` to catch up on exactly the messages you missed.
+
+  ```typescript
+  // New fields on existing types:
+  interface Message {
+    seq?: number;   // monotonic per-conversation counter
+    // ...
+  }
+
+  interface Conversation {
+    lastSeq?: number;  // highest seq in this conversation — use as afterSeq cursor
+    // ...
+  }
+
+  interface MessageAckEvent {
+    seq?: number;   // seq assigned to this message by the server
+    // ...
+  }
+
+  interface ConversationUpdatedEvent {  // NEW type (v1.3.0)
+    id: string;
+    lastMessage?: Partial<Message> | null;
+    unreadCount?: number;
+    updatedAt?: string;
+    lastSeq?: number;     // advance your afterSeq cursor on every message
+    participants?: Participant[];
+  }
+  ```
+
+- **New: `conversationSyncBySeq` server endpoint** — `GET /conversations/:id/sync?afterSeq=N` returns the next page of messages starting from seq N+1 (forward direction). Prefer this over timestamp-based sync when `Conversation.lastSeq` is available — seq cursors are collision-safe, never require a clock comparison, and enable exact-page pagination. Returns `hasMore: boolean` and `nextSeq: number | null` for looping.
+
+- **New: `useConvSeq` / `setConvSeq` (RN SDK)** — `@antzsoft/chat-rn-sdk` exports `getConvSeq(conversationId)` and `setConvSeq(conversationId, seq)` for persisting the per-conversation seq cursor in AsyncStorage. `useConversationSync` in the RN SDK now automatically uses the stored seq for forward syncs — no code changes needed in the host app.
+
+- **Migration 006** — `006_backfill_message_seq` runs automatically on first deploy. Assigns sequential `seq` values to all existing messages in each conversation (ordered by `createdAt`). Idempotent — safe to run multiple times.
+
+- **New exported type: `ConversationUpdatedEvent`.**
+
+- **No breaking changes** — `seq` and `lastSeq` are additive optional fields. Clients that don't use them are unaffected.
+
+### v1.2.9
+
+- **New: `deliveredReceipts[]` in sync responses — delivery tick marks now survive offline gaps** — Both `CrossConversationSyncResponse` (from `syncApi.pull()`) and `ConversationSyncResponse` (from `syncApi.pullConversation()`) now include a `deliveredReceipts: SyncDeliveredReceipt[]` field. This mirrors the existing `readReceipts[]` pattern and is sourced from the `chat_message_deliveries` time-series collection. Mobile apps merge these into each message's `deliveredTo[]` array and recompute `status` via `resolveMessageStatus` — single-tick → double-tick transitions that occurred while offline are now correctly replayed on reconnect.
+
+  ```typescript
+  interface SyncDeliveredReceipt {
+    messageId: string;
+    conversationId: string;
+    userId: string;
+    deliveredAt: string | null;
+  }
+  ```
+
+  **No integration changes required** — the `SyncService.applyShared()` in the RN app already handles `deliveredReceipts` via `ChatRepository.applyDeliveredReceipts()`. The field is absent on older server versions and is safely ignored by any older client. **New exported type: `SyncDeliveredReceipt`.**
+
+- **Fix: Attachment URLs in sync messages are now properly signed** — Previously, sync responses (`pullAll` / `pullConversation`) returned raw `storageKey`, `provider`, and `bucket` fields for attachment records. These fields are internal storage identifiers — clients cannot use them to render images or play audio. The sync service now generates signed, short-lived `url`s for all attachments (same Redis-cached signing logic as the message list API, 2400 s cache / 3600 s expiry). The raw storage fields are stripped from the sync response. **Clients that were silently ignoring `storageKey` now receive a working `url`.**
+
+- **Fix: `replyTo.attachmentSnapshot.url` now signed in sync** — The `replyTo.attachmentSnapshot` object (thumbnail of the quoted attachment shown in reply bubbles) was also missing a signed `url` in sync responses. The attachment snapshot now carries a properly signed `url` alongside its `type`, `filename`, `mimeType`, `size`, `duration`, and `dimensions`. `storageKey` / `provider` / `bucket` are not included in the snapshot output.
+
+- **Fix: `replyTo.messageId` now serialized as a string in sync** — `replyTo.messageId` was returned as a MongoDB `ObjectId` object in sync responses due to a missing `.toString()` call on the lean document. It is now always a plain string, consistent with all other ID fields. No client-side workaround needed.
+
+- **Fix: `applyReadReceipts` now recomputes `status` after merge** — The mobile `ChatRepository.applyReadReceipts()` function was merging the new read entries into `msg.readBy[]` but not re-running `resolveMessageStatus`. Messages whose `readBy` grew to include all recipients after a sync were not being promoted to `status: 'read'` — tick marks stayed at double-tick even when all recipients had read the message. Fixed by calling `resolveMessageStatus(updated)` and persisting the result after every merge.
+
+- **No breaking changes** — all additions are purely additive. `deliveredReceipts` is absent on older server versions and treated as an empty array by any client. Existing sync handling, socket events, and API contracts are unchanged.
+
 ### v1.2.8
 
 - **New: `deliveryStatus` on `Conversation.lastMessage`** — The conversation list API (`GET /conversations`) and the `conversation_updated` socket event now include `deliveryStatus` on the `lastMessage` object. This is the tick state (`'sent'` | `'delivered'` | `'read'`) of the last message as seen by the sender. It is computed and stored directly on the conversation document — no extra queries at list time.