stream-chat 9.21.0 → 9.22.1

package/dist/types/channel.d.ts

@@ -1,8 +1,9 @@
 import { ChannelState } from './channel_state';
+import { MessageComposer } from './messageComposer';
+import { MessageReceiptsTracker } from './messageDelivery';
 import type { StreamChat } from './client';
 import type { AIState, APIResponse, AscDesc, BanUserOptions, ChannelAPIResponse, ChannelData, ChannelMemberAPIResponse, ChannelMemberResponse, ChannelQueryOptions, ChannelResponse, ChannelUpdateOptions, CreateDraftResponse, DeleteChannelAPIResponse, DraftMessagePayload, Event, EventAPIResponse, EventHandler, EventTypes, GetDraftResponse, GetMultipleMessagesAPIResponse, GetReactionsAPIResponse, GetRepliesAPIResponse, LiveLocationPayload, LocalMessage, MarkReadOptions, MarkUnreadOptions, MemberFilters, MemberSort, Message, MessageFilters, MessageOptions, MessagePaginationOptions, MessageResponse, MessageSetType, MuteChannelAPIResponse, NewMemberPayload, PartialUpdateChannel, PartialUpdateChannelAPIResponse, PartialUpdateMember, PartialUpdateMemberAPIResponse, PinnedMessagePaginationOptions, PinnedMessagesSort, PollVoteData, PushPreference, QueryChannelAPIResponse, QueryMembersOptions, Reaction, ReactionAPIResponse, SearchAPIResponse, SearchOptions, SendMessageAPIResponse, SendMessageOptions, SendReactionOptions, StaticLocationPayload, TruncateChannelAPIResponse, TruncateOptions, UpdateChannelAPIResponse, UpdateChannelOptions, UpdateLocationPayload, UserResponse } from './types';
 import type { Role } from './permissions';
-import { MessageComposer } from './messageComposer';
 /**
  * Channel - The Channel class manages it's own state.
  */
@@ -39,6 +40,7 @@ export declare class Channel {
     disconnected: boolean;
     push_preferences?: PushPreference;
     readonly messageComposer: MessageComposer;
+    readonly messageReceiptsTracker: MessageReceiptsTracker;
     /**
      * constructor - Create a channel
      *
@@ -440,12 +442,19 @@ export declare class Channel {
      */
     lastMessage(): LocalMessage | undefined;
     /**
-     * markRead - Send the mark read event for this user, only works if the `read_events` setting is enabled
+     * markRead - Send the mark read event for this user, only works if the `read_events` setting is enabled. Syncs the message delivery report candidates local state.
      *
      * @param {MarkReadOptions} data
      * @return {Promise<EventAPIResponse | null>} Description
      */
     markRead(data?: MarkReadOptions): Promise<EventAPIResponse | null>;
+    /**
+     * markReadRequest - Send the mark read event for this user, only works if the `read_events` setting is enabled
+     *
+     * @param {MarkReadOptions} data
+     * @return {Promise<EventAPIResponse | null>} Description
+     */
+    markAsReadRequest(data?: MarkReadOptions): Promise<EventAPIResponse | null>;
     /**
      * markUnread - Mark the channel as unread from messageID, only works if the `read_events` setting is enabled
      *

package/dist/types/channel_state.d.ts

@@ -206,9 +206,15 @@ export declare class ChannelState {
      * @return {ReturnType<ChannelState['formatMessage']>} Returns the message, or undefined if the message wasn't found
      */
     findMessage(messageId: string, parentMessageId?: string): LocalMessage | undefined;
+    findMessageByTimestamp(timestampMs: number, parentMessageId?: string, exactTsMatch?: boolean): LocalMessage | null;
     private switchToMessageSet;
     private areMessageSetsOverlap;
     private findMessageSetIndex;
+    /**
+     * Identifies the set index into which a message set would pertain if its first item's creation date corresponded to oldestTimestampMs.
+     * @param oldestTimestampMs
+     */
+    private findMessageSetByOldestTimestamp;
     private findTargetMessageSet;
 }
 export {};

package/dist/types/client.d.ts

