Add new method to fetch unread message counts for user's channels (#185)

* Add new API method returning paginated unread message counts
* PubNub kotlin 0.13.0 release

---------

Co-authored-by: PubNub Release Bot <120067856+pubnub-release-bot@users.noreply.github.com>

Author: jguz-pubnub

.pubnub.yml

@@ -1,5 +1,5 @@
 name: kmp-chat
-version: 0.12.1
+version: 0.13.0
 schema: 1
 scm: github.com/pubnub/kmp-chat
 sdks:
@@ -21,8 +21,8 @@ sdks:
             -
               distribution-type: library
               distribution-repository: maven
-              package-name: pubnub-chat-0.12.1
-              location: https://repo.maven.apache.org/maven2/com/pubnub/pubnub-chat/0.12.1/
+              package-name: pubnub-chat-0.13.0
+              location: https://repo.maven.apache.org/maven2/com/pubnub/pubnub-chat/0.13.0/
               supported-platforms:
                 supported-operating-systems:
                   Android:
@@ -77,6 +77,11 @@ sdks:
                   license-url: https://github.com/pubnub/kotlin/blob/master/LICENSE
                   is-required: Required
 changelog:
+  - date: 2025-05-09
+    version: 0.13.0
+    changes:
+      - type: feature
+        text: "Add new API method returning paginated unread message counts."
   - date: 2025-03-21
     version: 0.12.1
     changes:

Package.swift

