stream-chat 9.50.3 → 10.0.0-rc.2

package/src/offline-support/offline_support_api.ts

@@ -1,10 +1,14 @@
 import type {
-  APIErrorResponse,
+  APIError,
   ChannelResponse,
   Event,
+  EventPayload,
+  EventType,
   LocalMessage,
-  Message,
+  MessageRequest,
   MessageResponse,
+  OwnUserResponse,
+  RequireLiteral,
 } from '../types';
 
 import type {
@@ -14,18 +18,24 @@ import type {
   PrepareBatchDBQueries,
 } from './types';
 import { OfflineError } from './types';
+import { isEphemeral } from '../errors';
 import type { StreamChat } from '../client';
 import type { AxiosError } from 'axios';
 import { OfflineDBSyncManager } from './offline_sync_manager';
+import { chatLoggerSystem } from '../logger';
 import { StateStore } from '../store';
 import {
   channelHasReadEvents,
   channelTracksReadLocally,
+  formatMessage,
   localMessageToNewMessagePayload,
   runDetached,
 } from '../utils';
 import { isMessageUpdateReplayable } from './util';
 
+const logger = chatLoggerSystem.getLogger('offline-db');
+import type { WSEvent } from '../gen/models';
+
 /**
  * Abstract base class for an offline database implementation used with StreamChat.
  *
@@ -45,12 +55,11 @@ export abstract class AbstractOfflineDB implements OfflineDBApi {
     this.syncManager = new OfflineDBSyncManager({ client, offlineDb: this });
     this.state = new StateStore<OfflineDBState>({
       initialized: false,
-      userId: this.client.userID,
+      userId: this.client.userId,
     });
   }
 
   /**
-   * @abstract
    * Inserts a reaction into the DB.
    * Will write to:
    * - The reactions table with the new reaction
@@ -58,24 +67,24 @@ export abstract class AbstractOfflineDB implements OfflineDBApi {
    * - The users table with any users associated
    * Will return the prepared queries for delayed execution (even if they are
    * already executed).
+   *
    * @param {DBInsertReactionType} options
    * @returns {Promise<ExecuteBatchDBQueriesType>}
    */
   abstract insertReaction: OfflineDBApi['insertReaction'];
 
   /**
-   * @abstract
    * Upserts the list of CIDs for a filter + sort query hash.
    * Will write to only the table containing the cids.
    * Will return the prepared queries for delayed execution (even if they are
    * already executed).
+   *
    * @param {DBUpsertCidsForQueryType} options
    * @returns {Promise<ExecuteBatchDBQueriesType>}
    */
   abstract upsertCidsForQuery: OfflineDBApi['upsertCidsForQuery'];
 
   /**
-   * @abstract
    * Upserts the channels passed as an argument within the DB. Relies on
    * writing the properties we need from a ChannelResponse into the adequate
    * tables.
@@ -89,72 +98,72 @@ export abstract class AbstractOfflineDB implements OfflineDBApi {
    * - The reads table for each user
    * Will return the prepared queries for delayed execution (even if they are
    * already executed).
+   *
    * @param {DBUpsertChannelsType} options
    * @returns {Promise<ExecuteBatchDBQueriesType>}
    */
   abstract upsertChannels: OfflineDBApi['upsertChannels'];
 
   /**
-   * @abstract
    * Upserts the current active user's sync status.
    * Will only write to the sync status table.
    * Will return the prepared queries for delayed execution (even if they are
    * already executed).
+   *
    * @param {DBUpsertUserSyncStatusType} options
    * @returns {Promise<ExecuteBatchDBQueriesType>}
    */
   abstract upsertUserSyncStatus: OfflineDBApi['upsertUserSyncStatus'];
 
   /**
-   * @abstract
    * Upserts the app settings for the current Stream App into the DB. It
    * is only intended to be run once per lifecycle of the app.
    * Will only write to the respective app settings table.
    * Will return the prepared queries for delayed execution (even if they are
    * already executed).
+   *
    * @param {DBUpsertAppSettingsType} options
    * @returns {Promise<ExecuteBatchDBQueriesType>}
    */
   abstract upsertAppSettings: OfflineDBApi['upsertAppSettings'];
 
   /**
-   * @abstract
    * Upserts a poll fully in the DB.
    * Will write to the polls table. It should not update the message
    * associated due to how the poll state works.
    * Will return the prepared queries for delayed execution (even if they are
    * already executed).
+   *
    * @param {DBUpsertPollType} options
    * @returns {Promise<ExecuteBatchDBQueriesType>}
    */
   abstract upsertPoll: OfflineDBApi['upsertPoll'];
 
   /**
-   * @abstract
    * Upserts only the channel.data for the provided channels in the DB.
    * Will only write to the channels table.
    * Will return the prepared queries for delayed execution (even if they are
    * already executed).
+   *
    * @param {DBUpsertChannelDataType} options
    * @returns {Promise<ExecuteBatchDBQueriesType>}
    */
   abstract upsertChannelData: OfflineDBApi['upsertChannelData'];
 
   /**
-   * @abstract
    * Upserts the provided reads in the DB.
    * Will write to:
    * - The reads table
    * - The users table for each user associated with a read
    * Will return the prepared queries for delayed execution (even if they are
    * already executed).
+   *
    * @param {DBUpsertReadsType} options
    * @returns {Promise<ExecuteBatchDBQueriesType>}
    */
   abstract upsertReads: OfflineDBApi['upsertReads'];
 
   /**
-   * @abstract
    * Upserts the messages in the DB.
    * Will write to:
    * - The messages table
@@ -164,287 +173,288 @@ export abstract class AbstractOfflineDB implements OfflineDBApi {
    * - The users table
    * Will return the prepared queries for delayed execution (even if they are
    * already executed).
+   *
    * @param {DBUpsertMessagesType} options
    * @returns {Promise<ExecuteBatchDBQueriesType>}
    */
   abstract upsertMessages: OfflineDBApi['upsertMessages'];
 
   /**
-   * @abstract
    * Upserts the members in the DB.
    * Will write to:
    * - The users table (for each user associated with a member)
    * - The members table
    * Will return the prepared queries for delayed execution (even if they are
    * already executed).
+   *
    * @param {DBUpsertMembersType} options
    * @returns {Promise<ExecuteBatchDBQueriesType>}
    */
   abstract upsertMembers: OfflineDBApi['upsertMembers'];
 
   /**
-   * @abstract
    * Updates a reaction in the DB. Will update the DB the same way
    * a reaction.updated event would (it assumes enforce_unique is true
    * and removes all other reactions associated with the user.
    * Will write to the reactions table.
    * Will return the prepared queries for delayed execution (even if they are
    * already executed).
+   *
    * @param {DBUpdateReactionType} options
    * @returns {Promise<ExecuteBatchDBQueriesType>}
    */
   abstract updateReaction: OfflineDBApi['updateReaction'];
 
   /**
-   * @abstract
    * Updates a single message in the DB. This is used as a faster
    * alternative to upsertMessages with more optimized queries.
    * Will write to the messages table.
    * Will return the prepared queries for delayed execution (even if they are
    * already executed).
+   *
    * @param {DBUpdateMessageType} options
    * @returns {Promise<ExecuteBatchDBQueriesType>}
    */
   abstract updateMessage: OfflineDBApi['updateMessage'];
 
   /**
-   * @abstract
    * Fetches the provided draft from the DB. Should return as close to
    * the server side DraftResponse as possible.
+   *
    * @param {DBGetDraftType} options
    * @returns {Promise<DraftResponse | null>}
    */
   abstract getDraft: OfflineDBApi['getDraft'];
   /**
-   * @abstract
    * Upserts a draft in the DB.
    * Will write to the draft table upserting the draft.
    * Will return the prepared queries for delayed execution (even if they are
    * already executed).
+   *
    * @param {DBUpsertDraftType} options
    * @returns {Promise<ExecuteBatchDBQueriesType>}
    */
   abstract upsertDraft: OfflineDBApi['upsertDraft'];
   /**
-   * @abstract
    * Deletes a draft from the DB.
    * Will write to the draft table removing the draft.
    * Will return the prepared queries for delayed execution (even if they are
    * already executed).
+   *
    * @param {DBDeleteDraftType} options
    * @returns {Promise<ExecuteBatchDBQueriesType>}
    */
   abstract deleteDraft: OfflineDBApi['deleteDraft'];
 
   /**
-   * @abstract
    * Fetches the provided channels from the DB and aggregates all data associated
-   * with them in a single ChannelAPIResponse. The implementation itself is responsible
+   * with them in a single ChannelStateResponseFields. The implementation itself is responsible
    * for aggregating and serialization of all of the data. Should return as close to
-   * the server side ChannelAPIResponse as possible.
+   * the server side ChannelStateResponseFields as possible.
+   *
    * @param {DBGetChannelsType} options
-   * @returns {Promise<Omit<ChannelAPIResponse, 'duration'>[] | null>}
+   * @returns {Promise<Omit<ChannelStateResponseFields, 'duration'>[] | null>}
    */
   abstract getChannels: OfflineDBApi['getChannels'];
 
   /**
-   * @abstract
    * Fetches the channels from the DB that were the last known response to a filters & sort
-   * hash as a query and aggregates all data associated with them in a single ChannelAPIResponse.
+   * hash as a query and aggregates all data associated with them in a single ChannelStateResponseFields.
    * The implementation itself is responsible for aggregating and serialization of all of the data.
-   * Should return as close to the server side ChannelAPIResponse as possible.
+   * Should return as close to the server side ChannelStateResponseFields as possible.
+   *
    * @param {DBGetChannelsForQueryType} options
-   * @returns {Promise<Omit<ChannelAPIResponse, 'duration'>[] | null>}
+   * @returns {Promise<Omit<ChannelStateResponseFields, 'duration'>[] | null>}
    */
   abstract getChannelsForQuery: OfflineDBApi['getChannelsForQuery'];
 
   /**
-   * @abstract
    * Will return a list of all available CIDs in the DB. The same can be achieved
    * by fetching all channels, however this is meant to be much faster as a query.
+   *
    * @returns {Promise<string[]>}
    */
   abstract getAllChannelCids: OfflineDBApi['getAllChannelCids'];
 
   /**
-   * @abstract
    * Fetches the timestamp of the last sync of the DB.
+   *
    * @param {DBGetLastSyncedAtType} options
    * @returns {Promise<string | undefined>}
    */
   abstract getLastSyncedAt: OfflineDBApi['getLastSyncedAt'];
 
   /**
-   * @abstract
    * Fetches all pending tasks from the DB. It will return them in an
    * ordered fashion by the time they were created.
+   *
    * @param {DBGetPendingTasksType} [conditions]
    * @returns {Promise<PendingTask[]>}
    */
   abstract getPendingTasks: OfflineDBApi['getPendingTasks'];
 
   /**
-   * @abstract
    * Fetches the app settings stored in the DB. Is mainly meant to be used
    * only while offline and opening the application, as we only update the
    * app settings whenever they are fetched again so it has the potential to
    * be stale.
+   *
    * @param {DBGetAppSettingsType} options
-   * @returns {Promise<AppSettingsAPIResponse | null>}
+   * @returns {Promise<GetApplicationResponse | null>}
    */
   abstract getAppSettings: OfflineDBApi['getAppSettings'];
 
   /**
-   * @abstract
    * Fetches reactions from the DB for a given filter & sort hash and
    * for a given message ID.
+   *
    * @param {DBGetReactionsType} options
    * @returns {Promise<ReactionResponse[] | null>}
    */
   abstract getReactions: OfflineDBApi['getReactions'];
 
   /**
-   * @abstract
    * Executes multiple queries in a batched fashion. It will also be done
    * within a transaction.
+   *
    * @param {ExecuteBatchDBQueriesType} queries
    * @returns {Promise<unknown>}
    */
   abstract executeSqlBatch: OfflineDBApi['executeSqlBatch'];
 
   /**
-   * @abstract
    * Adds a pending task to the pending tasks table. Can only be one of the
    * supported types of pending tasks, otherwise its execution will throw.
    * Will return the prepared queries for delayed execution (even if they are
    * already executed).
+   *
    * @param {PendingTask} task
    * @returns {Promise<() => Promise<void>>}
    */
   abstract addPendingTask: OfflineDBApi['addPendingTask'];
 
   /**
-   * @abstract
    * Updates a pending task in the DB, given its ID.
    * Will return the prepared queries for delayed execution (even if they are
    * already executed).
+   *
    * @param {DBUpdatePendingTaskType} options
    * @returns {Promise<ExecuteBatchDBQueriesType>}
    */
   abstract updatePendingTask: OfflineDBApi['updatePendingTask'];
 
   /**
-   * @abstract
    * Deletes a pending task from the DB, given its ID.
    * Will return the prepared queries for delayed execution (even if they are
    * already executed).
+   *
    * @param {DBDeletePendingTaskType} options
    * @returns {Promise<ExecuteBatchDBQueriesType>}
    */
   abstract deletePendingTask: OfflineDBApi['deletePendingTask'];
 
   /**
-   * @abstract
    * Deletes a reaction from the DB.
    * Will write to the reactions table removing the reaction.
    * Will return the prepared queries for delayed execution (even if they are
    * already executed).
+   *
    * @param {DBDeleteReactionType} options
    * @returns {Promise<ExecuteBatchDBQueriesType>}
    */
   abstract deleteReaction: OfflineDBApi['deleteReaction'];
 
   /**
-   * @abstract
    * Deletes a member from the DB.
    * Will only write to the members table.
    * Will return the prepared queries for delayed execution (even if they are
    * already executed).
+   *
    * @param {DBDeleteMemberType} options
    * @returns {Promise<ExecuteBatchDBQueriesType>}
    */
   abstract deleteMember: OfflineDBApi['deleteMember'];
 
   /**
-   * @abstract
    * Deletes a channel from the DB.
    * It will also delete all other entities associated with the channel in
    * a cascading fashion (messages, reactions, members etc.).
    * Will return the prepared queries for delayed execution (even if they are
    * already executed).
+   *
    * @param {DBDeleteChannelType} options
    * @returns {Promise<ExecuteBatchDBQueriesType>}
    */
   abstract deleteChannel: OfflineDBApi['deleteChannel'];
 
   /**
-   * @abstract
    * Deletes multiple messages for a given channel. Works as `channel.truncated` would.
    * Should remove entities primarily from the messages table and then from all associated
    * tables in a cascading fashion (reactions, polls etc.).
    * Will return the prepared queries for delayed execution (even if they are
    * already executed).
+   *
    * @param {DBDeleteMessagesForChannelType} options
    * @returns {Promise<ExecuteBatchDBQueriesType>}
    */
   abstract deleteMessagesForChannel: OfflineDBApi['deleteMessagesForChannel'];
 
   /**
-   * @abstract
    * Deletes all pending tasks from the DB.
    * Will only update the pending tasks table.
    * Will return the prepared queries for delayed execution (even if they are
    * already executed).
+   *
    * @param {DBDropPendingTasksType} options
    * @returns {Promise<ExecuteBatchDBQueriesType>}
    */
   abstract dropPendingTasks: OfflineDBApi['dropPendingTasks'];
 
   /**
-   * @abstract
    * Deletes a message from the DB.
    * All other entities associated with the message will also be deleted
    * in a cascading fashion (reactions, polls etc.).
    * Will return the prepared queries for delayed execution (even if they are
    * already executed).
+   *
    * @param {DBDeleteMessageType} options
    * @returns {Promise<ExecuteBatchDBQueriesType>}
    */
   abstract hardDeleteMessage: OfflineDBApi['hardDeleteMessage'];
 
   /**
-   * @abstract
    * Updates a message with a deleted_at value in the DB.
    * Will only update the messages table, as the message is simply marked
    * as deleted and not removed from the DB.
    * Will return the prepared queries for delayed execution (even if they are
    * already executed).
+   *
    * @param {DBDeleteMessageType} options
    * @returns {Promise<ExecuteBatchDBQueriesType>}
    */
   abstract softDeleteMessage: OfflineDBApi['softDeleteMessage'];
 
   /**
-   * @abstract
    * Drops all tables and reinitializes the connection to the DB.
+   *
    * @returns {Promise<unknown>}
    */
   abstract resetDB: OfflineDBApi['resetDB'];
 
   /**
-   * @abstract
    * A utility query that checks whether a specific channel exists in the DB.
    * Technically the same as actually fetching that channel through other queries,
    * but much faster.
+   *
    * @param {DBChannelExistsType} options
    * @returns {Promise<boolean>}
    */
   abstract channelExists: OfflineDBApi['channelExists'];
 
   /**
-   * @abstract
    * Initializes the DB (typically creating a simple file handle as a connection pointer for
    * SQLite and likely similar for other DBs).
+   *
    * @returns {Promise<boolean>}
    */
   abstract initializeDB: OfflineDBApi['initializeDB'];
@@ -452,6 +462,7 @@ export abstract class AbstractOfflineDB implements OfflineDBApi {
   /**
    * Initializes the DB as well as its syncManager for a given userId.
    * It will update the DBs reactive state with initialization values.
+   *
    * @param userId - the user ID for which we want to initialize
    */
   public init = async (userId: string) => {
@@ -469,13 +480,16 @@ export abstract class AbstractOfflineDB implements OfflineDBApi {
       }
     } catch (error) {
       this.state.partialNext({ initialized: false, userId: undefined });
-      console.log('Error Initializing DB:', error);
+      logger
+        .withExtraTags('init')
+        .error('Failed to initialize the offline database.', { error });
     }
   };
 
   /**
    * Checks whether the DB should be initialized or if it has been initialized already.
-   * @param {string} userId - the user ID for which we want to check initialization
+   *
+   * @param userId - the user ID for which we want to check initialization
    */
   public shouldInitialize(userId: string): boolean {
     const { userId: userIdFromState, initialized } = this.state.getLatestValue();
@@ -487,6 +501,7 @@ export abstract class AbstractOfflineDB implements OfflineDBApi {
    * passed uses a reference to the DB itself and will handle errors gracefully
    * and silently. Only really meant to be used for write queries that need to
    * be run in synchronous functions.
+   *
    * @param queryCallback - a callback wrapping all query logic that is to be executed
    * @param method - a utility parameter used for proper logging (will make sure the method
    * is logged on failure)
@@ -515,21 +530,29 @@ export abstract class AbstractOfflineDB implements OfflineDBApi {
    * If both fail, it will not execute the query as it would result in a foreign key constraint
    * error.
    *
-   * @param event - the WS event we are trying to process
-   * @param execute - whether to immediately execute the operation.
-   * @param forceUpdate - whether to upsert the channel data anyway
-   * @param createQueries - a callback function to creation of the queries that we want to execute
+   * @param event - The WS event we are trying to process.
+   * @param event.execute - Whether to immediately execute the operation (optional, defaults to `true`).
+   * @param event.forceUpdate - Whether to upsert the channel data anyway (optional, defaults to `false`).
+   * @param createQueries - A callback that creates the queries to execute.
+   * @returns The list of prepared queries (executed when `execute` is `true`).
    */
   public queriesWithChannelGuard = async (
     {
       event,
       execute = true,
       forceUpdate = false,
-    }: { event: Event; execute?: boolean; forceUpdate?: boolean },
+    }: {
+      event: Extract<
+        Event,
+        { channel?: any; cid?: any; channel_type?: any; channel_id?: any }
+      >;
+      execute?: boolean;
+      forceUpdate?: boolean;
+    },
     createQueries: (executeOverride?: boolean) => Promise<PrepareBatchDBQueries[]>,
   ) => {
-    const channelFromEvent = event.channel;
-    const cid = event.cid || channelFromEvent?.cid;
+    const channelFromEvent = (event as Extract<WSEvent, { channel?: any }>).channel;
+    const cid = (event as Extract<WSEvent, { cid?: any }>).cid || channelFromEvent?.cid;
     const type = event.type;
 
     if (!cid) {
@@ -542,11 +565,13 @@ export abstract class AbstractOfflineDB implements OfflineDBApi {
     // This can happen for example when a message.new event is received for a channel that is not in the db due to a channel being hidden.
     const shouldUpsertChannelData = forceUpdate || !(await this.channelExists({ cid }));
     if (shouldUpsertChannelData) {
+      const event_ = event as Extract<WSEvent, { channel_type?: any }>;
+
       let channelData = channelFromEvent;
-      if (!channelData && event.channel_type && event.channel_id) {
+      if (!channelData && event_.channel_type && event_.channel_id) {
         const channelFromState = this.client.channel(
-          event.channel_type,
-          event.channel_id,
+          event_.channel_type,
+          event_.channel_id,
         );
         if (channelFromState.initialized && !channelFromState.disconnected) {
           channelData = channelFromState.data as unknown as ChannelResponse;
@@ -565,17 +590,21 @@ export abstract class AbstractOfflineDB implements OfflineDBApi {
           }
           return newQueries;
         } else {
-          console.warn(
-            `Couldn't create channel queries on ${type} event for an initialized channel that is not in DB, skipping event`,
-            { event },
-          );
+          logger
+            .withExtraTags('queriesWithChannelGuard')
+            .warn(
+              `Could not create channel queries on a "${type}" event for an initialized channel that is not in the database. Skipping the event.`,
+              { event },
+            );
           return [];
         }
       } else {
-        console.warn(
-          `Received ${type} event for a non initialized channel that is not in DB, skipping event`,
-          { event },
-        );
+        logger
+          .withExtraTags('queriesWithChannelGuard')
+          .warn(
+            `Received a "${type}" event for a non-initialized channel that is not in the database. Skipping the event.`,
+            { event },
+          );
         return [];
       }
     }
@@ -587,14 +616,15 @@ export abstract class AbstractOfflineDB implements OfflineDBApi {
    * and it is going to make sure that both messages and reads are upserted. It will not
    * try to fetch the reads from the DB first and it will rely on channel.state to handle
    * the number of unreads.
-   * @param event - the WS event we are trying to process
-   * @param execute - whether to immediately execute the operation.
+   *
+   * @param payload.event - the WS event we are trying to process
+   * @param payload.execute - Whether to immediately execute the operation (optional, defaults to `true`).
    */
   public handleNewMessage = async ({
     event,
     execute = true,
   }: {
-    event: Event;
+    event: EventPayload<'message.new'>;
     execute?: boolean;
   }) => {
     const client = this.client;
@@ -628,10 +658,13 @@ export abstract class AbstractOfflineDB implements OfflineDBApi {
               execute: false,
               reads: [
                 {
-                  last_read: (ownReads?.last_read ?? new Date(0)).toISOString() as string,
+                  last_read: ownReads?.last_read ?? new Date(0),
                   last_read_message_id: ownReads?.last_read_message_id,
                   unread_messages: unreadCount,
-                  user: client.user,
+                  user: client.user as RequireLiteral<
+                    OwnUserResponse,
+                    'blocked_user_ids'
+                  >, // TODO: drop RequireLiteral once the oapi spec is adjusted
                 },
               ],
             });
@@ -652,14 +685,15 @@ export abstract class AbstractOfflineDB implements OfflineDBApi {
   /**
    * A handler for message deletion. It provides a channel guard and determines whether
    * it should hard delete or soft delete the message.
-   * @param event - the WS event we are trying to process
-   * @param execute - whether to immediately execute the operation.
+   *
+   * @param payload.event - the WS event we are trying to process
+   * @param payload.execute - Whether to immediately execute the operation (optional, defaults to `true`).
    */
   public handleDeleteMessage = async ({
     event,
     execute = true,
   }: {
-    event: Event;
+    event: EventPayload<'message.deleted'>;
     execute?: boolean;
   }) => {
     const { message, deleted_for_me, hard_delete = false } = event;
@@ -684,8 +718,9 @@ export abstract class AbstractOfflineDB implements OfflineDBApi {
    * A utility method used for removing a message that has already failed from the
    * state as well as the DB. We want to drop all pending tasks and finally hard
    * delete the message from the DB.
-   * @param messageId - the message id of the message we want to remove
-   * @param execute - whether to immediately execute the operation.
+   *
+   * @param payload.messageId - The ID of the message we want to remove.
+   * @param payload.execute - Whether to immediately execute the operation (optional, defaults to `true`).
    */
   public handleRemoveMessage = async ({
     messageId,
@@ -717,22 +752,29 @@ export abstract class AbstractOfflineDB implements OfflineDBApi {
    * The unreadMessages argument is useful for cases where we know the exact number of unreads
    * (for example reading an entire channel), but `unread_messages` might not necessarily exist
    * in the event (or it exists with a stale value if we know what we want to ultimately update to).
-   * @param event - the WS event we are trying to process
-   * @param unreadMessages - an override of unread_messages that will be preferred when upserting reads
-   * @param execute - whether to immediately execute the operation.
+   *
+   * @param payload.event - The WS event we are trying to process.
+   * @param payload.unreadMessages - An override of `unread_messages` that will be preferred when upserting reads.
+   * @param payload.execute - Whether to immediately execute the operation (optional, defaults to `true`).
    */
   public handleRead = async ({
     event,
     unreadMessages,
     execute = true,
   }: {
-    event: Event;
+    event: EventPayload<
+      | 'message.read'
+      | 'message.read_locally'
+      | 'notification.mark_read'
+      | 'notification.mark_unread'
+    >;
     unreadMessages?: number;
     execute?: boolean;
   }) => {
     const {
-      received_at: last_read,
+      received_at: last_read = new Date(),
       last_read_message_id,
+      // @ts-expect-error property missing
       unread_messages = 0,
       user,
       cid,
@@ -747,7 +789,7 @@ export abstract class AbstractOfflineDB implements OfflineDBApi {
           execute: executeOverride,
           reads: [
             {
-              last_read: last_read as string,
+              last_read,
               last_read_message_id,
               unread_messages: overriddenUnreadMessages,
               user,
@@ -764,14 +806,15 @@ export abstract class AbstractOfflineDB implements OfflineDBApi {
    * A utility method used to handle member events. It guards the processing
    * of each event with a channel guard and also forces an update of member_count
    * for the respective channel if applicable.
-   * @param event - the WS event we are trying to process
-   * @param execute - whether to immediately execute the operation.
+   *
+   * @param payload.event - the WS event we are trying to process
+   * @param payload.execute - Whether to immediately execute the operation (optional, defaults to `true`).
    */
   public handleMemberEvent = async ({
     event,
     execute = true,
   }: {
-    event: Event;
+    event: EventPayload<`member.${string}`>;
     execute?: boolean;
   }) => {
     const { member, cid, type } = event;
@@ -802,14 +845,15 @@ export abstract class AbstractOfflineDB implements OfflineDBApi {
   /**
    * A utility method used to handle message.updated events. It guards each
    * event handler within a channel guard.
-   * @param event - the WS event we are trying to process
-   * @param execute - whether to immediately execute the operation.
+   *
+   * @param payload.event - the WS event we are trying to process
+   * @param payload.execute - Whether to immediately execute the operation (optional, defaults to `true`).
    */
   public handleMessageUpdatedEvent = async ({
     event,
     execute = true,
   }: {
-    event: Event;
+    event: EventPayload<'message.updated' | 'message.undeleted'>;
     execute?: boolean;
   }) => {
     const { message } = event;
@@ -831,14 +875,15 @@ export abstract class AbstractOfflineDB implements OfflineDBApi {
    * simple upsertion is not enough.
    * It will update the hidden property of a channel to true if handling the `channel.hidden`
    * event and to false if handling `channel.visible`.
-   * @param event - the WS event we are trying to process
-   * @param execute - whether to immediately execute the operation.
+   *
+   * @param payload. - the WS event we are trying to process
+   * @param payload.execute - Whether to immediately execute the operation (optional, defaults to `true`).
    */
   public handleChannelVisibilityEvent = async ({
     event,
     execute = true,
   }: {
-    event: Event;
+    event: EventPayload<'channel.visible' | 'channel.hidden'>;
     execute?: boolean;
   }) => {
     const { type, channel } = event;
@@ -858,14 +903,15 @@ export abstract class AbstractOfflineDB implements OfflineDBApi {
    * A utility handler used to handle channel.truncated events. It handles both
    * removing all messages and relying on truncated_at as well. It will also upsert
    * reads adequately (and calculate the correct unread messages when truncating).
-   * @param event - the WS event we are trying to process
-   * @param execute - whether to immediately execute the operation.
+   *
+   * @param payload.event - the WS event we are trying to process
+   * @param payload.execute - Whether to immediately execute the operation (optional, defaults to `true`).
    */
   public handleChannelTruncatedEvent = async ({
     event,
     execute = true,
   }: {
-    event: Event;
+    event: EventPayload<'channel.truncated'>;
     execute?: boolean;
   }) => {
     const { channel } = event;
@@ -900,10 +946,10 @@ export abstract class AbstractOfflineDB implements OfflineDBApi {
           execute: false,
           reads: [
             {
-              last_read: (ownReads?.last_read ?? new Date(0)).toString() as string,
+              last_read: ownReads?.last_read ?? new Date(0),
               last_read_message_id: ownReads?.last_read_message_id,
               unread_messages: unreadCount,
-              user: ownUser,
+              user: ownUser as RequireLiteral<OwnUserResponse, 'blocked_user_ids'>, // TODO: drop RequireLiteral once the oapi spec is adjusted
             },
           ],
         });
@@ -926,14 +972,15 @@ export abstract class AbstractOfflineDB implements OfflineDBApi {
    * - reaction.new -> insertReaction
    * - reaction.updated -> updateReaction
    * - reaction.deleted -> deleteReaction
-   * @param event - the WS event we are trying to process
-   * @param execute - whether to immediately execute the operation.
+   *
+   * @param payload.event - the WS event we are trying to process
+   * @param payload.execute - Whether to immediately execute the operation (optional, defaults to `true`).
    */
   public handleReactionEvent = async ({
     event,
     execute = true,
   }: {
-    event: Event;
+    event: EventPayload<`reaction.${string}`>;
     execute?: boolean;
   }) => {
     const { type, message, reaction } = event;
@@ -942,7 +989,7 @@ export abstract class AbstractOfflineDB implements OfflineDBApi {
       return [];
     }
 
-    const getReactionMethod = (type: Event['type']) => {
+    const getReactionMethod = (type: EventType) => {
       switch (type) {
         case 'reaction.new':
           return this.insertReaction;
@@ -968,14 +1015,15 @@ export abstract class AbstractOfflineDB implements OfflineDBApi {
    * A utility handler for all draft events:
    * - draft.updated -> updateDraft
    * - draft.deleted -> deleteDraft
-   * @param event - the WS event we are trying to process
-   * @param execute - whether to immediately execute the operation.
+   *
+   * @param payload.event - the WS event we are trying to process
+   * @param payload.execute - Whether to immediately execute the operation (optional, defaults to `true`).
    */
   handleDraftEvent = async ({
     event,
     execute = true,
   }: {
-    event: Event;
+    event: EventPayload<`draft.${string}`>;
     execute?: boolean;
   }) => {
     const { cid, draft, type } = event;
@@ -1006,8 +1054,9 @@ export abstract class AbstractOfflineDB implements OfflineDBApi {
    * A generic event handler that decides which DB API to invoke based on
    * event.type for all events we are currently handling. It is used to both
    * react on WS events as well as process the sync API events.
-   * @param event - the WS event we are trying to process
-   * @param execute - whether to immediately execute the operation.
+   *
+   * @param payload.event - the WS event we are trying to process
+   * @param payload.execute - Whether to immediately execute the operation (optional, defaults to `true`).
    */
   public handleEvent = async ({
     event,
@@ -1016,10 +1065,13 @@ export abstract class AbstractOfflineDB implements OfflineDBApi {
     event: Event;
     execute?: boolean;
   }) => {
-    const { type, channel } = event;
+    const { type } = event;
 
     if (type.startsWith('reaction')) {
-      return await this.handleReactionEvent({ event, execute });
+      return await this.handleReactionEvent({
+        event: event as EventPayload<`reaction.${string}`>,
+        execute,
+      });
     }
 
     if (type === 'message.new') {
@@ -1055,7 +1107,10 @@ export abstract class AbstractOfflineDB implements OfflineDBApi {
     }
 
     if (type.startsWith('member.')) {
-      return await this.handleMemberEvent({ event, execute });
+      return await this.handleMemberEvent({
+        event: event as EventPayload<`member.${string}`>,
+        execute,
+      });
     }
 
     if (type === 'channel.hidden' || type === 'channel.visible') {
@@ -1077,18 +1132,18 @@ export abstract class AbstractOfflineDB implements OfflineDBApi {
       (type === 'channel.updated' ||
         type === 'notification.message_new' ||
         type === 'notification.added_to_channel') &&
-      channel
+      event.channel
     ) {
-      return await this.upsertChannelData({ channel, execute });
+      return await this.upsertChannelData({ channel: event.channel, execute });
     }
 
     if (
       (type === 'channel.deleted' ||
         type === 'notification.channel_deleted' ||
         type === 'notification.removed_from_channel') &&
-      channel
+      event.channel
     ) {
-      return await this.deleteChannel({ cid: channel.cid, execute });
+      return await this.deleteChannel({ cid: event.channel.cid, execute });
     }
 
     if (type === 'channel.truncated') {
@@ -1107,6 +1162,7 @@ export abstract class AbstractOfflineDB implements OfflineDBApi {
    * 3. If it is, it will insert the task in the pending tasks table
    *
    * It will return the response from the execution if it succeeded.
+   *
    * @param task - the pending task we want to execute
    */
   public queueTask = async <T>({ task }: { task: PendingTask }): Promise<T> => {
@@ -1122,7 +1178,7 @@ export abstract class AbstractOfflineDB implements OfflineDBApi {
     try {
       return await attemptTaskExecution();
     } catch (e) {
-      if (!this.shouldSkipQueueingTask(e as AxiosError<APIErrorResponse>)) {
+      if (!this.shouldSkipQueueingTask(e as AxiosError<APIError>)) {
         await this.handleAddPendingTask({ task });
       }
       throw e;
@@ -1130,27 +1186,28 @@ export abstract class AbstractOfflineDB implements OfflineDBApi {
   };
 
   /**
-   * A utility method that determines if a failed task should be added to the
-   * queue based on its error.
-   * Error code 4 - bad request data
-   * Error code 17 - missing own_capabilities to execute the task
-   * @param error
+   * A utility method that determines if a failed task should be skipped (NOT added to the queue) -
+   * i.e. the failure is a definitive rejection rather than an ephemeral/retryable one. A task is
+   * kept in the queue only when its error is {@link isEphemeral} (connection/network error or a
+   * retryable server code). A non retryable server response (i.e bad request, not allowed etc) is
+   * skipped since retrying it would never succeed.
+   *
+   * @param error - The error thrown while executing the failed task.
    */
-  private shouldSkipQueueingTask = (error: AxiosError<APIErrorResponse>) =>
-    error?.response?.data?.code === 4 || error?.response?.data?.code === 17;
+  private shouldSkipQueueingTask = (error: AxiosError<APIError>) => !isEphemeral(error);
 
   private mergeFailedMessageUpdateIntoPendingSendMessage = ({
     editedMessage,
     pendingMessage,
   }: {
     editedMessage: LocalMessage | Partial<MessageResponse>;
-    pendingMessage: Message;
+    pendingMessage: MessageRequest;
   }) => {
     const normalizedEditedMessageSource = {
       ...editedMessage,
     } as LocalMessage & { message_text_updated_at?: string };
 
-    if (editedMessage.status === 'failed') {
+    if ((editedMessage as LocalMessage).status === 'failed') {
       delete normalizedEditedMessageSource.message_text_updated_at;
     }
 
@@ -1165,7 +1222,7 @@ export abstract class AbstractOfflineDB implements OfflineDBApi {
       ...(typeof pendingMessageStatus !== 'undefined'
         ? { status: pendingMessageStatus }
         : {}),
-    } as Message;
+    } as MessageRequest;
   };
 
   private isPendingSendMessageTask = (
@@ -1176,12 +1233,12 @@ export abstract class AbstractOfflineDB implements OfflineDBApi {
   private handleOfflineFailedUpdateMessagePendingTask = async (
     task: Extract<PendingTask, { type: 'update-message' }>,
   ) => {
-    const [message] = task.payload;
-    if (!message.id) {
+    const [{ id, message }] = task.payload;
+    if (!id) {
       return;
     }
 
-    const pendingTasks = await this.getPendingTasks({ messageId: message.id });
+    const pendingTasks = await this.getPendingTasks({ messageId: id });
     const pendingSendMessageTask = pendingTasks.find(this.isPendingSendMessageTask);
 
     if (!pendingSendMessageTask) {
@@ -1190,14 +1247,20 @@ export abstract class AbstractOfflineDB implements OfflineDBApi {
 
     const updatedPendingSendMessage = this.mergeFailedMessageUpdateIntoPendingSendMessage(
       {
-        editedMessage: message,
-        pendingMessage: pendingSendMessageTask.payload[0],
+        // TODO: this is not good, we have too many message types, should probably only have two (request, response)
+        editedMessage: message as unknown as LocalMessage,
+        pendingMessage: pendingSendMessageTask.payload[0].message as MessageRequest,
       },
     );
 
     const updatedPendingTask: Extract<PendingTask, { type: 'send-message' }> = {
       ...pendingSendMessageTask,
-      payload: [updatedPendingSendMessage, pendingSendMessageTask.payload[1]],
+      payload: [
+        {
+          ...pendingSendMessageTask.payload[0],
+          message: updatedPendingSendMessage,
+        },
+      ],
     };
 
     if (pendingSendMessageTask.id) {
@@ -1219,14 +1282,17 @@ export abstract class AbstractOfflineDB implements OfflineDBApi {
    * or rewrites an existing pending `send-message` task for offline edits of failed messages.
    */
   public handleAddPendingTask = async ({ task }: { task: PendingTask }) => {
-    if (task.type === 'update-message' && !isMessageUpdateReplayable(task.payload[0])) {
+    if (
+      task.type === 'update-message' &&
+      !isMessageUpdateReplayable(task.payload[0].message ?? {})
+    ) {
       return;
     }
 
     if (
       task.type === 'update-message' &&
       !this.client.wsConnection?.isHealthy &&
-      task.payload[0].status === 'failed'
+      (task.payload[0].message as { status?: string } | undefined)?.status === 'failed'
     ) {
       await this.handleOfflineFailedUpdateMessagePendingTask(task);
       return;
@@ -1246,6 +1312,7 @@ export abstract class AbstractOfflineDB implements OfflineDBApi {
    * - Creating a draft
    * - Deleting a draft
    * It will throw if we try to execute a pending task that is not supported.
+   *
    * @param task - The task we want to execute
    * @param isPendingTask - a control value telling us if it's an actual pending task being executed
    * or delayed execution
@@ -1293,7 +1360,7 @@ export abstract class AbstractOfflineDB implements OfflineDBApi {
               timestampChanged: true,
             });
           }
-          channel.state.addMessageSorted(newMessage, true);
+          channel.messagePaginator.trackLastMessage(formatMessage(newMessage));
         }
         return newMessageResponse;
       }
@@ -1325,7 +1392,7 @@ export abstract class AbstractOfflineDB implements OfflineDBApi {
           true,
         );
       } catch (e) {
-        const error = e as AxiosError<APIErrorResponse>;
+        const error = e as AxiosError<APIError>;
         if (!this.shouldSkipQueueingTask(error)) {
           // executing the pending task has failed, so keep it in the queue
           continue;