@asiriindatissa/capacitor-health 8.4.2 → 8.4.4

package/README.md

@@ -162,6 +162,52 @@ const { workouts } = await Health.queryWorkouts({
 - Workout energy and distance data are aggregated from separate Health Connect records during the workout time period. If you don't request permissions for `calories`/`totalCalories` and `distance`, these fields will be missing from workout results.
 - If `totalEnergyBurned` or `totalDistance` are missing despite having permissions, it means no calorie or distance data was recorded during that workout period in Health Connect.
 
+### Sleep
+
+To query sleep sessions, you need to request read permission for `'sleep'`:
+
+```ts
+// Request permission to read sleep data
+await Health.requestAuthorization({
+  read: ['sleep'],
+  write: [],
+});
+
+// Query recent sleep sessions
+const { sleepSessions } = await Health.querySleep({
+  startDate: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString(),
+  endDate: new Date().toISOString(),
+  limit: 10,
+});
+
+// Each sleep session includes:
+// - duration (in seconds), startDate, endDate (always present)
+// - title (optional, if provided by the source app)
+// - stages (optional array of sleep stage records if available)
+// - sourceName, sourceId (source app information)
+
+// Sleep stages can be: 'unknown', 'awake', 'sleeping', 'outOfBed',
+// 'awakeInBed', 'light', 'deep', 'rem'
+```
+
+**Supported Sleep Stages:**
+
+| Stage        | Description                                    |
+| ------------ | ---------------------------------------------- |
+| `unknown`    | Unspecified or unknown if the user is sleeping |
+| `awake`      | The user is awake within a sleep cycle         |
+| `sleeping`   | Generic or non-granular sleep description      |
+| `outOfBed`   | The user gets out of bed during sleep session  |
+| `awakeInBed` | The user is awake in bed                       |
+| `light`      | Light sleep cycle                              |
+| `deep`       | Deep sleep cycle                               |
+| `rem`        | REM sleep cycle                                |
+
+**Note:**
+
+- `'sleep'` is a special read-only permission type. You cannot write sleep data with this plugin.
+- Not all sleep sessions include detailed sleep stages. Some apps may only record the overall sleep duration.
+
 ## API
 
 <docgen-index>
@@ -175,6 +221,8 @@ const { workouts } = await Health.queryWorkouts({
 * [`openHealthConnectSettings()`](#openhealthconnectsettings)
 * [`showPrivacyPolicy()`](#showprivacypolicy)
 * [`queryWorkouts(...)`](#queryworkouts)
+* [`querySleep(...)`](#querysleep)
+* [`queryHydration(...)`](#queryhydration)
 * [Interfaces](#interfaces)
 * [Type Aliases](#type-aliases)
 
@@ -324,6 +372,40 @@ Queries workout sessions from the native health store on Android (Health Connect
 --------------------
 
 
+### querySleep(...)
+
+```typescript
+querySleep(options: QuerySleepOptions) => Promise<QuerySleepResult>
+```
+
+Queries sleep sessions from the native health store on Android (Health Connect).
+
+| Param         | Type                                                            | Description                                               |
+| ------------- | --------------------------------------------------------------- | --------------------------------------------------------- |
+| **`options`** | <code><a href="#querysleepoptions">QuerySleepOptions</a></code> | Query options including date range, limit, and sort order |
+
+**Returns:** <code>Promise&lt;<a href="#querysleepresult">QuerySleepResult</a>&gt;</code>
+
+--------------------
+
+
+### queryHydration(...)
+
+```typescript
+queryHydration(options: QueryHydrationOptions) => Promise<QueryHydrationResult>
+```
+
+Queries hydration records from the native health store on Android (Health Connect).
+
+| Param         | Type                                                                    | Description                                               |
+| ------------- | ----------------------------------------------------------------------- | --------------------------------------------------------- |
+| **`options`** | <code><a href="#queryhydrationoptions">QueryHydrationOptions</a></code> | Query options including date range, limit, and sort order |
+
+**Returns:** <code>Promise&lt;<a href="#queryhydrationresult">QueryHydrationResult</a>&gt;</code>
+
+--------------------
+
+
 ### Interfaces
 
 
@@ -430,6 +512,75 @@ Queries workout sessions from the native health store on Android (Health Connect
 | **`ascending`**   | <code>boolean</code>                                | Return results sorted ascending by start date (defaults to false).        |
 
 
+#### QuerySleepResult
+
+| Prop                | Type                        |
+| ------------------- | --------------------------- |
+| **`sleepSessions`** | <code>SleepSession[]</code> |
+
+
+#### SleepSession
+
+| Prop             | Type                                                            | Description                                              |
+| ---------------- | --------------------------------------------------------------- | -------------------------------------------------------- |
+| **`title`**      | <code>string</code>                                             | Title/name of the sleep session (if available).          |
+| **`duration`**   | <code>number</code>                                             | Duration of the sleep session in seconds.                |
+| **`startDate`**  | <code>string</code>                                             | ISO 8601 start date of the sleep session.                |
+| **`endDate`**    | <code>string</code>                                             | ISO 8601 end date of the sleep session.                  |
+| **`stages`**     | <code>SleepStageRecord[]</code>                                 | Array of sleep stages during the session (if available). |
+| **`sourceName`** | <code>string</code>                                             | Source name that recorded the sleep session.             |
+| **`sourceId`**   | <code>string</code>                                             | Source bundle identifier.                                |
+| **`metadata`**   | <code><a href="#record">Record</a>&lt;string, string&gt;</code> | Additional metadata (if available).                      |
+
+
+#### SleepStageRecord
+
+| Prop            | Type                                              | Description                              |
+| --------------- | ------------------------------------------------- | ---------------------------------------- |
+| **`stage`**     | <code><a href="#sleepstage">SleepStage</a></code> | The sleep stage type.                    |
+| **`startDate`** | <code>string</code>                               | ISO 8601 start date of this sleep stage. |
+| **`endDate`**   | <code>string</code>                               | ISO 8601 end date of this sleep stage.   |
+
+
+#### QuerySleepOptions
+
+| Prop            | Type                 | Description                                                        |
+| --------------- | -------------------- | ------------------------------------------------------------------ |
+| **`startDate`** | <code>string</code>  | Inclusive ISO 8601 start date (defaults to now - 1 day).           |
+| **`endDate`**   | <code>string</code>  | Exclusive ISO 8601 end date (defaults to now).                     |
+| **`limit`**     | <code>number</code>  | Maximum number of sleep sessions to return (defaults to 100).      |
+| **`ascending`** | <code>boolean</code> | Return results sorted ascending by start date (defaults to false). |
+
+
+#### QueryHydrationResult
+
+| Prop                   | Type                           |
+| ---------------------- | ------------------------------ |
+| **`hydrationRecords`** | <code>HydrationRecord[]</code> |
+
+
+#### HydrationRecord
+
+| Prop             | Type                                                            | Description                                  |
+| ---------------- | --------------------------------------------------------------- | -------------------------------------------- |
+| **`volume`**     | <code>number</code>                                             | Volume of water consumed in liters.          |
+| **`startDate`**  | <code>string</code>                                             | ISO 8601 start date of the hydration record. |
+| **`endDate`**    | <code>string</code>                                             | ISO 8601 end date of the hydration record.   |
+| **`sourceName`** | <code>string</code>                                             | Source name that recorded the hydration.     |
+| **`sourceId`**   | <code>string</code>                                             | Source bundle identifier.                    |
+| **`metadata`**   | <code><a href="#record">Record</a>&lt;string, string&gt;</code> | Additional metadata (if available).          |
+
+
+#### QueryHydrationOptions
+
+| Prop            | Type                 | Description                                                        |
+| --------------- | -------------------- | ------------------------------------------------------------------ |
+| **`startDate`** | <code>string</code>  | Inclusive ISO 8601 start date (defaults to now - 1 day).           |
+| **`endDate`**   | <code>string</code>  | Exclusive ISO 8601 end date (defaults to now).                     |
+| **`limit`**     | <code>number</code>  | Maximum number of hydration records to return (defaults to 100).   |
+| **`ascending`** | <code>boolean</code> | Return results sorted ascending by start date (defaults to false). |
+
+
 ### Type Aliases
 
 
@@ -437,8 +588,10 @@ Queries workout sessions from the native health store on Android (Health Connect
 
 Data types that can be requested for read authorization.
 Includes 'workouts' for querying workout sessions via queryWorkouts().
+Includes 'sleep' for querying sleep sessions via querySleep().
+Includes 'hydration' for querying hydration records via queryHydration().
 
-<code><a href="#healthdatatype">HealthDataType</a> | 'workouts'</code>
+<code><a href="#healthdatatype">HealthDataType</a> | 'workouts' | 'sleep' | 'hydration'</code>
 
 
 #### HealthDataType
@@ -462,6 +615,11 @@ Construct a type with a set of properties K of type T
 
 <code>'running' | 'cycling' | 'walking' | 'swimming' | 'yoga' | 'strengthTraining' | 'hiking' | 'tennis' | 'basketball' | 'soccer' | 'americanFootball' | 'baseball' | 'crossTraining' | 'elliptical' | 'rowing' | 'stairClimbing' | 'traditionalStrengthTraining' | 'waterFitness' | 'waterPolo' | 'waterSports' | 'wrestling' | 'other'</code>
 
+
+#### SleepStage
+
+<code>'unknown' | 'awake' | 'sleeping' | 'outOfBed' | 'awakeInBed' | 'light' | 'deep' | 'rem'</code>
+
 </docgen-api>
 
 ### Credits:

package/android/src/main/AndroidManifest.xml

@@ -13,6 +13,10 @@
     <uses-permission android:name="android.permission.health.READ_HEIGHT" />
     <uses-permission android:name="android.permission.health.WRITE_HEIGHT" />
     <uses-permission android:name="android.permission.health.READ_EXERCISE" />
+    <uses-permission android:name="android.permission.health.READ_SLEEP" />
+    <uses-permission android:name="android.permission.health.WRITE_SLEEP" />
+    <uses-permission android:name="android.permission.health.READ_HYDRATION" />
+    <uses-permission android:name="android.permission.health.WRITE_HYDRATION" />
 
     <!-- Query for Health Connect availability -->
     <queries>

package/android/src/main/java/app/capgo/plugin/health/HealthManager.kt

@@ -8,7 +8,9 @@ import androidx.health.connect.client.records.DistanceRecord
 import androidx.health.connect.client.records.ExerciseSessionRecord
 import androidx.health.connect.client.records.HeartRateRecord
 import androidx.health.connect.client.records.HeightRecord
+import androidx.health.connect.client.records.HydrationRecord
 import androidx.health.connect.client.records.Record
+import androidx.health.connect.client.records.SleepSessionRecord
 import androidx.health.connect.client.records.StepsRecord
 import androidx.health.connect.client.records.TotalCaloriesBurnedRecord
 import androidx.health.connect.client.records.WeightRecord
@@ -17,6 +19,7 @@ import androidx.health.connect.client.time.TimeRangeFilter
 import androidx.health.connect.client.units.Energy
 import androidx.health.connect.client.units.Length
 import androidx.health.connect.client.units.Mass
+import androidx.health.connect.client.units.Volume
 import androidx.health.connect.client.records.metadata.Metadata
 import java.time.Duration
 import com.getcapacitor.JSArray
@@ -32,20 +35,30 @@ class HealthManager {
 
     private val formatter: DateTimeFormatter = DateTimeFormatter.ISO_INSTANT
 
-    fun permissionsFor(readTypes: Collection<HealthDataType>, writeTypes: Collection<HealthDataType>, includeWorkouts: Boolean = false): Set<String> = buildSet {
+    fun permissionsFor(readTypes: Collection<HealthDataType>, writeTypes: Collection<HealthDataType>, includeWorkouts: Boolean = false, includeSleep: Boolean = false, includeHydration: Boolean = false): Set<String> = buildSet {
         readTypes.forEach { add(it.readPermission) }
         writeTypes.forEach { add(it.writePermission) }
         // Include workout read permission if explicitly requested
         if (includeWorkouts) {
             add(HealthPermission.getReadPermission(ExerciseSessionRecord::class))
         }
+        // Include sleep read permission if explicitly requested
+        if (includeSleep) {
+            add(HealthPermission.getReadPermission(SleepSessionRecord::class))
+        }
+        // Include hydration read permission if explicitly requested
+        if (includeHydration) {
+            add(HealthPermission.getReadPermission(HydrationRecord::class))
+        }
     }
 
     suspend fun authorizationStatus(
         client: HealthConnectClient,
         readTypes: Collection<HealthDataType>,
         writeTypes: Collection<HealthDataType>,
-        includeWorkouts: Boolean = false
+        includeWorkouts: Boolean = false,
+        includeSleep: Boolean = false,
+        includeHydration: Boolean = false
     ): JSObject {
         val granted = client.permissionController.getGrantedPermissions()
 
@@ -69,6 +82,26 @@ class HealthManager {
             }
         }
 
+        // Check sleep permission if requested
+        if (includeSleep) {
+            val sleepPermission = HealthPermission.getReadPermission(SleepSessionRecord::class)
+            if (granted.contains(sleepPermission)) {
+                readAuthorized.put("sleep")
+            } else {
+                readDenied.put("sleep")
+            }
+        }
+
+        // Check hydration permission if requested
+        if (includeHydration) {
+            val hydrationPermission = HealthPermission.getReadPermission(HydrationRecord::class)
+            if (granted.contains(hydrationPermission)) {
+                readAuthorized.put("hydration")
+            } else {
+                readDenied.put("hydration")
+            }
+        }
+
         val writeAuthorized = JSArray()
         val writeDenied = JSArray()
         writeTypes.forEach { type ->
@@ -501,6 +534,188 @@ class HealthManager {
         return payload
     }
 
+    suspend fun querySleep(
+        client: HealthConnectClient,
+        startTime: Instant,
+        endTime: Instant,
+        limit: Int,
+        ascending: Boolean
+    ): JSArray {
+        val sleepSessions = mutableListOf<Pair<Instant, JSObject>>()
+        
+        var pageToken: String? = null
+        val pageSize = if (limit > 0) min(limit, MAX_PAGE_SIZE) else DEFAULT_PAGE_SIZE
+        var fetched = 0
+        
+        do {
+            val request = ReadRecordsRequest(
+                recordType = SleepSessionRecord::class,
+                timeRangeFilter = TimeRangeFilter.between(startTime, endTime),
+                pageSize = pageSize,
+                pageToken = pageToken
+            )
+            val response = client.readRecords(request)
+            
+            response.records.forEach { record ->
+                val session = record as SleepSessionRecord
+                val payload = createSleepPayload(session)
+                sleepSessions.add(session.startTime to payload)
+            }
+            
+            fetched += response.records.size
+            pageToken = response.pageToken
+        } while (pageToken != null && (limit <= 0 || fetched < limit))
+        
+        val sorted = sleepSessions.sortedBy { it.first }
+        val ordered = if (ascending) sorted else sorted.asReversed()
+        val limited = if (limit > 0) ordered.take(limit) else ordered
+        
+        val array = JSArray()
+        limited.forEach { array.put(it.second) }
+        return array
+    }
+
+    private fun createSleepPayload(session: SleepSessionRecord): JSObject {
+        val payload = JSObject()
+
+        // Title if available
+        session.title?.let { title ->
+            if (title.isNotBlank()) {
+                payload.put("title", title)
+            }
+        }
+
+        // Duration in seconds
+        val durationSeconds = Duration.between(session.startTime, session.endTime).seconds.toInt()
+        payload.put("duration", durationSeconds)
+
+        // Start and end dates
+        payload.put("startDate", formatter.format(session.startTime))
+        payload.put("endDate", formatter.format(session.endTime))
+
+        // Sleep stages if available
+        if (session.stages.isNotEmpty()) {
+            val stagesArray = JSArray()
+            session.stages.forEach { stage ->
+                val stageObject = JSObject()
+                stageObject.put("stage", sleepStageToString(stage.stage))
+                stageObject.put("startDate", formatter.format(stage.startTime))
+                stageObject.put("endDate", formatter.format(stage.endTime))
+                stagesArray.put(stageObject)
+            }
+            payload.put("stages", stagesArray)
+        }
+
+        // Source information
+        val dataOrigin = session.metadata.dataOrigin
+        payload.put("sourceId", dataOrigin.packageName)
+        payload.put("sourceName", dataOrigin.packageName)
+        session.metadata.device?.let { device ->
+            val manufacturer = device.manufacturer?.takeIf { it.isNotBlank() }
+            val model = device.model?.takeIf { it.isNotBlank() }
+            val label = listOfNotNull(manufacturer, model).joinToString(" ").trim()
+            if (label.isNotEmpty()) {
+                payload.put("sourceName", label)
+            }
+        }
+
+        return payload
+    }
+
+    private fun sleepStageToString(stage: Int): String {
+        return when (stage) {
+            SleepSessionRecord.STAGE_TYPE_UNKNOWN -> "unknown"
+            SleepSessionRecord.STAGE_TYPE_AWAKE -> "awake"
+            SleepSessionRecord.STAGE_TYPE_SLEEPING -> "sleeping"
+            SleepSessionRecord.STAGE_TYPE_OUT_OF_BED -> "outOfBed"
+            SleepSessionRecord.STAGE_TYPE_LIGHT -> "light"
+            SleepSessionRecord.STAGE_TYPE_DEEP -> "deep"
+            SleepSessionRecord.STAGE_TYPE_REM -> "rem"
+            SleepSessionRecord.STAGE_TYPE_AWAKE_IN_BED -> "awakeInBed"
+            else -> "unknown"
+        }
+    }
+
+    suspend fun queryHydration(
+        client: HealthConnectClient,
+        startTime: Instant,
+        endTime: Instant,
+        limit: Int,
+        ascending: Boolean
+    ): JSArray {
+        val hydrationRecords = mutableListOf<Pair<Instant, JSObject>>()
+
+        var pageToken: String? = null
+        val pageSize = if (limit > 0) min(limit, MAX_PAGE_SIZE) else DEFAULT_PAGE_SIZE
+        var fetched = 0
+
+        do {
+            val request = ReadRecordsRequest(
+                recordType = HydrationRecord::class,
+                timeRangeFilter = TimeRangeFilter.between(startTime, endTime),
+                pageSize = pageSize,
+                pageToken = pageToken
+            )
+            val response = client.readRecords(request)
+
+            response.records.forEach { record ->
+                val hydration = record as HydrationRecord
+                val payload = createHydrationPayload(hydration)
+                hydrationRecords.add(hydration.startTime to payload)
+            }
+
+            fetched += response.records.size
+            pageToken = response.pageToken
+        } while (pageToken != null && (limit <= 0 || fetched < limit))
+
+        val sorted = hydrationRecords.sortedBy { it.first }
+        val ordered = if (ascending) sorted else sorted.asReversed()
+        val limited = if (limit > 0) ordered.take(limit) else ordered
+
+        val array = JSArray()
+        limited.forEach { array.put(it.second) }
+        return array
+    }
+
+    private fun createHydrationPayload(hydration: HydrationRecord): JSObject {
+        val payload = JSObject()
+
+        // Volume in liters
+        val volumeLiters = hydration.volume.inLiters
+        payload.put("volume", volumeLiters)
+
+        // Start and end dates
+        payload.put("startDate", formatter.format(hydration.startTime))
+        payload.put("endDate", formatter.format(hydration.endTime))
+
+        // Source information
+        val dataOrigin = hydration.metadata.dataOrigin
+        payload.put("sourceId", dataOrigin.packageName)
+        payload.put("sourceName", dataOrigin.packageName)
+        hydration.metadata.device?.let { device ->
+            val manufacturer = device.manufacturer?.takeIf { it.isNotBlank() }
+            val model = device.model?.takeIf { it.isNotBlank() }
+            val label = listOfNotNull(manufacturer, model).joinToString(" ").trim()
+            if (label.isNotEmpty()) {
+                payload.put("sourceName", label)
+            }
+        }
+
+        // Metadata if available
+        if (hydration.metadata.clientRecordId != null || hydration.metadata.clientRecordVersion > 0) {
+            val metadataObj = JSObject()
+            hydration.metadata.clientRecordId?.let { metadataObj.put("clientRecordId", it) }
+            if (hydration.metadata.clientRecordVersion > 0) {
+                metadataObj.put("clientRecordVersion", hydration.metadata.clientRecordVersion)
+            }
+            if (metadataObj.length() > 0) {
+                payload.put("metadata", metadataObj)
+            }
+        }
+
+        return payload
+    }
+
     companion object {
         private const val DEFAULT_PAGE_SIZE = 100
         private const val MAX_PAGE_SIZE = 500