feat(data): add getBatchForStudyDeployments endpoint with filtering

carp.data.core/src/commonMain/kotlin/dk/cachet/carp/data/application/DataStreamBatch.kt

@@ -3,6 +3,7 @@
 package dk.cachet.carp.data.application
 
 import dk.cachet.carp.common.application.data.Data
+import dk.cachet.carp.common.application.data.DataType
 import kotlinx.serialization.*
 import kotlinx.serialization.builtins.*
 import kotlinx.serialization.descriptors.*
@@ -90,7 +91,7 @@ class MutableDataStreamBatch : DataStreamBatch
     /**
      * Append all data stream sequences contained in [batch] to this batch.
      *
-     * @throws IllegalArgumentException when the start of any of the sequences contained in [batch]
+     * @throws IllegalArgumentException when the start of the sequences contained in [batch]
      *   precede the end of a previously appended sequence to the same data stream.
      */
     fun appendBatch( batch: DataStreamBatch )

carp.data.core/src/commonMain/kotlin/dk/cachet/carp/data/application/DataStreamService.kt

@@ -2,10 +2,13 @@ package dk.cachet.carp.data.application
 
 
 import dk.cachet.carp.common.application.UUID
+import dk.cachet.carp.common.application.data.DataType
 import dk.cachet.carp.common.application.services.ApiVersion
 import dk.cachet.carp.common.application.services.ApplicationService
 import dk.cachet.carp.common.application.services.IntegrationEvent
