Initial changes

marcin-cebo · marcin-cebo · commit ea1020460022 · 2025-10-02T14:27:44.000+02:00
diff --git a/pubnub-gson/pubnub-gson-api/src/main/java/com/pubnub/api/java/endpoints/presence/HereNow.java b/pubnub-gson/pubnub-gson-api/src/main/java/com/pubnub/api/java/endpoints/presence/HereNow.java
@@ -11,4 +11,8 @@ public interface HereNow extends Endpoint<PNHereNowResult> {
     HereNow includeState(boolean includeState);
 
     HereNow includeUUIDs(boolean includeUUIDs);
+
+    HereNow limit(int limit);
+
+    HereNow startFrom(Integer startFrom);
 }
diff --git a/pubnub-gson/pubnub-gson-impl/src/main/java/com/pubnub/internal/java/endpoints/presence/HereNowImpl.java b/pubnub-gson/pubnub-gson-impl/src/main/java/com/pubnub/internal/java/endpoints/presence/HereNowImpl.java
@@ -20,6 +20,8 @@ public class HereNowImpl extends PassthroughEndpoint<PNHereNowResult> implements
     private List<String> channelGroups = new ArrayList<>();
     private boolean includeState = false;
     private boolean includeUUIDs = true;
+    private int limit = 1000;
+    private Integer startFrom = null;
 
     public HereNowImpl(PubNub pubnub) {
         super(pubnub);
@@ -32,7 +34,9 @@ protected Endpoint<PNHereNowResult> createRemoteAction() {
                 channels,
                 channelGroups,
                 includeState,
-                includeUUIDs
+                includeUUIDs,
+                limit,
+                startFrom
         );
     }
 }
diff --git a/pubnub-kotlin/pubnub-kotlin-api/src/appleMain/kotlin/com/pubnub/api/PubNubImpl.kt b/pubnub-kotlin/pubnub-kotlin-api/src/appleMain/kotlin/com/pubnub/api/PubNubImpl.kt
@@ -353,14 +353,18 @@ class PubNubImpl(private val pubNubObjC: KMPPubNub) : PubNub {
         channels: List<String>,
         channelGroups: List<String>,
         includeState: Boolean,
-        includeUUIDs: Boolean
+        includeUUIDs: Boolean,
+        limit: Int,
+        startFrom: Int?
     ): HereNow {
         return HereNowImpl(
             pubnub = pubNubObjC,
             channels = channels,
             channelGroups = channelGroups,
             includeState = includeState,
-            includeUUIDs = includeUUIDs
+            includeUUIDs = includeUUIDs,
+            limit = limit,
+            startFrom = startFrom
         )
     }
 