@@ -18,7 +18,7 @@ let package = Package(
   targets: [
     .binaryTarget(
       name: "PubNubChatRemoteBinaryPackage",
-      url: "https://github.com/pubnub/kmp-chat/releases/download/kotlin-0.12.1/PubNubChat.xcframework.zip",
+      url: "https://github.com/pubnub/kmp-chat/releases/download/kotlin-0.13.0/PubNubChat.xcframework.zip",
       checksum: "3153a4429665fe51861cfdc3b63cdb873260e777dcb41d52f14301698b2b2a91"
     )
   ]

README.md

@@ -31,7 +31,7 @@ You will need the publish and subscribe keys to authenticate your app. Get your
       <dependency>
          <groupId>com.pubnub</groupId>
          <artifactId>pubnub-chat</artifactId>
-         <version>0.12.1</version>
+         <version>0.13.0</version>
       </dependency>
       ```
 

gradle.properties

@@ -10,7 +10,7 @@ SONATYPE_HOST=DEFAULT
 SONATYPE_AUTOMATIC_RELEASE=false
 GROUP=com.pubnub
 POM_PACKAGING=jar
-VERSION_NAME=0.12.1
+VERSION_NAME=0.13.0
 
 
 POM_NAME=PubNub Chat SDK

js-chat/tests/channel.test.ts

@@ -102,6 +102,34 @@ describe("Channel test", () => {
     expect(secondPage.messages.length).toBeGreaterThanOrEqual(1)
   })
 
+  test("should fetch unread messages counts with pagination", async () => {
+    const channel1 = await createRandomChannel()
+    const channel2 = await createRandomChannel()
+
+    await channel1.invite(chat.currentUser)
+    await channel2.invite(chat.currentUser)
+    await channel1.sendText("Some text")
+    await channel2.sendText("Some text")
+
+    const firstResults = await chat.fetchUnreadMessagesCounts({ limit: 1 })
+    expect(firstResults.countsByChannel.length).toEqual(1)
+    expect(firstResults.countsByChannel.at(0).count).toEqual(1)
+    expect(firstResults.countsByChannel.at(0).channel.id in arrayOf(channel1.id, channel2.id)).toBeTruthy()
+
+    const secondResults = await chat.fetchUnreadMessagesCounts({ page: { next: firstResults.page.next } })
+    expect(secondResults.countsByChannel.length).toEqual(1)
+    expect(secondResults.countsByChannel.at(0).count).toEqual(1)
+    expect(secondResults.countsByChannel.at(0).channel.id in arrayOf(channel1.id, channel2.id)).toBeTruthy()
+
+    const thirdResults = await chat.fetchUnreadMessagesCounts({ page: { next: secondResults.page.next } })
+    expect(thirdResults.countsByChannel.length).toEqual(0)
+
+    await channel1.leave()
+    await channel2.leave()
+    await channel1.delete()
+    await channel2.delete()
+  })
+
   test("should fail when trying to send a message to a non-existent channel", async () => {
     const nonExistentChannel = (await chat.getChannel("non-existing-channel")) as Channel
 

pubnub-chat-api/api/pubnub-chat-api.api

@@ -77,6 +77,8 @@ public abstract interface class com/pubnub/chat/Chat {
 	public abstract fun destroy ()V
 	public abstract fun emitEvent (Ljava/lang/String;Lcom/pubnub/chat/types/EventContent;Ljava/util/Map;)Lcom/pubnub/kmp/PNFuture;
 	public static synthetic fun emitEvent$default (Lcom/pubnub/chat/Chat;Ljava/lang/String;Lcom/pubnub/chat/types/EventContent;Ljava/util/Map;ILjava/lang/Object;)Lcom/pubnub/kmp/PNFuture;
+	public abstract fun fetchUnreadMessagesCounts (Ljava/lang/Integer;Lcom/pubnub/api/models/consumer/objects/PNPage;Ljava/lang/String;Ljava/util/Collection;)Lcom/pubnub/kmp/PNFuture;
+	public static synthetic fun fetchUnreadMessagesCounts$default (Lcom/pubnub/chat/Chat;Ljava/lang/Integer;Lcom/pubnub/api/models/consumer/objects/PNPage;Ljava/lang/String;Ljava/util/Collection;ILjava/lang/Object;)Lcom/pubnub/kmp/PNFuture;
 	public abstract fun getChannel (Ljava/lang/String;)Lcom/pubnub/kmp/PNFuture;
 	public abstract fun getChannels (Ljava/lang/String;Ljava/util/Collection;Ljava/lang/Integer;Lcom/pubnub/api/models/consumer/objects/PNPage;)Lcom/pubnub/kmp/PNFuture;
 	public static synthetic fun getChannels$default (Lcom/pubnub/chat/Chat;Ljava/lang/String;Ljava/util/Collection;Ljava/lang/Integer;Lcom/pubnub/api/models/consumer/objects/PNPage;ILjava/lang/Object;)Lcom/pubnub/kmp/PNFuture;
@@ -464,6 +466,13 @@ public final class com/pubnub/chat/message/MarkAllMessageAsReadResponse {
 	public final fun getTotal ()I
 }
 
+public final class com/pubnub/chat/message/UnreadMessagesCounts {
+	public fun <init> (Ljava/util/List;Lcom/pubnub/api/models/consumer/objects/PNPage$PNNext;Lcom/pubnub/api/models/consumer/objects/PNPage$PNPrev;)V
+	public final fun getCountsByChannel ()Ljava/util/List;
+	public final fun getNext ()Lcom/pubnub/api/models/consumer/objects/PNPage$PNNext;
+	public final fun getPrev ()Lcom/pubnub/api/models/consumer/objects/PNPage$PNPrev;
+}
+
 public abstract interface class com/pubnub/chat/mutelist/MutedUsersManager {
 	public abstract fun getMutedUsers ()Ljava/util/Set;
 	public abstract fun muteUser (Ljava/lang/String;)Lcom/pubnub/kmp/PNFuture;

pubnub-chat-api/src/commonMain/kotlin/com/pubnub/chat/Chat.kt

@@ -11,6 +11,7 @@ import com.pubnub.api.models.consumer.push.PNPushRemoveChannelResult
 import com.pubnub.chat.config.ChatConfiguration
 import com.pubnub.chat.message.GetUnreadMessagesCounts
 import com.pubnub.chat.message.MarkAllMessageAsReadResponse
+import com.pubnub.chat.message.UnreadMessagesCounts
 import com.pubnub.chat.mutelist.MutedUsersManager
 import com.pubnub.chat.restrictions.Restriction
 import com.pubnub.chat.types.ChannelType
@@ -423,13 +424,35 @@ interface Chat {
      *
      * @return [PNFuture] containing list of [GetUnreadMessagesCounts]
      */
+    @Deprecated(
+        message = "Use `fetchUnreadMessagesCounts()` instead",
+        level = DeprecationLevel.WARNING,
+    )
     fun getUnreadMessagesCounts(
         limit: Int? = null,
         page: PNPage? = null,
         filter: String? = null,
         sort: Collection<PNSortKey<PNMembershipKey>> = listOf(),
     ): PNFuture<List<GetUnreadMessagesCounts>>
 
+    /**
+     * Returns info on all messages you didn't read on all joined channels. You can display this number on UI in the
+     * channel list of your chat app.
+     *
+     * @param limit Number of objects to return in response. The default (and maximum) value is 100.
+     * @param page Object used for pagination to define which previous or next result page you want to fetch.
+     * @param filter Expression used to filter the results. Returns only these channels whose properties satisfy the given expression are returned.
+     * @param sort A collection to specify the sort order. Available options are id, name, and updated. Use asc or desc.
+     *
+     * @return [PNFuture] containing list of [UnreadMessagesCounts]
+     */
+    fun fetchUnreadMessagesCounts(
+        limit: Int? = null,
+        page: PNPage? = null,
+        filter: String? = null,
+        sort: Collection<PNSortKey<PNMembershipKey>> = listOf(),
+    ): PNFuture<UnreadMessagesCounts>
+
     /**
      * Allows you to mark as read all messages you didn't read on all joined channels.
      *

pubnub-chat-api/src/commonMain/kotlin/com/pubnub/chat/message/UnreadMessagesCounts.kt

@@ -0,0 +1,16 @@
+package com.pubnub.chat.message
+
+import com.pubnub.api.models.consumer.objects.PNPage
+
+/**
+ * Response wrapper for unread message counts that includes pagination information.
+ *
+ * @property countsByChannel List of unread messages for different channels.
+ * @property next The pagination token for fetching the next page of results, if available.
+ * @property prev The pagination token for fetching the previous page of results, if available.
+ */
+class UnreadMessagesCounts(
+    val countsByChannel: List<GetUnreadMessagesCounts>,
+    val next: PNPage.PNNext?,
+    val prev: PNPage.PNPrev?
+)

pubnub-chat-impl/src/commonMain/kotlin/com/pubnub/chat/internal/ChatImpl.kt

@@ -85,6 +85,7 @@ import com.pubnub.chat.internal.utils.cyrb53a
 import com.pubnub.chat.membership.MembershipsResponse
 import com.pubnub.chat.message.GetUnreadMessagesCounts
 import com.pubnub.chat.message.MarkAllMessageAsReadResponse
+import com.pubnub.chat.message.UnreadMessagesCounts
 import com.pubnub.chat.restrictions.Restriction
 import com.pubnub.chat.restrictions.RestrictionType
 import com.pubnub.chat.types.ChannelMentionData
@@ -834,14 +835,24 @@ class ChatImpl(
         filter: String?,
         sort: Collection<PNSortKey<PNMembershipKey>>
     ): PNFuture<List<GetUnreadMessagesCounts>> {
+        return fetchUnreadMessagesCounts(limit, page, filter, sort).then {
+            it.countsByChannel
+        }
+    }
+
+    override fun fetchUnreadMessagesCounts(
+        limit: Int?,
+        page: PNPage?,
+        filter: String?,
+        sort: Collection<PNSortKey<PNMembershipKey>>
+    ): PNFuture<UnreadMessagesCounts> {
         return currentUser.getMemberships(limit = limit, page = page, filter = filter, sort = sort)
             .thenAsync { membershipsResponse: MembershipsResponse ->
                 val memberships = membershipsResponse.memberships
                 if (memberships.isEmpty()) {
-                    return@thenAsync emptyList<GetUnreadMessagesCounts>().asFuture()
+                    return@thenAsync UnreadMessagesCounts(emptyList(), null, null).asFuture()
                 }
                 val channels = memberships.map { membership -> membership.channel.id }
-
                 val channelsTimetoken = memberships.map { membership -> membership.lastReadMessageTimetoken ?: 0 }
 
                 pubNub.messageCounts(channels = channels, channelsTimetoken = channelsTimetoken)
@@ -854,10 +865,14 @@ class ChatImpl(
                                 GetUnreadMessagesCounts(
                                     channel = membershipMatchingChannel.channel,
                                     membership = membershipMatchingChannel,
-                                    count = messageCount
+                                    count = messageCount,
                                 )
                             }
-                        unreadMessageCounts.filter { unreadMessageCount -> unreadMessageCount.count > 0 }
+                        UnreadMessagesCounts(
+                            countsByChannel = unreadMessageCounts.filter { unreadMessageCount -> unreadMessageCount.count > 0 },
+                            prev = membershipsResponse.prev,
+                            next = membershipsResponse.next
+                        )
                     }
             }
     }

pubnub-chat-impl/src/commonTest/kotlin/com/pubnub/kmp/utils/FakeChat.kt

@@ -22,6 +22,7 @@ import com.pubnub.chat.internal.timer.TimerManager
 import com.pubnub.chat.internal.timer.createTimerManager
 import com.pubnub.chat.message.GetUnreadMessagesCounts
 import com.pubnub.chat.message.MarkAllMessageAsReadResponse
+import com.pubnub.chat.message.UnreadMessagesCounts
 import com.pubnub.chat.mutelist.MutedUsersManager
 import com.pubnub.chat.restrictions.Restriction
 import com.pubnub.chat.types.ChannelType
@@ -251,6 +252,15 @@ abstract class FakeChat(override val config: ChatConfiguration, override val pub
         TODO("Not yet implemented")
     }
 
+    override fun fetchUnreadMessagesCounts(
+        limit: Int?,
+        page: PNPage?,
+        filter: String?,
+        sort: Collection<PNSortKey<PNMembershipKey>>
+    ): PNFuture<UnreadMessagesCounts> {
+        TODO("Not yet implemented")
+    }
+
     override fun getUnreadMessagesCounts(
         limit: Int?,
         page: PNPage?,