stream-chat 9.21.0 → 9.22.0

package/src/messageDelivery/MessageReceiptsTracker.ts

@@ -0,0 +1,417 @@
+import type { ReadResponse, UserResponse } from '../types';
+
+type UserId = string;
+type MessageId = string;
+export type MsgRef = { timestampMs: number; msgId: MessageId };
+export type OwnMessageReceiptsTrackerMessageLocator = (
+  timestampMs: number,
+) => MsgRef | null;
+export type UserProgress = {
+  user: UserResponse;
+  lastReadRef: MsgRef; // MIN_REF if none
+  lastDeliveredRef: MsgRef; // MIN_REF if none; always >= readRef
+};
+
+// ---------- ordering utilities ----------
+
+const MIN_REF: MsgRef = { timestampMs: Number.NEGATIVE_INFINITY, msgId: '' } as const;
+
+const compareRefsAsc = (a: MsgRef, b: MsgRef) =>
+  a.timestampMs !== b.timestampMs ? a.timestampMs - b.timestampMs : 0;
+
+const findIndex = <T>(arr: T[], target: MsgRef, keyOf: (x: T) => MsgRef): number => {
+  let lo = 0,
+    hi = arr.length;
+  while (lo < hi) {
+    const mid = (lo + hi) >>> 1;
+    if (compareRefsAsc(keyOf(arr[mid]), target) >= 0) hi = mid;
+    else lo = mid + 1;
+  }
+  return lo;
+};
+
+/**
+ * For insertion after the last equal item. E.g. array [a] exists and b is being inserted -> we want [a,b], not [b,a].
+ * @param arr
+ * @param target
+ * @param keyOf
+ */
+const findUpperIndex = <T>(arr: T[], target: MsgRef, keyOf: (x: T) => MsgRef): number => {
+  let lo = 0,
+    hi = arr.length;
+  while (lo < hi) {
+    const mid = (lo + hi) >>> 1;
+    if (compareRefsAsc(keyOf(arr[mid]), target) > 0) hi = mid;
+    else lo = mid + 1;
+  }
+  return lo;
+};
+
+const insertByKey = (
+  arr: UserProgress[],
+  item: UserProgress,
+  keyOf: (x: UserProgress) => MsgRef,
+) => arr.splice(findUpperIndex(arr, keyOf(item), keyOf), 0, item);
+
+const removeByOldKey = (
+  arr: UserProgress[],
+  item: UserProgress,
+  oldKey: MsgRef,
+  keyOf: (x: UserProgress) => MsgRef,
+) => {
+  // Find the plateau for oldKey, scan to match by user id
+  let i = findIndex(arr, oldKey, keyOf);
+  while (i < arr.length && compareRefsAsc(keyOf(arr[i]), oldKey) === 0) {
+    if (arr[i].user.id === item.user.id) {
+      arr.splice(i, 1);
+      return;
+    }
+    i++;
+  }
+};
+
+export type OwnMessageReceiptsTrackerOptions = {
+  locateMessage: OwnMessageReceiptsTrackerMessageLocator;
+};
+
+/**
+ * MessageReceiptsTracker
+ * --------------------------------
+ * Tracks **other participants’** delivery/read progress toward **own (outgoing) messages**
+ * within a **single timeline** (one channel/thread).
+ *
+ * How it works
+ * ------------
+ * - Each user has a compact progress record:
+ *     - `lastReadRef`: latest message they have **read**
+ *     - `lastDeliveredRef`: latest message they have **received** (always `>= lastReadRef`)
+ * - Internally keeps two arrays sorted **ascending by timestamp**:
+ *     - `readSorted` (by `lastReadRef`)
+ *     - `deliveredSorted` (by `lastDeliveredRef`)
+ * - Queries like “who read message M?” become a **binary search + suffix slice**.
+ *
+ * Construction
+ * ------------
+ * `new MessageReceiptsTracker({locateMessage})`
+ * - `locateMessage(timestamp) => MsgRef | null` must resolve a message ref representation - `{ timestamp, msgId }`.
+ *   - If `locateMessage` returns `null`, the event is ignored (message unknown locally).
+ *
+ * Event ingestion
+ * ---------------
+ * - `ingestInitial(rows: ReadResponse[])`: Builds initial state from server snapshot.
+ *   If a user’s `last_read` is ahead of `last_delivered_at`, the tracker enforces
+ *   the invariant `lastDeliveredRef >= lastReadRef`.
+ * - `onMessageRead(user, readAtISO)`:
+ *   Advances the user’s read; also bumps delivered to match if needed.
+ * - `onMessageDelivered(user, deliveredAtISO)`:
+ *   Advances the user’s delivered to `max(currentRead, deliveredAt)`.
+ *
+ * Queries
+ * -------
+ * - `readersForMessage(msgRef)         : UserResponse[]` → users with `lastReadRef >= msgRef`
+ * - `deliveredForMessage(msgRef)       : UserResponse[]` → users with `lastDeliveredRef >= msgRef`
+ * - `deliveredNotReadForMessage(msgRef): UserResponse[]` → delivered but `lastReadRef < msgRef`
+ * - `usersWhoseLastReadIs              : UserResponse[]` →  users for whom `msgRef` is their *last read* (exact match)
+ * - `usersWhoseLastDeliveredIs         : UserResponse[]` →  users for whom `msgRef` is their *last delivered* (exact match)
+ * - `groupUsersByLastReadMessage       : Record<MsgId, UserResponse[]> → mapping of messages to their readers
+ * - `groupUsersByLastDeliveredMessage  : Record<MsgId, UserResponse[]> → mapping of messages to their receivers
+ * - `hasUserRead(msgRef, userId)       : boolean`
+ * - `hasUserDelivered(msgRef, userId)  : boolean`
+ *
+ * Complexity
+ * ----------
+ * - Update on read/delivered: **O(log U)** (binary search + one splice) per event, where U is count of users stored by tracker.
+ * - Query lists: **O(log U + K)** where `K` is the number of returned users (suffix length).
+ * - Memory: **O(U)** - tracker’s memory grows linearly with the number of users in the channel/thread and does not depend on the number of messages.
+ *
+ * Scope & notes
+ * -------------
+ * - One tracker instance is **scoped to a single timeline**. Instantiate per channel/thread.
+ * - Ordering is by **ascending timestamp**; ties are kept stable by inserting at the end of the
+ *   equal-timestamp plateau (upper-bound insertion), preserving intuitive arrival order.
+ * - This tracker models **others’ progress toward own messages**;
+ */
+export class MessageReceiptsTracker {
+  private byUser = new Map<UserId, UserProgress>();
+  private readSorted: UserProgress[] = []; // asc by lastReadRef
+  private deliveredSorted: UserProgress[] = []; // asc by lastDeliveredRef
+  private locateMessage: OwnMessageReceiptsTrackerMessageLocator;
+
+  constructor({ locateMessage }: OwnMessageReceiptsTrackerOptions) {
+    this.locateMessage = locateMessage;
+  }
+
+  /** Build initial state from server snapshots (single pass + sort). */
+  ingestInitial(responses: ReadResponse[]) {
+    this.byUser.clear();
+    this.readSorted = [];
+    this.deliveredSorted = [];
+    for (const r of responses) {
+      const lastReadTimestamp = r.last_read ? new Date(r.last_read).getTime() : null;
+      const lastDeliveredTimestamp = r.last_delivered_at
+        ? new Date(r.last_delivered_at).getTime()
+        : null;
+      const lastReadRef = lastReadTimestamp
+        ? (this.locateMessage(lastReadTimestamp) ?? MIN_REF)
+        : MIN_REF;
+      let lastDeliveredRef = lastDeliveredTimestamp
+        ? (this.locateMessage(lastDeliveredTimestamp) ?? MIN_REF)
+        : MIN_REF;
+      const isReadAfterDelivered = compareRefsAsc(lastDeliveredRef, lastReadRef) < 0;
+      if (isReadAfterDelivered) lastDeliveredRef = lastReadRef;
+
+      const userProgress: UserProgress = { user: r.user, lastReadRef, lastDeliveredRef };
+      this.byUser.set(r.user.id, userProgress);
+      this.readSorted.splice(
+        findIndex(this.readSorted, lastReadRef, (up) => up.lastReadRef),
+        0,
+        userProgress,
+      );
+      this.deliveredSorted.splice(
+        findIndex(this.deliveredSorted, lastDeliveredRef, (up) => up.lastDeliveredRef),
+        0,
+        userProgress,
+      );
+    }
+  }
+
+  /** message.delivered — user device confirmed delivery up to and including messageId. */
+  onMessageDelivered({
+    user,
+    deliveredAt,
+    lastDeliveredMessageId,
+  }: {
+    user: UserResponse;
+    deliveredAt: string;
+    lastDeliveredMessageId?: string;
+  }) {
+    const timestampMs = new Date(deliveredAt).getTime();
+    const msgRef = lastDeliveredMessageId
+      ? { timestampMs, msgId: lastDeliveredMessageId }
+      : this.locateMessage(new Date(deliveredAt).getTime());
+    if (!msgRef) return;
+    const userProgress = this.ensureUser(user);
+
+    const newDelivered =
+      compareRefsAsc(msgRef, userProgress.lastReadRef) < 0
+        ? userProgress.lastReadRef
+        : msgRef; // max(read, loc)
+    // newly announced delivered is older than or equal what is already registered
+    if (compareRefsAsc(newDelivered, userProgress.lastDeliveredRef) <= 0) return;
+
+    removeByOldKey(
+      this.deliveredSorted,
+      userProgress,
+      userProgress.lastDeliveredRef,
+      (x) => x.lastDeliveredRef,
+    );
+    userProgress.lastDeliveredRef = newDelivered;
+    insertByKey(this.deliveredSorted, userProgress, (x) => x.lastDeliveredRef);
+  }
+
+  /** message.read — user read up to and including messageId. */
+  onMessageRead({
+    user,
+    readAt,
+    lastReadMessageId,
+  }: {
+    user: UserResponse;
+    readAt: string;
+    lastReadMessageId?: string;
+  }) {
+    const timestampMs = new Date(readAt).getTime();
+    const msgRef = lastReadMessageId
+      ? { timestampMs, msgId: lastReadMessageId }
+      : this.locateMessage(timestampMs);
+    if (!msgRef) return;
+    const userProgress = this.ensureUser(user);
+    // newly announced read message is older than or equal the already recorded last read message
+    if (compareRefsAsc(msgRef, userProgress.lastReadRef) <= 0) return;
+
+    // move in readSorted
+    removeByOldKey(
+      this.readSorted,
+      userProgress,
+      userProgress.lastReadRef,
+      (x) => x.lastReadRef,
+    );
+    userProgress.lastReadRef = msgRef;
+    insertByKey(this.readSorted, userProgress, (x) => x.lastReadRef);
+
+    // keep delivered >= read
+    if (compareRefsAsc(userProgress.lastDeliveredRef, userProgress.lastReadRef) < 0) {
+      removeByOldKey(
+        this.deliveredSorted,
+        userProgress,
+        userProgress.lastDeliveredRef,
+        (x) => x.lastDeliveredRef,
+      );
+      userProgress.lastDeliveredRef = userProgress.lastReadRef;
+      insertByKey(this.deliveredSorted, userProgress, (x) => x.lastDeliveredRef);
+    }
+  }
+
+  /** notification.mark_unread — user marked messages unread starting at `first_unread_message_id`.
+   * Sets lastReadRef to the event’s last_read_* values. Delivery never moves backward.
+   * The event is sent only to the user that triggered the action (own user), so we will never adjust read ref
+   * for other users - we will not see changes in the UI for other users. However, this implementation does not
+   * take into consideration this fact and is ready to handle the mark-unread event for any user.
+   */
+  onNotificationMarkUnread({
+    user,
+    lastReadAt,
+    lastReadMessageId,
+  }: {
+    user: UserResponse;
+    lastReadAt?: string;
+    lastReadMessageId?: string;
+  }) {
+    const userProgress = this.ensureUser(user);
+
+    const newReadRef: MsgRef = lastReadAt
+      ? { timestampMs: new Date(lastReadAt).getTime(), msgId: lastReadMessageId ?? '' }
+      : { ...MIN_REF };
+
+    // If no change, exit early.
+    if (
+      compareRefsAsc(newReadRef, userProgress.lastReadRef) === 0 &&
+      newReadRef.msgId === userProgress.lastReadRef.msgId
+    ) {
+      return;
+    }
+
+    removeByOldKey(
+      this.readSorted,
+      userProgress,
+      userProgress.lastReadRef,
+      (x) => x.lastReadRef,
+    );
+    userProgress.lastReadRef = newReadRef;
+    insertByKey(this.readSorted, userProgress, (x) => x.lastReadRef);
+
+    // Maintain invariant delivered >= read.
+    if (compareRefsAsc(userProgress.lastDeliveredRef, userProgress.lastReadRef) < 0) {
+      removeByOldKey(
+        this.deliveredSorted,
+        userProgress,
+        userProgress.lastDeliveredRef,
+        (x) => x.lastDeliveredRef,
+      );
+      userProgress.lastDeliveredRef = userProgress.lastReadRef;
+      insertByKey(this.deliveredSorted, userProgress, (x) => x.lastDeliveredRef);
+    }
+  }
+
+  /** All users who READ this message. */
+  readersForMessage(msgRef: MsgRef): UserResponse[] {
+    const index = findIndex(this.readSorted, msgRef, ({ lastReadRef }) => lastReadRef);
+    return this.readSorted.slice(index).map((x) => x.user);
+  }
+
+  /** All users who have it DELIVERED (includes readers). */
+  deliveredForMessage(msgRef: MsgRef): UserResponse[] {
+    const pos = findIndex(
+      this.deliveredSorted,
+      msgRef,
+      ({ lastDeliveredRef }) => lastDeliveredRef,
+    );
+    return this.deliveredSorted.slice(pos).map((x) => x.user);
+  }
+
+  /** Users who delivered but have NOT read. */
+  deliveredNotReadForMessage(msgRef: MsgRef): UserResponse[] {
+    const pos = findIndex(
+      this.deliveredSorted,
+      msgRef,
+      ({ lastDeliveredRef }) => lastDeliveredRef,
+    );
+    const usersDeliveredNotRead: UserResponse[] = [];
+    for (let i = pos; i < this.deliveredSorted.length; i++) {
+      const userProgress = this.deliveredSorted[i];
+      if (compareRefsAsc(userProgress.lastReadRef, msgRef) < 0)
+        usersDeliveredNotRead.push(userProgress.user);
+    }
+    return usersDeliveredNotRead;
+  }
+
+  /** Users for whom `msgRef` is their *last read* (exact match). */
+  usersWhoseLastReadIs(msgRef: MsgRef): UserResponse[] {
+    if (!msgRef.msgId) return [];
+    const start = findIndex(this.readSorted, msgRef, (x) => x.lastReadRef);
+    const end = findUpperIndex(this.readSorted, msgRef, (x) => x.lastReadRef);
+    const users: UserResponse[] = [];
+    for (let i = start; i < end; i++) {
+      const up = this.readSorted[i];
+      if (up.lastReadRef.msgId === msgRef.msgId) users.push(up.user);
+    }
+    return users;
+  }
+
+  /** Users for whom `msgRef` is their *last delivered* (exact match). */
+  usersWhoseLastDeliveredIs(msgRef: MsgRef): UserResponse[] {
+    if (!msgRef.msgId) return [];
+    const start = findIndex(this.deliveredSorted, msgRef, (x) => x.lastDeliveredRef);
+    const end = findUpperIndex(this.deliveredSorted, msgRef, (x) => x.lastDeliveredRef);
+    const users: UserResponse[] = [];
+    for (let i = start; i < end; i++) {
+      const up = this.deliveredSorted[i];
+      if (up.lastDeliveredRef.msgId === msgRef.msgId) users.push(up.user);
+    }
+    return users;
+  }
+
+  // ---- queries: per-user status ----
+
+  hasUserRead(msgRef: MsgRef, userId: string): boolean {
+    const up = this.byUser.get(userId);
+    return !!up && compareRefsAsc(up.lastReadRef, msgRef) >= 0;
+  }
+
+  hasUserDelivered(msgRef: MsgRef, userId: string): boolean {
+    const up = this.byUser.get(userId);
+    return !!up && compareRefsAsc(up.lastDeliveredRef, msgRef) >= 0;
+  }
+
+  getUserProgress(userId: string): UserProgress | null {
+    const userProgress = this.byUser.get(userId);
+    if (!userProgress) return null;
+    return userProgress;
+  }
+
+  groupUsersByLastReadMessage(): Record<MessageId, UserResponse[]> {
+    return Array.from(this.byUser.values()).reduce<Record<MessageId, UserResponse[]>>(
+      (acc, userProgress) => {
+        const msgId = userProgress.lastReadRef.msgId;
+        if (!msgId) return acc;
+        if (!acc[msgId]) acc[msgId] = [];
+        acc[msgId].push(userProgress.user);
+        return acc;
+      },
+      {},
+    );
+  }
+
+  groupUsersByLastDeliveredMessage(): Record<MessageId, UserResponse[]> {
+    return Array.from(this.byUser.values()).reduce<Record<MessageId, UserResponse[]>>(
+      (acc, userProgress) => {
+        const msgId = userProgress.lastDeliveredRef.msgId;
+        if (!msgId) return acc;
+        if (!acc[msgId]) acc[msgId] = [];
+        acc[msgId].push(userProgress.user);
+        return acc;
+      },
+      {},
+    );
+  }
+
+  private ensureUser(user: UserResponse): UserProgress {
+    let up = this.byUser.get(user.id);
+    if (!up) {
+      up = { user, lastReadRef: MIN_REF, lastDeliveredRef: MIN_REF };
+      this.byUser.set(user.id, up);
+      insertByKey(this.readSorted, up, (x) => x.lastReadRef);
+      insertByKey(this.deliveredSorted, up, (x) => x.lastDeliveredRef);
+    }
+    return up;
+  }
+}