diff --git a/pubnub-kotlin/pubnub-kotlin-api/src/appleMain/kotlin/com/pubnub/api/endpoints/presence/HereNow.ios.kt b/pubnub-kotlin/pubnub-kotlin-api/src/appleMain/kotlin/com/pubnub/api/endpoints/presence/HereNow.ios.kt
@@ -27,18 +27,24 @@ class HereNowImpl(
     private val channels: List<String>,
     private val channelGroups: List<String>,
     private val includeState: Boolean,
-    private val includeUUIDs: Boolean
+    private val includeUUIDs: Boolean,
+    private val limit: Int = 1000,
+    private val startFrom: Int? = null,
 ) : HereNow {
     override fun async(callback: Consumer<Result<PNHereNowResult>>) {
         pubnub.hereNowWithChannels(
             channels = channels,
             channelGroups = channelGroups,
             includeState = includeState,
             includeUUIDs = includeUUIDs,
+            // todo pass limit and startFrom once available
+            // limit = limit,
+            // startFrom = startFrom,
             onSuccess = callback.onSuccessHandler {
                 PNHereNowResult(
                     totalChannels = it?.totalChannels()?.toInt() ?: 0,
                     totalOccupancy = it?.totalOccupancy()?.toInt() ?: 0,
+                    // nextStartFrom = it?.nextStartFrom()?.toInt(), // todo uncomment once available
                     channels = (it?.channels()?.safeCast<String, KMPHereNowChannelData>())?.mapValues { entry ->
                         PNHereNowChannelData(
                             channelName = entry.value.channelName(),
@@ -51,6 +57,7 @@ class HereNowImpl(
                             }
                         )
                     }?.toMutableMap() ?: emptyMap<String, PNHereNowChannelData>().toMutableMap()
+
                 )
             },
             onFailure = callback.onFailureHandler()
diff --git a/pubnub-kotlin/pubnub-kotlin-api/src/commonMain/kotlin/com/pubnub/api/PubNub.kt b/pubnub-kotlin/pubnub-kotlin-api/src/commonMain/kotlin/com/pubnub/api/PubNub.kt
@@ -171,6 +171,8 @@ expect interface PubNub {
         channelGroups: List<String> = emptyList(),
         includeState: Boolean = false,
         includeUUIDs: Boolean = true,
+        limit: Int = 1000,
+        startFrom: Int? = null,
     ): HereNow
 
     fun whereNow(uuid: String = configuration.userId.value): WhereNow
diff --git a/pubnub-kotlin/pubnub-kotlin-api/src/jvmMain/kotlin/com/pubnub/api/PubNub.kt b/pubnub-kotlin/pubnub-kotlin-api/src/jvmMain/kotlin/com/pubnub/api/PubNub.kt
@@ -774,6 +774,8 @@ actual interface PubNub : StatusEmitter, EventEmitter {
         channelGroups: List<String>,
         includeState: Boolean,
         includeUUIDs: Boolean,
+        limit: Int,
+        startFrom: Int?,
     ): HereNow
 
     /**
diff --git a/pubnub-kotlin/pubnub-kotlin-api/src/jvmMain/kotlin/com/pubnub/api/endpoints/presence/HereNow.kt b/pubnub-kotlin/pubnub-kotlin-api/src/jvmMain/kotlin/com/pubnub/api/endpoints/presence/HereNow.kt
@@ -11,4 +11,6 @@ actual interface HereNow : Endpoint<PNHereNowResult> {
     val channelGroups: List<String>
     val includeState: Boolean
     val includeUUIDs: Boolean
+    val limit: Int
+    val startFrom: Int?
 }
diff --git a/pubnub-kotlin/pubnub-kotlin-api/src/nonJvm/kotlin/com/pubnub/api/PubNub.nonJvm.kt b/pubnub-kotlin/pubnub-kotlin-api/src/nonJvm/kotlin/com/pubnub/api/PubNub.nonJvm.kt
@@ -158,7 +158,9 @@ actual interface PubNub {
         channels: List<String>,
         channelGroups: List<String>,
         includeState: Boolean,
-        includeUUIDs: Boolean
+        includeUUIDs: Boolean,
+        limit: Int,
+        startFrom: Int?
     ): HereNow
 
     actual fun whereNow(uuid: String): WhereNow
diff --git a/pubnub-kotlin/pubnub-kotlin-core-api/src/commonMain/kotlin/com/pubnub/api/PubNubError.kt b/pubnub-kotlin/pubnub-kotlin-core-api/src/commonMain/kotlin/com/pubnub/api/PubNubError.kt
@@ -239,6 +239,16 @@ enum class PubNubError(private val code: Int, val message: String) {
         181,
         "Channel and/or ChannelGroup contains empty string which is not allowed.",
     ),
+
+    HERE_NOW_LIMIT_OUT_OF_RANGE(
+        182,
+        "HereNow limit is out of range. Valid range is 1 to 1000.",
+    ),
+    HERE_NOW_START_FROM_OUT_OF_RANGE(
+        183,
+        "HereNow startFrom is out of range. Valid range is 0 to infinity.",
+    )
+
     ;
 
     override fun toString(): String {
diff --git a/pubnub-kotlin/pubnub-kotlin-core-api/src/commonMain/kotlin/com/pubnub/api/models/consumer/presence/PNHereNow.kt b/pubnub-kotlin/pubnub-kotlin-core-api/src/commonMain/kotlin/com/pubnub/api/models/consumer/presence/PNHereNow.kt
@@ -8,12 +8,14 @@ import com.pubnub.api.JsonElement
  * @property totalChannels Total number channels matching the associated HereNow call.
  * @property totalOccupancy Total occupancy matching the associated HereNow call.
  * @property channels A map with values of [PNHereNowChannelData] for each channel.
+ * @property nextStartFrom Starting position for next page of results. Null if no more pages available.
  */
 class PNHereNowResult(
     val totalChannels: Int,
     val totalOccupancy: Int,
     // TODO this should be immutable
     val channels: MutableMap<String, PNHereNowChannelData> = mutableMapOf(),
+    val nextStartFrom: Int? = null,
 )
 
 /**
diff --git a/pubnub-kotlin/pubnub-kotlin-docs/src/main/kotlin/com/pubnub/docs/presence/HereNowMain.kt b/pubnub-kotlin/pubnub-kotlin-docs/src/main/kotlin/com/pubnub/docs/presence/HereNowMain.kt
@@ -41,6 +41,7 @@ fun main() {
 fun singleChannelHereNow(pubnub: PubNub, channel: String) {
     println("\n# Basic hereNow for single channel: $channel")
 
+    // todo consider adding limit and startFrom to docs
     pubnub.hereNow(
         channels = listOf(channel)
     ).async { result ->
diff --git a/pubnub-kotlin/pubnub-kotlin-impl/src/main/kotlin/com/pubnub/internal/PubNubImpl.kt b/pubnub-kotlin/pubnub-kotlin-impl/src/main/kotlin/com/pubnub/internal/PubNubImpl.kt
@@ -576,13 +576,17 @@ open class PubNubImpl(
         channelGroups: List<String>,
         includeState: Boolean,
         includeUUIDs: Boolean,
+        limit: Int,
+        startFrom: Int?,
     ): HereNow {
         return HereNowEndpoint(
             pubnub = this,
             channels = channels,
             channelGroups = channelGroups,
             includeState = includeState,
             includeUUIDs = includeUUIDs,
+            limit = limit,
+            startFrom = startFrom,
         )
     }
 
diff --git a/pubnub-kotlin/pubnub-kotlin-impl/src/main/kotlin/com/pubnub/internal/endpoints/presence/HereNowEndpoint.kt b/pubnub-kotlin/pubnub-kotlin-impl/src/main/kotlin/com/pubnub/internal/endpoints/presence/HereNowEndpoint.kt
@@ -1,6 +1,8 @@
 package com.pubnub.internal.endpoints.presence
 
 import com.google.gson.JsonElement
+import com.pubnub.api.PubNubError
+import com.pubnub.api.PubNubException
 import com.pubnub.api.endpoints.presence.HereNow
 import com.pubnub.api.enums.PNOperationType
 import com.pubnub.api.logging.LogMessage
@@ -18,6 +20,8 @@ import com.pubnub.internal.toCsv
 import retrofit2.Call
 import retrofit2.Response
 
+private const val MAX_NUMBER_OF_RESULT_ON_ONE_PAGE = 1000
+
 /**
  * @see [PubNubImpl.hereNow]
  */
@@ -27,6 +31,8 @@ class HereNowEndpoint internal constructor(
     override val channelGroups: List<String> = emptyList(),
     override val includeState: Boolean = false,
     override val includeUUIDs: Boolean = true,
+    override val limit: Int = MAX_NUMBER_OF_RESULT_ON_ONE_PAGE,
+    override val startFrom: Int? = null,
 ) : EndpointCore<Envelope<JsonElement>, PNHereNowResult>(pubnub), HereNow {
     private val log: PNLogger = LoggerManager.instance.getLogger(pubnub.logConfig, this::class.java)
 
@@ -37,6 +43,14 @@ class HereNowEndpoint internal constructor(
     override fun getAffectedChannelGroups() = channelGroups
 
     override fun doWork(queryParams: HashMap<String, String>): Call<Envelope<JsonElement>> {
+        if (limit !in 1..MAX_NUMBER_OF_RESULT_ON_ONE_PAGE) {
+            throw PubNubException(PubNubError.HERE_NOW_LIMIT_OUT_OF_RANGE)
+        }
+        if (startFrom != null && startFrom < 0) {
+            throw PubNubException(PubNubError.HERE_NOW_START_FROM_OUT_OF_RANGE)
+
+        }
+
         log.debug(
             LogMessage(
                 message = LogMessageContent.Object(
@@ -45,7 +59,9 @@ class HereNowEndpoint internal constructor(
                         "channelGroups" to channelGroups,
                         "includeState" to includeState,
                         "includeUUIDs" to includeUUIDs,
-                        "isGlobalHereNow" to isGlobalHereNow()
+                        "limit" to limit,
+                        "startFrom" to (startFrom?.toString() ?: "null"),
+                        "isGlobalHereNow" to isGlobalHereNow(),
                     ),
                     operation = this::class.simpleName
                 ),
@@ -81,49 +97,74 @@ class HereNowEndpoint internal constructor(
 
     override fun getEndpointGroupName(): RetryableEndpointGroup = RetryableEndpointGroup.PRESENCE
 
+    internal fun calculateNextStartFrom(actualResultSize: Int): Int? {
+        return when {
+            actualResultSize < limit -> null
+            actualResultSize == limit -> (startFrom ?: 0) + limit
+            else -> null
+        }
+    }
+
     private fun parseSingleChannelResponse(input: Envelope<JsonElement>): PNHereNowResult {
+        val occupants = if (includeUUIDs) {
+            prepareOccupantData(input.uuids!!)
+        } else {
+            emptyList()
+        }
+        val actualResultSize = occupants.size
+
         val pnHereNowResult =
             PNHereNowResult(
                 totalChannels = 1,
                 totalOccupancy = input.occupancy,
+                nextStartFrom = calculateNextStartFrom(actualResultSize),
             )
 
         val pnHereNowChannelData =
             PNHereNowChannelData(
                 channelName = channels[0],
                 occupancy = input.occupancy,
+                occupants = occupants
             )
 
         if (includeUUIDs) {
-            pnHereNowChannelData.occupants = prepareOccupantData(input.uuids!!)
             pnHereNowResult.channels[channels[0]] = pnHereNowChannelData
         }
 
         return pnHereNowResult
     }
 
     private fun parseMultipleChannelResponse(input: JsonElement): PNHereNowResult {
-        val pnHereNowResult =
-            PNHereNowResult(
-                totalChannels = pubnub.mapper.elementToInt(input, "total_channels"),
-                totalOccupancy = pubnub.mapper.elementToInt(input, "total_occupancy"),
-            )
-
         val it = pubnub.mapper.getObjectIterator(input, "channels")
+        var totalOccupantsReturned = 0
 
+        val channelsMap = mutableMapOf<String, PNHereNowChannelData>()
         while (it.hasNext()) {
             val entry = it.next()
+            val occupants = if (includeUUIDs) {
+                prepareOccupantData(pubnub.mapper.getField(entry.value, "uuids")!!)
+            } else {
+                emptyList()
+            }
+            totalOccupantsReturned += occupants.size
+
             val pnHereNowChannelData =
                 PNHereNowChannelData(
                     channelName = entry.key,
                     occupancy = pubnub.mapper.elementToInt(entry.value, "occupancy"),
+                    occupants = occupants
                 )
-            if (includeUUIDs) {
-                pnHereNowChannelData.occupants = prepareOccupantData(pubnub.mapper.getField(entry.value, "uuids")!!)
-            }
-            pnHereNowResult.channels[entry.key] = pnHereNowChannelData
+            channelsMap[entry.key] = pnHereNowChannelData
         }
 
+        val pnHereNowResult =
+            PNHereNowResult(
+                totalChannels = pubnub.mapper.elementToInt(input, "total_channels"),
+                totalOccupancy = pubnub.mapper.elementToInt(input, "total_occupancy"),
+                channels = channelsMap,
+                nextStartFrom = calculateNextStartFrom(totalOccupantsReturned),
+            )
+
         return pnHereNowResult
     }
 
@@ -160,5 +201,7 @@ class HereNowEndpoint internal constructor(
         if (channelGroups.isNotEmpty()) {
             queryParams["channel-group"] = channelGroups.toCsv()
         }
+        queryParams["limit"] = limit.toString()
+        startFrom?.let { queryParams["offset"] = it.toString() }
     }
 }
diff --git a/pubnub-kotlin/pubnub-kotlin-impl/src/test/kotlin/com/pubnub/internal/endpoints/presence/HereNowPaginationTest.kt b/pubnub-kotlin/pubnub-kotlin-impl/src/test/kotlin/com/pubnub/internal/endpoints/presence/HereNowPaginationTest.kt
diff --git a/pubnub-kotlin/pubnub-kotlin-impl/src/test/kotlin/com/pubnub/internal/suite/presence/HereNowPaginationTestSuite.kt b/pubnub-kotlin/pubnub-kotlin-impl/src/test/kotlin/com/pubnub/internal/suite/presence/HereNowPaginationTestSuite.kt

Original file line number	Diff line number	Diff line change
`@@ -11,4 +11,8 @@ public interface HereNow extends Endpoint<PNHereNowResult> {`
`11`	`11`	`HereNow includeState(boolean includeState);`
`12`	`12`
`13`	`13`	`HereNow includeUUIDs(boolean includeUUIDs);`
	`14`	`+`
	`15`	`+ HereNow limit(int limit);`
	`16`	`+`
	`17`	`+ HereNow startFrom(Integer startFrom);`
`14`	`18`	`}`
Original file line number	Diff line number	Diff line change
`@@ -11,4 +11,6 @@ actual interface HereNow : Endpoint<PNHereNowResult> {`
`11`	`11`	`val channelGroups: List<String>`
`12`	`12`	`val includeState: Boolean`
`13`	`13`	`val includeUUIDs: Boolean`
	`14`	`+ val limit: Int`
	`15`	`+ val startFrom: Int?`
`14`	`16`	`}`