@@ -7,7 +7,7 @@ import { TokenManager } from './token_manager';
 import { WSConnectionFallback } from './connection_fallback';
 import { Campaign } from './campaign';
 import { Segment } from './segment';
-import type { ActiveLiveLocationsAPIResponse, APIErrorResponse, APIResponse, AppSettings, AppSettingsAPIResponse, BannedUsersFilters, BannedUsersPaginationOptions, BannedUsersResponse, BannedUsersSort, BanUserOptions, BaseDeviceFields, BlockList, BlockListResponse, BlockUserAPIResponse, CampaignData, CampaignFilters, CampaignQueryOptions, CampaignResponse, CampaignSort, CastVoteAPIResponse, ChannelAPIResponse, ChannelData, ChannelFilters, ChannelMute, ChannelOptions, ChannelResponse, ChannelSort, ChannelStateOptions, CheckPushResponse, CheckSNSResponse, CheckSQSResponse, Configs, ConnectAPIResponse, CreateChannelOptions, CreateChannelResponse, CreateCommandOptions, CreateCommandResponse, CreateImportOptions, CreateImportResponse, CreateImportURLResponse, CreatePollAPIResponse, CreatePollData, CreatePollOptionAPIResponse, CreateReminderOptions, CustomPermissionOptions, DeactivateUsersOptions, DeleteCommandResponse, DeleteUserOptions, Device, DeviceIdentifier, DraftFilters, DraftSort, EndpointName, Event, EventAPIResponse, EventHandler, ExportChannelOptions, ExportChannelRequest, ExportChannelResponse, ExportChannelStatusResponse, ExportUsersRequest, ExportUsersResponse, FlagMessageResponse, FlagReportsFilters, FlagReportsPaginationOptions, FlagReportsResponse, FlagsFilters, FlagsPaginationOptions, FlagsResponse, FlagUserResponse, GetBlockedUsersAPIResponse, GetCampaignOptions, GetChannelTypeResponse, GetCommandResponse, GetHookEventsResponse, GetImportResponse, GetMessageOptions, GetPollAPIResponse, GetRateLimitsResponse, GetThreadAPIResponse, GetThreadOptions, GetUnreadCountAPIResponse, GetUnreadCountBatchAPIResponse, ListChannelResponse, ListCommandsResponse, ListImportsPaginationOptions, ListImportsResponse, LocalMessage, Logger, MarkChannelsReadOptions, MarkDeliveredOptions, MessageFilters, MessageFlagsFilters, MessageFlagsPaginationOptions, MessageFlagsResponse, MessageResponse, Mute, MuteUserOptions, MuteUserResponse, OGAttachment, OwnUserResponse, Pager, PartialMessageUpdate, PartialPollUpdate, PartialThreadUpdate, PartialUserUpdate, PermissionAPIResponse, PermissionsAPIResponse, PollAnswersAPIResponse, PollData, PollOptionData, PollSort, PollVote, PollVoteData, PollVotesAPIResponse, Product, PushPreference, PushProvider, PushProviderConfig, PushProviderID, PushProviderListResponse, PushProviderUpsertResponse, QueryDraftsResponse, QueryMessageHistoryFilters, QueryMessageHistoryOptions, QueryMessageHistoryResponse, QueryMessageHistorySort, QueryPollsFilters, QueryPollsOptions, QueryPollsResponse, QueryReactionsAPIResponse, QueryReactionsOptions, QueryRemindersOptions, QueryRemindersResponse, QuerySegmentsOptions, QuerySegmentTargetsFilter, QueryThreadsOptions, QueryVotesFilters, QueryVotesOptions, ReactionFilters, ReactionResponse, ReactionSort, ReactivateUserOptions, ReactivateUsersOptions, ReminderAPIResponse, ReviewFlagReportOptions, ReviewFlagReportResponse, SdkIdentifier, SearchAPIResponse, SearchOptions, SegmentData, SegmentResponse, SegmentTargetsResponse, SegmentType, SendFileAPIResponse, SharedLocationResponse, SortParam, StreamChatOptions, SyncOptions, SyncResponse, TaskResponse, TaskStatus, TestPushDataInput, TestSNSDataInput, TestSQSDataInput, TokenOrProvider, TranslateResponse, UnBanUserOptions, UpdateChannelTypeRequest, UpdateChannelTypeResponse, UpdateCommandOptions, UpdateCommandResponse, UpdateLocationPayload, UpdateMessageAPIResponse, UpdateMessageOptions, UpdatePollAPIResponse, UpdateReminderOptions, UpdateSegmentData, UpsertPushPreferencesResponse, UserCustomEvent, UserFilters, UserOptions, UserResponse, UserSort, VoteSort } from './types';
+import type { ActiveLiveLocationsAPIResponse, APIErrorResponse, APIResponse, AppSettings, AppSettingsAPIResponse, BannedUsersFilters, BannedUsersPaginationOptions, BannedUsersResponse, BannedUsersSort, BanUserOptions, BaseDeviceFields, BlockList, BlockListResponse, BlockUserAPIResponse, CampaignData, CampaignFilters, CampaignQueryOptions, CampaignResponse, CampaignSort, CastVoteAPIResponse, ChannelAPIResponse, ChannelData, ChannelFilters, ChannelMute, ChannelOptions, ChannelResponse, ChannelSort, ChannelStateOptions, CheckPushResponse, CheckSNSResponse, CheckSQSResponse, Configs, ConnectAPIResponse, CreateChannelOptions, CreateChannelResponse, CreateCommandOptions, CreateCommandResponse, CreateImportOptions, CreateImportResponse, CreateImportURLResponse, CreatePollAPIResponse, CreatePollData, CreatePollOptionAPIResponse, CreateReminderOptions, CustomPermissionOptions, DeactivateUsersOptions, DeleteCommandResponse, DeleteMessageOptions, DeleteUserOptions, Device, DeviceIdentifier, DraftFilters, DraftSort, EndpointName, Event, EventAPIResponse, EventHandler, ExportChannelOptions, ExportChannelRequest, ExportChannelResponse, ExportChannelStatusResponse, ExportUsersRequest, ExportUsersResponse, FlagMessageResponse, FlagReportsFilters, FlagReportsPaginationOptions, FlagReportsResponse, FlagsFilters, FlagsPaginationOptions, FlagsResponse, FlagUserResponse, GetBlockedUsersAPIResponse, GetCampaignOptions, GetChannelTypeResponse, GetCommandResponse, GetHookEventsResponse, GetImportResponse, GetMessageOptions, GetPollAPIResponse, GetRateLimitsResponse, GetThreadAPIResponse, GetThreadOptions, GetUnreadCountAPIResponse, GetUnreadCountBatchAPIResponse, ListChannelResponse, ListCommandsResponse, ListImportsPaginationOptions, ListImportsResponse, LocalMessage, Logger, MarkChannelsReadOptions, MarkDeliveredOptions, MessageFilters, MessageFlagsFilters, MessageFlagsPaginationOptions, MessageFlagsResponse, MessageResponse, Mute, MuteUserOptions, MuteUserResponse, OGAttachment, OwnUserResponse, Pager, PartialMessageUpdate, PartialPollUpdate, PartialThreadUpdate, PartialUserUpdate, PermissionAPIResponse, PermissionsAPIResponse, PollAnswersAPIResponse, PollData, PollOptionData, PollSort, PollVote, PollVoteData, PollVotesAPIResponse, Product, PushPreference, PushProvider, PushProviderConfig, PushProviderID, PushProviderListResponse, PushProviderUpsertResponse, QueryDraftsResponse, QueryMessageHistoryFilters, QueryMessageHistoryOptions, QueryMessageHistoryResponse, QueryMessageHistorySort, QueryPollsFilters, QueryPollsOptions, QueryPollsResponse, QueryReactionsAPIResponse, QueryReactionsOptions, QueryRemindersOptions, QueryRemindersResponse, QuerySegmentsOptions, QuerySegmentTargetsFilter, QueryThreadsOptions, QueryVotesFilters, QueryVotesOptions, ReactionFilters, ReactionResponse, ReactionSort, ReactivateUserOptions, ReactivateUsersOptions, ReminderAPIResponse, ReviewFlagReportOptions, ReviewFlagReportResponse, SdkIdentifier, SearchAPIResponse, SearchOptions, SegmentData, SegmentResponse, SegmentTargetsResponse, SegmentType, SendFileAPIResponse, SharedLocationResponse, SortParam, StreamChatOptions, SyncOptions, SyncResponse, TaskResponse, TaskStatus, TestPushDataInput, TestSNSDataInput, TestSQSDataInput, TokenOrProvider, TranslateResponse, UnBanUserOptions, UpdateChannelTypeRequest, UpdateChannelTypeResponse, UpdateCommandOptions, UpdateCommandResponse, UpdateLocationPayload, UpdateMessageAPIResponse, UpdateMessageOptions, UpdatePollAPIResponse, UpdateReminderOptions, UpdateSegmentData, UpsertPushPreferencesResponse, UserCustomEvent, UserFilters, UserOptions, UserResponse, UserSort, VoteSort } from './types';
 import { ErrorFromResponse } from './types';
 import { InsightMetrics } from './insights';
 import { Thread } from './thread';
