stream-chat 9.50.3 → 10.0.0-rc.2

package/src/channel.ts

@@ -1,101 +1,163 @@
 import type { AxiosRequestConfig } from 'axios';
 import { ChannelState } from './channel_state';
 import { CooldownTimer } from './CooldownTimer';
+import { isEphemeral } from './errors';
+import { applyReactionLocally } from './entityStore';
 import { MessageComposer } from './messageComposer';
 import { MessageReceiptsTracker } from './messageDelivery';
+import type { ReadStoreReconcileMeta } from './messageDelivery';
+import { MessagePaginator, PinnedMessagePaginator } from './pagination/paginators';
+import { MessageOperations } from './messageOperations';
 import {
   channelHasReadEvents,
+  formatMessage,
   generateChannelTempCid,
+  localMessageToNewMessagePayload,
   logChatPromiseExecution,
-  messageSetPagination,
-  normalizeQuerySort,
 } from './utils';
 import type { StreamChat } from './client';
+import { chatLoggerSystem } from './logger';
 import { DEFAULT_QUERY_CHANNEL_MESSAGE_LIST_PAGE_SIZE } from './constants';
 import type {
   AIState,
   APIResponse,
-  AscDesc,
   BanUserOptions,
-  ChannelAPIResponse,
   ChannelData,
-  ChannelFilters,
-  ChannelMemberAPIResponse,
+  ChannelGetOrCreateRequest,
   ChannelMemberResponse,
-  ChannelPushPreference,
-  ChannelQueryOptions,
   ChannelResponse,
+  ChannelStateResponseFields,
   ChannelUpdateOptions,
   CreateDraftResponse,
-  DeleteChannelAPIResponse,
-  DraftMessagePayload,
+  DeleteMessageOptions,
   Event,
   EventAPIResponse,
   EventHandler,
-  EventTypes,
-  GetDraftResponse,
-  GetMultipleMessagesAPIResponse,
-  GetReactionsAPIResponse,
+  EventPayload,
+  EventType,
   GetRepliesAPIResponse,
-  LiveLocationPayload,
+  GetRepliesRequest,
   LocalMessage,
-  MarkReadOptions,
-  MarkUnreadOptions,
-  MemberFilters,
-  MemberSort,
-  Message,
-  MessageFilters,
-  MessageOptions,
+  MarkReadRequest,
+  MarkUnreadRequest,
   MessagePaginationOptions,
+  MessageRequest,
   MessageResponse,
   MessageSetType,
-  MuteChannelAPIResponse,
-  NewMemberPayload,
-  PartialUpdateChannel,
-  PartialUpdateChannelAPIResponse,
-  PartialUpdateMember,
-  PartialUpdateMemberAPIResponse,
   PinnedMessagePaginationOptions,
   PinnedMessagesSort,
-  PollVoteData,
-  QueryChannelAPIResponse,
-  QueryMembersOptions,
-  Reaction,
+  QueryMembersPayload,
   ReactionAPIResponse,
-  SearchAPIResponse,
-  SearchMessageSortBase,
-  SearchOptions,
+  ReactionRequest,
   SearchPayload,
-  SendMessageAPIResponse,
   SendMessageOptions,
-  SendReactionOptions,
-  StaticLocationPayload,
-  TruncateChannelAPIResponse,
-  TruncateOptions,
+  SendReactionRequest,
+  SharedLocation,
   UnBanUserOptions,
-  UpdateChannelAPIResponse,
-  UpdateChannelOptions,
-  UpdateLocationPayload,
+  UpdateChannelPartialRequest,
+  UpdateLiveLocationRequest,
+  UpdateMessageOptions,
   UserResponse,
 } from './types';
-import type { Role } from './permissions';
-import type { CustomChannelData } from './custom_types';
+import type { RoleName } from './permissions';
+import { StateStore } from './store';
+import type {
+  ChannelMemberRequest as Gen_ChannelMemberRequest,
+  ChannelPushPreferencesResponse as Gen_ChannelPushPreferencesResponse,
+  ChannelStopWatchingRequest as Gen_ChannelStopWatchingRequest,
+  CreateDraftRequest as Gen_CreateDraftRequest,
+  HideChannelRequest as Gen_HideChannelRequest,
+  MuteChannelRequest as Gen_MuteChannelRequest,
+  SendMessageRequest as Gen_SendMessageRequest,
+  ShowChannelRequest as Gen_ShowChannelRequest,
+  UnmuteChannelRequest as Gen_UnmuteChannelRequest,
+  UpdateChannelRequest as Gen_UpdateChannelRequest,
+  WSEvent,
+} from './gen/models';
+import type { ChatApi } from './gen/chat/ChatApi';
+import { ChannelApi } from './gen/chat/ChannelApi';
+
+const logger = chatLoggerSystem.getLogger('channel');
+const offlineDbLogger = chatLoggerSystem.getLogger('offline-db');
+
+// todo: move to dedicated file
+export type SendMessageWithStateUpdateParams = {
+  localMessage: LocalMessage;
+  message?: MessageRequest;
+  options?: SendMessageOptions;
+  /**
+   * Per-call override for the send/retry request (advanced).
+   * If set, it takes precedence over channel instance configuration handlers.
+   */
+  sendMessageRequestFn?: CustomSendMessageRequestFn;
+};
+
+export type RetrySendMessageWithLocalUpdateParams = Omit<
+  SendMessageWithStateUpdateParams,
+  'message'
+>;
+
+export type UpdateMessageWithStateUpdateParams = {
+  localMessage: LocalMessage;
+  options?: UpdateMessageOptions;
+  /**
+   * Per-call override for the update request (advanced).
+   * If set, it takes precedence over channel instance configuration handlers.
+   */
+  updateMessageRequestFn?: CustomUpdateMessageRequestFn;
+};
+
+export type DeleteMessageWithStateUpdateParams = {
+  localMessage: LocalMessage;
+  options?: DeleteMessageOptions;
+  /**
+   * Per-call override for the delete request (advanced).
+   * If set, it takes precedence over channel instance configuration handlers.
+   */
+  deleteMessageRequestFn?: CustomDeleteMessageRequestFn;
+};
+
+// Custom request function types for configuration
+export type CustomSendMessageRequestFn = (
+  params: Omit<SendMessageWithStateUpdateParams, 'sendMessageRequestFn'>,
+) => Promise<{ message: MessageResponse }>;
+
+export type CustomUpdateMessageRequestFn = (
+  params: Omit<UpdateMessageWithStateUpdateParams, 'updateMessageRequestFn'>,
+) => Promise<{ message: MessageResponse }>;
+
+export type CustomDeleteMessageRequestFn = (
+  params: Omit<DeleteMessageWithStateUpdateParams, 'deleteMessageRequestFn'>,
+) => Promise<{ message: MessageResponse }>;
+
+export type CustomMarkReadRequestFn = (params: {
+  channel: Channel;
+  options?: MarkReadRequest;
+}) => Promise<EventAPIResponse | null>;
+
+export type ChannelInstanceConfig = {
+  requestHandlers?: {
+    deleteMessageRequest?: CustomDeleteMessageRequestFn;
+    markReadRequest?: CustomMarkReadRequestFn;
+    sendMessageRequest?: CustomSendMessageRequestFn;
+    retrySendMessageRequest?: CustomSendMessageRequestFn;
+    updateMessageRequest?: CustomUpdateMessageRequestFn;
+  };
+};
 
 /**
- * Channel - The Channel class manages it's own state.
+ * The Channel class manages its own state.
  */