package/src/messageDelivery/index.ts

@@ -0,0 +1,2 @@
+export * from './MessageDeliveryReporter';
+export * from './MessageReceiptsTracker';

package/src/thread.ts

@@ -534,7 +534,7 @@ export class Thread extends WithSubscriptions {
       return null;
     }
 
-    return await this.channel.markRead({ thread_id: this.id });
+    return await this.client.messageDeliveryReporter.markRead(this);
   };
 
   private throttledMarkAsRead = throttle(

package/src/types.ts

@@ -713,6 +713,7 @@ export type MessageResponseBase = MessageBase & {
   status?: string;
   thread_participants?: UserResponse[];
   updated_at?: string;
+  deleted_for_me?: boolean;
 };
 
 export type ReactionGroupResponse = {
@@ -968,7 +969,7 @@ export type BanUserOptions = UnBanUserOptions & {
   ip_ban?: boolean;
   reason?: string;
   timeout?: number;
-  delete_messages?: DeleteMessagesOptions;
+  delete_messages?: MessageDeletionStrategy;
 };
 
 export type ChannelOptions = {
@@ -1468,14 +1469,15 @@ export type Event = CustomEventData & {
   ai_state?: AIState;
   channel?: ChannelResponse;
   channel_custom?: CustomChannelData;
-  channel_member_count?: number;
   channel_id?: string;
+  channel_member_count?: number;
   channel_type?: string;
   cid?: string;
   clear_history?: boolean;
   connection_id?: string;
   // event creation timestamp, format Date ISO string
   created_at?: string;
+  deleted_for_me?: boolean;
   draft?: DraftResponse;
   // id of the message that was marked as unread - all the following messages are considered unread. (notification.mark_unread)
   first_unread_message_id?: string;
@@ -3602,14 +3604,21 @@ export type CustomCheckFlag = {
   reason?: string;
 };
 
-export type DeleteMessagesOptions = 'soft' | 'hard';
+export type MessageDeletionStrategy = 'soft' | 'hard';
+// @deprecated use type MessageDeletionStrategy instead
+export type DeleteMessagesOptions = MessageDeletionStrategy;
+
+export type DeleteMessageOptions = {
+  deleteForMe?: boolean;
+  hardDelete?: boolean;
+};
 
 export type SubmitActionOptions = {
   ban?: {
     channel_ban_only?: boolean;
     reason?: string;
     timeout?: number;
-    delete_messages?: DeleteMessagesOptions;
+    delete_messages?: MessageDeletionStrategy;
   };
   delete_message?: {
     hard_delete?: boolean;

package/src/utils.ts

@@ -748,7 +748,8 @@ export const debounce = <T extends (...args: any[]) => any>(
 };
 
 // works exactly the same as lodash.throttle
-export const throttle = <T extends (...args: unknown[]) => unknown>(
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const throttle = <T extends (...args: any[]) => any>(
   fn: T,
   timeout = 200,
   { leading = true, trailing = false }: { leading?: boolean; trailing?: boolean } = {},