-import kotlinx.serialization.*
+import kotlinx.datetime.Instant
+import kotlinx.serialization.Required
+import kotlinx.serialization.Serializable
 
 
 /**
@@ -60,6 +63,33 @@ interface DataStreamService : ApplicationService<DataStreamService, DataStreamSe
         toSequenceIdInclusive: Long? = null
     ): DataStreamBatch
 
+    /**
+     * Retrieve data across multiple study deployments, optionally filtered by device role names,
+     * data types, and time range.
+     *
+     * The response is a canonical [DataStreamBatch]: for each [DataStreamId], sequences are
+     * ordered by start time and non-overlapping (contract preserved). No derived/secondary
+     * indexing is applied in this API; analytics-specific projections are out of scope here.
+     *
+     * Time range semantics: if [from] or [to] are specified, sequences are clipped to the
+     * half-open interval [from, to) (inclusive start, exclusive end).
+     *
+     * @param studyDeploymentIds Study deployments to query. Must not be empty.
+     * @param deviceRoleNames Optional device role name filter (e.g., "phone"). If null or empty, all are included.
+     * @param dataTypes Optional data type filter. If null or empty, all are included.
+     * @param from Optional absolute start time (inclusive). If null, no lower bound.
+     * @param to Optional absolute end time (exclusive). If null, no upper bound.
+     * @return A [DataStreamBatch] containing matching data sequences, preserving per-stream invariants.
+     */
+    suspend fun getBatchForStudyDeployments(
+        studyDeploymentIds: Set<UUID>,
+        deviceRoleNames: Set<String>? = null,
+        dataTypes: Set<DataType>? = null,
+        from: Instant? = null,
+        to: Instant? = null
+    ): DataStreamBatch
+
+
     /**
      * Stop accepting incoming data for all data streams for each of the [studyDeploymentIds].
      *

carp.data.core/src/commonMain/kotlin/dk/cachet/carp/data/infrastructure/DataStreamServiceDecorator.kt

@@ -1,13 +1,15 @@
 package dk.cachet.carp.data.infrastructure
 
 import dk.cachet.carp.common.application.UUID
+import dk.cachet.carp.common.application.data.DataType
 import dk.cachet.carp.common.infrastructure.services.ApplicationServiceDecorator
 import dk.cachet.carp.common.infrastructure.services.ApplicationServiceInvoker
 import dk.cachet.carp.common.infrastructure.services.Command
 import dk.cachet.carp.data.application.DataStreamBatch
 import dk.cachet.carp.data.application.DataStreamId
 import dk.cachet.carp.data.application.DataStreamService
 import dk.cachet.carp.data.application.DataStreamsConfiguration
+import kotlinx.datetime.Instant
 
 
 class DataStreamServiceDecorator(
@@ -32,6 +34,22 @@ class DataStreamServiceDecorator(
         toSequenceIdInclusive: Long?
     ) = invoke( DataStreamServiceRequest.GetDataStream( dataStream, fromSequenceId, toSequenceIdInclusive ) )
 
+    override suspend fun getBatchForStudyDeployments(
+        studyDeploymentIds: Set<UUID>,
+        deviceRoleNames: Set<String>?,
+        dataTypes: Set<DataType>?,
+        from: Instant?,
+        to: Instant?
+    ) = invoke(
+        DataStreamServiceRequest.GetBatchForStudyDeployments(
+        studyDeploymentIds,
+        deviceRoleNames,
+        dataTypes,
+        from,
+        to
+    )
+    )
+
     override suspend fun closeDataStreams( studyDeploymentIds: Set<UUID> ) =
         invoke( DataStreamServiceRequest.CloseDataStreams( studyDeploymentIds ) )
 
@@ -51,5 +69,12 @@ object DataStreamServiceInvoker : ApplicationServiceInvoker<DataStreamService, D
                 service.getDataStream( dataStream, fromSequenceId, toSequenceIdInclusive )
             is DataStreamServiceRequest.CloseDataStreams -> service.closeDataStreams( studyDeploymentIds )
             is DataStreamServiceRequest.RemoveDataStreams -> service.removeDataStreams( studyDeploymentIds )
+            is DataStreamServiceRequest.GetBatchForStudyDeployments -> service.getBatchForStudyDeployments(
+                studyDeploymentIds,
+                deviceRoleNames,
+                dataTypes,
+                from,
+                to
+            )
         }
 }

carp.data.core/src/commonMain/kotlin/dk/cachet/carp/data/infrastructure/DataStreamServiceRequest.kt

@@ -1,6 +1,7 @@
 package dk.cachet.carp.data.infrastructure
 
 import dk.cachet.carp.common.application.UUID
+import dk.cachet.carp.common.application.data.DataType
 import dk.cachet.carp.common.application.services.ApiVersion
 import dk.cachet.carp.common.infrastructure.serialization.ignoreTypeParameters
 import dk.cachet.carp.common.infrastructure.services.ApplicationServiceRequest
@@ -9,6 +10,7 @@ import dk.cachet.carp.data.application.DataStreamBatchSerializer
 import dk.cachet.carp.data.application.DataStreamId
 import dk.cachet.carp.data.application.DataStreamService
 import dk.cachet.carp.data.application.DataStreamsConfiguration
+import kotlinx.datetime.Instant
 import kotlinx.serialization.*
 import kotlin.js.JsExport
 
@@ -54,15 +56,25 @@ sealed class DataStreamServiceRequest<out TReturn> : ApplicationServiceRequest<D
     }
 
     @Serializable
-    data class CloseDataStreams( val studyDeploymentIds: Set<UUID> ) :
-        DataStreamServiceRequest<Unit>()
+    data class GetBatchForStudyDeployments(
+        val studyDeploymentIds: Set<UUID>,
+        val deviceRoleNames: Set<String>? = null,
+        val dataTypes: Set<DataType>? = null,
+        val from: Instant? = null,
+        val to: Instant? = null
+    ) : DataStreamServiceRequest<DataStreamBatch>()
+    {
+        override fun getResponseSerializer() = DataStreamBatchSerializer
+    }
+
+    @Serializable
+    data class CloseDataStreams( val studyDeploymentIds: Set<UUID> ) : DataStreamServiceRequest<Unit>()
     {
         override fun getResponseSerializer() = serializer<Unit>()
     }
 
     @Serializable
-    data class RemoveDataStreams( val studyDeploymentIds: Set<UUID> ) :
-        DataStreamServiceRequest<Set<UUID>>()
+    data class RemoveDataStreams( val studyDeploymentIds: Set<UUID> ) : DataStreamServiceRequest<Set<UUID>>()
     {
         override fun getResponseSerializer() = serializer<Set<UUID>>()
     }