@@ -16,6 +16,7 @@ import { ThreadManager } from './thread_manager';
 import { PollManager } from './poll_manager';
 import type { ChannelManagerEventHandlerOverrides, ChannelManagerOptions, QueryChannelsRequestType } from './channel_manager';
 import { ChannelManager } from './channel_manager';
+import { MessageDeliveryReporter } from './messageDelivery';
 import { NotificationManager } from './notifications';
 import { ReminderManager } from './reminders';
 import { StateStore } from './store';
@@ -38,6 +39,7 @@ export type MessageComposerSetupState = {
 };
 export declare class StreamChat {
     private static _instance?;
+    messageDeliveryReporter: MessageDeliveryReporter;
     _user?: OwnUserResponse | UserResponse;
     appSettingsPromise?: Promise<AppSettingsAPIResponse>;
     activeChannels: {
@@ -1064,6 +1066,7 @@ export declare class StreamChat {
         status?: string;
         thread_participants?: UserResponse[];
         updated_at?: string;
+        deleted_for_me?: boolean;
     } & {
         quoted_message?: import("./types").MessageResponseBase;
     }>;
@@ -1140,10 +1143,17 @@ export declare class StreamChat {
     partialUpdateMessage(id: string, partialMessageObject: PartialMessageUpdate, partialUserOrUserId?: string | {
         id: string;
     }, options?: UpdateMessageOptions): Promise<UpdateMessageAPIResponse>;
-    deleteMessage(messageID: string, hardDelete?: boolean): Promise<APIResponse & {
+    /**
+     * deleteMessage - Delete a message
+     *
+     * @param {string} messageID The id of the message to delete
+     * @param {boolean | DeleteMessageOptions | undefined} [optionsOrHardDelete]
+     * @return {Promise<APIResponse & { message: MessageResponse }>} The API response
+     */
+    deleteMessage(messageID: string, optionsOrHardDelete?: DeleteMessageOptions | boolean): Promise<APIResponse & {
         message: MessageResponse;
     }>;
-    _deleteMessage(messageID: string, hardDelete?: boolean): Promise<APIResponse & {
+    _deleteMessage(messageID: string, optionsOrHardDelete?: DeleteMessageOptions | boolean): Promise<APIResponse & {
         message: MessageResponse;
     }>;
     /**
@@ -1730,6 +1740,7 @@ export declare class StreamChat {
         status?: string;
         thread_participants?: UserResponse[];
         updated_at?: string;
+        deleted_for_me?: boolean;
     } & {
         quoted_message?: import("./types").MessageResponseBase;
     }>;
@@ -1971,11 +1982,12 @@ export declare class StreamChat {
      */
     deleteImage(url: string): Promise<APIResponse>;
     /**
-     * Send the mark delivered event for this user, only works if the `delivery_receipts` setting is enabled
+     * Send the mark delivered event for this user
      *
      * @param {MarkDeliveredOptions} data
      * @return {Promise<EventAPIResponse | void>} Description
      */
-    markChannelsDelivered(data?: MarkDeliveredOptions): Promise<EventAPIResponse | undefined>;
+    markChannelsDelivered(data: MarkDeliveredOptions): Promise<EventAPIResponse | undefined>;
+    syncDeliveredCandidates(collections: Channel[]): void;
 }
 export {};

package/dist/types/events.d.ts

@@ -31,6 +31,7 @@ export declare const EVENT_MAP: {
     'notification.mark_unread': boolean;
     'notification.message_new': boolean;
     'notification.mutes_updated': boolean;
+    'notification.reminder_due': boolean;
     'notification.removed_from_channel': boolean;
     'notification.thread_message_new': boolean;
     'poll.closed': boolean;
@@ -41,6 +42,9 @@ export declare const EVENT_MAP: {
     'reaction.deleted': boolean;
     'reaction.new': boolean;
     'reaction.updated': boolean;
+    'reminder.created': boolean;
+    'reminder.deleted': boolean;
+    'reminder.updated': boolean;
     'thread.updated': boolean;
     'typing.start': boolean;
     'typing.stop': boolean;
@@ -64,8 +68,4 @@ export declare const EVENT_MAP: {
     'capabilities.changed': boolean;
     'live_location_sharing.started': boolean;
     'live_location_sharing.stopped': boolean;
-    'reminder.created': boolean;
-    'reminder.updated': boolean;
-    'reminder.deleted': boolean;
-    'notification.reminder_due': boolean;
 };

package/dist/types/index.d.ts

@@ -8,6 +8,7 @@ export * from './connection';
 export * from './events';
 export * from './insights';
 export * from './messageComposer';
+export * from './messageDelivery';
 export * from './middleware';
 export * from './moderation';
 export * from './notifications';

package/dist/types/messageDelivery/MessageDeliveryReporter.d.ts

@@ -0,0 +1,74 @@
+import type { StreamChat } from '../client';
+import { Channel } from '../channel';
+import { Thread } from '../thread';
+import type { EventAPIResponse, MarkDeliveredOptions, MarkReadOptions } from '../types';
+type MessageId = string;
+type ChannelThreadCompositeId = string;
+export type AnnounceDeliveryOptions = Omit<MarkDeliveredOptions, 'latest_delivered_messages'>;
+export type MessageDeliveryReporterOptions = {
+    client: StreamChat;
+};
+export declare class MessageDeliveryReporter {
+    protected client: StreamChat;
+    protected deliveryReportCandidates: Map<ChannelThreadCompositeId, MessageId>;
+    protected nextDeliveryReportCandidates: Map<ChannelThreadCompositeId, MessageId>;
+    protected markDeliveredRequestPromise: Promise<EventAPIResponse | void> | null;
+    protected markDeliveredTimeout: ReturnType<typeof setTimeout> | null;
+    constructor({ client }: MessageDeliveryReporterOptions);
+    private get markDeliveredRequestInFlight();
+    private get hasTimer();
+    private get hasDeliveryCandidates();
+    /**
+     * Build latest_delivered_messages payload from an arbitrary buffer (deliveryReportCandidates / nextDeliveryReportCandidates)
+     */
+    private confirmationsFrom;
+    private confirmationsFromDeliveryReportCandidates;
+    /**
+     * Generate candidate key for storing in the candidates buffer
+     * @param collection
+     * @private
+     */
+    private candidateKeyFor;
+    /**
+     * Retrieve the reference to the latest message in the state that is nor read neither reported as delivered
+     * @param collection
+     */
+    private getNextDeliveryReportCandidate;
+    /**
+     * Updates the delivery candidates buffer with the latest delivery candidates
+     * @param collection
+     */
+    private trackDeliveredCandidate;
+    /**
+     * Removes candidate from the delivery report buffer
+     * @param collection
+     * @private
+     */
+    private removeCandidateFor;
+    /**
+     * Records the latest message delivered for Channel or Thread instances and schedules the next report
+     * if not already scheduled and candidates exist.
+     * Should be used for WS handling (message.new) as well as for ingesting HTTP channel query results.
+     * @param collections
+     */
+    syncDeliveredCandidates(collections: (Channel | Thread)[]): void;
+    /**
+     * Fires delivery announcement request followed by immediate delivery candidate buffer reset.
+     * @param options
+     */
+    announceDelivery: (options?: AnnounceDeliveryOptions) => void;
+    announceDeliveryBuffered: (options?: AnnounceDeliveryOptions) => void;
+    /**
+     * Delegates the mark-read call to the Channel or Thread instance
+     * @param collection
+     * @param options
+     */
+    markRead: (collection: Channel | Thread, options?: MarkReadOptions) => Promise<EventAPIResponse | null>;
+    /**
+     * Throttles the MessageDeliveryReporter.markRead call
+     * @param collection
+     * @param options
+     */
+    throttledMarkRead: (collection: Channel | Thread, options?: MarkReadOptions | undefined) => void;
+}
+export {};

package/dist/types/messageDelivery/MessageReceiptsTracker.d.ts

@@ -0,0 +1,121 @@
+import type { ReadResponse, UserResponse } from '../types';
+type MessageId = string;
+export type MsgRef = {
+    timestampMs: number;
+    msgId: MessageId;
+};
+export type OwnMessageReceiptsTrackerMessageLocator = (timestampMs: number) => MsgRef | null;
+export type UserProgress = {
+    user: UserResponse;
+    lastReadRef: MsgRef;
+    lastDeliveredRef: MsgRef;
+};
+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 declare class MessageReceiptsTracker {
+    private byUser;
+    private readSorted;
+    private deliveredSorted;
+    private locateMessage;
+    constructor({ locateMessage }: OwnMessageReceiptsTrackerOptions);
+    /** Build initial state from server snapshots (single pass + sort). */
+    ingestInitial(responses: ReadResponse[]): void;
+    /** message.delivered — user device confirmed delivery up to and including messageId. */
+    onMessageDelivered({ user, deliveredAt, lastDeliveredMessageId, }: {
+        user: UserResponse;
+        deliveredAt: string;
+        lastDeliveredMessageId?: string;
+    }): void;
+    /** message.read — user read up to and including messageId. */
+    onMessageRead({ user, readAt, lastReadMessageId, }: {
+        user: UserResponse;
+        readAt: string;
+        lastReadMessageId?: string;
+    }): void;
+    /** 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;
+    }): void;
+    /** All users who READ this message. */
+    readersForMessage(msgRef: MsgRef): UserResponse[];
+    /** All users who have it DELIVERED (includes readers). */
+    deliveredForMessage(msgRef: MsgRef): UserResponse[];
+    /** Users who delivered but have NOT read. */
+    deliveredNotReadForMessage(msgRef: MsgRef): UserResponse[];
+    /** Users for whom `msgRef` is their *last read* (exact match). */
+    usersWhoseLastReadIs(msgRef: MsgRef): UserResponse[];
+    /** Users for whom `msgRef` is their *last delivered* (exact match). */
+    usersWhoseLastDeliveredIs(msgRef: MsgRef): UserResponse[];
+    hasUserRead(msgRef: MsgRef, userId: string): boolean;
+    hasUserDelivered(msgRef: MsgRef, userId: string): boolean;
+    getUserProgress(userId: string): UserProgress | null;
+    groupUsersByLastReadMessage(): Record<MessageId, UserResponse[]>;
+    groupUsersByLastDeliveredMessage(): Record<MessageId, UserResponse[]>;
+    private ensureUser;
+}
+export {};

package/dist/types/messageDelivery/index.d.ts

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

package/dist/types/types.d.ts

@@ -605,6 +605,7 @@ export type MessageResponseBase = MessageBase & {
     status?: string;
     thread_participants?: UserResponse[];
     updated_at?: string;
+    deleted_for_me?: boolean;
 };
 export type ReactionGroupResponse = {
     count: number;
@@ -821,7 +822,7 @@ export type BanUserOptions = UnBanUserOptions & {
     ip_ban?: boolean;
     reason?: string;
     timeout?: number;
-    delete_messages?: DeleteMessagesOptions;
+    delete_messages?: MessageDeletionStrategy;
 };
 export type ChannelOptions = {
     limit?: number;
@@ -1271,13 +1272,14 @@ 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;
     created_at?: string;
+    deleted_for_me?: boolean;
     draft?: DraftResponse;
     first_unread_message_id?: string;
     hard_delete?: boolean;
@@ -2627,13 +2629,18 @@ export type CustomCheckFlag = {
     labels?: string[];
     reason?: string;
 };
-export type DeleteMessagesOptions = 'soft' | 'hard';
+export type MessageDeletionStrategy = 'soft' | 'hard';
+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/dist/types/utils.d.ts

@@ -136,6 +136,7 @@ export declare const toDeletedMessage: ({ message, deletedAt, hardDelete, }: {
     shadowed?: boolean | undefined;
     shared_location?: import("./types").SharedLocationResponse | undefined;
     thread_participants?: UserResponse[] | undefined;
+    deleted_for_me?: boolean | undefined;
     created_at: Date;
     pinned_at: Date | null;
     status: string;
@@ -212,7 +213,7 @@ export declare const debounce: <T extends (...args: any[]) => any>(fn: T, timeou
     leading?: boolean;
     trailing?: boolean;
 }) => DebouncedFunc<T>;
-export declare const throttle: <T extends (...args: unknown[]) => unknown>(fn: T, timeout?: number, { leading, trailing }?: {
+export declare const throttle: <T extends (...args: any[]) => any>(fn: T, timeout?: number, { leading, trailing }?: {
     leading?: boolean;
     trailing?: boolean;
 }) => (...args: Parameters<T>) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stream-chat",
-  "version": "9.21.0",
+  "version": "9.22.1",
   "description": "JS SDK for the Stream Chat API",
   "homepage": "https://getstream.io/chat/",
   "author": {

package/src/channel.ts

@@ -1,4 +1,6 @@
 import { ChannelState } from './channel_state';
+import { MessageComposer } from './messageComposer';
+import { MessageReceiptsTracker } from './messageDelivery';
 import {
   generateChannelTempCid,
   logChatPromiseExecution,
@@ -74,7 +76,6 @@ import type {
 } from './types';
 import type { Role } from './permissions';
 import type { CustomChannelData } from './custom_types';
-import { MessageComposer } from './messageComposer';
 
 /**
  * Channel - The Channel class manages it's own state.
@@ -110,6 +111,7 @@ export class Channel {
   disconnected: boolean;
   push_preferences?: PushPreference;
   public readonly messageComposer: MessageComposer;
+  public readonly messageReceiptsTracker: MessageReceiptsTracker;
 
   /**
    * constructor - Create a channel
@@ -158,6 +160,13 @@ export class Channel {
       client: this._client,
       compositionContext: this,
     });
+
+    this.messageReceiptsTracker = new MessageReceiptsTracker({
+      locateMessage: (timestampMs) => {
+        const msg = this.state.findMessageByTimestamp(timestampMs);
+        return msg && { timestampMs, msgId: msg.id };
+      },
+    });
   }
 
   /**
@@ -1131,16 +1140,26 @@ export class Channel {
   }
 
   /**
-   * markRead - Send the mark read event for this user, only works if the `read_events` setting is enabled
+   * markRead - Send the mark read event for this user, only works if the `read_events` setting is enabled. Syncs the message delivery report candidates local state.
    *
    * @param {MarkReadOptions} data
    * @return {Promise<EventAPIResponse | null>} Description
    */
   async markRead(data: MarkReadOptions = {}) {
+    return await this.getClient().messageDeliveryReporter.markRead(this, data);
+  }
+
+  /**
+   * markReadRequest - Send the mark read event for this user, only works if the `read_events` setting is enabled
+   *
+   * @param {MarkReadOptions} data
+   * @return {Promise<EventAPIResponse | null>} Description
+   */
+  async markAsReadRequest(data: MarkReadOptions = {}) {
     this._checkInitialized();
 
     if (!this.getConfig()?.read_events && !this.getClient()._isUsingServerAuth()) {
-      return Promise.resolve(null);
+      return null;
     }
 
     return await this.getClient().post<EventAPIResponse>(this._channelURL() + '/read', {
@@ -1554,6 +1573,7 @@ export class Channel {
       { method: 'upsertChannels' },
     );
 
+    this.getClient().syncDeliveredCandidates([this]);
     return state;
   }
 
@@ -1874,18 +1894,50 @@ export class Channel {
         break;
       case 'message.read':
         if (event.user?.id && event.created_at) {
+          const previousReadState = channelState.read[event.user.id];
           channelState.read[event.user.id] = {
+            // in case we already have delivery information
+            ...previousReadState,
             last_read: new Date(event.created_at),
             last_read_message_id: event.last_read_message_id,
             user: event.user,
             unread_messages: 0,
           };
+          this.messageReceiptsTracker.onMessageRead({
+            user: event.user,
+            readAt: event.created_at,
+            lastReadMessageId: event.last_read_message_id,
+          });
+          const client = this.getClient();
 
-          if (event.user?.id === this.getClient().user?.id) {
+          const isOwnEvent = event.user?.id === client.user?.id;
+
+          if (isOwnEvent) {
             channelState.unreadCount = 0;
+            client.syncDeliveredCandidates([this]);
           }
         }
         break;
+      case 'message.delivered':
+        // todo: update also on thread
+        if (event.user?.id && event.created_at) {
+          const previousReadState = channelState.read[event.user.id];
+          channelState.read[event.user.id] = {
+            ...previousReadState,
+            last_delivered_at: event.last_delivered_at
+              ? new Date(event.last_delivered_at)
+              : undefined,
+            last_delivered_message_id: event.last_delivered_message_id,
+            user: event.user,
+          };
+
+          this.messageReceiptsTracker.onMessageDelivered({
+            user: event.user,
+            deliveredAt: event.created_at,
+            lastDeliveredMessageId: event.last_delivered_message_id,
+          });
+        }
+        break;
       case 'user.watching.start':
       case 'user.updated':
         if (event.user?.id) {
@@ -1921,8 +1973,9 @@ export class Channel {
         break;
       case 'message.new':
         if (event.message) {
+          const client = this.getClient();
           /* if message belongs to current user, always assume timestamp is changed to filter it out and add again to avoid duplication */
-          const ownMessage = event.user?.id === this.getClient().user?.id;
+          const ownMessage = event.user?.id === client.user?.id;
           const isThreadMessage =
             event.message.parent_id && !event.message.show_in_channel;
 
@@ -1947,6 +2000,8 @@ export class Channel {
                   last_read: new Date(event.created_at as string),
                   user: event.user,
                   unread_messages: 0,
+                  last_delivered_at: new Date(event.created_at as string),
+                  last_delivered_message_id: event.message.id,
                 };
               } else {
                 channelState.read[userId].unread_messages += 1;
@@ -1957,6 +2012,8 @@ export class Channel {
           if (this._countMessageAsUnread(event.message)) {
             channelState.unreadCount = channelState.unreadCount + 1;
           }
+
+          client.syncDeliveredCandidates([this]);
         }
         break;
       case 'message.updated':
@@ -2057,11 +2114,13 @@ export class Channel {
         break;
       case 'notification.mark_unread': {
         const ownMessage = event.user?.id === this.getClient().user?.id;
-        if (!(ownMessage && event.user)) break;
+        if (!ownMessage || !event.user) break;
 
         const unreadCount = event.unread_messages ?? 0;
-
+        const currentState = channelState.read[event.user.id];
         channelState.read[event.user.id] = {
+          // keep the message delivery info
+          ...currentState,
           first_unread_message_id: event.first_unread_message_id,
           last_read: new Date(event.last_read_at as string),
           last_read_message_id: event.last_read_message_id,
@@ -2070,6 +2129,11 @@ export class Channel {
         };
 
         channelState.unreadCount = unreadCount;
+        this.messageReceiptsTracker.onNotificationMarkUnread({
+          user: event.user,
+          lastReadAt: event.last_read_at,
+          lastReadMessageId: event.last_read_message_id,
+        });
         break;
       }
       case 'channel.updated':
@@ -2286,6 +2350,8 @@ export class Channel {
           this.state.unreadCount = this.state.read[read.user.id].unread_messages;
         }
       }
+
+      this.messageReceiptsTracker.ingestInitial(state.read);
     }
 
     return {