-export class Channel {
+export class Channel extends ChannelApi {
   _client: StreamChat;
-  type: string;
-  id: string | undefined;
-  data: Partial<ChannelData & ChannelResponse> | undefined;
-  _data: Partial<ChannelData & ChannelResponse>;
+  data: Partial<ChannelResponse> | undefined;
+  _data: ChannelData;
   cid: string;
   /**  */
-  listeners: { [key: string]: (string | EventHandler)[] };
+  listeners: Map<EventType, Set<EventHandler>>;
   state: ChannelState;
   /**
-   * This boolean is a vague indication of weather the channel exists on chat backend.
+   * This boolean is a vague indication of whether the channel exists on chat backend.
    *
    * If the value is true, then that means the channel has been initialized by either calling
    * channel.create() or channel.query() or channel.watch().
@@ -105,7 +167,7 @@ export class Channel {
    */
   initialized: boolean;
   /**
-   * Indicates weather channel has been initialized by manually populating the state with some messages, members etc.
+   * Indicates whether channel has been initialized by manually populating the state with some messages, members etc.
    * Static state indicates that channel exists on backend, but is not being watched yet.
    */
   offlineMode: boolean;
@@ -113,20 +175,23 @@ export class Channel {
   lastTypingEvent: Date | null;
   isTyping: boolean;
   disconnected: boolean;
-  push_preferences?: ChannelPushPreference;
+  push_preferences?: Gen_ChannelPushPreferencesResponse;
+  public readonly configState = new StateStore<ChannelInstanceConfig>({});
   public readonly messageComposer: MessageComposer;
   public readonly messageReceiptsTracker: MessageReceiptsTracker;
+  public readonly messagePaginator: MessagePaginator;
+  public readonly pinnedMessagesPaginator: PinnedMessagePaginator;
+  public readonly messageOperations: MessageOperations;
   public readonly cooldownTimer: CooldownTimer;
 
   /**
-   * constructor - Create a channel
+   * Creates a `Channel` instance bound to the given chat client.
    *
-   * @param {StreamChat} client the chat client
-   * @param {string} type  the type of channel
-   * @param {string} [id]  the id of the chat
-   * @param {ChannelData} data any additional custom params
-   *
-   * @return {Channel} Returns a new uninitialized channel
+   * @param client - The chat client.
+   * @param type - The type of channel.
+   * @param id - The ID of the chat (optional).
+   * @param data - Any additional custom params.
+   * @returns A new uninitialized channel.
    */
   constructor(
     client: StreamChat,
@@ -144,15 +209,15 @@ export class Channel {
       throw new Error(`Invalid chat id ${id}, letters, numbers and "!-_" are allowed`);
     }
 
+    super(client, type, id);
+
     this._client = client;
-    this.type = type;
-    this.id = id;
     // used by the frontend, gets updated:
-    this.data = data;
+    this.data = data as Partial<ChannelResponse>;
     // this._data is used for the requests...
     this._data = { ...data };
     this.cid = `${type}:${id}`;
-    this.listeners = {};
+    this.listeners = new Map();
     // perhaps the state variable should be private
     this.state = new ChannelState(this);
     this.initialized = false;
@@ -166,20 +231,87 @@ export class Channel {
       compositionContext: this,
     });
 
-    this.messageReceiptsTracker = new MessageReceiptsTracker({
-      locateMessage: (timestampMs) => {
-        const msg = this.state.findMessageByTimestamp(timestampMs);
-        return msg && { timestampMs, msgId: msg.id };
-      },
-    });
+    // Created before MessageReceiptsTracker and CooldownTimer: both read the message paginator
+    // (receipts resolve read cursors via findItemByTimestamp; CooldownTimer.refresh reads the
+    // latest window at construction).
+    this.messagePaginator = new MessagePaginator({ channel: this });
+    this.pinnedMessagesPaginator = new PinnedMessagePaginator({ channel: this });
+
+    this.messageReceiptsTracker = new MessageReceiptsTracker({ channel: this });
+    this.messageReceiptsTracker.registerSubscriptions();
 
     this.cooldownTimer = new CooldownTimer({ channel: this });
+
+    this.messageOperations = new MessageOperations({
+      ingest: (m) => {
+        this.messagePaginator.ingestItem(m);
+        this.getClient().messageStore.flushSubscribers(m.id);
+      },
+      get: (id) => this.messagePaginator.getItem(id),
+      handlers: () => {
+        const { requestHandlers } = this.configState.getLatestValue();
+        const deleteMessageRequest = requestHandlers?.deleteMessageRequest;
+        const sendMessageRequest = requestHandlers?.sendMessageRequest;
+        const retrySendMessageRequest = requestHandlers?.retrySendMessageRequest;
+        const updateMessageRequest = requestHandlers?.updateMessageRequest;
+        return {
+          delete: deleteMessageRequest
+            ? (p) =>
+                deleteMessageRequest({
+                  localMessage: p.localMessage,
+                  options: p.options,
+                })
+            : undefined,
+          send: sendMessageRequest
+            ? (p) =>
+                sendMessageRequest({
+                  localMessage: p.localMessage,
+                  message: p.message,
+                  options: p.options,
+                })
+            : undefined,
+          retry: retrySendMessageRequest
+            ? (p) =>
+                retrySendMessageRequest({
+                  localMessage: p.localMessage,
+                  message: p.message,
+                  options: p.options,
+                })
+            : undefined,
+          update: updateMessageRequest
+            ? (p) =>
+                updateMessageRequest({
+                  localMessage: p.localMessage,
+                  options: p.options,
+                })
+            : undefined,
+        };
+      },
+      defaults: {
+        delete: async (id, o) => {
+          const result = await this.getClient().deleteMessage({ id, ...o });
+          return { message: result.message };
+        },
+        send: async (m, o) => {
+          const result = await this.sendMessage({ message: m, ...o });
+          return { message: result.message };
+        },
+        update: async (m, o) => {
+          const result = await this.getClient().updateMessage({
+            id: m.id,
+            message: localMessageToNewMessagePayload(m),
+            ...o,
+          });
+          return { message: result.message };
+        },
+      },
+    });
   }
 
   /**
-   * getClient - Get the chat client for this channel. If client.disconnect() was called, this function will error
+   * Returns the chat client for this channel. Throws if `client.disconnect()` was called.
    *
-   * @return {StreamChat}
+   * @returns The chat client.
    */
   getClient(): StreamChat {
     if (this.disconnected === true) {
@@ -189,73 +321,186 @@ export class Channel {
   }
 
   /**
-   * getConfig - Get the config for this channel id (cid)
+   * Returns the config for this channel ID (CID).
    *
-   * @return {Record<string, unknown>}
+   * @returns The channel config.
    */
   getConfig() {
     const client = this.getClient();
     return client.configs[this.cid];
   }
 
+  _sendMessage(request: Gen_SendMessageRequest) {
+    return super.sendMessage(request);
+  }
+
   /**
-   * sendMessage - Send a message to this channel
+   * Sends a message to this channel.
    *
-   * @param {Message} message The Message object
-   * @param {boolean} [options.skip_enrich_url] Do not try to enrich the URLs within message
-   * @param {boolean} [options.skip_push] Skip sending push notifications
-   * @param {boolean} [options.is_pending_message] DEPRECATED, please use `pending` instead.
-   * @param {boolean} [options.pending] Make this message pending
-   * @param {Record<string,string>} [options.pending_message_metadata] Metadata for the pending message
-   * @param {boolean} [options.force_moderation] Apply force moderation for server-side requests
-   *
-   * @return {Promise<SendMessageAPIResponse>} The Server Response
+   * @param request - The send message request payload, including the message body and optional flags
+   *   such as `skip_enrich_url`, `skip_push`, and `keep_channel_hidden`.
+   * @returns The server response.
+   */
+  override async sendMessage(request: Gen_SendMessageRequest) {
+    try {
+      const offlineDb = this.getClient().offlineDb;
+      const messageId = request.message?.id;
+      if (offlineDb && messageId) {
+        return await offlineDb.queueTask<Awaited<ReturnType<ChatApi['sendMessage']>>>({
+          task: {
+            channelId: this.id as string,
+            channelType: this.type,
+            messageId,
+            payload: [request],
+            type: 'send-message',
+          },
+        });
+      }
+    } catch (error) {
+      offlineDbLogger
+        .withExtraTags('sendMessage', this.cid)
+        .error('Sending the message failed.', { error });
+    }
+    return await this._sendMessage(request);
+  }
+
+  /**
+   * Sends a message with optimistic local state update.
    */
-  async _sendMessage(message: Message, options?: SendMessageOptions) {
-    return await this.getClient().post<SendMessageAPIResponse>(
-      this._channelURL() + '/message',
+  async sendMessageWithLocalUpdate(
+    params: SendMessageWithStateUpdateParams,
+  ): Promise<void> {
+    await this.messageOperations.send(
       {
-        message,
-        ...options,
+        localMessage: params.localMessage,
+        message: params.message,
+        options: params.options,
+      },
+      params.sendMessageRequestFn,
+    );
+    if (this.messageComposer.config.text.publishTypingEvents) await this.stopTyping();
+  }
+
+  /**
+   * Retry sending a failed message.
+   */
+  async retrySendMessageWithLocalUpdate(
+    params: Omit<SendMessageWithStateUpdateParams, 'message'>,
+  ) {
+    await this.messageOperations.retry(
+      {
+        localMessage: { ...params.localMessage, type: 'regular' },
+        options: params.options,
       },
+      params.sendMessageRequestFn,
     );
   }
 
-  async sendMessage(message: Message, options?: SendMessageOptions) {
+  /**
+   * Updates a message with optimistic local state update.
+   */
+  async updateMessageWithLocalUpdate(params: UpdateMessageWithStateUpdateParams) {
+    await this.messageOperations.update(
+      {
+        localMessage: params.localMessage,
+        options: params.options,
+      },
+      params.updateMessageRequestFn,
+    );
+  }
+
+  /**
+   * Deletes a message with local state update.
+   */
+  async deleteMessageWithLocalUpdate(params: DeleteMessageWithStateUpdateParams) {
+    await this.messageOperations.delete(
+      {
+        localMessage: params.localMessage,
+        options: params.options,
+      },
+      params.deleteMessageRequestFn,
+    );
+  }
+
+  /**
+   * Adds a reaction with an optimistic local state update: the reaction is applied to the cached
+   * message immediately ({@link applyReactionLocally}), then the request is
+   * fired via {@link Channel.sendReaction} (which owns the offline-DB write + queue). The
+   * server-authoritative counts reconcile on the response; the message is rolled back on failure.
+   */
+  async addReactionWithLocalUpdate({
+    messageId,
+    reaction,
+    options,
+  }: {
+    messageId: string;
+    reaction: ReactionRequest;
+    options?: Pick<SendReactionRequest, 'enforce_unique' | 'skip_push'>;
+  }) {
+    const client = this.getClient();
+    const undo = applyReactionLocally(client, {
+      enforceUnique: options?.enforce_unique ?? false,
+      messageId,
+      reaction,
+    });
+
     try {
-      const offlineDb = this.getClient().offlineDb;
-      if (offlineDb) {
-        const messageId = message.id;
-        if (messageId) {
-          return await offlineDb.queueTask<SendMessageAPIResponse>({
-            task: {
-              channelId: this.id as string,
-              channelType: this.type,
-              messageId,
-              payload: [message, options],
-              type: 'send-message',
-            },
-          });
-        }
+      const response = await this.sendReaction({ id: messageId, reaction, ...options });
+      // reconcile the server copy only if we still hold it — a bare upsert of an unheld id would
+      // orphan it (the store's refcount GC only reclaims held ids).
+      if (response?.message && client.messageStore.has(response.message.id)) {
+        client.messageStore.upsert(formatMessage(response.message));
       }
     } catch (error) {
-      this._client.logger('error', `offlineDb:send-message`, {
-        tags: ['channel', 'offlineDb'],
-        error,
-      });
+      if (undo && (!client.offlineDb || !isEphemeral(error as Error))) {
+        undo();
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Removes the current user's reaction with an optimistic local state update, mirroring
+   * {@link Channel.addReactionWithLocalUpdate}.
+   */
+  async deleteReactionWithLocalUpdate({
+    messageId,
+    type,
+  }: {
+    messageId: string;
+    type: string;
+  }) {
+    const client = this.getClient();
+    const undo = applyReactionLocally(client, {
+      messageId,
+      reaction: { type },
+      removed: true,
+    });
+
+    try {
+      const response = await this.deleteReaction({ id: messageId, type });
+      // reconcile the server copy only if we still hold it — a bare upsert of an unheld id would
+      // orphan it (the store's refcount GC only reclaims held ids).
+      if (response?.message && client.messageStore.has(response.message.id)) {
+        client.messageStore.upsert(formatMessage(response.message));
+      }
+    } catch (error) {
+      if (undo && (!client.offlineDb || !isEphemeral(error as Error))) {
+        undo();
+      }
+      throw error;
     }
-    return await this._sendMessage(message, options);
   }
 
   /**
    * Upload a file to this channel’s file endpoint (multipart). Forwards to the client’s `sendFile` implementation.
    *
-   * @param uri File source: URL string, `File`, `Buffer`, or readable stream (Node).
-   * @param name File name sent in the multipart body.
-   * @param contentType MIME type; defaults are applied when omitted.
-   * @param user Optional user payload appended to the form as JSON.
-   * @param axiosRequestConfig Optional Axios per-request config, merged after upload defaults (e.g. `onUploadProgress`, `signal` from `AbortController`).
-   * @return Promise resolving to `{ file: string, ... }` with the CDN URL.
+   * @param uri - File source: URL string, `File`, `Buffer`, or readable stream (Node).
+   * @param name - File name sent in the multipart body (optional).
+   * @param contentType - MIME type; defaults are applied when omitted (optional).
+   * @param user - User payload appended to the form as JSON (optional).
+   * @param axiosRequestConfig - Axios per-request config, merged after upload defaults, e.g. `onUploadProgress`, `signal` from `AbortController` (optional).
+   * @returns A promise resolving to `{ file: string, ... }` with the CDN URL.
    */
   sendFile(
     uri: string | NodeJS.ReadableStream | Buffer | File,
@@ -264,7 +509,7 @@ export class Channel {
     user?: UserResponse,
     axiosRequestConfig?: AxiosRequestConfig,
   ) {
-    return this.getClient().sendFile(
+    return this.getClient().api.sendFile(
       `${this._channelURL()}/file`,
       uri,
       name,
@@ -275,14 +520,14 @@ export class Channel {
   }
 
   /**
-   * Upload an image to this channel’s image endpoint (multipart). Uses the same transport as `sendFile`.
+   * Upload an image to this channel's image endpoint (multipart). Uses the same transport as `sendFile`.
    *
-   * @param uri Image source: URL string, `File`, or readable stream (Node). For `Buffer` uploads, use `sendFile` toward the channel file endpoint instead.
-   * @param name File name sent in the multipart body.
-   * @param contentType MIME type.
-   * @param user Optional user payload appended to the form as JSON.
-   * @param axiosRequestConfig Optional Axios per-request config, merged after upload defaults (e.g. `onUploadProgress`, `signal`).
-   * @return Promise resolving to `{ file: string, ... }` with the CDN URL.
+   * @param uri - Image source: URL string, `File`, or readable stream (Node). For `Buffer` uploads, use `sendFile` toward the channel file endpoint instead.
+   * @param name - File name sent in the multipart body (optional).
+   * @param contentType - MIME type (optional).
+   * @param user - User payload appended to the form as JSON (optional).
+   * @param axiosRequestConfig - Axios per-request config, merged after upload defaults, e.g. `onUploadProgress`, `signal` (optional).
+   * @returns A promise resolving to `{ file: string, ... }` with the CDN URL.
    */
   sendImage(
     uri: string | NodeJS.ReadableStream | File,
@@ -291,7 +536,7 @@ export class Channel {
     user?: UserResponse,
     axiosRequestConfig?: AxiosRequestConfig,
   ) {
-    return this.getClient().sendFile(
+    return this.getClient().api.sendFile(
       `${this._channelURL()}/image`,
       uri,
       name,
@@ -302,427 +547,223 @@ export class Channel {
   }
 
   deleteFile(url: string) {
-    return this.getClient().delete<APIResponse>(`${this._channelURL()}/file`, { url });
+    return this.deleteChannelFile({ url });
   }
 
   deleteImage(url: string) {
-    return this.getClient().delete<APIResponse>(`${this._channelURL()}/image`, { url });
+    return this.deleteChannelImage({ url });
   }
 
   /**
-   * sendEvent - Send an event on this channel
-   *
-   * @param {Event} event for example {type: 'message.read'}
+   * Sends an event on this channel.
    *
-   * @return {Promise<EventAPIResponse>} The Server Response
+   * @param event - For example `{ type: 'message.read' }`.
+   * @returns The server response.
    */
-  async sendEvent(event: Event) {
+  override async sendEvent(request: { event: Event }) {
     this._checkInitialized();
-    return await this.getClient().post<EventAPIResponse>(this._channelURL() + '/event', {
-      event,
-    });
+    return await super.sendEvent(request);
   }
 
   /**
-   * search - Query messages
-   *
-   * @param {MessageFilters | string}  query search query or object MongoDB style filters
-   * @param {{client_id?: string; connection_id?: string; query?: string; message_filter_conditions?: MessageFilters}} options Option object, {user_id: 'tommaso'}
+   * Queries messages.
    *
-   * @return {Promise<SearchAPIResponse>} search messages response
+   * @param request - The search request payload (optional). The inner `payload` accepts
+   *   MongoDB-style filters and additional options such as `user_id`.
+   * @returns The search messages response.
    */
-  async search(
-    query: MessageFilters | string,
-    options: SearchOptions & {
-      client_id?: string;
-      connection_id?: string;
-      message_filter_conditions?: MessageFilters;
-      message_options?: MessageOptions;
-      query?: string;
-    } = {},
-  ) {
-    if (options.offset && options.next) {
-      throw Error(`Cannot specify offset with next`);
-    }
-    // Return a list of channels
-    const payload: SearchPayload = {
-      filter_conditions: { cid: this.cid } as ChannelFilters,
-      ...options,
-      sort: options.sort
-        ? normalizeQuerySort<SearchMessageSortBase>(options.sort)
-        : undefined,
-    };
-    if (typeof query === 'string') {
-      payload.query = query;
-    } else if (typeof query === 'object') {
-      payload.message_filter_conditions = query;
-    } else {
-      throw Error(`Invalid type ${typeof query} for query parameter`);
-    }
-    // Make sure we wait for the connect promise if there is a pending one
-    await this.getClient().wsPromise;
-
-    return await this.getClient().get<SearchAPIResponse>(
-      this.getClient().baseURL + '/search',
-      {
-        payload,
-      },
-    );
+  async search(request?: { payload?: SearchPayload }) {
+    return await this.getClient().search(request);
   }
 
   /**
-   * queryMembers - Query Members
-   *
-   * @param {MemberFilters}  filterConditions object MongoDB style filters
-   * @param {MemberSort} [sort] Sort options, for instance [{created_at: -1}].
-   * When using multiple fields, make sure you use array of objects to guarantee field order, for instance [{name: -1}, {created_at: 1}]
-   * @param {{ limit?: number; offset?: number }} [options] Option object, {limit: 10, offset:10}
+   * Queries members.
    *
-   * @return {Promise<ChannelMemberAPIResponse>} Query Members response
+   * @param request - The query members request payload (optional). The inner `payload` accepts
+   *   MongoDB-style filters, sort directions (e.g. `[{ field: 'created_at', direction: -1 }]`),
+   *   and pagination options (`limit`, `offset`).
+   * @returns The query members response.
    */
-  async queryMembers(
-    filterConditions: MemberFilters,
-    sort: MemberSort = [],
-    options: QueryMembersOptions = {},
-  ) {
-    let id: string | undefined;
-    const type = this.type;
-    let members: string[] | ChannelMemberResponse[] | undefined;
+  async queryMembers(request?: { payload?: Partial<QueryMembersPayload> }) {
+    const payload = {
+      type: this.type,
+      // TODO: these should be probably optional in the OAPI spec
+      // filter_conditions: ...
+    } as QueryMembersPayload;
+
     if (this.id) {
-      id = this.id;
-    } else if (this.data?.members && Array.isArray(this.data.members)) {
-      members = this.data.members;
+      payload.id = this.id;
+    } else if (Array.isArray(this.data?.members)) {
+      payload.members = this.data.members.map((m) => ({
+        ...m,
+        // TODO: this should not be needed Gen_QueryMembersResponse should not come with user_id as optinal
+        user_id: (m.user_id ?? m.user?.id) as string,
+      }));
     }
     // Return a list of members
-    return await this.getClient().get<ChannelMemberAPIResponse>(
-      this.getClient().baseURL + '/members',
-      {
-        payload: {
-          type,
-          id,
-          members,
-          sort: normalizeQuerySort(sort),
-          filter_conditions: filterConditions,
-          ...options,
-        },
+    return await this.getClient().queryMembers({
+      payload: {
+        ...payload,
+        ...request?.payload,
       },
-    );
-  }
-
-  /**
-   * updateMemberPartial - Partial update a member
-   *
-   * @param {PartialUpdateMember}  updates
-   * @param {{ user_id?: string }} [options] Option object, {user_id: 'jane'} to optionally specify the user id
-
-   * @return {Promise<ChannelMemberResponse>} Updated member
-   */
-  async updateMemberPartial(updates: PartialUpdateMember, options?: { userId?: string }) {
-    const url = new URL(`${this._channelURL()}/member`);
-
-    if (options?.userId) {
-      url.searchParams.append('user_id', options.userId);
-    }
-
-    return await this.getClient().patch<PartialUpdateMemberAPIResponse>(
-      url.toString(),
-      updates,
-    );
-  }
-
-  /**
-   * @deprecated Use `updateMemberPartial` instead
-   * partialUpdateMember - Partial update a member
-   *
-   * @param {string} user_id member user id
-   * @param {PartialUpdateMember}  updates
-   *
-   * @return {Promise<ChannelMemberResponse>} Updated member
-   */
-  async partialUpdateMember(user_id: string, updates: PartialUpdateMember) {
-    if (!user_id) {
-      throw Error('Please specify the user id');
-    }
-
-    return await this.getClient().patch<PartialUpdateMemberAPIResponse>(
-      this._channelURL() + `/member/${encodeURIComponent(user_id)}`,
-      updates,
-    );
+    });
   }
 
   /**
-   * sendReaction - Sends a reaction to a message. If offline support is enabled, it will make sure
+   * Sends a reaction to a message. If offline support is enabled, it will make sure
    * that sending the reaction is queued up if it fails due to bad internet conditions and executed
    * later.
    *
-   * @param {string} messageID the message id
-   * @param {Reaction} reaction the reaction object for instance {type: 'love'}
-   * @param {{ enforce_unique?: boolean, skip_push?: boolean }} [options] Option object, {enforce_unique: true, skip_push: true} to override any existing reaction or skip sending push notifications
-   *
-   * @return {Promise<ReactionAPIResponse>} The Server Response
+   * @param request - The send-reaction request payload, including the target message ID, the
+   *   reaction object (e.g. `{ type: 'love' }`), and optional flags such as `enforce_unique` and
+   *   `skip_push`.
+   * @returns The server response.
    */
-  async sendReaction(
-    messageID: string,
-    reaction: Reaction,
-    options?: SendReactionOptions,
-  ) {
-    if (!messageID) {
-      throw Error(`Message id is missing`);
-    }
-    if (!reaction || Object.keys(reaction).length === 0) {
-      throw Error(`Reaction object is missing`);
-    }
+  async sendReaction(request: Parameters<ChatApi['sendReaction']>[0]) {
+    const { id: messageId } = request;
 
     try {
       const offlineDb = this.getClient().offlineDb;
       if (offlineDb) {
+        // The optimistic reaction row is written by the local-update layer
+        // (`applyReactionLocally`); here we only queue the request for replay.
         return await offlineDb.queueTask<ReactionAPIResponse>({
           task: {
             channelId: this.id as string,
             channelType: this.type,
-            messageId: messageID,
-            payload: [messageID, reaction, options],
+            messageId,
+            payload: [request],
             type: 'send-reaction',
           },
         });
       }
     } catch (error) {
-      this._client.logger('error', `offlineDb:send-reaction`, {
-        tags: ['channel', 'offlineDb'],
-        error,
-      });
+      offlineDbLogger
+        .withExtraTags('sendReaction', this.cid)
+        .error('Sending the reaction failed.', { error });
     }
 
-    return this._sendReaction(messageID, reaction, options);
+    return this._sendReaction(request);
   }
 
-  /**
-   * sendReaction - Send a reaction about a message
-   *
-   * @param {string} messageID the message id
-   * @param {Reaction} reaction the reaction object for instance {type: 'love'}
-   * @param {{ enforce_unique?: boolean, skip_push?: boolean }} [options] Option object, {enforce_unique: true, skip_push: true} to override any existing reaction or skip sending push notifications
-   *
-   * @return {Promise<ReactionAPIResponse>} The Server Response
-   */
-  async _sendReaction(
-    messageID: string,
-    reaction: Reaction,
-    options?: SendReactionOptions,
-  ) {
-    if (!messageID) {
-      throw Error(`Message id is missing`);
-    }
-    if (!reaction || Object.keys(reaction).length === 0) {
-      throw Error(`Reaction object is missing`);
-    }
-
-    return await this.getClient().post<ReactionAPIResponse>(
-      this.getClient().baseURL + `/messages/${encodeURIComponent(messageID)}/reaction`,
-      {
-        reaction,
-        ...options,
-      },
-    );
+  _sendReaction(request: Parameters<ChatApi['sendReaction']>[0]) {
+    return this.getClient().sendReaction(request);
   }
 
-  async deleteReaction(messageID: string, reactionType: string, user_id?: string) {
+  async deleteReaction(request: Parameters<ChatApi['deleteReaction']>[0]) {
     this._checkInitialized();
-    if (!reactionType || !messageID) {
-      throw Error(
-        'Deleting a reaction requires specifying both the message and reaction type',
-      );
-    }
 
     try {
       const offlineDb = this.getClient().offlineDb;
       if (offlineDb) {
-        const message = this.state.messages.find(({ id }) => id === messageID);
-        const reaction = {
-          created_at: '',
-          updated_at: '',
-          message_id: messageID,
-          type: reactionType,
-          user_id: (this.getClient().userID as string) ?? user_id,
-        };
-
-        if (message) {
-          await offlineDb.deleteReaction({
-            message,
-            reaction,
-          });
-        }
-
+        // The optimistic reaction-row removal is handled by the local-update layer
+        // (`applyReactionLocally`); here we only queue the request for replay.
         return await offlineDb.queueTask<ReactionAPIResponse>({
           task: {
             channelId: this.id as string,
             channelType: this.type,
-            messageId: messageID,
-            payload: [messageID, reactionType],
+            messageId: request.id,
+            payload: [request],
             type: 'delete-reaction',
           },
         });
       }
     } catch (error) {
-      this._client.logger('error', `offlineDb:delete-reaction`, {
-        tags: ['channel', 'offlineDb'],
-        error,
-      });
+      offlineDbLogger
+        .withExtraTags('deleteReaction', this.cid)
+        .error('Deleting the reaction failed.', { error });
     }
 
-    return await this._deleteReaction(messageID, reactionType, user_id);
+    return await this._deleteReaction(request);
   }
 
   /**
-   * deleteReaction - Delete a reaction by user and type
-   *
-   * @param {string} messageID the id of the message from which te remove the reaction
-   * @param {string} reactionType the type of reaction that should be removed
-   * @param {string} [user_id] the id of the user (used only for server side request) default null
+   * Deletes a reaction by user and type.
    *
-   * @return {Promise<ReactionAPIResponse>} The Server Response
+   * @param request - The delete reaction request payload identifying the target message and reaction type.
+   * @returns The server response.
    */
-  async _deleteReaction(messageID: string, reactionType: string, user_id?: string) {
-    this._checkInitialized();
-    if (!reactionType || !messageID) {
-      throw Error(
-        'Deleting a reaction requires specifying both the message and reaction type',
-      );
-    }
-
-    const url =
-      this.getClient().baseURL +
-      `/messages/${encodeURIComponent(messageID)}/reaction/${encodeURIComponent(
-        reactionType,
-      )}`;
-    //provided when server side request
-    if (user_id) {
-      return await this.getClient().delete<ReactionAPIResponse>(url, { user_id });
-    }
-
-    return await this.getClient().delete<ReactionAPIResponse>(url, {});
+  async _deleteReaction(request: Parameters<ChatApi['deleteReaction']>[0]) {
+    return await this.getClient().deleteReaction(request);
   }
 
   /**
-   * update - Edit the channel's custom properties
+   * Edit the channel using the inherited `update()` from `ChannelApi`. Caches the
+   * server-returned channel onto `this.data`.
    *
-   * @param {ChannelData} channelData The object to update the custom properties of this channel with
-   * @param {Message} [updateMessage] Optional message object for channel members notification
-   * @param {ChannelUpdateOptions} [options] Option object, configuration to control the behavior while updating
-   * @return {Promise<UpdateChannelAPIResponse>} The server response
+   * @param request - Channel update payload, e.g. `{ data: { name: 'foo' }, message }` (optional).
+   * @returns The server response.
    */
-  async update(
-    channelData: Partial<ChannelData & ChannelResponse> = {},
-    updateMessage?: Message,
-    options?: ChannelUpdateOptions,
-  ) {
-    // Strip out reserved names that will result in API errors.
-    // TODO: this needs to be typed better
-    const reserved: Exclude<
-      keyof (ChannelResponse & ChannelData),
-      keyof CustomChannelData
-    >[] = [
-      'config',
-      'cid',
-      'created_by',
-      'id',
-      'member_count',
-      'type',
-      'created_at',
-      'updated_at',
-      'last_message_at',
-      'own_capabilities',
-    ];
-
-    reserved.forEach((key) => {
-      delete channelData[key];
-    });
-
-    return await this._update({
-      message: updateMessage,
-      data: channelData,
-      ...options,
-    });
+  override async update(request?: Gen_UpdateChannelRequest) {
+    const previousData = this.data;
+    const data = await super.update(request);
+    this.data = data.channel;
+    this._syncStateFromChannelData(this.data, previousData);
+    return data;
   }
 
   /**
-   * updatePartial - partial update channel properties
+   * Partial update of channel properties.
    *
-   * @param {PartialUpdateChannel} partial update request
-   *
-   * @return {Promise<PartialUpdateChannelAPIResponse>}
+   * @param update - The partial update request.
+   * @returns The server response.
    */
-  async updatePartial(update: PartialUpdateChannel) {
-    const data = await this.getClient().patch<PartialUpdateChannelAPIResponse>(
-      this._channelURL(),
-      update,
-    );
+  async updatePartial(update: UpdateChannelPartialRequest) {
+    const data = await this.updateChannelPartial(update);
 
-    const areCapabilitiesChanged =
-      [...(data.channel.own_capabilities || [])].sort().join() !==
-      [
-        ...(Array.isArray(this.data?.own_capabilities)
-          ? (this.data?.own_capabilities as string[])
-          : []),
-      ]
-        .sort()
-        .join();
-    this.data = data.channel;
+    if (!this.getClient()._cacheEnabled) return data;
+
+    const channel = data.channel;
+    const currentCapabilities = this.data?.own_capabilities ?? [];
+    const newCapabilities = channel?.own_capabilities;
+
+    const capabilitiesChanged =
+      newCapabilities &&
+      [...currentCapabilities].sort().join() !== [...newCapabilities].sort().join();
+
+    const previousData = this.data;
+    this.data = channel;
+    this._syncStateFromChannelData(this.data, previousData);
     // If the capabiltities are changed, we trigger the `capabilities.changed` event.
-    if (areCapabilitiesChanged) {
+    if (capabilitiesChanged) {
       this.getClient().dispatchEvent({
         type: 'capabilities.changed',
         cid: this.cid,
-        own_capabilities: data.channel.own_capabilities,
+        own_capabilities: newCapabilities,
       });
     }
+
     return data;
   }
 
   /**
-   * enableSlowMode - enable slow mode
+   * Enables slow mode.
    *
-   * @param {number} coolDownInterval the cooldown interval in seconds
-   * @return {Promise<UpdateChannelAPIResponse>} The server response
+   * @param coolDownInterval - The cooldown interval in seconds.
+   * @returns The server response.
    */
   async enableSlowMode(coolDownInterval: number) {
-    const data = await this.getClient().post<UpdateChannelAPIResponse>(
-      this._channelURL(),
-      {
-        cooldown: coolDownInterval,
-      },
-    );
-    this.data = data.channel;
-    return data;
+    return await this.update({ cooldown: coolDownInterval });
   }
 
   /**
-   * disableSlowMode - disable slow mode
+   * Disables slow mode.
    *
-   * @return {Promise<UpdateChannelAPIResponse>} The server response
+   * @returns The server response.
    */
   async disableSlowMode() {
-    const data = await this.getClient().post<UpdateChannelAPIResponse>(
-      this._channelURL(),
-      {
-        cooldown: 0,
-      },
-    );
-    this.data = data.channel;
-    return data;
+    return await this.update({ cooldown: 0 });
   }
 
-  public async sendSharedLocation(
-    location: StaticLocationPayload | LiveLocationPayload,
-    userId?: string,
-  ) {
+  public async sendSharedLocation(location: SharedLocation & { message_id?: string }) {
     const result = await this.sendMessage({
-      id: location.message_id,
-      shared_location: location,
-      user: userId ? { id: userId } : undefined,
+      message: {
+        id: location.message_id,
+        shared_location: location,
+      },
     });
 
-    if ((location as LiveLocationPayload).end_at) {
+    if (location.end_at) {
       this.getClient().dispatchEvent({
         message: result.message,
         type: 'live_location_sharing.started',
@@ -732,10 +773,10 @@ export class Channel {
     return result;
   }
 
-  public async stopLiveLocationSharing(payload: UpdateLocationPayload) {
-    const location = await this.getClient().updateLocation({
+  public async stopLiveLocationSharing(payload: UpdateLiveLocationRequest) {
+    const location = await this.getClient().updateLiveLocation({
       ...payload,
-      end_at: new Date().toISOString(),
+      end_at: new Date(),
     });
     this.getClient().dispatchEvent({
       live_location: location,
@@ -744,359 +785,284 @@ export class Channel {
   }
 
   /**
-   * delete - Delete the channel. Messages are permanently removed.
+   * Accepts an invitation to the channel.
    *
-   * @param {boolean} [options.hard_delete] Defines if the channel is hard deleted or not
-   *
-   * @return {Promise<DeleteChannelAPIResponse>} The server response
+   * @param options - The object to update the custom properties of this channel with (optional, defaults to `{}`).
+   * @returns The server response.
    */
-  async delete(options: { hard_delete?: boolean } = {}) {
-    return await this.getClient().delete<DeleteChannelAPIResponse>(this._channelURL(), {
-      ...options,
-    });
+  async acceptInvite(options: ChannelUpdateOptions = {}) {
+    return await this.update({ accept_invite: true, ...options });
   }
 
   /**
-   * truncate - Removes all messages from the channel
-   * @param {TruncateOptions} [options] Defines truncation options
-   * @return {Promise<TruncateChannelAPIResponse>} The server response
-   */
-  async truncate(options: TruncateOptions = {}) {
-    return await this.getClient().post<TruncateChannelAPIResponse>(
-      this._channelURL() + '/truncate',
-      options,
-    );
-  }
-
-  /**
-   * acceptInvite - accept invitation to the channel
-   *
-   * @param {UpdateChannelOptions} [options] The object to update the custom properties of this channel with
+   * Rejects an invitation to the channel.
    *
-   * @return {Promise<UpdateChannelAPIResponse>} The server response
+   * @param options - The object to update the custom properties of this channel with (optional, defaults to `{}`).
+   * @returns The server response.
    */
-  async acceptInvite(options: UpdateChannelOptions = {}) {
-    return await this._update({ accept_invite: true, ...options });
+  async rejectInvite(options: ChannelUpdateOptions = {}) {
+    return await this.update({ reject_invite: true, ...options });
   }
 
   /**
-   * rejectInvite - reject invitation to the channel
+   * Adds members to the channel.
    *
-   * @param {UpdateChannelOptions} [options] The object to update the custom properties of this channel with
-   *
-   * @return {Promise<UpdateChannelAPIResponse>} The server response
-   */
-  async rejectInvite(options: UpdateChannelOptions = {}) {
-    return await this._update({ reject_invite: true, ...options });
-  }
-
-  /**
-   * addMembers - add members to the channel
-   *
-   * @param {string[] | Array<NewMemberPayload>} members An array of members to add to the channel
-   * @param {Message} [message] Optional message object for channel members notification
-   * @param {ChannelUpdateOptions} [options] Option object, configuration to control the behavior while updating
-   * @return {Promise<UpdateChannelAPIResponse>} The server response
+   * @param members - An array of members to add to the channel.
+   * @param message - Message object for channel members notification (optional).
+   * @param options - Configuration to control the behavior while updating (optional, defaults to `{}`).
+   * @returns The server response.
    */
   async addMembers(
-    members: string[] | Array<NewMemberPayload>,
-    message?: Message,
+    members: string[] | Array<Gen_ChannelMemberRequest>,
+    message?: MessageRequest,
     options: ChannelUpdateOptions = {},
   ) {
-    return await this._update({ add_members: members, message, ...options });
+    return await this.update({
+      add_members: members.map((member) =>
+        typeof member === 'string' ? { user_id: member } : member,
+      ),
+      message,
+      ...options,
+    });
   }
 
   /**
-   * addFilterTags - add filter tags to the channel
+   * Adds filter tags to the channel.
    *
-   * @param {string[]} tags An array of tags to add to the channel
-   * @param {Message} [message] Optional message object for channel members notification
-   * @param {ChannelUpdateOptions} [options] Option object, configuration to control the behavior while updating
-   * @return {Promise<UpdateChannelAPIResponse>} The server response
+   * @param tags - An array of tags to add to the channel.
+   * @param message - Message object for channel members notification (optional).
+   * @param options - Configuration to control the behavior while updating (optional, defaults to `{}`).
+   * @returns The server response.
    */
   async addFilterTags(
     tags: string[],
-    message?: Message,
+    message?: MessageRequest,
     options: ChannelUpdateOptions = {},
   ) {
-    return await this._update({ add_filter_tags: tags, message, ...options });
+    return await this.update({ add_filter_tags: tags, message, ...options });
   }
 
   /**
-   * removeFilterTags - remove filter tags from the channel
+   * Removes filter tags from the channel.
    *
-   * @param {string[]} tags An array of tags to remove from the channel
-   * @param {Message} [message] Optional message object for channel members notification
-   * @param {ChannelUpdateOptions} [options] Option object, configuration to control the behavior while updating
-   * @return {Promise<UpdateChannelAPIResponse>} The server response
+   * @param tags - An array of tags to remove from the channel.
+   * @param message - Message object for channel members notification (optional).
+   * @param options - Configuration to control the behavior while updating (optional, defaults to `{}`).
+   * @returns The server response.
    */
   async removeFilterTags(
     tags: string[],
-    message?: Message,
+    message?: MessageRequest,
     options: ChannelUpdateOptions = {},
   ) {
-    return await this._update({ remove_filter_tags: tags, message, ...options });
+    return await this.update({ remove_filter_tags: tags, message, ...options });
   }
 
   /**
-   * addModerators - add moderators to the channel
+   * Adds moderators to the channel.
    *
-   * @param {string[]} members An array of member identifiers
-   * @param {Message} [message] Optional message object for channel members notification
-   * @param {ChannelUpdateOptions} [options] Option object, configuration to control the behavior while updating
-   * @return {Promise<UpdateChannelAPIResponse>} The server response
+   * @param members - An array of member identifiers.
+   * @param message - Message object for channel members notification (optional).
+   * @param options - Configuration to control the behavior while updating (optional, defaults to `{}`).
+   * @returns The server response.
    */
   async addModerators(
     members: string[],
-    message?: Message,
+    message?: MessageRequest,
     options: ChannelUpdateOptions = {},
   ) {
-    return await this._update({ add_moderators: members, message, ...options });
+    return await this.update({ add_moderators: members, message, ...options });
   }
 
   /**
-   * assignRoles - sets member roles in a channel
+   * Sets member roles in a channel.
    *
-   * @param {{channel_role: Role, user_id: string}[]} roles List of role assignments
-   * @param {Message} [message] Optional message object for channel members notification
-   * @param {ChannelUpdateOptions} [options] Option object, configuration to control the behavior while updating
-   * @return {Promise<UpdateChannelAPIResponse>} The server response
+   * @param roles - List of role assignments.
+   * @param message - Message object for channel members notification (optional).
+   * @param options - Configuration to control the behavior while updating (optional, defaults to `{}`).
+   * @returns The server response.
    */
   async assignRoles(
-    roles: { channel_role: Role; user_id: string }[],
-    message?: Message,
+    roles: { channel_role: RoleName; user_id: string }[],
+    message?: MessageRequest,
     options: ChannelUpdateOptions = {},
   ) {
-    return await this._update({ assign_roles: roles, message, ...options });
+    return await this.update({ assign_roles: roles, message, ...options });
   }
 
   /**
-   * inviteMembers - invite members to the channel
+   * Invite members to the channel.
    *
-   * @param {string[] | Array<NewMemberPayload>} members An array of members to invite to the channel
-   * @param {Message} [message] Optional message object for channel members notification
-   * @param {ChannelUpdateOptions} [options] Option object, configuration to control the behavior while updating
-   * @return {Promise<UpdateChannelAPIResponse>} The server response
+   * @param members - An array of members to invite to the channel.
+   * @param message - Message object for channel members notification (optional).
+   * @param options - Configuration to control the behavior while updating (optional, defaults to `{}`).
+   * @returns The server response.
    */
   async inviteMembers(
-    members: string[] | Required<Omit<NewMemberPayload, 'channel_role'>>[],
-    message?: Message,
+    members: string[] | Required<Omit<Gen_ChannelMemberRequest, 'channel_role'>>[],
+    message?: MessageRequest,
     options: ChannelUpdateOptions = {},
   ) {
-    return await this._update({ invites: members, message, ...options });
+    return await this.update({
+      invites: members.map((member) =>
+        typeof member === 'string' ? { user_id: member } : member,
+      ),
+      message,
+      ...options,
+    });
   }
 
   /**
-   * removeMembers - remove members from channel
+   * Removes members from the channel.
    *
-   * @param {string[]} members An array of member identifiers
-   * @param {Message} [message] Optional message object for channel members notification
-   * @param {ChannelUpdateOptions} [options] Option object, configuration to control the behavior while updating
-   * @return {Promise<UpdateChannelAPIResponse>} The server response
+   * @param members - An array of member identifiers.
+   * @param message - Message object for channel members notification (optional).
+   * @param options - Configuration to control the behavior while updating (optional, defaults to `{}`).
+   * @returns The server response.
    */
   async removeMembers(
     members: string[],
-    message?: Message,
+    message?: MessageRequest,
     options: ChannelUpdateOptions = {},
   ) {
-    return await this._update({ remove_members: members, message, ...options });
+    return await this.update({ remove_members: members, message, ...options });
   }
 
   /**
-   * demoteModerators - remove moderator role from channel members
+   * Removes the moderator role from channel members.
    *
-   * @param {string[]} members An array of member identifiers
-   * @param {Message} [message] Optional message object for channel members notification
-   * @param {ChannelUpdateOptions} [options] Option object, configuration to control the behavior while updating
-   * @return {Promise<UpdateChannelAPIResponse>} The server response
+   * @param members - An array of member identifiers.
+   * @param message - Message object for channel members notification (optional).
+   * @param options - Configuration to control the behavior while updating (optional, defaults to `{}`).
+   * @returns The server response.
    */
   async demoteModerators(
     members: string[],
-    message?: Message,
+    message?: MessageRequest,
     options: ChannelUpdateOptions = {},
   ) {
-    return await this._update({ demote_moderators: members, message, ...options });
+    return await this.update({ demote_moderators: members, message, ...options });
   }
 
   /**
-   * _update - executes channel update request
-   * @param payload Object Update Channel payload
-   * @return {Promise<UpdateChannelAPIResponse>} The server response
-   * TODO: introduce new type instead of Object in the next major update
-   */
-  async _update(payload: object) {
-    const data = await this.getClient().post<UpdateChannelAPIResponse>(
-      this._channelURL(),
-      payload,
-    );
-    this.data = data.channel;
-    return data;
-  }
-
-  /**
-   * mute - mutes the current channel
-   * @param {{ user_id?: string, expiration?: string }} opts expiration in minutes or user_id
-   * @return {Promise<MuteChannelAPIResponse>} The server response
+   * Mutes the current channel.
    *
-   * example with expiration:
-   * await channel.mute({expiration: moment.duration(2, 'weeks')});
+   * @example
+   * // with expiration
+   * await channel.mute({ expiration: moment.duration(2, 'weeks') });
    *
-   * example server side:
-   * await channel.mute({user_id: userId});
+   * @example
+   * // server side
+   * await channel.mute({ user_id: userId });
    *
+   * @param options - Mute options (optional, defaults to `{}`).
+   * @param options.expiration - Expiration in minutes (optional).
+   * @returns The server response.
    */
-  async mute(opts: { expiration?: number; user_id?: string } = {}) {
-    return await this.getClient().post<MuteChannelAPIResponse>(
-      this.getClient().baseURL + '/moderation/mute/channel',
-      {
-        channel_cid: this.cid,
-        ...opts,
-      },
-    );
+  async mute(options?: Gen_MuteChannelRequest) {
+    return await this.getClient().muteChannel({
+      channel_cids: [this.cid],
+      ...options,
+    });
   }
 
   /**
-   * unmute - mutes the current channel
-   * @param {{ user_id?: string}} opts user_id
-   * @return {Promise<APIResponse>} The server response
+   * Unmutes the current channel.
    *
-   * example server side:
-   * await channel.unmute({user_id: userId});
+   * @example
+   * // server side
+   * await channel.unmute({ user_id: userId });
+   *
+   * @param options - Unmute options (optional, defaults to `{}`).
+   * @param options.user_id - User ID (optional).
+   * @returns The server response.
    */
-  async unmute(opts: { user_id?: string } = {}) {
-    return await this.getClient().post<APIResponse>(
-      this.getClient().baseURL + '/moderation/unmute/channel',
-      {
-        channel_cid: this.cid,
-        ...opts,
-      },
-    );
+  async unmute(options?: Gen_UnmuteChannelRequest) {
+    return await this.getClient().unmuteChannel({
+      channel_cids: [this.cid],
+      ...options,
+    });
   }
 
   /**
-   * archive - archives the current channel
-   * @param {{ user_id?: string }} opts user_id if called server side
-   * @return {Promise<ChannelMemberResponse>} The server response
-   *
-   * example:
-   * await channel.archives();
+   * Archives the current channel.
    *
-   * example server side:
-   * await channel.archive({user_id: userId});
+   * @example
+   * await channel.archive();
    *
+   * @returns The server response.
    */
-  async archive(opts: { user_id?: string } = {}) {
-    const cli = this.getClient();
-    const uid = opts.user_id || cli.userID;
-    if (!uid) {
-      throw Error('A user_id is required for archiving a channel');
-    }
-    const resp = await this.partialUpdateMember(uid, { set: { archived: true } });
-    return resp.channel_member;
+  async archive() {
+    return await this.updateMemberPartial({ set: { archived: true } });
   }
 
   /**
-   * unarchive - unarchives the current channel
-   * @param {{ user_id?: string }} opts user_id if called server side
-   * @return {Promise<ChannelMemberResponse>} The server response
+   * Unarchives the current channel.
    *
-   * example:
+   * @example
    * await channel.unarchive();
    *
-   * example server side:
-   * await channel.unarchive({user_id: userId});
-   *
+   * @returns The server response.
    */
-  async unarchive(opts: { user_id?: string } = {}) {
-    const cli = this.getClient();
-    const uid = opts.user_id || cli.userID;
-    if (!uid) {
-      throw Error('A user_id is required for unarchiving a channel');
-    }
-    const resp = await this.partialUpdateMember(uid, { set: { archived: false } });
-    return resp.channel_member;
+  async unarchive() {
+    return await this.updateMemberPartial({ set: { archived: false } });
   }
 
   /**
-   * pin - pins the current channel
-   * @param {{ user_id?: string }} opts user_id if called server side
-   * @return {Promise<ChannelMemberResponse>} The server response
+   * Pins the current channel.
    *
-   * example:
+   * @example
    * await channel.pin();
    *
-   * example server side:
-   * await channel.pin({user_id: userId});
-   *
+   * @returns The server response.
    */
-  async pin(opts: { user_id?: string } = {}) {
-    const cli = this.getClient();
-    const uid = opts.user_id || cli.userID;
-    if (!uid) {
-      throw new Error('A user_id is required for pinning a channel');
-    }
-    const resp = await this.partialUpdateMember(uid, { set: { pinned: true } });
-    return resp.channel_member;
+  async pin() {
+    return await this.updateMemberPartial({ set: { pinned: true } });
   }
 
   /**
-   * unpin - unpins the current channel
-   * @param {{ user_id?: string }} opts user_id if called server side
-   * @return {Promise<ChannelMemberResponse>} The server response
+   * Unpins the current channel.
    *
-   * example:
+   * @example
    * await channel.unpin();
    *
-   * example server side:
-   * await channel.unpin({user_id: userId});
-   *
+   * @returns The server response.
    */
-  async unpin(opts: { user_id?: string } = {}) {
-    const cli = this.getClient();
-    const uid = opts.user_id || cli.userID;
-    if (!uid) {
-      throw new Error('A user_id is required for unpinning a channel');
-    }
-    const resp = await this.partialUpdateMember(uid, { set: { pinned: false } });
-    return resp.channel_member;
+  async unpin() {
+    return await this.updateMemberPartial({ set: { pinned: false } });
   }
 
   /**
-   * muteStatus - returns the mute status for the current channel
-   * @return {{ muted: boolean; createdAt: Date | null; expiresAt: Date | null }} { muted: true | false, createdAt: Date | null, expiresAt: Date | null}
+   * Returns the mute status for the current channel.
+   *
+   * @returns An object of the form `{ muted: true | false, createdAt: Date | null, expiresAt: Date | null }`.
    */
-  muteStatus(): {
-    createdAt: Date | null;
-    expiresAt: Date | null;
-    muted: boolean;
-  } {
+  muteStatus() {
     this._checkInitialized();
     return this.getClient()._muteStatus(this.cid);
   }
 
-  sendAction(messageID: string, formData: Record<string, string>) {
+  sendAction(messageId: string, formData: Record<string, string>) {
     this._checkInitialized();
-    if (!messageID) {
-      throw Error(`Message id is missing`);
+    if (!messageId) {
+      throw Error(`Message ID is missing`);
     }
-    return this.getClient().post<SendMessageAPIResponse>(
-      this.getClient().baseURL + `/messages/${encodeURIComponent(messageID)}/action`,
-      {
-        message_id: messageID,
-        form_data: formData,
-        id: this.id,
-        type: this.type,
-      },
-    );
+    return this.getClient().runMessageAction({
+      id: messageId,
+      form_data: formData,
+    });
   }
 
   /**
-   * keystroke - First of the typing.start and typing.stop events based on the users keystrokes.
-   * Call this on every keystroke
+   * First of the `typing.start` and `typing.stop` events based on the user's keystrokes.
+   * Call this on every keystroke.
+   *
    * @see {@link https://getstream.io/chat/docs/typing_indicators/?language=js|Docs}
-   * @param {string} [parent_id] set this field to `message.id` to indicate that typing event is happening in a thread
+   *
+   * @param parentId - Set this field to `message.id` to indicate that the typing event is happening in a thread (optional).
+   * @param options - Optional override carrying a `user_id` (optional).
    */
-  async keystroke(parent_id?: string, options?: { user_id: string }) {
+  async keystroke(parentId?: string, options?: { user_id: string }) {
     if (!this._isTypingIndicatorsEnabled()) {
       return;
     }
@@ -1108,10 +1074,14 @@ export class Channel {
     if (diff === null || diff > 2000) {
       this.lastTypingEvent = new Date();
       await this.sendEvent({
-        type: 'typing.start',
-        parent_id,
-        ...(options || {}),
-      } as Event);
+        event: {
+          type: 'typing.start',
+          parent_id: parentId,
+          ...(options || {}),
+          created_at: new Date(),
+          custom: {},
+        },
+      });
     }
   }
 
@@ -1120,8 +1090,9 @@ export class Channel {
    * Typically used by the server connected to the AI service to notify clients of state changes.
    *
    * @param messageId - The ID of the message associated with the AI state.
-   * @param state - The new state of the AI process (e.g., thinking, generating).
-   * @param options - Optional parameters, such as `ai_message`, to include additional details in the event.
+   * @param state - The new state of the AI process, e.g. thinking, generating.
+   * @param options - Parameters such as `ai_message` to include additional details in the event (optional, defaults to `{}`).
+   * @param options.ai_message - Additional message detail to include in the event (optional).
    */
   async updateAIState(
     messageId: string,
@@ -1129,11 +1100,15 @@ export class Channel {
     options: { ai_message?: string } = {},
   ) {
     await this.sendEvent({
-      ...options,
-      type: 'ai_indicator.update',
-      message_id: messageId,
-      ai_state: state,
-    } as Event);
+      event: {
+        ...options,
+        type: 'ai_indicator.update',
+        message_id: messageId,
+        ai_state: state,
+        created_at: new Date(),
+        custom: {},
+      },
+    });
   }
 
   /**
@@ -1142,8 +1117,12 @@ export class Channel {
    */
   async clearAIIndicator() {
     await this.sendEvent({
-      type: 'ai_indicator.clear',
-    } as Event);
+      event: {
+        type: 'ai_indicator.clear',
+        created_at: new Date(),
+        custom: {},
+      },
+    });
   }
 
   /**
@@ -1152,26 +1131,37 @@ export class Channel {
    */
   async stopAIResponse() {
     await this.sendEvent({
-      type: 'ai_indicator.stop',
-    } as Event);
+      event: {
+        type: 'ai_indicator.stop',
+        created_at: new Date(),
+        custom: {},
+      },
+    });
   }
 
   /**
-   * stopTyping - Sets last typing to null and sends the typing.stop event
+   * Sets last typing to null and sends the `typing.stop` event.
+   *
    * @see {@link https://getstream.io/chat/docs/typing_indicators/?language=js|Docs}
-   * @param {string} [parent_id] set this field to `message.id` to indicate that typing event is happening in a thread
+   *
+   * @param parentId - Set this field to `message.id` to indicate that the typing event is happening in a thread (optional).
+   * @param options - Optional override carrying a `user_id` (optional).
    */
-  async stopTyping(parent_id?: string, options?: { user_id: string }) {
+  async stopTyping(parentId?: string, options?: { user_id: string }) {
     if (!this._isTypingIndicatorsEnabled()) {
       return;
     }
     this.lastTypingEvent = null;
     this.isTyping = false;
     await this.sendEvent({
-      type: 'typing.stop',
-      parent_id,
-      ...(options || {}),
-    } as Event);
+      event: {
+        type: 'typing.stop',
+        parent_id: parentId,
+        ...(options || {}),
+        created_at: new Date(),
+        custom: {},
+      },
+    });
   }
 
   _isTypingIndicatorsEnabled(): boolean {
@@ -1182,74 +1172,53 @@ export class Channel {
   }
 
   /**
-   * lastMessage - return the last message, takes into account that last few messages might not be perfectly sorted
+   * Run this user's mark-read reporter for this channel. Delegates to
+   * `MessageDeliveryReporter`, which batches the underlying `markRead` request
+   * with the user's read receipts state.
    *
-   * @return {ReturnType<ChannelState['formatMessage']> | undefined} Description
-   */
-  lastMessage(): LocalMessage | undefined {
-    // get last 5 messages, sort, return the latest
-    // get a slice of the last 5
-    let min = this.state.latestMessages.length - 5;
-    if (min < 0) {
-      min = 0;
-    }
-    const max = this.state.latestMessages.length + 1;
-    const messageSlice = this.state.latestMessages.slice(min, max);
-
-    // sort by pk desc
-    messageSlice.sort((a, b) => b.created_at.getTime() - a.created_at.getTime());
-
-    return messageSlice[0];
-  }
-
-  /**
-   * 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.
+   * Use the inherited `markRead()` from `ChannelApi` for a direct, unbatched call.
    *
-   * @param {MarkReadOptions} data
-   * @return {Promise<EventAPIResponse | null>} Description
+   * @param data - Mark read options (optional, defaults to `{}`).
    */
-  async markRead(data: MarkReadOptions = {}) {
+  async markReadViaReporter(data: MarkReadRequest = {}) {
     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
+   * Override of the inherited `markRead()` from `ChannelApi` that requires the
+   * channel to be initialized and respects the `read_events` channel config.
    *
-   * @param {MarkReadOptions} data
-   * @return {Promise<EventAPIResponse | null>} Description
+   * @param data - Mark read options (optional, defaults to `{}`).
+   * @returns The server response, or `null` if the request was skipped.
    */
-  async markAsReadRequest(data: MarkReadOptions = {}) {
+  override async markRead(data?: MarkReadRequest) {
     this._checkInitialized();
 
-    if (!this.getConfig()?.read_events && !this.getClient()._isUsingServerAuth()) {
-      return null;
+    if (!this.getConfig()?.read_events) {
+      throw new Error('Read events are disabled for this application');
     }
 
-    return await this.getClient().post<EventAPIResponse>(this._channelURL() + '/read', {
-      ...data,
-    });
+    return await super.markRead(data);
   }
 
   /**
-   * markUnread - Mark the channel as unread from messageID, only works if the `read_events` setting is enabled
+   * Marks the channel as unread from `messageId`. Only works when the `read_events` setting is enabled.
    *
-   * @param {MarkUnreadOptions} data
-   * @return {APIResponse} An API response
+   * @param data - Mark unread options.
+   * @returns An API response, or `null` if the request was skipped.
    */
-  async markUnread(data: MarkUnreadOptions) {
+  override async markUnread(data?: MarkUnreadRequest) {
     this._checkInitialized();
 
-    if (!this.getConfig()?.read_events && !this.getClient()._isUsingServerAuth()) {
-      return Promise.resolve(null);
+    if (!this.getConfig()?.read_events) {
+      throw new Error('Read events are disabled for this application');
     }
 
-    return await this.getClient().post<APIResponse>(this._channelURL() + '/unread', {
-      ...data,
-    });
+    return await super.markUnread(data);
   }
 
   /**
-   * markReadLocally - Resets this user's unread count locally, without any backend call. Intended for
+   * Resets this user's unread count locally, without any backend call. Intended for
    * channels that have read events disabled (e.g. livestreams) when the client is created with the
    * `isLocalUnreadCountEnabled` option. Dispatches a dedicated, client-only `message.read_locally` event
    * that runs through the same `_handleChannelEvent` read logic as a real `message.read` (minus the
@@ -1257,21 +1226,21 @@ export class Channel {
    * is enabled, the offline DB persists the reset for read-events-disabled channels, so the local
    * count stays consistent across app restarts.
    *
-   * @return {Event | undefined} The dispatched `message.read_locally` event, or `undefined` if there is no connected user.
+   * @returns The dispatched `message.read_locally` event, or `undefined` if there is no connected user.
    */
   markReadLocally() {
     const client = this.getClient();
-    if (!client.userID) return;
+    if (!client.userId) return;
 
-    const event: Event = {
+    const event: EventPayload<'message.read_locally'> = {
       channel_id: this.id,
       channel_type: this.type,
       cid: this.cid,
-      created_at: new Date().toISOString(),
-      last_read_message_id: this.lastMessage()?.id,
+      created_at: new Date(),
+      last_read_message_id: this.messagePaginator.headmostItem?.id,
       team: this.data?.team,
       type: 'message.read_locally',
-      user: client.user,
+      user: client.user as UserResponse,
     };
     client.dispatchEvent(event);
 
@@ -1279,7 +1248,7 @@ export class Channel {
   }
 
   /**
-   * clean - Cleans the channel state and fires stop typing if needed
+   * Cleans the channel state and fires stop typing if needed.
    */
   clean() {
     if (this.lastKeyStroke) {
@@ -1294,13 +1263,12 @@ export class Channel {
   }
 
   /**
-   * watch - Loads the initial channel state and watches for changes
-   *
-   * @param {ChannelQueryOptions} options additional options for the query endpoint
+   * Loads the initial channel state and watches for changes.
    *
-   * @return {Promise<QueryChannelAPIResponse>} The server response
+   * @param options - Additional options for the query endpoint (optional).
+   * @returns The server response.
    */
-  async watch(options?: ChannelQueryOptions) {
+  async watch(options?: ChannelGetOrCreateRequest) {
     const defaultOptions = {
       state: true,
       watch: true,
@@ -1317,138 +1285,102 @@ export class Channel {
     const combined = { ...defaultOptions, ...options };
     const state = await this.query(combined, 'latest');
     this.initialized = true;
+    const previousData = this.data;
     this.data = state.channel;
+    this._syncStateFromChannelData(this.data, previousData);
 
-    this._client.logger(
-      'info',
-      `channel:watch() - started watching channel ${this.cid}`,
-      {
-        tags: ['channel'],
-        channel: this,
-      },
-    );
+    // The message paginator is seeded synchronously inside query() (before read-state hydration),
+    // so a channel opened via watch() alone — a deep-link restore, a search result, a freshly
+    // created DM — already has its latest page loaded here.
+
+    logger.withExtraTags('watch', this.cid).info('Started watching the channel.');
     return state;
   }
 
   /**
-   * stopWatching - Stops watching the channel
+   * Stops watching the channel.
    *
-   * @return {Promise<APIResponse>} The server response
+   * @param request - The stop-watching request payload (optional).
+   * @returns The server response.
    */
-  async stopWatching() {
-    const response = await this.getClient().post<APIResponse>(
-      this._channelURL() + '/stop-watching',
-      {},
-    );
+  override async stopWatching(request?: Gen_ChannelStopWatchingRequest) {
+    const response = await super.stopWatching(request);
 
-    this._client.logger(
-      'info',
-      `channel:watch() - stopped watching channel ${this.cid}`,
-      {
-        tags: ['channel'],
-        channel: this,
-      },
-    );
+    logger.withExtraTags('stopWatching', this.cid).info('Stopped watching the channel.');
 
     return response;
   }
 
   /**
-   * getReplies - List the message replies for a parent message.
+   * List the message replies for a parent message.
    *
-   * The recommended way of working with threads is to use the Thread class.
+   * The recommended way of working with threads is to use the `Thread` class.
    *
-   * @param {string} parent_id The message parent id, ie the top of the thread
-   * @param {MessagePaginationOptions & { user?: UserResponse; user_id?: string }} options Pagination params, ie {limit:10, id_lte: 10}
-   *
-   * @return {Promise<GetRepliesAPIResponse>} A response with a list of messages
+   * @param request - The get-replies request payload, including the parent message ID, pagination
+   *   params, and optional sort directions for `created_at`.
+   * @returns A response with a list of messages.
    */
-  async getReplies(
-    parent_id: string,
-    options: MessagePaginationOptions & { user?: UserResponse; user_id?: string },
-    sort?: { created_at: AscDesc }[],
-  ) {
-    const normalizedSort = sort ? normalizeQuerySort(sort) : undefined;
-    const data = await this.getClient().get<GetRepliesAPIResponse>(
-      this.getClient().baseURL + `/messages/${encodeURIComponent(parent_id)}/replies`,
-      {
-        sort: normalizedSort,
-        ...options,
-      },
-    );
-
-    // add any messages to our thread state
-    if (data.messages) {
-      this.state.addMessagesSorted(data.messages);
-    }
+  async getReplies(request: GetRepliesRequest) {
+    const data = await this.getClient().getReplies(request);
 
+    // Thread reply state is owned by the Thread object (Thread.messagePaginator); the returned
+    // replies are consumed there. The channel message list is owned by channel.messagePaginator.
     return data;
   }
 
+  // TODO: find out v2 equivalent
   /**
-   * getPinnedMessages - List list pinned messages of the channel
-   *
-   * @param {PinnedMessagePaginationOptions & { user?: UserResponse; user_id?: string }} options Pagination params, ie {limit:10, id_lte: 10}
-   * @param {PinnedMessagesSort} sort defines sorting direction of pinned messages
+   * List pinned messages of the channel.
    *
-   * @return {Promise<GetRepliesAPIResponse>} A response with a list of messages
+   * @param options - Pagination params, e.g. `{ limit: 10, id_lte: 10 }`.
+   * @param sort - Defines sorting direction of pinned messages (optional, defaults to `[]`).
+   * @returns A response with a list of messages.
    */
   async getPinnedMessages(
-    options: PinnedMessagePaginationOptions & { user?: UserResponse; user_id?: string },
+    options: PinnedMessagePaginationOptions,
     sort: PinnedMessagesSort = [],
   ) {
-    return await this.getClient().get<GetRepliesAPIResponse>(
+    return await this.getClient().api.get<GetRepliesAPIResponse>(
       this._channelURL() + '/pinned_messages',
       {
         payload: {
           ...options,
-          sort: normalizeQuerySort(sort),
+          sort,
         },
       },
     );
   }
 
   /**
-   * getReactions - List the reactions, supports pagination
-   *
-   * @param {string} message_id The message id
-   * @param {{ limit?: number; offset?: number }} options The pagination options
+   * List the reactions; supports pagination.
    *
-   * @return {Promise<GetReactionsAPIResponse>} Server response
+   * @param request - The request payload, including the target message ID and
+   *   pagination options (`limit`, `offset`).
+   * @returns The server response.
    */
-  getReactions(message_id: string, options: { limit?: number; offset?: number }) {
-    return this.getClient().get<GetReactionsAPIResponse>(
-      this.getClient().baseURL + `/messages/${encodeURIComponent(message_id)}/reactions`,
-      {
-        ...options,
-      },
-    );
+  getReactions(request: Parameters<ChatApi['getReactions']>[0]) {
+    return this.getClient().getReactions(request);
   }
 
   /**
-   * getMessagesById - Retrieves a list of messages by ID
+   * Retrieves a list of messages by ID.
    *
-   * @param {string[]} messageIds The ids of the messages to retrieve from this channel
-   *
-   * @return {Promise<GetMultipleMessagesAPIResponse>} Server response
+   * @param messageIds - The IDs of the messages to retrieve from this channel.
+   * @returns Server response.
    */
   getMessagesById(messageIds: string[]) {
-    return this.getClient().get<GetMultipleMessagesAPIResponse>(
-      this._channelURL() + '/messages',
-      {
-        ids: messageIds.join(','),
-      },
-    );
+    return this.getManyMessages({ ids: messageIds });
   }
 
   /**
-   * lastRead - returns the last time the user marked the channel as read if the user never marked the channel as read, this will return null
-   * @return {Date | null | undefined}
+   * Returns the last time the user marked the channel as read. If the user never marked the channel as read, this will return `null`.
+   *
+   * @returns The last-read `Date`, `null` if never read, or `undefined` if the user is unset.
    */
   lastRead() {
-    const { userID } = this.getClient();
-    if (userID) {
-      return this.state.read[userID] ? this.state.read[userID].last_read : null;
+    const { userId } = this.getClient();
+    if (userId) {
+      return this.state.read[userId] ? this.state.read[userId].last_read : null;
     }
   }
 
@@ -1456,7 +1388,7 @@ export class Channel {
     if (message.shadowed) return false;
     if (message.silent) return false;
     if (message.parent_id && !message.show_in_channel) return false;
-    if (message.user?.id === this.getClient().userID) return false;
+    if (message.user?.id === this.getClient().userId) return false;
     if (message.user?.id && this.getClient().userMuteStatus(message.user.id))
       return false;
 
@@ -1478,18 +1410,17 @@ export class Channel {
   }
 
   /**
-   * countUnread - Count of unread messages
-   *
-   * @param {Date | null} [lastRead] lastRead the time that the user read a message, defaults to current user's read state
+   * Count of unread messages.
    *
-   * @return {number} Unread count
+   * @param lastRead - The time that the user read a message (optional, defaults to the current user's read state).
+   * @returns Unread count.
    */
   countUnread(lastRead?: Date | null) {
     if (!lastRead) return this.state.unreadCount;
-    // todo: prevent finding the latest message set on each iteration
     let count = 0;
-    for (let i = 0; i < this.state.latestMessages.length; i += 1) {
-      const message = this.state.latestMessages[i];
+    const latestMessages = this.messagePaginator.headItems;
+    for (let i = 0; i < latestMessages.length; i += 1) {
+      const message = latestMessages[i];
       if (message.created_at > lastRead && this._countMessageAsUnread(message)) {
         count++;
       }
@@ -1498,21 +1429,22 @@ export class Channel {
   }
 
   /**
-   * countUnreadMentions - Count the number of unread messages mentioning the current user
+   * Count the number of unread messages mentioning the current user.
    *
-   * @return {number} Unread mentions count
+   * @returns Unread mentions count.
    */
   countUnreadMentions() {
     const lastRead = this.lastRead();
-    const userID = this.getClient().userID;
+    const userId = this.getClient().userId;
 
     let count = 0;
-    for (let i = 0; i < this.state.latestMessages.length; i += 1) {
-      const message = this.state.latestMessages[i];
+    const latestMessages = this.messagePaginator.headItems;
+    for (let i = 0; i < latestMessages.length; i += 1) {
+      const message = latestMessages[i];
       if (
         this._countMessageAsUnread(message) &&
         (!lastRead || message.created_at > lastRead) &&
-        message.mentioned_users?.some((user) => user.id === userID)
+        message.mentioned_users?.some((user) => user.id === userId)
       ) {
         count++;
       }
@@ -1521,12 +1453,12 @@ export class Channel {
   }
 
   /**
-   * create - Creates a new channel
-   *
-   * @return {Promise<QueryChannelAPIResponse>} The Server Response
+   * Creates a new channel.
    *
+   * @param options - Channel query options (optional).
+   * @returns The server response.
    */
-  create = async (options?: ChannelQueryOptions) => {
+  create = async (options?: ChannelGetOrCreateRequest) => {
     const defaultOptions = {
       ...options,
       watch: false,
@@ -1537,53 +1469,42 @@ export class Channel {
   };
 
   /**
-   * query - Query the API, get messages, members or other channel fields
-   *
-   * @param {ChannelQueryOptions} options The query options
-   * @param {MessageSetType} messageSetToAddToIfDoesNotExist It's possible to load disjunct sets of a channel's messages into state, use `current` to load the initial channel state or if you want to extend the currently displayed messages, use `latest` if you want to load/extend the latest messages, `new` is used for loading a specific message and it's surroundings
+   * Queries the API to load messages, members, or other channel fields.
    *
-   * @return {Promise<QueryChannelAPIResponse>} Returns a query response
+   * @param options - The query options (optional, defaults to `{}`).
+   * @param messageSetToAddToIfDoesNotExist - It's possible to load disjunct sets of a channel's
+   *   messages into state. Use `current` to load the initial channel state or to extend the
+   *   currently displayed messages; use `latest` to load/extend the latest messages; `new` is
+   *   used for loading a specific message and its surroundings (optional, defaults to `'current'`).
+   * @returns A query response.
    */
   async query(
-    options: ChannelQueryOptions = {},
+    options: ChannelGetOrCreateRequest = {},
     messageSetToAddToIfDoesNotExist: MessageSetType = 'current',
   ) {
     // Make sure we wait for the connect promise if there is a pending one
     await this.getClient().wsPromise;
 
-    const createdById =
-      options.created_by?.id ??
-      options.created_by_id ??
-      this._data?.created_by?.id ??
-      this._data?.created_by_id;
-
-    if (this.getClient()._isUsingServerAuth() && typeof createdById !== 'string') {
-      this.getClient().logger(
-        'warn',
-        'Either `created_by` (with `id` property) or `created_by_id` are missing from both `Channel._data` and `options` parameter',
-      );
-    }
+    const queryPayload: ChannelGetOrCreateRequest = {
+      data: this._data,
+      state: true,
+      ...options,
+    };
 
-    let queryURL = `${this.getClient().baseURL}/channels/${encodeURIComponent(
-      this.type,
-    )}`;
-    if (this.id) {
-      queryURL += `/${encodeURIComponent(this.id)}`;
-    }
+    const state = this.id
+      ? await this.getOrCreate(queryPayload)
+      : await this.getClient().getOrCreateDistinctChannel({
+          type: this.type,
+          ...queryPayload,
+        });
 
-    const state = await this.getClient().post<QueryChannelAPIResponse>(
-      queryURL + '/query',
-      {
-        data: this._data,
-        state: true,
-        ...options,
-      },
-    );
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    const channel = state.channel!;
 
     // update the channel id if it was missing
     if (!this.id) {
-      this.id = state.channel.id;
-      this.cid = state.channel.cid;
+      this.id = channel.id;
+      this.cid = channel.cid;
       // set the channel as active...
 
       const tempChannelCid = generateChannelTempCid(
@@ -1605,34 +1526,41 @@ export class Channel {
       }
     }
 
-    this.getClient()._addChannelConfig(state.channel);
+    this.getClient()._addChannelConfig(channel);
 
     // the only config param that is necessary to be updated based on server config soon as the config is delivered
-    if (typeof state.channel.config?.shared_locations !== 'undefined') {
+    if (typeof channel.config?.shared_locations !== 'undefined') {
       this.messageComposer.updateConfig({
-        location: { enabled: state.channel.config.shared_locations },
+        location: { enabled: channel.config.shared_locations },
       });
     }
 
-    // add any messages to our channel state
-    const { messageSet, filteredMessageIds } = this._initializeState(
-      state,
-      messageSetToAddToIfDoesNotExist,
-    );
-    messageSet.pagination = {
-      ...messageSet.pagination,
-      ...messageSetPagination({
-        parentSet: messageSet,
-        messagePaginationOptions: options?.messages,
-        requestedPageSize:
-          options?.messages?.limit ?? DEFAULT_QUERY_CHANNEL_MESSAGE_LIST_PAGE_SIZE,
-        returnedPage: state.messages,
-        filteredReturnedPage: state.messages.filter(
-          (m) => !filteredMessageIds.includes(m.id),
-        ),
-        logger: this.getClient().logger,
-      }),
-    };
+    // Seed the message paginator with the first (latest) page BEFORE _initializeState, which
+    // hydrates the read state and (via MessageReceiptsTracker) resolves read/delivered cursors
+    // against this paginator. Seeding first guarantees the tracker sees a populated timeline; a
+    // later async seed would run after the reconcile and mislabel delivery status. Only the
+    // latest-page open paths (watch/create) pass 'latest' — the paginator's own pagination queries
+    // use 'current' and must not be reseeded as a first page here.
+    if (messageSetToAddToIfDoesNotExist === 'latest' && Array.isArray(state.messages)) {
+      const requestedPageSize =
+        options?.messages?.limit ?? DEFAULT_QUERY_CHANNEL_MESSAGE_LIST_PAGE_SIZE;
+      // Pass the query's message pagination options through: a channel can be opened AROUND a
+      // message (id_around / created_at_around), in which case the fetched page is a jump window,
+      // not the latest page — the paginator must reconcile it with jump semantics.
+      this.messagePaginator.seedFirstPageSync(
+        state.messages.map(formatMessage),
+        requestedPageSize,
+        options?.messages,
+      );
+    }
+
+    // Seed read/members/pinned/thread-cleanup state; the message list is in the paginator.
+    this._initializeState(state);
+    // The queried page is the latest set unless this was a jump/around query.
+    const isLatestMessageSet =
+      messageSetToAddToIfDoesNotExist === 'latest' &&
+      !options?.messages?.id_around &&
+      !(options?.messages as MessagePaginationOptions | undefined)?.created_at_around;
 
     this.getClient().polls.hydratePollCache(state.messages, true);
     this.getClient().reminders.hydrateState(state.messages);
@@ -1640,7 +1568,7 @@ export class Channel {
     this.messageComposer.initStateFromChannelResponse(state);
 
     const areCapabilitiesChanged =
-      [...(state.channel.own_capabilities || [])].sort().join() !==
+      [...(channel.own_capabilities || [])].sort().join() !==
       [
         ...(this.data && Array.isArray(this.data?.own_capabilities)
           ? this.data.own_capabilities
@@ -1648,7 +1576,9 @@ export class Channel {
       ]
         .sort()
         .join();
-    this.data = state.channel;
+    const previousData = this.data;
+    this.data = channel;
+    this._syncStateFromChannelData(this.data, previousData);
     this.offlineMode = false;
     this.cooldownTimer.refresh();
 
@@ -1656,7 +1586,7 @@ export class Channel {
       this.getClient().dispatchEvent({
         type: 'capabilities.changed',
         cid: this.cid,
-        own_capabilities: state.channel.own_capabilities,
+        own_capabilities: channel.own_capabilities ?? [],
       });
     }
 
@@ -1664,14 +1594,14 @@ export class Channel {
       type: 'channels.queried',
       queriedChannels: {
         channels: [state],
-        isLatestMessageSet: messageSet.isLatest,
+        isLatestMessageSet,
       },
     });
     this.getClient().offlineDb?.executeQuerySafely(
       (db) =>
         db.upsertChannels?.({
           channels: [state],
-          isLatestMessagesSet: messageSet.isLatest,
+          isLatestMessagesSet: isLatestMessageSet,
         }),
       { method: 'upsertChannels' },
     );
@@ -1681,15 +1611,15 @@ export class Channel {
   }
 
   /**
-   * banUser - Bans a user from a channel
+   * Bans a user from a channel.
    *
-   * @param {string} targetUserID
-   * @param {BanUserOptions} options
-   * @returns {Promise<APIResponse>}
+   * @param targetUserId - The user to ban.
+   * @param options - Ban options.
+   * @returns The server response.
    */
-  async banUser(targetUserID: string, options: BanUserOptions) {
+  async banUser(targetUserId: string, options: BanUserOptions) {
     this._checkInitialized();
-    return await this.getClient().banUser(targetUserID, {
+    return await this.getClient().banUser(targetUserId, {
       ...options,
       type: this.type,
       id: this.id,
@@ -1697,45 +1627,39 @@ export class Channel {
   }
 
   /**
-   * hides the channel from queryChannels for the user until a message is added
-   * If clearHistory is set to true - all messages will be removed for the user
+   * Hides the channel from `queryChannels` for the user until a message is added.
+   * If `clear_history` is set to `true`, all messages will be removed for the user.
    *
-   * @param {string | null} userId
-   * @param {boolean} clearHistory
-   * @returns {Promise<APIResponse>}
+   * @param request - The hide channel request payload (optional). Pass `{ clear_history: true }`
+   *   to clear message history for the user.
+   * @returns The server response.
    */
-  async hide(userId: string | null = null, clearHistory = false) {
+  override async hide(request?: Gen_HideChannelRequest) {
     this._checkInitialized();
-
-    return await this.getClient().post<APIResponse>(`${this._channelURL()}/hide`, {
-      user_id: userId,
-      clear_history: clearHistory,
-    });
+    return await super.hide(request);
   }
 
   /**
-   * removes the hidden status for a channel
+   * Removes the hidden status for a channel. Ensures the channel is initialized first.
    *
-   * @param {string | null} userId
-   * @returns {Promise<APIResponse>}
+   * @param request - The show channel request payload (optional).
+   * @returns The server response.
    */
-  async show(userId: string | null = null) {
+  override async show(request?: Gen_ShowChannelRequest) {
     this._checkInitialized();
-    return await this.getClient().post<APIResponse>(`${this._channelURL()}/show`, {
-      user_id: userId,
-    });
+    return await super.show(request);
   }
 
   /**
-   * unbanUser - Removes the bans for a user on a channel
+   * Removes the bans for a user on a channel.
    *
-   * @param {string} targetUserID
-   * @param {UnBanUserOptions} options
-   * @returns {Promise<APIResponse>}
+   * @param targetUserId - The user to unban.
+   * @param options - Unban options (optional).
+   * @returns The server response.
    */
-  async unbanUser(targetUserID: string, options?: UnBanUserOptions) {
+  async unbanUser(targetUserId: string, options?: UnBanUserOptions) {
     this._checkInitialized();
-    return await this.getClient().unbanUser(targetUserID, {
+    return await this.getClient().unbanUser(targetUserId, {
       ...options,
       type: this.type,
       id: this.id,
@@ -1743,15 +1667,15 @@ export class Channel {
   }
 
   /**
-   * shadowBan - Shadow bans a user from a channel
+   * Shadow bans a user from a channel.
    *
-   * @param {string} targetUserID
-   * @param {BanUserOptions} options
-   * @returns {Promise<APIResponse>}
+   * @param targetUserId - The user to shadow ban.
+   * @param options - Ban options.
+   * @returns The server response.
    */
-  async shadowBan(targetUserID: string, options: BanUserOptions) {
+  async shadowBan(targetUserId: string, options: BanUserOptions) {
     this._checkInitialized();
-    return await this.getClient().shadowBan(targetUserID, {
+    return await this.getClient().shadowBan(targetUserId, {
       ...options,
       type: this.type,
       id: this.id,
@@ -1759,242 +1683,245 @@ export class Channel {
   }
 
   /**
-   * removeShadowBan - Removes the shadow ban for a user on a channel
+   * Removes the shadow ban for a user on a channel.
    *
-   * @param {string} targetUserID
-   * @returns {Promise<APIResponse>}
+   * @param targetUserId - The user to remove the shadow ban for.
+   * @returns The server response.
    */
-  async removeShadowBan(targetUserID: string) {
+  async removeShadowBan(targetUserId: string) {
     this._checkInitialized();
-    return await this.getClient().removeShadowBan(targetUserID, {
+    return await this.getClient().removeShadowBan(targetUserId, {
       type: this.type,
       id: this.id,
     });
   }
 
   /**
-   * Cast or cancel one or more votes on a poll
-   * @param pollId string The poll id
-   * @param votes PollVoteData[] The votes that will be casted (or canceled in case of an empty array)
-   * @returns {APIResponse & PollVoteResponse} The poll votes
+   * Casts or cancels one or more votes on a poll.
+   *
+   * @param request - The cast-poll-vote request payload, including the target message ID, poll ID,
+   *   and the vote to cast (or an empty payload to cancel).
+   * @returns The poll vote response.
    */
-  async vote(messageId: string, pollId: string, vote: PollVoteData) {
-    return await this.getClient().castPollVote(messageId, pollId, vote);
+  async vote(request: Parameters<ChatApi['castPollVote']>[0]) {
+    return await this.getClient().castPollVote(request);
   }
 
-  async removeVote(messageId: string, pollId: string, voteId: string) {
-    return await this.getClient().removePollVote(messageId, pollId, voteId);
+  async removeVote(request: Parameters<ChatApi['deletePollVote']>[0]) {
+    return await this.getClient().deletePollVote(request);
   }
 
-  /**
-   * createDraft - Creates or updates a draft message in a channel
-   *
-   * @param {DraftMessagePayload} message The draft message to create or update
-   *
-   * @return {Promise<CreateDraftResponse>} Response containing the created draft
-   */
-  async _createDraft(message: DraftMessagePayload) {
-    return await this.getClient().post<CreateDraftResponse>(
-      this._channelURL() + '/draft',
-      {
-        message,
-      },
-    );
+  async _createDraft(request: Gen_CreateDraftRequest) {
+    return await super.createDraft(request);
   }
 
   /**
-   * createDraft - Creates or updates a draft message in a channel. If offline support is
-   * enabled, it will make sure that creating the draft is queued up if it fails due to
-   * bad internet conditions and executed later.
-   *
-   * @param {DraftMessagePayload} message The draft message to create or update
-   *
-   * @return {Promise<CreateDraftResponse>} Response containing the created draft
+   * Creates or updates a draft message in a channel. If offline support is enabled, the
+   * call is queued so it is replayed on reconnect.
    */
-  async createDraft(message: DraftMessagePayload) {
+  override async createDraft(request: Gen_CreateDraftRequest) {
     try {
       const offlineDb = this.getClient().offlineDb;
       if (offlineDb) {
-        return await offlineDb.queueTask<CreateDraftResponse>({
+        return (await offlineDb.queueTask<CreateDraftResponse>({
           task: {
             channelId: this.id as string,
             channelType: this.type,
-            threadId: message.parent_id,
-            payload: [message],
+            threadId: request.message?.parent_id,
+            payload: [request],
             type: 'create-draft',
           },
-        });
+        })) as Awaited<ReturnType<ChannelApi['createDraft']>>;
       }
     } catch (error) {
-      this._client.logger('error', `offlineDb:create-draft`, {
-        tags: ['channel', 'offlineDb'],
-        error,
-      });
+      offlineDbLogger
+        .withExtraTags('createDraft', this.cid)
+        .error('Creating the draft in the offline database failed.', { error });
     }
 
-    return this._createDraft(message);
+    return this._createDraft(request);
   }
 
-  /**
-   * deleteDraft - Deletes a draft message from a channel or a thread.
-   *
-   * @param {Object} options
-   * @param {string} options.parent_id Optional parent message ID for drafts in threads
-   *
-   * @return {Promise<APIResponse>} API response
-   */
-  async _deleteDraft({ parent_id }: { parent_id?: string } = {}) {
-    return await this.getClient().delete<APIResponse>(this._channelURL() + '/draft', {
-      parent_id,
-    });
+  async _deleteDraft(request?: Parameters<ChannelApi['deleteDraft']>[0]) {
+    return await super.deleteDraft(request);
   }
 
   /**
-   * deleteDraft - Deletes a draft message from a channel or a thread. If offline support is
-   * enabled, it will make sure that deleting the draft is queued up if it fails due to
-   * bad internet conditions and executed later.
-   *
-   * @param {Object} options
-   * @param {string} options.parent_id Optional parent message ID for drafts in threads
-   *
-   * @return {Promise<APIResponse>} API response
+   * Deletes a draft message from a channel or a thread. If offline support is enabled, the
+   * call is queued so it is replayed on reconnect.
    */
-  async deleteDraft(options: { parent_id?: string } = {}) {
-    const { parent_id } = options;
+  override async deleteDraft(request?: Parameters<ChannelApi['deleteDraft']>[0]) {
     try {
       const offlineDb = this.getClient().offlineDb;
       if (offlineDb) {
-        return await offlineDb.queueTask<APIResponse>({
+        return (await offlineDb.queueTask<APIResponse>({
           task: {
             channelId: this.id as string,
             channelType: this.type,
-            threadId: parent_id,
-            payload: [options],
+            threadId: request?.parent_id,
+            payload: [request],
             type: 'delete-draft',
           },
-        });
+        })) as Awaited<ReturnType<ChannelApi['deleteDraft']>>;
       }
     } catch (error) {
-      this._client.logger('error', `offlineDb:delete-draft`, {
-        tags: ['channel', 'offlineDb'],
-        error,
-      });
+      offlineDbLogger
+        .withExtraTags('deleteDraft', this.cid)
+        .error('Deleting the draft from the offline database failed.', { error });
     }
 
-    return this._deleteDraft(options);
+    return this._deleteDraft(request);
   }
 
   /**
-   * getDraft - Retrieves a draft message from a channel
+   * Listens to events on this channel.
    *
-   * @param {Object} options
-   * @param {string} options.parent_id Optional parent message ID for drafts in threads
-   *
-   * @return {Promise<GetDraftResponse>} Response containing the draft
-   */
-  async getDraft({ parent_id }: { parent_id?: string } = {}) {
-    return await this.getClient().get<GetDraftResponse>(this._channelURL() + '/draft', {
-      parent_id,
-    });
-  }
-
-  /**
-   * on - Listen to events on this channel.
+   * @example
+   * channel.on('message.new', (event) => {
+   *   console.log('my new message', event, channel.state.messages);
+   * });
    *
-   * channel.on('message.new', event => {console.log("my new message", event, channel.state.messages)})
-   * or
-   * channel.on(event => {console.log(event.type)})
+   * @example
+   * channel.on((event) => {
+   *   console.log(event.type);
+   * });
    *
-   * @param {EventHandler | EventTypes} callbackOrString  The event type to listen for (optional)
-   * @param {EventHandler} [callbackOrNothing] The callback to call
+   * @param callbackOrString - The event type to listen for, or the callback when listening to all events.
+   * @param callbackOrNothing - The callback to call when an event type was provided (optional).
+   * @returns An object with an `unsubscribe()` method.
    */
-  on(eventType: EventTypes, callback: EventHandler): { unsubscribe: () => void };
+  on<T extends EventType | string>(
+    eventType: T,
+    callback: EventHandler<T>,
+  ): { unsubscribe: () => void };
   on(callback: EventHandler): { unsubscribe: () => void };
   on(
-    callbackOrString: EventHandler | EventTypes,
+    callbackOrString: EventHandler | string,
     callbackOrNothing?: EventHandler,
   ): { unsubscribe: () => void } {
-    const key = callbackOrNothing ? (callbackOrString as string) : 'all';
-    const callback = callbackOrNothing ? callbackOrNothing : callbackOrString;
-    if (!(key in this.listeners)) {
-      this.listeners[key] = [];
-    }
-    this._client.logger(
-      'info',
-      `Attaching listener for ${key} event on channel ${this.cid}`,
-      {
-        tags: ['event', 'channel'],
-        channel: this,
-      },
-    );
+    const key = callbackOrNothing ? (callbackOrString as EventType) : 'all';
+    const callback = callbackOrNothing
+      ? callbackOrNothing
+      : (callbackOrString as EventHandler);
+
+    const set = this.listeners.get(key) ?? new Set();
 
-    this.listeners[key].push(callback);
+    logger
+      .withExtraTags('on', this.cid)
+      .debug(`Attaching a listener for the "${key}" event.`);
+    set.add(callback);
+
+    if (!this.listeners.has(key)) {
+      this.listeners.set(key, set);
+    }
 
     return {
       unsubscribe: () => {
-        this._client.logger(
-          'info',
-          `Removing listener for ${key} event from channel ${this.cid}`,
-          {
-            tags: ['event', 'channel'],
-            channel: this,
-          },
-        );
-
-        this.listeners[key] = this.listeners[key].filter((el) => el !== callback);
+        logger
+          .withExtraTags('on', this.cid)
+          .debug(`Removing the listener for the "${key}" event.`);
+        set.delete(callback);
+        if (!set.size) {
+          this.listeners.delete(key);
+        }
       },
     };
   }
 
   /**
-   * off - Remove the event handler
+   * Removes the event handler.
    *
+   * @param callbackOrString - The event type, or the callback when removing an all-events listener.
+   * @param callbackOrNothing - The callback to remove when an event type was provided (optional).
    */
-  off(eventType: EventTypes, callback: EventHandler): void;
+  off<T extends EventType | string>(eventType: T, callback: EventHandler): void;
   off(callback: EventHandler): void;
-  off(
-    callbackOrString: EventHandler | EventTypes,
-    callbackOrNothing?: EventHandler,
-  ): void {
-    const key = callbackOrNothing ? (callbackOrString as string) : 'all';
-    const callback = callbackOrNothing ? callbackOrNothing : callbackOrString;
-    if (!(key in this.listeners)) {
-      this.listeners[key] = [];
+  off(callbackOrString: EventHandler | string, callbackOrNothing?: EventHandler): void {
+    const key = callbackOrNothing ? (callbackOrString as EventType) : 'all';
+    const callback = callbackOrNothing
+      ? callbackOrNothing
+      : (callbackOrString as EventHandler);
+
+    logger
+      .withExtraTags('off', this.cid)
+      .debug(`Removing the listener for the "${key}" event.`);
+
+    const set = this.listeners.get(key);
+
+    set?.delete(callback);
+
+    if (!set?.size) {
+      this.listeners.delete(key);
     }
+  }
 
-    this._client.logger(
-      'info',
-      `Removing listener for ${key} event from channel ${this.cid}`,
-      {
-        tags: ['event', 'channel'],
-        channel: this,
-      },
-    );
-    this.listeners[key] = this.listeners[key].filter((value) => value !== callback);
+  private _patchReadState(
+    patch: (currentReadState: ChannelState['read']) => ChannelState['read'],
+    reconcileMeta?: ReadStoreReconcileMeta,
+  ) {
+    let hasStateChanged = false;
+    this.messageReceiptsTracker.setPendingReadStoreReconcileMeta(reconcileMeta);
+
+    this.state.readStore.next((currentReadStoreState) => {
+      const nextReadState = patch(currentReadStoreState.read);
+
+      if (nextReadState === currentReadStoreState.read) {
+        return currentReadStoreState;
+      }
+      hasStateChanged = true;
+
+      return {
+        ...currentReadStoreState,
+        read: nextReadState,
+      };
+    });
+
+    if (!hasStateChanged) {
+      this.messageReceiptsTracker.setPendingReadStoreReconcileMeta(undefined);
+    }
+  }
+
+  private _upsertReadState(
+    userId: string,
+    update: (
+      currentUserReadState: ChannelState['read'][string] | undefined,
+    ) => ChannelState['read'][string],
+    reconcileMeta?: ReadStoreReconcileMeta,
+  ) {
+    let nextUserReadState: ChannelState['read'][string] | undefined;
+
+    this._patchReadState((currentReadState) => {
+      const currentUserReadState = currentReadState[userId];
+      const updatedUserReadState = update(currentUserReadState);
+
+      nextUserReadState = updatedUserReadState;
+
+      return {
+        ...currentReadState,
+        [userId]: updatedUserReadState,
+      };
+    }, reconcileMeta);
+
+    return nextUserReadState;
   }
 
   _handleChannelEvent(event: Event) {
     // eslint-disable-next-line @typescript-eslint/no-this-alias
     const channel = this;
-    this._client.logger(
-      'info',
-      `channel:_handleChannelEvent - Received event of type { ${event.type} } on ${this.cid}`,
-      {
-        tags: ['event', 'channel'],
-        channel: this,
-      },
-    );
+    logger
+      .withExtraTags('_handleChannelEvent', this.cid)
+      .debug(`Received an event of type "${event.type}".`, { event });
 
     const channelState = channel.state;
     switch (event.type) {
       case 'typing.start':
         if (event.user?.id) {
-          channelState.typing[event.user.id] = event;
+          channelState.setTypingEvent(event.user.id, event);
         }
         break;
       case 'typing.stop':
         if (event.user?.id) {
-          delete channelState.typing[event.user.id];
+          channelState.removeTypingEvent(event.user.id);
         }
         break;
       // `message.read_locally` is the client-only event dispatched by `markReadLocally()` when read
@@ -2004,22 +1931,45 @@ export class Channel {
       case 'message.read_locally':
       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();
+          const eventUser = event.user;
+          const readAtDate = new Date(event.created_at);
+          const toDate = (value?: string | Date) =>
+            value ? (value instanceof Date ? value : new Date(value)) : undefined;
+          const userReadState = this._upsertReadState(
+            eventUser.id,
+            (currentUserReadState) => {
+              const currentDeliveredAt = toDate(currentUserReadState?.last_delivered_at);
+
+              return {
+                // preserve delivery information already known for user
+                ...currentUserReadState,
+                ...(currentUserReadState?.last_read
+                  ? { last_read: toDate(currentUserReadState.last_read) }
+                  : null),
+                ...(currentDeliveredAt
+                  ? { last_delivered_at: currentDeliveredAt }
+                  : null),
+                last_read: readAtDate,
+                last_read_message_id: event.last_read_message_id,
+                last_delivered_at:
+                  !currentDeliveredAt || currentDeliveredAt < readAtDate
+                    ? readAtDate
+                    : currentDeliveredAt,
+                last_delivered_message_id:
+                  !currentDeliveredAt || currentDeliveredAt < readAtDate
+                    ? (event.last_read_message_id ??
+                      currentUserReadState?.last_delivered_message_id)
+                    : currentUserReadState?.last_delivered_message_id,
+                first_unread_message_id: undefined,
+                user: eventUser,
+                unread_messages: 0,
+              };
+            },
+            { changedUserIds: [eventUser.id] },
+          );
+          void userReadState;
 
+          const client = this.getClient();
           const isOwnEvent = event.user?.id === client.user?.id;
 
           if (isOwnEvent) {
@@ -2035,21 +1985,40 @@ export class Channel {
       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,
-          });
+          const eventUser = event.user;
+          const createdAt = event.created_at;
+          const toDate = (value?: string | Date) =>
+            value ? (value instanceof Date ? value : new Date(value)) : undefined;
+          const resolvedDeliveredAt = new Date(event.last_delivered_at ?? createdAt);
+          const userReadState = this._upsertReadState(
+            eventUser.id,
+            (currentUserReadState) => {
+              const currentDeliveredAt = toDate(currentUserReadState?.last_delivered_at);
+              const currentReadAt = toDate(currentUserReadState?.last_read);
+
+              return {
+                ...currentUserReadState,
+                ...(currentReadAt ? { last_read: currentReadAt } : null),
+                ...(currentDeliveredAt
+                  ? { last_delivered_at: currentDeliveredAt }
+                  : null),
+                last_delivered_at:
+                  currentDeliveredAt && currentDeliveredAt > resolvedDeliveredAt
+                    ? currentDeliveredAt
+                    : resolvedDeliveredAt,
+                last_delivered_message_id:
+                  currentDeliveredAt && currentDeliveredAt > resolvedDeliveredAt
+                    ? currentUserReadState?.last_delivered_message_id
+                    : event.last_delivered_message_id,
+                user: eventUser,
+                // delivery events can be received before read events
+                last_read: currentReadAt ?? new Date(createdAt),
+                unread_messages: currentUserReadState?.unread_messages ?? 0,
+              };
+            },
+            { changedUserIds: [eventUser.id] },
+          );
+          void userReadState;
 
           const client = this.getClient();
           const isOwnEvent = event.user?.id === client.user?.id;
@@ -2075,23 +2044,37 @@ export class Channel {
       case 'message.deleted':
         if (event.message) {
           this._extendEventWithOwnReactions(event);
-          if (event.hard_delete) channelState.removeMessage(event.message);
-          else channelState.addMessageSorted(event.message, false, false);
-
-          channelState.removeQuotedMessageReferences(event.message);
-
-          if (event.message.pinned) {
-            channelState.removePinnedMessage(event.message);
+          const formattedMessage = formatMessage(event.message);
+          const isThreadReply =
+            !!event.message.parent_id && !event.message.show_in_channel;
+          // Thread-only replies are handled by the Thread object; the channel owns the main list.
+          if (!isThreadReply) {
+            if (event.hard_delete) {
+              this.messagePaginator.removeItem({ id: event.message.id });
+              this.pinnedMessagesPaginator.removeItem({ id: event.message.id });
+            } else {
+              this.messagePaginator.ingestItem(formattedMessage);
+              this.pinnedMessagesPaginator.ingestItem(formattedMessage);
+            }
           }
+          this.messagePaginator.reflectQuotedMessageUpdate(formattedMessage);
+          this.pinnedMessagesPaginator.reflectQuotedMessageUpdate(formattedMessage);
         }
         break;
       case 'user.messages.deleted':
         if (event.user) {
-          this.state.deleteUserMessages(
-            event.user,
-            !!event.hard_delete,
-            new Date(event.created_at ?? Date.now()),
-          );
+          const deletedAt = new Date(event.created_at ?? Date.now());
+          const hardDelete = !!event.hard_delete;
+          this.messagePaginator.applyMessageDeletionForUser({
+            userId: event.user.id,
+            hardDelete,
+            deletedAt,
+          });
+          this.pinnedMessagesPaginator.applyMessageDeletionForUser({
+            userId: event.user.id,
+            hardDelete,
+            deletedAt,
+          });
         }
         break;
       case 'message.new':
@@ -2102,12 +2085,13 @@ export class Channel {
           const isThreadMessage =
             event.message.parent_id && !event.message.show_in_channel;
 
-          if (this.state.isUpToDate || isThreadMessage) {
-            channelState.addMessageSorted(event.message, ownMessage);
-          }
-
-          if (event.message.pinned) {
-            channelState.addPinnedMessage(event.message);
+          if (!isThreadMessage) {
+            // ingestItem advances the paginator's tracked latest message (→ last_message_at). A
+            // message that arrives while the viewer has scrolled to an older window lands in the
+            // head interval, not the active one, so the view is preserved without an isUpToDate flag.
+            this.messagePaginator.ingestItem(formatMessage(event.message));
+            // ingestItem auto-adds when pinned (matchesFilter { pinned: true }).
+            this.pinnedMessagesPaginator.ingestItem(formatMessage(event.message));
           }
 
           // do not increase the unread count - the back-end does not increase the count neither in the following cases:
@@ -2120,23 +2104,54 @@ export class Channel {
           if (preventUnreadCountUpdate) break;
 
           if (event.user?.id) {
-            for (const userId in channelState.read) {
-              if (userId === event.user.id) {
-                channelState.read[event.user.id] = {
-                  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;
-              }
-            }
+            const eventUser = event.user;
+            const eventUserId = eventUser.id;
+            const createdAt = new Date(event.created_at ?? Date.now());
+            const eventMessageId = event.message.id;
+            this._patchReadState(
+              (currentReadState) => {
+                const userIds = Object.keys(currentReadState);
+                if (!userIds.length) return currentReadState;
+
+                const nextReadState = { ...currentReadState };
+
+                for (const userId of userIds) {
+                  if (userId === eventUserId) {
+                    nextReadState[eventUserId] = {
+                      last_read: createdAt,
+                      user: eventUser,
+                      unread_messages: 0,
+                      last_delivered_at: createdAt,
+                      last_delivered_message_id: eventMessageId,
+                    };
+                  } else {
+                    nextReadState[userId] = {
+                      ...currentReadState[userId],
+                      unread_messages:
+                        (currentReadState[userId]?.unread_messages ?? 0) + 1,
+                    };
+                  }
+                }
+
+                return nextReadState;
+              },
+              { changedUserIds: Object.keys(channelState.read) },
+            );
           }
 
-          if (this._countMessageAsUnread(event.message)) {
+          // Skip the own-unread bump when the user is actively viewing the latest messages (app
+          // foregrounded + newest message on screen). Without this, a message read in real time
+          // momentarily bumps `unreadCount`/the snapshot — the "N new" separator/banner + the
+          // channel-list badge would flash until the SDK's mark-read resets it. The SDK reports the
+          // viewing state via `messagePaginator.setViewingLive` and marks the message read itself.
+          // Only the OWN unread accounting is gated; the per-user read/receipt tracking above is
+          // intentionally left intact.
+          const isViewingLive = this.messagePaginator.isViewingLive;
+          if (!isViewingLive && this._countMessageAsUnread(event.message)) {
             channelState.unreadCount = channelState.unreadCount + 1;
+            this.messagePaginator.setUnreadSnapshot({
+              unreadCount: channelState.unreadCount,
+            });
           }
 
           client.syncDeliveredCandidates([this]);
@@ -2146,44 +2161,38 @@ export class Channel {
       case 'message.undeleted':
         if (event.message) {
           this._extendEventWithOwnReactions(event);
-          channelState.addMessageSorted(event.message, false, false);
-          channelState._updateQuotedMessageReferences({ message: event.message });
-          if (event.message.pinned) {
-            channelState.addPinnedMessage(event.message);
-          } else {
-            channelState.removePinnedMessage(event.message);
+          const formattedMessage = formatMessage(event.message);
+          if (!event.message.parent_id) {
+            this.messagePaginator.ingestItem(formattedMessage);
+            this.messagePaginator.reflectQuotedMessageUpdate(formattedMessage);
+            // ingestItem auto-adds on pin / auto-removes on unpin (matchesFilter { pinned: true }).
+            this.pinnedMessagesPaginator.ingestItem(formattedMessage);
+            this.pinnedMessagesPaginator.reflectQuotedMessageUpdate(formattedMessage);
           }
         }
         break;
       case 'channel.truncated':
         if (event.channel?.truncated_at) {
-          const truncatedAt = +new Date(event.channel.truncated_at);
-
-          channelState.messageSets.forEach((messageSet, messageSetIndex) => {
-            messageSet.messages.forEach(({ created_at: createdAt, id }) => {
-              if (truncatedAt > +createdAt)
-                channelState.removeMessage({ id, messageSetIndex });
-            });
-          });
-
-          channelState.pinnedMessages.forEach(({ id, created_at: createdAt }) => {
-            if (truncatedAt > +createdAt)
-              channelState.removePinnedMessage({ id } as MessageResponse);
-          });
-          channelState.unreadCount = this.countUnread(
-            new Date(event.channel.truncated_at),
-          );
+          const truncatedAtDate = new Date(event.channel.truncated_at);
+
+          channelState.unreadCount = this.countUnread(truncatedAtDate);
+          // Partial truncation: keep messages newer than the cutoff. clearStateAndCache would wipe
+          // the whole paginator (readers now source from it), so use the partial truncate. The
+          // channel-wide read/unread context is reset by the truncation, so drop the unread snapshot
+          // too (clearStateAndCache did this for the full-truncate branch).
+          this.messagePaginator.truncate({ truncatedAt: truncatedAtDate });
+          this.messagePaginator.clearUnreadSnapshot();
+          this.pinnedMessagesPaginator.truncate({ truncatedAt: truncatedAtDate });
         } else {
-          channelState.clearMessages();
           channelState.unreadCount = 0;
+          this.messagePaginator.clearStateAndCache();
+          this.pinnedMessagesPaginator.clearStateAndCache();
         }
 
         // system messages don't increment unread counts
         if (event.message) {
-          channelState.addMessageSorted(event.message);
-          if (event.message.pinned) {
-            channelState.addPinnedMessage(event.message);
-          }
+          this.messagePaginator.ingestItem(formatMessage(event.message));
+          this.pinnedMessagesPaginator.ingestItem(formatMessage(event.message));
         }
 
         break;
@@ -2208,7 +2217,7 @@ export class Channel {
           };
         }
 
-        const currentUserId = this.getClient().userID;
+        const currentUserId = this.getClient().userId;
         if (
           typeof currentUserId === 'string' &&
           typeof memberCopy?.user?.id === 'string' &&
@@ -2233,26 +2242,33 @@ 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 || !event.last_read_at) break;
+        const eventUser = event.user;
+        const lastReadAt = event.last_read_at;
         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,
-          user: event.user,
-          unread_messages: unreadCount,
-        };
+        this._upsertReadState(
+          eventUser.id,
+          (currentUserReadState) => ({
+            // keep the message delivery info
+            ...currentUserReadState,
+            first_unread_message_id: event.first_unread_message_id,
+            last_read: new Date(lastReadAt),
+            last_read_message_id: event.last_read_message_id,
+            user: eventUser,
+            unread_messages: unreadCount,
+          }),
+          { changedUserIds: [eventUser.id] },
+        );
 
-        channelState.unreadCount = unreadCount;
-        this.messageReceiptsTracker.onNotificationMarkUnread({
-          user: event.user,
-          lastReadAt: event.last_read_at,
-          lastReadMessageId: event.last_read_message_id,
+        this.messagePaginator.setUnreadSnapshot({
+          firstUnreadMessageId:
+            channelState.read[event.user.id].first_unread_message_id ?? null,
+          lastReadAt: channelState.read[event.user.id].last_read,
+          lastReadMessageId: channelState.read[event.user.id].last_read_message_id,
+          unreadCount,
         });
+
+        channelState.unreadCount = unreadCount;
         break;
       }
       case 'channel.updated':
@@ -2263,57 +2279,98 @@ export class Channel {
           if (isFrozenChanged) {
             this.query({ state: false, messages: { limit: 0 }, watchers: { limit: 0 } });
           }
+          const previousChannelData = channel.data;
           const newChannelData = {
             ...event.channel,
             hidden: event.channel?.hidden ?? channel.data?.hidden,
+            member_count: event.channel?.member_count ?? channel.data?.member_count,
             own_capabilities:
               event.channel?.own_capabilities ?? channel.data?.own_capabilities,
           };
           channel.data = newChannelData;
+          channel._syncStateFromChannelData(channel.data, previousChannelData);
           this.cooldownTimer.refresh();
         }
         break;
       case 'reaction.new':
         if (event.message && event.reaction) {
-          const { message, reaction } = event;
-          event.message = channelState.addReaction(reaction, message) as MessageResponse;
+          const { reaction } = event;
+          // Reflect main messages AND show_in_channel replies (both live in these paginators);
+          // pure replies are handled by the thread's own reaction subscription.
+          if (!event.message?.parent_id || event.message.show_in_channel) {
+            this.messagePaginator.reflectReaction({ message: event.message, reaction });
+            this.pinnedMessagesPaginator.reflectReaction({
+              message: event.message,
+              reaction,
+            });
+          }
         }
         break;
       case 'reaction.deleted':
         if (event.message && event.reaction) {
-          const { message, reaction } = event;
-          event.message = channelState.removeReaction(reaction, message);
+          const { reaction } = event;
+          if (
+            event.message &&
+            (!event.message.parent_id || event.message.show_in_channel)
+          ) {
+            this.messagePaginator.reflectReaction({
+              message: event.message,
+              reaction,
+              removed: true,
+            });
+            this.pinnedMessagesPaginator.reflectReaction({
+              message: event.message,
+              reaction,
+              removed: true,
+            });
+          }
         }
         break;
       case 'reaction.updated':
         if (event.message && event.reaction) {
-          const { message, reaction } = event;
+          const { reaction } = event;
           // assuming reaction.updated is only called if enforce_unique is true
-          event.message = channelState.addReaction(
-            reaction,
-            message,
-            true,
-          ) as MessageResponse;
+          if (!event.message?.parent_id || event.message.show_in_channel) {
+            this.messagePaginator.reflectReaction({
+              enforceUnique: true,
+              message: event.message,
+              reaction,
+            });
+            this.pinnedMessagesPaginator.reflectReaction({
+              enforceUnique: true,
+              message: event.message,
+              reaction,
+            });
+          }
         }
         break;
-      case 'channel.hidden':
+      case 'channel.hidden': {
+        const previousChannelData = channel.data;
         channel.data = {
-          ...channel.data,
-          blocked: !!event.channel?.blocked,
+          // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+          ...channel.data!,
+          blocked: event.channel?.blocked ?? false,
           hidden: true,
         };
+        channel._syncStateFromChannelData(channel.data, previousChannelData);
         if (event.clear_history) {
-          channelState.clearMessages();
+          this.messagePaginator.clearStateAndCache();
+          this.pinnedMessagesPaginator.clearStateAndCache();
         }
         break;
-      case 'channel.visible':
+      }
+      case 'channel.visible': {
+        const previousChannelData = channel.data;
         channel.data = {
-          ...channel.data,
-          blocked: !!event.channel?.blocked,
+          // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+          ...channel.data!,
+          blocked: event.channel?.blocked ?? false,
           hidden: false,
         };
+        channel._syncStateFromChannelData(channel.data, previousChannelData);
         this.getClient().offlineDb?.handleChannelVisibilityEvent({ event });
         break;
+      }
       case 'user.banned':
         if (!event.user?.id) break;
         channelState.members[event.user.id] = {
@@ -2335,36 +2392,26 @@ export class Channel {
       default:
     }
 
+    const typedEvent = event as Extract<WSEvent, { watcher_count?: any }>;
     // any event can send over the online count
-    if (event.watcher_count !== undefined) {
-      channel.state.watcher_count = event.watcher_count;
+    if (typeof typedEvent.watcher_count !== 'undefined') {
+      channel.state.watcher_count = typedEvent.watcher_count;
     }
   }
 
-  _callChannelListeners = (event: Event) => {
-    // eslint-disable-next-line @typescript-eslint/no-this-alias
-    const channel = this;
-    // gather and call the listeners
-    const listeners = [];
-    if (channel.listeners.all) {
-      listeners.push(...channel.listeners.all);
-    }
-    if (channel.listeners[event.type]) {
-      listeners.push(...channel.listeners[event.type]);
-    }
+  _callChannelListeners = (event: WSEvent) => {
+    const allSet = this.listeners.get('all');
+    const targetSet = this.listeners.get(event.type);
 
-    // call the event and send it to the listeners
-    for (const listener of listeners) {
-      if (typeof listener !== 'string') {
-        listener(event);
-      }
-    }
+    [allSet, targetSet].forEach((set) =>
+      set?.forEach((handleEvent) => handleEvent(event)),
+    );
   };
 
   /**
-   * _channelURL - Returns the channel url
+   * Returns the channel url.
    *
-   * @return {string} The channel url
+   * @returns The channel url.
    */
   _channelURL = () => {
     if (!this.id) {
@@ -2376,21 +2423,22 @@ export class Channel {
   };
 
   _checkInitialized() {
-    if (
-      !this.initialized &&
-      !this.offlineMode &&
-      !this.getClient()._isUsingServerAuth()
-    ) {
+    if (!this.initialized && !this.offlineMode) {
       throw Error(
         `Channel ${this.cid} hasn't been initialized yet. Make sure to call .watch() and wait for it to resolve`,
       );
     }
   }
 
-  _initializeState(
-    state: ChannelAPIResponse,
-    messageSetToAddToIfDoesNotExist: MessageSetType = 'latest',
+  _syncStateFromChannelData(
+    data: Channel['data'],
+    fallbackData: Channel['data'] = this.data,
   ) {
+    this.state.syncOwnCapabilitiesFromChannelData(data, fallbackData);
+    this.state.syncMemberCountFromChannelData(data, fallbackData);
+  }
+
+  _initializeState(state: ChannelStateResponseFields) {
     const { state: clientState, user, userID } = this.getClient();
 
     // add the members and users
@@ -2404,24 +2452,22 @@ export class Channel {
       }
     }
 
-    this.state.membership = state.membership || {};
-
-    const messages = state.messages || [];
-    if (!this.state.messages) {
-      this.state.initMessages();
+    if (state.membership) {
+      this.state.membership = state.membership;
     }
-    const { messageSet, filteredMessageIds } = this.state.addMessagesSorted(
-      messages,
-      false,
-      true,
-      true,
-      messageSetToAddToIfDoesNotExist,
-    );
 
-    if (!this.state.pinnedMessages) {
-      this.state.pinnedMessages = [];
-    }
-    this.state.addPinnedMessages(state.pinned_messages || []);
+    // Seed the message paginator's `lastMessageAt` aggregate from the server's authoritative
+    // `last_message_at`. The first-page seed (Channel.query / client.hydrateActiveChannels) also
+    // advances it from ingested messages; both feed the same monotonic max, so this additionally
+    // covers the path where the paginator seed is skipped (an already-loaded channel the viewer has
+    // jumped away from, where re-seeding would clobber their window).
+    this.messagePaginator.seedLastMessageAt(state.channel?.last_message_at);
+
+    // Seed the pinned-messages paginator from the same response.
+    this.pinnedMessagesPaginator.seedFirstPageSync(
+      (state.pinned_messages || []).map(formatMessage),
+      this.pinnedMessagesPaginator.pageSize,
+    );
     if (state.pending_messages) {
       this.state.pending_messages = state.pending_messages;
     }
@@ -2441,11 +2487,12 @@ export class Channel {
     // initialize read state to last message or current time if the channel is empty
     // if the user is a member, this value will be overwritten later on otherwise this ensures
     // that everything up to this point is not marked as unread
+    const readUpdates: ChannelState['read'] = {};
     if (userID != null) {
-      const last_read = this.state.last_message_at || new Date();
+      const last_read = this.messagePaginator.lastMessageAt || new Date();
       if (user) {
-        this.state.read[user.id] = {
-          user,
+        readUpdates[user.id] = {
+          user: user as UserResponse,
           last_read,
           unread_messages: 0,
         };
@@ -2455,7 +2502,7 @@ export class Channel {
     // apply read state if part of the state
     if (state.read) {
       for (const read of state.read) {
-        this.state.read[read.user.id] = {
+        readUpdates[read.user.id] = {
           last_delivered_at: read.last_delivered_at
             ? new Date(read.last_delivered_at)
             : undefined,
@@ -2467,24 +2514,41 @@ export class Channel {
         };
 
         if (read.user.id === user?.id) {
-          this.state.unreadCount = this.state.read[read.user.id].unread_messages;
+          this.state.unreadCount = readUpdates[read.user.id].unread_messages;
         }
       }
-
-      this.messageReceiptsTracker.ingestInitial(state.read);
     }
 
-    return {
-      messageSet,
-      filteredMessageIds,
-    };
+    const entries = Object.entries(readUpdates);
+    if (entries.length) {
+      this._patchReadState(
+        (currentReadState) => {
+          let hasChanges = false;
+          const nextReadState = { ...currentReadState };
+
+          for (const [userId, readState] of entries) {
+            if (nextReadState[userId] === readState) continue;
+            nextReadState[userId] = readState;
+            hasChanges = true;
+          }
+
+          return hasChanges ? nextReadState : currentReadState;
+        },
+        { changedUserIds: entries.map(([userId]) => userId) },
+      );
+    }
   }
 
-  _extendEventWithOwnReactions(event: Event) {
+  _extendEventWithOwnReactions(
+    event: EventPayload<'message.undeleted' | 'message.updated' | 'message.deleted'>,
+  ) {
     if (!event.message) {
       return;
     }
-    const message = this.state.findMessage(event.message.id, event.message.parent_id);
+    // The channel message list is owned by the paginator; enrich from it. Thread-only replies are
+    // not in the paginator (getItem returns undefined) — the Thread object preserves their
+    // own_reactions on its own reply store.
+    const message = this.messagePaginator.getItem(event.message.id);
     if (message) {
       event.message.own_reactions = message.own_reactions;
     }
@@ -2524,17 +2588,15 @@ export class Channel {
   }
 
   _disconnect() {
-    this._client.logger(
-      'info',
-      `channel:disconnect() - Disconnecting the channel ${this.cid}`,
-      {
-        tags: ['connection', 'channel'],
-        channel: this,
-      },
-    );
+    logger.withExtraTags('_disconnect', this.cid).info('Disconnecting the channel.');
 
     this.disconnected = true;
+    this.messageReceiptsTracker.unregisterSubscriptions();
     this.cooldownTimer.clearTimeout();
-    this.state.setIsUpToDate(false);
+    // Release the store-backed paginators so the message store no longer pins this removed channel
+    // (and its whole message graph) through its subscriber registry. The channel is being discarded
+    // here (disconnected + deleted from activeChannels, never reused), mirroring Thread teardown.
+    this.messagePaginator.dispose();
+    this.pinnedMessagesPaginator.dispose();
   }
 }