Mark messages as unread using timestamp (#3885)

Author: laevandus

CHANGELOG.md

@@ -9,6 +9,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - Add `ChatClient.deleteAttachment(remoteUrl:)` [#3883](https://github.com/GetStream/stream-chat-swift/pull/3883)
 - Add `CDNClient.deleteAttachment(remoteUrl:)` [#3883](https://github.com/GetStream/stream-chat-swift/pull/3883)
 - Add `heic`, `heif` and `svg` formats to the supported image file types [#3883](https://github.com/GetStream/stream-chat-swift/pull/3883)
+- Add `ChatChannelController.markUnread(from:completion:)` and `Chat.markUnread(from:)` where the from argument is `Date` [#3885](https://github.com/GetStream/stream-chat-swift/pull/3885)
 - Add support for filter tags in channels [#3886](https://github.com/GetStream/stream-chat-swift/pull/3886)
   - Add `ChatChannel.filterTags`
   - Add `filterTags` channel list filtering key

DemoApp/StreamChat/Components/DemoChatChannelListRouter.swift

@@ -463,6 +463,24 @@ final class DemoChatChannelListRouter: ChatChannelListRouter {
                     }
                 }
             }),
+            .init(title: "Mark channel unread with timestamp", isEnabled: true, handler: { [unowned self] _ in
+                self.rootViewController.presentAlert(title: "Mark messages as unread with timestamp", message: "Marks messages as unread from the last number of days", textFieldPlaceholder: "Days") { offsetInDaysString in
+                    let calendar = Calendar.current
+                    guard let offsetInDays = Int(offsetInDaysString ?? ""),
+                          let date = calendar.date(byAdding: .day, value: -abs(offsetInDays), to: calendar.startOfDay(for: Date())) else {
+                        self.rootViewController.presentAlert(title: "Timestamp offset is not valid")
+                        return
+                    }
+                    channelController.markUnread(from: date) { result in
+                        switch result {
+                        case .failure(let error):
+                            self.rootViewController.presentAlert(title: "Couldn't mark messages as unread \(cid)", message: "\(error)")
+                        case .success:
+                            break
+                        }
+                    }
+                }
+            }),
             .init(title: "Cool channel", isEnabled: canMuteChannel, handler: { [unowned self] _ in
                 channelController.partialChannelUpdate(extraData: ["is_cool": true]) { error in
                     if let error = error {

Sources/StreamChat/APIClient/Endpoints/ChannelEndpoints.swift

@@ -269,16 +269,13 @@ extension Endpoint {
         )
     }
 
-    static func markUnread(cid: ChannelId, messageId: MessageId, userId: UserId) -> Endpoint<EmptyResponse> {
+    static func markUnread(cid: ChannelId, payload: MarkUnreadPayload) -> Endpoint<EmptyResponse> {
         .init(
             path: .markChannelUnread(cid.apiPath),
             method: .post,
             queryItems: nil,
             requiresConnectionId: false,
-            body: [
-                "message_id": messageId,
-                "user_id": userId
-            ]
+            body: payload
         )
     }
 

Sources/StreamChat/APIClient/Endpoints/Payloads/MarkUnreadPayload.swift

@@ -0,0 +1,34 @@
+//
+// Copyright © 2025 Stream.io Inc. All rights reserved.
+//
+
+import Foundation
+
+enum MarkUnreadCriteria: Sendable, Equatable {
+    /// The ID of the message from where the channel is marked unread
+    case messageId(String)
+    /// The timestamp of the message from where the channel is marked unread
+    case messageTimestamp(Date)
+}
+
+struct MarkUnreadPayload: Encodable, Sendable {
+    let criteria: MarkUnreadCriteria
+    let userId: String
+    
+    func encode(to encoder: any Encoder) throws {
+        var container = encoder.container(keyedBy: CodingKeys.self)
+        try container.encode(userId, forKey: .userId)
+        switch criteria {
+        case .messageId(let messageId):
+            try container.encode(messageId, forKey: .messageId)
+        case .messageTimestamp(let messageTimestamp):
+            try container.encode(messageTimestamp, forKey: .messageTimestamp)
+        }
+    }
+    
+    private enum CodingKeys: String, CodingKey {
+        case messageId = "message_id"
+        case messageTimestamp = "message_timestamp"
+        case userId = "user_id"
+    }
+}

Sources/StreamChat/Controllers/ChannelController/ChannelController.swift

@@ -1333,7 +1333,47 @@ public class ChatChannelController: DataController, DelegateCallable, DataStoreP
         }
 
         readStateHandler.markUnread(
-            from: messageId,
+            from: .messageId(messageId),
+            in: channel
+        ) { [weak self] result in
+            self?.callback {
+                completion?(result)
+            }
+        }
+    }
+    
+    /// Marks all messages of the channel as unread that were created after the specified timestamp.
+    ///
+    /// This method finds the first message with a creation timestamp greater than to the provided timestamp,
+    /// and marks all messages from that point forward as unread. If no message is found after the timestamp,
+    /// the operation completes without error but no messages are marked as unread.
+    ///
+    /// - Parameters:
+    ///   - timestamp: The timestamp used to find the first message to mark as unread. All messages created after this timestamp will be marked as unread.
+    ///   - completion: The completion handler to be called after marking messages as unread. Called with a `Result` containing the updated `ChatChannel` on success, or an `Error` on failure.
+    public func markUnread(from timestamp: Date, completion: ((Result<ChatChannel, Error>) -> Void)? = nil) {
+        /// Perform action only if channel is already created on backend side and have a valid `cid`.
+        guard let channel = channel else {
+            let error = ClientError.ChannelNotCreatedYet()
+            log.error(error.localizedDescription)
+            callback {
+                completion?(.failure(error))
+            }
+            return
+        }
+
+        /// Read events are not enabled for this channel
+        guard channel.canReceiveReadEvents == true else {
+            let error = ClientError.ChannelFeatureDisabled("Channel feature: read events is disabled for this channel.")
+            log.error(error.localizedDescription)
+            callback {
+                completion?(.failure(error))
+            }
+            return
+        }
+
+        readStateHandler.markUnread(
+            from: .messageTimestamp(timestamp),
             in: channel
         ) { [weak self] result in
             self?.callback {

Sources/StreamChat/Database/DTOs/ChannelReadDTO.swift

@@ -138,23 +138,44 @@ extension NSManagedObjectContext {
     func markChannelAsUnread(
         for cid: ChannelId,
         userId: UserId,
-        from messageId: MessageId,
+        from unreadCriteria: MarkUnreadCriteria,
         lastReadMessageId: MessageId?,
         lastReadAt: Date?,
         unreadMessagesCount: Int?
     ) {
-        guard let read = loadChannelRead(cid: cid, userId: userId),
-              let message = self.message(id: messageId) else {
-            return
+        guard let read = loadChannelRead(cid: cid, userId: userId) else { return }
+        
+        let findMessageDTO: () -> MessageDTO? = {
+            switch unreadCriteria {
+            case .messageId(let messageId):
+                return self.message(id: messageId)
+            case .messageTimestamp(let messageTimestamp):
+                let clientConfig = self.chatClientConfig
+                return try? MessageDTO.loadMessage(
+                    beforeOrEqual: messageTimestamp,
+                    cid: cid.rawValue,
+                    deletedMessagesVisibility: clientConfig?.deletedMessagesVisibility ?? .alwaysVisible,
+                    shouldShowShadowedMessages: clientConfig?.shouldShowShadowedMessages ?? false,
+                    context: self
+                )
+            }
         }
+        guard let message = findMessageDTO() else { return }
 
         let lastReadAt = lastReadAt ?? message.createdAt.bridgeDate
         read.lastReadAt = lastReadAt.bridgeDate
         read.lastReadMessageId = lastReadMessageId
 
+        let excludesMessageId: Bool = {
+            switch unreadCriteria {
+            case .messageId: return false
+            case .messageTimestamp: return true
+            }
+        }()
         let messagesCount = unreadMessagesCount ?? MessageDTO.countOtherUserMessages(
             in: read.channel.cid,
             createdAtFrom: lastReadAt,
+            excludingMessageId: excludesMessageId ? message.id : nil,
             context: self
         )
         read.unreadMessageCount = Int32(messagesCount)

Sources/StreamChat/Database/DTOs/MessageDTO.swift

@@ -558,13 +558,17 @@ class MessageDTO: NSManagedObject {
     static func countOtherUserMessages(
         in cid: String,
         createdAtFrom: Date,
+        excludingMessageId: MessageId?,
         context: NSManagedObjectContext
     ) -> Int {
-        let subpredicates: [NSPredicate] = [
+        var subpredicates: [NSPredicate] = [
             sentMessagesPredicate(for: cid),
             .init(format: "createdAt >= %@", createdAtFrom.bridgeDate),
             .init(format: "user.currentUser == nil")
         ]
+        if let excludingMessageId {
+            subpredicates.append(.init(format: "id != %@", excludingMessageId))
+        }
 
         let request = NSFetchRequest<MessageDTO>(entityName: MessageDTO.entityName)
         request.sortDescriptors = [NSSortDescriptor(keyPath: \MessageDTO.defaultSortingKey, ascending: false)]
@@ -607,6 +611,23 @@ class MessageDTO: NSManagedObject {
         return try context.fetch(request).first
     }
 
+    static func loadMessage(
+        beforeOrEqual timestamp: Date,
+        cid: String,
+        deletedMessagesVisibility: ChatClientConfig.DeletedMessageVisibility,
+        shouldShowShadowedMessages: Bool,
+        context: NSManagedObjectContext
+    ) throws -> MessageDTO? {
+        let request = NSFetchRequest<MessageDTO>(entityName: entityName)
+        request.predicate = NSCompoundPredicate(andPredicateWithSubpredicates: [
+            .init(format: "createdAt <= %@", timestamp.bridgeDate),
+            channelMessagesPredicate(for: cid, deletedMessagesVisibility: deletedMessagesVisibility, shouldShowShadowedMessages: shouldShowShadowedMessages)
+        ])
+        request.sortDescriptors = [NSSortDescriptor(keyPath: \MessageDTO.createdAt, ascending: false)]
+        request.fetchLimit = 1
+        return try context.fetch(request).first
+    }
+    
     static func loadMessages(
         from fromIncludingDate: Date,
         to toIncludingDate: Date,

Sources/StreamChat/Database/DatabaseSession.swift

@@ -396,12 +396,12 @@ protocol ChannelReadDatabaseSession {
     /// Sets the channel `cid` as read for `userId`
     func markChannelAsRead(cid: ChannelId, userId: UserId, at: Date)
 
-    /// Sets the channel `cid` as unread for `userId` starting from the `messageId`
+    /// Sets the channel `cid` as unread for `userId` starting from the message id or timestamp.
     /// Uses `lastReadAt` and `unreadMessagesCount` if passed, otherwise it calculates it.
     func markChannelAsUnread(
         for cid: ChannelId,
         userId: UserId,
-        from messageId: MessageId,
+        from unreadCriteria: MarkUnreadCriteria,
         lastReadMessageId: MessageId?,
         lastReadAt: Date?,
         unreadMessagesCount: Int?

Sources/StreamChat/Repositories/ChannelRepository.swift

@@ -58,23 +58,23 @@ class ChannelRepository {
         }
     }
 
-    /// Marks a subset of the messages of the channel as unread. All the following messages, including the one that is
+    /// Marks a subset of the messages of the channel as unread. All the following messages including the one that is
     /// passed as parameter, will be marked as not read.
     /// - Parameters:
     ///   - cid: The id of the channel to be marked as unread
     ///   - userId: The id of the current user
-    ///   - messageId: The id of the first message that will be marked as unread.
+    ///   - unreadCriteria: The id or timestamp of the first message that will be marked as unread.
     ///   - lastReadMessageId: The id of the last message that was read.
     ///   - completion: Called when the API call is finished. Called with `Error` if the remote update fails.
     func markUnread(
         for cid: ChannelId,
         userId: UserId,
-        from messageId: MessageId,
+        from unreadCriteria: MarkUnreadCriteria,
         lastReadMessageId: MessageId?,
         completion: ((Result<ChatChannel, Error>) -> Void)? = nil
     ) {
         apiClient.request(
-            endpoint: .markUnread(cid: cid, messageId: messageId, userId: userId)
+            endpoint: .markUnread(cid: cid, payload: .init(criteria: unreadCriteria, userId: userId))
         ) { [weak self] result in
             if let error = result.error {
                 completion?(.failure(error))
@@ -86,7 +86,7 @@ class ChannelRepository {
                 session.markChannelAsUnread(
                     for: cid,
                     userId: userId,
-                    from: messageId,
+                    from: unreadCriteria,
                     lastReadMessageId: lastReadMessageId,
                     lastReadAt: nil,
                     unreadMessagesCount: nil

Sources/StreamChat/Repositories/MessageRepository.swift

@@ -339,7 +339,7 @@ class MessageRepository {
 
     /// Fetches a message id before the specified message when sorting by the creation date in the local database.
     func getMessage(
-        before messageId: MessageId,
+        before unreadCriteria: MarkUnreadCriteria,
         in cid: ChannelId,
         completion: @escaping (Result<MessageId?, Error>) -> Void
     ) {
@@ -349,14 +349,26 @@ class MessageRepository {
             let deletedMessagesVisibility = clientConfig?.deletedMessagesVisibility ?? .alwaysVisible
             let shouldShowShadowedMessages = clientConfig?.shouldShowShadowedMessages ?? false
             do {
-                let resultId = try MessageDTO.loadMessage(
-                    before: messageId,
-                    cid: cid.rawValue,
-                    deletedMessagesVisibility: deletedMessagesVisibility,
-                    shouldShowShadowedMessages: shouldShowShadowedMessages,
-                    context: context
-                )?.id
-                completion(.success(resultId))
+                switch unreadCriteria {
+                case .messageId(let messageId):
+                    let resultId = try MessageDTO.loadMessage(
+                        before: messageId,
+                        cid: cid.rawValue,
+                        deletedMessagesVisibility: deletedMessagesVisibility,
+                        shouldShowShadowedMessages: shouldShowShadowedMessages,
+                        context: context
+                    )?.id
+                    completion(.success(resultId))
+                case .messageTimestamp(let messageTimestamp):
+                    let resultId = try MessageDTO.loadMessage(
+                        beforeOrEqual: messageTimestamp,
+                        cid: cid.rawValue,
+                        deletedMessagesVisibility: deletedMessagesVisibility,
+                        shouldShowShadowedMessages: shouldShowShadowedMessages,
+                        context: context
+                    )?.id
+                    completion(.success(resultId))
+                }
             } catch {
                 completion(.failure(error))
             }