@flomentumsolutions/capacitor-health-extended 0.6.3 → 0.7.0

package/README.md

@@ -27,7 +27,8 @@ Thanks [@mley](https://github.com/mley) for the ground work. The goal of this fo
 - Request and verify health permissions
 - Query aggregated data like steps or calories
 - Retrieve workout sessions with optional route and heart rate data
-- Fetch the latest samples for steps, distance (incl. cycling), calories (active/total/basal), heart‑rate, resting HR, HRV, respiratory rate, blood pressure, oxygen saturation, blood glucose, body temperature (basal + core), body fat, height, weight, flights climbed, sleep, and exercise time.
+- Create workout sessions (e.g., rock climbing) with totals, optional routes, and heart-rate samples (write APIs)
+- Fetch the latest samples for steps, distance (incl. cycling), calories (active/total/basal), heart‑rate, resting HR, HRV, respiratory rate, blood pressure, oxygen saturation, blood glucose, body temperature (basal + core), body fat, height, weight, flights climbed, sleep (incl. REM duration), and exercise time.
 - Read profile characteristics on iOS: biological sex, blood type, date of birth, Fitzpatrick skin type, wheelchair use.
 
 ### Supported data types (parity iOS + Android)
@@ -36,7 +37,7 @@ Thanks [@mley](https://github.com/mley) for the ground work. The goal of this fo
 - Vitals: heart rate, resting heart rate, HRV, respiratory rate, blood pressure, oxygen saturation, blood glucose, body temperature, basal body temperature
 - Body: weight, height, body fat
 - Characteristics (iOS): biological sex, blood type, date of birth, Fitzpatrick skin type, wheelchair use
-- Sessions: mindfulness, sleep
+- Sessions: mindfulness, sleep, sleep REM (latest sample only)
 
 ## Install
 
@@ -57,6 +58,7 @@ you can keep using the CocoaPods spec `FlomentumSolutionsCapacitorHealthExtended
 * Make sure your app id has the 'HealthKit' entitlement when this plugin is installed (see iOS dev center).
 * Also, make sure your app and App Store description comply with the Apple review guidelines.
 * There are two keys to be added to the info.plist file: NSHealthShareUsageDescription and NSHealthUpdateUsageDescription.
+* Request WRITE_* permissions with `requestHealthPermissions` to enable saving workouts/energy/distance/routes/heart-rate samples to HealthKit.
 
 ### Android
 
@@ -90,8 +92,16 @@ you can keep using the CocoaPods spec `FlomentumSolutionsCapacitorHealthExtended
     <uses-permission android:name="android.permission.health.READ_FLOORS_CLIMBED" />
     <uses-permission android:name="android.permission.health.READ_BASAL_METABOLIC_RATE" />
     <uses-permission android:name="android.permission.health.READ_SLEEP" />
+    <uses-permission android:name="android.permission.health.WRITE_EXERCISE" />
+    <uses-permission android:name="android.permission.health.WRITE_ACTIVE_CALORIES_BURNED" />
+    <uses-permission android:name="android.permission.health.WRITE_TOTAL_CALORIES_BURNED" />
+    <uses-permission android:name="android.permission.health.WRITE_DISTANCE" />
+    <uses-permission android:name="android.permission.health.WRITE_HEART_RATE" />
+    <uses-permission android:name="android.permission.health.WRITE_EXERCISE_ROUTE" />
 ```
 
+Include the WRITE_* entries when you call `saveWorkout` to insert exercise sessions, energy, distance, routes, or heart rate samples.
+
 * Android Manifest in application tag
 ```xml
     <!-- Handle Health Connect rationale (Android 13-) -->
@@ -223,6 +233,7 @@ This setup ensures your WebView will load HTTPS content securely and complies wi
 * [`queryHeight()`](#queryheight)
 * [`queryHeartRate()`](#queryheartrate)
 * [`querySteps()`](#querysteps)
+* [`saveWorkout(...)`](#saveworkout)
 * [Interfaces](#interfaces)
 * [Type Aliases](#type-aliases)
 
@@ -384,6 +395,7 @@ queryLatestSample(request: { dataType: LatestDataType; }) => Promise<QueryLatest
 
 Query latest sample for a specific data type
 - Latest sleep sample returns the most recent complete sleep session (asleep states only) from the last ~36 hours; if a longer overnight session exists, shorter naps are ignored.
+- `sleep-rem` returns REM duration (minutes) for the latest sleep session; requires iOS 16+ sleep stages and Health Connect REM data on Android.
 
 | Param         | Type                                                                     |
 | ------------- | ------------------------------------------------------------------------ |
@@ -446,6 +458,26 @@ Query latest steps sample
 --------------------
 
 
+### saveWorkout(...)
+
+```typescript
+saveWorkout(request: SaveWorkoutRequest) => Promise<SaveWorkoutResponse>
+```
+
+Create a workout session with optional totals and route/heart-rate samples.
+- iOS stores an `HKWorkout` (activityType mapped from `activityType`) with total energy/distance and optional metadata/route/heart-rate samples.
+- Android stores an `ExerciseSessionRecord` plus `ActiveCaloriesBurnedRecord`, `DistanceRecord`, and `HeartRateRecord` when provided. Routes are attached via `ExerciseRoute`.
+- Requires matching WRITE_* permissions for the values you include (e.g., WRITE_WORKOUTS + WRITE_ACTIVE_CALORIES + WRITE_DISTANCE + WRITE_HEART_RATE + WRITE_ROUTE).
+
+| Param         | Type                                                              |
+| ------------- | ----------------------------------------------------------------- |
+| **`request`** | <code><a href="#saveworkoutrequest">SaveWorkoutRequest</a></code> |
+
+**Returns:** <code>Promise&lt;<a href="#saveworkoutresponse">SaveWorkoutResponse</a>&gt;</code>
+
+--------------------
+
+
 ### Interfaces
 
 
@@ -572,6 +604,28 @@ Query latest steps sample
 | **`metadata`**     | <code><a href="#record">Record</a>&lt;string, unknown&gt;</code> |
 
 
+#### SaveWorkoutResponse
+
+| Prop          | Type                 |
+| ------------- | -------------------- |
+| **`success`** | <code>boolean</code> |
+| **`id`**      | <code>string</code>  |
+
+
+#### SaveWorkoutRequest
+
+| Prop                   | Type                                                                |
+| ---------------------- | ------------------------------------------------------------------- |
+| **`activityType`**     | <code><a href="#workoutactivitytype">WorkoutActivityType</a></code> |
+| **`startDate`**        | <code>string</code>                                                 |
+| **`endDate`**          | <code>string</code>                                                 |
+| **`calories`**         | <code>number</code>                                                 |
+| **`distance`**         | <code>number</code>                                                 |
+| **`metadata`**         | <code><a href="#record">Record</a>&lt;string, any&gt;</code>        |
+| **`route`**            | <code>RouteSample[]</code>                                          |
+| **`heartRateSamples`** | <code>HeartRateSample[]</code>                                      |
+
+
 ### Type Aliases
 
 
@@ -584,7 +638,7 @@ Construct a type with a set of properties K of type T
 
 #### HealthPermission
 
-<code>'READ_STEPS' | 'READ_WORKOUTS' | 'READ_ACTIVE_CALORIES' | 'READ_TOTAL_CALORIES' | 'READ_DISTANCE' | 'READ_WEIGHT' | 'READ_HEIGHT' | 'READ_HEART_RATE' | 'READ_RESTING_HEART_RATE' | 'READ_ROUTE' | 'READ_MINDFULNESS' | 'READ_HRV' | 'READ_BLOOD_PRESSURE' | 'READ_BASAL_CALORIES' | 'READ_RESPIRATORY_RATE' | 'READ_OXYGEN_SATURATION' | 'READ_BLOOD_GLUCOSE' | 'READ_BODY_TEMPERATURE' | 'READ_BASAL_BODY_TEMPERATURE' | 'READ_BODY_FAT' | 'READ_FLOORS_CLIMBED' | 'READ_SLEEP' | 'READ_EXERCISE_TIME' | 'READ_BIOLOGICAL_SEX' | 'READ_BLOOD_TYPE' | 'READ_DATE_OF_BIRTH' | 'READ_FITZPATRICK_SKIN_TYPE' | 'READ_WHEELCHAIR_USE'</code>
+<code>'READ_STEPS' | 'READ_WORKOUTS' | 'WRITE_WORKOUTS' | 'READ_ACTIVE_CALORIES' | 'WRITE_ACTIVE_CALORIES' | 'READ_TOTAL_CALORIES' | 'WRITE_TOTAL_CALORIES' | 'READ_DISTANCE' | 'WRITE_DISTANCE' | 'READ_WEIGHT' | 'READ_HEIGHT' | 'READ_HEART_RATE' | 'WRITE_HEART_RATE' | 'READ_RESTING_HEART_RATE' | 'READ_ROUTE' | 'WRITE_ROUTE' | 'READ_MINDFULNESS' | 'READ_HRV' | 'READ_BLOOD_PRESSURE' | 'READ_BASAL_CALORIES' | 'READ_RESPIRATORY_RATE' | 'READ_OXYGEN_SATURATION' | 'READ_BLOOD_GLUCOSE' | 'READ_BODY_TEMPERATURE' | 'READ_BASAL_BODY_TEMPERATURE' | 'READ_BODY_FAT' | 'READ_FLOORS_CLIMBED' | 'READ_SLEEP' | 'READ_EXERCISE_TIME' | 'READ_BIOLOGICAL_SEX' | 'READ_BLOOD_TYPE' | 'READ_DATE_OF_BIRTH' | 'READ_FITZPATRICK_SKIN_TYPE' | 'READ_WHEELCHAIR_USE'</code>
 
 
 #### HealthBiologicalSex
@@ -609,6 +663,11 @@ Construct a type with a set of properties K of type T
 
 #### LatestDataType
 
-<code>'steps' | 'active-calories' | 'total-calories' | 'basal-calories' | 'distance' | 'weight' | 'height' | 'heart-rate' | 'resting-heart-rate' | 'respiratory-rate' | 'oxygen-saturation' | 'blood-glucose' | 'body-temperature' | 'basal-body-temperature' | 'body-fat' | 'flights-climbed' | 'exercise-time' | 'distance-cycling' | 'mindfulness' | 'sleep' | 'hrv' | 'blood-pressure'</code>
+<code>'steps' | 'active-calories' | 'total-calories' | 'basal-calories' | 'distance' | 'weight' | 'height' | 'heart-rate' | 'resting-heart-rate' | 'respiratory-rate' | 'oxygen-saturation' | 'blood-glucose' | 'body-temperature' | 'basal-body-temperature' | 'body-fat' | 'flights-climbed' | 'exercise-time' | 'distance-cycling' | 'mindfulness' | 'sleep' | 'sleep-rem' | 'hrv' | 'blood-pressure'</code>
+
+
+#### WorkoutActivityType
+
+<code>'rock-climbing' | 'climbing' | 'hiking' | 'running' | 'walking' | 'cycling' | 'biking' | 'strength-training' | 'yoga' | 'other'</code>
 
 </docgen-api>

package/android/src/main/java/com/flomentum/{health → vitals}/capacitor/HealthPlugin.kt

@@ -10,11 +10,14 @@ import androidx.health.connect.client.aggregate.AggregateMetric
 import androidx.health.connect.client.aggregate.AggregationResult
 import androidx.health.connect.client.aggregate.AggregationResultGroupedByPeriod
 import androidx.health.connect.client.records.*
+import androidx.health.connect.client.records.metadata.Metadata
 import androidx.health.connect.client.request.AggregateGroupByPeriodRequest
 import androidx.health.connect.client.request.AggregateRequest
 import androidx.health.connect.client.request.ReadRecordsRequest
 import androidx.health.connect.client.time.TimeRangeFilter
 import androidx.health.connect.client.records.Record
+import androidx.health.connect.client.units.kilocalories
+import androidx.health.connect.client.units.meters
 import com.getcapacitor.JSArray
 import com.getcapacitor.JSObject
 import com.getcapacitor.Plugin
@@ -57,7 +60,13 @@ enum class CapHealthPermission {
     READ_BODY_FAT,
     READ_FLOORS_CLIMBED,
     READ_BASAL_CALORIES,
-    READ_SLEEP;
+    READ_SLEEP,
+    WRITE_WORKOUTS,
+    WRITE_ACTIVE_CALORIES,
+    WRITE_TOTAL_CALORIES,
+    WRITE_DISTANCE,
+    WRITE_HEART_RATE,
+    WRITE_ROUTE;
 
     companion object {
         fun from(s: String): CapHealthPermission? {
@@ -95,7 +104,13 @@ enum class CapHealthPermission {
         Permission(alias = "READ_BODY_FAT", strings = ["android.permission.health.READ_BODY_FAT"]),
         Permission(alias = "READ_FLOORS_CLIMBED", strings = ["android.permission.health.READ_FLOORS_CLIMBED"]),
         Permission(alias = "READ_BASAL_CALORIES", strings = ["android.permission.health.READ_BASAL_METABOLIC_RATE"]),
-        Permission(alias = "READ_SLEEP", strings = ["android.permission.health.READ_SLEEP"])
+        Permission(alias = "READ_SLEEP", strings = ["android.permission.health.READ_SLEEP"]),
+        Permission(alias = "WRITE_WORKOUTS", strings = ["android.permission.health.WRITE_EXERCISE"]),
+        Permission(alias = "WRITE_ACTIVE_CALORIES", strings = ["android.permission.health.WRITE_ACTIVE_CALORIES_BURNED"]),
+        Permission(alias = "WRITE_TOTAL_CALORIES", strings = ["android.permission.health.WRITE_TOTAL_CALORIES_BURNED"]),
+        Permission(alias = "WRITE_DISTANCE", strings = ["android.permission.health.WRITE_DISTANCE"]),
+        Permission(alias = "WRITE_HEART_RATE", strings = ["android.permission.health.WRITE_HEART_RATE"]),
+        Permission(alias = "WRITE_ROUTE", strings = ["android.permission.health.WRITE_EXERCISE_ROUTE"])
     ]
 )
 
@@ -132,7 +147,13 @@ class HealthPlugin : Plugin() {
         CapHealthPermission.READ_BODY_FAT to HealthPermission.getReadPermission(BodyFatRecord::class),
         CapHealthPermission.READ_FLOORS_CLIMBED to HealthPermission.getReadPermission(FloorsClimbedRecord::class),
         CapHealthPermission.READ_BASAL_CALORIES to HealthPermission.getReadPermission(BasalMetabolicRateRecord::class),
-        CapHealthPermission.READ_SLEEP to HealthPermission.getReadPermission(SleepSessionRecord::class)
+        CapHealthPermission.READ_SLEEP to HealthPermission.getReadPermission(SleepSessionRecord::class),
+        CapHealthPermission.WRITE_WORKOUTS to HealthPermission.getWritePermission(ExerciseSessionRecord::class),
+        CapHealthPermission.WRITE_ACTIVE_CALORIES to HealthPermission.getWritePermission(ActiveCaloriesBurnedRecord::class),
+        CapHealthPermission.WRITE_TOTAL_CALORIES to HealthPermission.getWritePermission(TotalCaloriesBurnedRecord::class),
+        CapHealthPermission.WRITE_DISTANCE to HealthPermission.getWritePermission(DistanceRecord::class),
+        CapHealthPermission.WRITE_HEART_RATE to HealthPermission.getWritePermission(HeartRateRecord::class),
+        CapHealthPermission.WRITE_ROUTE to HealthPermission.PERMISSION_WRITE_EXERCISE_ROUTE
     )
 
     override fun load() {
@@ -405,6 +426,7 @@ class HealthPlugin : Plugin() {
                     "exercise-time" -> readLatestExerciseTime()
                     "mindfulness" -> readLatestMindfulness()
                     "sleep" -> readLatestSleep()
+                    "sleep-rem" -> readLatestSleepRem()
                     else -> throw IllegalArgumentException("Unsupported data type: $dataType")
                 }
                 call.resolve(result)
@@ -815,6 +837,32 @@ class HealthPlugin : Plugin() {
         }
     }
 
+    private suspend fun readLatestSleepRem(): JSObject {
+        val hasSleepPermission = hasPermission(CapHealthPermission.READ_SLEEP)
+        if (!hasSleepPermission) {
+            throw Exception("Permission for sleep not granted")
+        }
+        val request = ReadRecordsRequest(
+            recordType = SleepSessionRecord::class,
+            timeRangeFilter = TimeRangeFilter.after(Instant.EPOCH),
+            pageSize = 1
+        )
+        val record = healthConnectClient.readRecords(request).records.firstOrNull()
+            ?: throw Exception("No sleep data found")
+        val remMinutes = record.stages
+            .filter { it.stage == SleepSessionRecord.STAGE_TYPE_REM }
+            .sumOf { it.endTime.epochSecond - it.startTime.epochSecond } / 60.0
+        if (remMinutes <= 0) {
+            throw Exception("No REM sleep data found")
+        }
+        return JSObject().apply {
+            put("value", remMinutes)
+            put("timestamp", record.startTime.epochSecond * 1000)
+            put("endTimestamp", record.endTime.epochSecond * 1000)
+            put("unit", "min")
+        }
+    }
+
     private suspend fun sumActiveAndBasalCalories(
         timeRange: TimeRangeFilter,
         includeTotalMetricFallback: Boolean = false
@@ -1471,6 +1519,151 @@ class HealthPlugin : Plugin() {
         return granted.contains(targetPermission)
     }
 
+    @PluginMethod
+    fun saveWorkout(call: PluginCall) {
+        if (!ensureClientInitialized(call)) return
+
+        val activityTypeRaw = call.getString("activityType")
+        val startDate = call.getString("startDate")
+        val endDate = call.getString("endDate")
+        val calories = call.getDouble("calories")
+        val distance = call.getDouble("distance")
+        val metadata = call.getObject("metadata")
+        val routeArray = call.getArray("route")
+        val heartRateArray = call.getArray("heartRateSamples")
+
+        if (activityTypeRaw == null || startDate == null || endDate == null) {
+            call.reject("Missing required parameters: activityType, startDate, endDate")
+            return
+        }
+
+        val startInstant = parseInstant(startDate)
+        val endInstant = parseInstant(endDate)
+        if (startInstant == null || endInstant == null) {
+            call.reject("Invalid startDate or endDate; must be ISO-8601 strings.")
+            return
+        }
+        if (!startInstant.isBefore(endInstant)) {
+            call.reject("startDate must be before endDate")
+            return
+        }
+
+        CoroutineScope(Dispatchers.IO).launch {
+            try {
+                val granted = healthConnectClient.permissionController.getGrantedPermissions()
+                fun ensurePermission(cap: CapHealthPermission, name: String): Boolean {
+                    val hc = permissionMapping[cap]
+                    val ok = hc != null && granted.contains(hc)
+                    if (!ok) {
+                        call.reject("Missing $name permission")
+                    }
+                    return ok
+                }
+
+                if (!ensurePermission(CapHealthPermission.WRITE_WORKOUTS, "WRITE_WORKOUTS")) return@launch
+
+                val startZoneOffset = startInstant.atZone(ZoneId.systemDefault()).offset
+                val endZoneOffset = endInstant.atZone(ZoneId.systemDefault()).offset
+
+                val exerciseType = resolveExerciseType(activityTypeRaw)
+                val title = metadata?.optString("title")?.takeIf { it.isNotBlank() }
+                val notes = metadata?.optString("notes")?.takeIf { it.isNotBlank() }
+                    ?: metadata?.optString("description")?.takeIf { it.isNotBlank() }
+
+                val route = buildExerciseRoute(routeArray, startInstant, endInstant)
+                if (route != null && !granted.contains(HealthPermission.PERMISSION_WRITE_EXERCISE_ROUTE)) {
+                    call.reject("Missing WRITE_ROUTE permission")
+                    return@launch
+                }
+
+                val records = mutableListOf<Record>()
+                records.add(
+                    ExerciseSessionRecord(
+                        startTime = startInstant,
+                        startZoneOffset = startZoneOffset,
+                        endTime = endInstant,
+                        endZoneOffset = endZoneOffset,
+                        metadata = Metadata.manualEntry(),
+                        exerciseType = exerciseType,
+                        title = title,
+                        notes = notes,
+                        exerciseRoute = route
+                    )
+                )
+
+                if (calories != null) {
+                    when {
+                        granted.contains(permissionMapping[CapHealthPermission.WRITE_ACTIVE_CALORIES]) -> {
+                            records.add(
+                                ActiveCaloriesBurnedRecord(
+                                    startTime = startInstant,
+                                    startZoneOffset = startZoneOffset,
+                                    endTime = endInstant,
+                                    endZoneOffset = endZoneOffset,
+                                    energy = kilocalories(calories),
+                                    metadata = Metadata.manualEntry()
+                                )
+                            )
+                        }
+                        granted.contains(permissionMapping[CapHealthPermission.WRITE_TOTAL_CALORIES]) -> {
+                            records.add(
+                                TotalCaloriesBurnedRecord(
+                                    startTime = startInstant,
+                                    startZoneOffset = startZoneOffset,
+                                    endTime = endInstant,
+                                    endZoneOffset = endZoneOffset,
+                                    energy = kilocalories(calories),
+                                    metadata = Metadata.manualEntry()
+                                )
+                            )
+                        }
+                        else -> {
+                            call.reject("Missing WRITE_ACTIVE_CALORIES or WRITE_TOTAL_CALORIES permission")
+                            return@launch
+                        }
+                    }
+                }
+
+                if (distance != null) {
+                    if (!ensurePermission(CapHealthPermission.WRITE_DISTANCE, "WRITE_DISTANCE")) return@launch
+                    records.add(
+                        DistanceRecord(
+                            startTime = startInstant,
+                            startZoneOffset = startZoneOffset,
+                            endTime = endInstant,
+                            endZoneOffset = endZoneOffset,
+                            distance = meters(distance),
+                            metadata = Metadata.manualEntry()
+                        )
+                    )
+                }
+
+                val heartRateSamples = buildHeartRateSamples(heartRateArray, startInstant, endInstant)
+                if (heartRateSamples.isNotEmpty()) {
+                    if (!ensurePermission(CapHealthPermission.WRITE_HEART_RATE, "WRITE_HEART_RATE")) return@launch
+                    records.add(
+                        HeartRateRecord(
+                            startTime = heartRateSamples.first().time,
+                            startZoneOffset = heartRateSamples.first().time.atZone(ZoneId.systemDefault()).offset,
+                            endTime = heartRateSamples.last().time,
+                            endZoneOffset = heartRateSamples.last().time.atZone(ZoneId.systemDefault()).offset,
+                            samples = heartRateSamples,
+                            metadata = Metadata.manualEntry()
+                        )
+                    )
+                }
+
+                val response = healthConnectClient.insertRecords(records)
+                val result = JSObject()
+                result.put("success", true)
+                response.recordIdsList.firstOrNull()?.let { result.put("id", it) }
+                call.resolve(result)
+            } catch (e: Exception) {
+                call.reject("Failed to save workout: ${e.message}")
+            }
+        }
+    }
+
     @PluginMethod
     fun queryWorkouts(call: PluginCall) {
         if (!ensureClientInitialized(call)) return
@@ -1662,6 +1855,71 @@ class HealthPlugin : Plugin() {
         return routeArray
     }
 
+    private fun parseInstant(value: Any?): Instant? {
+        return when (value) {
+            is String -> {
+                try {
+                    Instant.parse(value)
+                } catch (_: Exception) {
+                    value.toDoubleOrNull()?.let { Instant.ofEpochMilli(it.toLong()) }
+                }
+            }
+            is Number -> Instant.ofEpochMilli(value.toLong())
+            else -> null
+        }
+    }
+
+    private fun resolveExerciseType(activityTypeRaw: String): Int {
+        val normalized = activityTypeRaw.lowercase().replace("-", "_")
+        return ExerciseSessionRecord.EXERCISE_TYPE_STRING_TO_INT_MAP[normalized]
+            ?: exerciseTypeMapping.entries.firstOrNull { it.value.equals(activityTypeRaw, ignoreCase = true) }?.key?.toInt()
+            ?: ExerciseSessionRecord.EXERCISE_TYPE_OTHER_WORKOUT
+    }
+
+    private fun buildExerciseRoute(routeArray: JSArray?, startTime: Instant, endTime: Instant): ExerciseRoute? {
+        val locations = routeArray
+            ?.toList<JSObject>()
+            ?.mapNotNull { point ->
+                val lat = point.optDouble("lat", Double.NaN)
+                val lng = point.optDouble("lng", Double.NaN)
+                val ts = parseInstant(point.opt("timestamp")) ?: return@mapNotNull null
+                if (lat.isNaN() || lng.isNaN()) return@mapNotNull null
+                if (ts.isBefore(startTime) || ts.isAfter(endTime)) return@mapNotNull null
+                val altitudeValue = point.optDouble("alt", Double.NaN)
+                ExerciseRoute.Location(
+                    time = ts,
+                    latitude = lat,
+                    longitude = lng,
+                    altitude = if (altitudeValue.isNaN()) null else meters(altitudeValue)
+                )
+            }
+            ?.sortedBy { it.time }
+            ?.toList()
+
+        if (locations.isNullOrEmpty()) {
+            return null
+        }
+        return ExerciseRoute(locations)
+    }
+
+    private fun buildHeartRateSamples(array: JSArray?, startTime: Instant, endTime: Instant): List<HeartRateRecord.Sample> {
+        return array
+            ?.toList<JSObject>()
+            ?.mapNotNull { point ->
+                val bpm = point.optDouble("bpm", Double.NaN)
+                val ts = parseInstant(point.opt("timestamp")) ?: return@mapNotNull null
+                if (bpm.isNaN()) return@mapNotNull null
+                val clampedBpm = bpm.toLong().coerceIn(1, 300)
+                HeartRateRecord.Sample(
+                    time = ts,
+                    beatsPerMinute = clampedBpm
+                )
+            }
+            ?.filter { !it.time.isBefore(startTime) && !it.time.isAfter(endTime) }
+            ?.sortedBy { it.time }
+            ?: emptyList()
+    }
+
 
     private val exerciseTypeMapping = mapOf(
         0 to "OTHER",

package/dist/esm/definitions.d.ts

@@ -64,6 +64,7 @@ export interface HealthPlugin {
     /**
      * Query latest sample for a specific data type
      * - Latest sleep sample returns the most recent complete sleep session (asleep states only) from the last ~36 hours; if a longer overnight session exists, shorter naps are ignored.
+     * - `sleep-rem` returns REM duration (minutes) for the latest sleep session; requires iOS 16+ sleep stages and Health Connect REM data on Android.
      * @param request
      */
     queryLatestSample(request: {
@@ -85,9 +86,16 @@ export interface HealthPlugin {
      * Query latest steps sample
      */
     querySteps(): Promise<QueryLatestSampleResponse>;
+    /**
+     * Create a workout session with optional totals and route/heart-rate samples.
+     * - iOS stores an `HKWorkout` (activityType mapped from `activityType`) with total energy/distance and optional metadata/route/heart-rate samples.
+     * - Android stores an `ExerciseSessionRecord` plus `ActiveCaloriesBurnedRecord`, `DistanceRecord`, and `HeartRateRecord` when provided. Routes are attached via `ExerciseRoute`.
+     * - Requires matching WRITE_* permissions for the values you include (e.g., WRITE_WORKOUTS + WRITE_ACTIVE_CALORIES + WRITE_DISTANCE + WRITE_HEART_RATE + WRITE_ROUTE).
+     */
+    saveWorkout(request: SaveWorkoutRequest): Promise<SaveWorkoutResponse>;
 }
-export declare type HealthPermission = 'READ_STEPS' | 'READ_WORKOUTS' | 'READ_ACTIVE_CALORIES' | 'READ_TOTAL_CALORIES' | 'READ_DISTANCE' | 'READ_WEIGHT' | 'READ_HEIGHT' | 'READ_HEART_RATE' | 'READ_RESTING_HEART_RATE' | 'READ_ROUTE' | 'READ_MINDFULNESS' | 'READ_HRV' | 'READ_BLOOD_PRESSURE' | 'READ_BASAL_CALORIES' | 'READ_RESPIRATORY_RATE' | 'READ_OXYGEN_SATURATION' | 'READ_BLOOD_GLUCOSE' | 'READ_BODY_TEMPERATURE' | 'READ_BASAL_BODY_TEMPERATURE' | 'READ_BODY_FAT' | 'READ_FLOORS_CLIMBED' | 'READ_SLEEP' | 'READ_EXERCISE_TIME' | 'READ_BIOLOGICAL_SEX' | 'READ_BLOOD_TYPE' | 'READ_DATE_OF_BIRTH' | 'READ_FITZPATRICK_SKIN_TYPE' | 'READ_WHEELCHAIR_USE';
-export type LatestDataType = 'steps' | 'active-calories' | 'total-calories' | 'basal-calories' | 'distance' | 'weight' | 'height' | 'heart-rate' | 'resting-heart-rate' | 'respiratory-rate' | 'oxygen-saturation' | 'blood-glucose' | 'body-temperature' | 'basal-body-temperature' | 'body-fat' | 'flights-climbed' | 'exercise-time' | 'distance-cycling' | 'mindfulness' | 'sleep' | 'hrv' | 'blood-pressure';
+export declare type HealthPermission = 'READ_STEPS' | 'READ_WORKOUTS' | 'WRITE_WORKOUTS' | 'READ_ACTIVE_CALORIES' | 'WRITE_ACTIVE_CALORIES' | 'READ_TOTAL_CALORIES' | 'WRITE_TOTAL_CALORIES' | 'READ_DISTANCE' | 'WRITE_DISTANCE' | 'READ_WEIGHT' | 'READ_HEIGHT' | 'READ_HEART_RATE' | 'WRITE_HEART_RATE' | 'READ_RESTING_HEART_RATE' | 'READ_ROUTE' | 'WRITE_ROUTE' | 'READ_MINDFULNESS' | 'READ_HRV' | 'READ_BLOOD_PRESSURE' | 'READ_BASAL_CALORIES' | 'READ_RESPIRATORY_RATE' | 'READ_OXYGEN_SATURATION' | 'READ_BLOOD_GLUCOSE' | 'READ_BODY_TEMPERATURE' | 'READ_BASAL_BODY_TEMPERATURE' | 'READ_BODY_FAT' | 'READ_FLOORS_CLIMBED' | 'READ_SLEEP' | 'READ_EXERCISE_TIME' | 'READ_BIOLOGICAL_SEX' | 'READ_BLOOD_TYPE' | 'READ_DATE_OF_BIRTH' | 'READ_FITZPATRICK_SKIN_TYPE' | 'READ_WHEELCHAIR_USE';
+export type LatestDataType = 'steps' | 'active-calories' | 'total-calories' | 'basal-calories' | 'distance' | 'weight' | 'height' | 'heart-rate' | 'resting-heart-rate' | 'respiratory-rate' | 'oxygen-saturation' | 'blood-glucose' | 'body-temperature' | 'basal-body-temperature' | 'body-fat' | 'flights-climbed' | 'exercise-time' | 'distance-cycling' | 'mindfulness' | 'sleep' | 'sleep-rem' | 'hrv' | 'blood-pressure';
 export interface PermissionsRequest {
     permissions: HealthPermission[];
 }
@@ -114,6 +122,21 @@ export interface RouteSample {
 export interface QueryWorkoutResponse {
     workouts: Workout[];
 }
+export type WorkoutActivityType = 'rock-climbing' | 'climbing' | 'hiking' | 'running' | 'walking' | 'cycling' | 'biking' | 'strength-training' | 'yoga' | 'other';
+export interface SaveWorkoutRequest {
+    activityType: WorkoutActivityType;
+    startDate: string;
+    endDate: string;
+    calories?: number;
+    distance?: number;
+    metadata?: Record<string, any>;
+    route?: RouteSample[];
+    heartRateSamples?: HeartRateSample[];
+}
+export interface SaveWorkoutResponse {
+    success: boolean;
+    id?: string;
+}
 export interface Workout {
     startDate: string;
     endDate: string;

package/dist/esm/definitions.js.map

@@ -1 +1 @@
-{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["export interface HealthPlugin {\n  /**\n   * Checks if health API is available.\n   * Android: If false is returned, the Google Health Connect app is probably not installed.\n   * See showHealthConnectInPlayStore()\n   *\n   */\n  isHealthAvailable(): Promise<{ available: boolean }>;\n\n  /**\n   * Android only: Returns for each given permission, if it was granted by the underlying health API\n   * @param permissions permissions to query\n   */\n  checkHealthPermissions(permissions: PermissionsRequest): Promise<PermissionResponse>;\n\n  /**\n   * Requests the permissions from the user.\n   *\n   * Android: Apps can ask only a few times for permissions, after that the user has to grant them manually in\n   * the Health Connect app. See openHealthConnectSettings()\n   *\n   * iOS: If the permissions are already granted or denied, this method will just return without asking the user. In iOS\n   * we can't really detect if a user granted or denied a permission. The return value reflects the assumption that all\n   * permissions were granted.\n   *\n   * @param permissions permissions to request\n   */\n  requestHealthPermissions(permissions: PermissionsRequest): Promise<PermissionResponse>;\n\n  /**\n   * Opens the apps settings, which is kind of wrong, because health permissions are configured under:\n   * Settings > Apps > (Apple) Health > Access and Devices > [app-name]\n   * But we can't go there directly.\n   */\n  openAppleHealthSettings(): Promise<void>;\n\n  /**\n   * Opens the Google Health Connect app\n   */\n  openHealthConnectSettings(): Promise<void>;\n\n  /**\n   * Opens the Google Health Connect app in PlayStore\n   */\n  showHealthConnectInPlayStore(): Promise<void>;\n\n  /**\n   * iOS only: Reads user characteristics such as biological sex, blood type, date of birth, Fitzpatrick skin type, and wheelchair use.\n   * Values are null when unavailable or permission was not granted. Android does not expose these characteristics; it returns `platformSupported: false` and a `platformMessage` for UI hints without emitting null values.\n   */\n  getCharacteristics(): Promise<CharacteristicsResponse>;\n\n  /**\n   * Query aggregated data\n   * - Blood-pressure aggregates return the systolic average in `value` plus `systolic`, `diastolic`, and `unit`.\n   * - `total-calories` is derived as active + basal energy on both iOS and Android for latest samples, aggregated queries, and workouts. We fall back to the platform's total‑calories metric (or active calories) when basal data isn't available or permission is missing. Request both `READ_ACTIVE_CALORIES` and `READ_BASAL_CALORIES` for full totals.\n   * - Weight/height aggregation returns the latest sample per day (no averaging).\n   * - Android aggregation currently supports daily buckets; unsupported buckets will be rejected.\n   * - Android `distance-cycling` aggregates distance recorded during biking exercise sessions (requires distance + workouts permissions).\n   * - Daily `bucket: \"day\"` queries use calendar-day boundaries in the device time zone (start-of-day through the next start-of-day) instead of a trailing 24-hour window. For “today,” send `startDate` at today’s start-of-day and `endDate` at now or tomorrow’s start-of-day.\n   * @param request\n   */\n  queryAggregated(request: QueryAggregatedRequest): Promise<QueryAggregatedResponse>;\n\n  /**\n   * Query workouts\n   * @param request\n   */\n  queryWorkouts(request: QueryWorkoutRequest): Promise<QueryWorkoutResponse>;\n\n  /**\n   * Query latest sample for a specific data type\n   * - Latest sleep sample returns the most recent complete sleep session (asleep states only) from the last ~36 hours; if a longer overnight session exists, shorter naps are ignored.\n   * @param request\n   */\n  queryLatestSample(request: { dataType: LatestDataType }): Promise<QueryLatestSampleResponse>;\n\n  /**\n   * Query latest weight sample\n   */\n  queryWeight(): Promise<QueryLatestSampleResponse>;\n\n  /**\n   * Query latest height sample\n   */\n  queryHeight(): Promise<QueryLatestSampleResponse>;\n\n  /**\n   * Query latest heart rate sample\n   */\n  queryHeartRate(): Promise<QueryLatestSampleResponse>;\n\n  /**\n   * Query latest steps sample\n   */\n  querySteps(): Promise<QueryLatestSampleResponse>;\n}\n\nexport declare type HealthPermission =\n  | 'READ_STEPS'\n  | 'READ_WORKOUTS'\n  | 'READ_ACTIVE_CALORIES'\n  | 'READ_TOTAL_CALORIES'\n  | 'READ_DISTANCE'\n  | 'READ_WEIGHT'\n  | 'READ_HEIGHT'\n  | 'READ_HEART_RATE'\n  | 'READ_RESTING_HEART_RATE'\n  | 'READ_ROUTE'\n  | 'READ_MINDFULNESS'\n  | 'READ_HRV'\n  | 'READ_BLOOD_PRESSURE'\n  | 'READ_BASAL_CALORIES'\n  | 'READ_RESPIRATORY_RATE'\n  | 'READ_OXYGEN_SATURATION'\n  | 'READ_BLOOD_GLUCOSE'\n  | 'READ_BODY_TEMPERATURE'\n  | 'READ_BASAL_BODY_TEMPERATURE'\n  | 'READ_BODY_FAT'\n  | 'READ_FLOORS_CLIMBED'\n  | 'READ_SLEEP'\n  | 'READ_EXERCISE_TIME'\n  | 'READ_BIOLOGICAL_SEX'\n  | 'READ_BLOOD_TYPE'\n  | 'READ_DATE_OF_BIRTH'\n  | 'READ_FITZPATRICK_SKIN_TYPE'\n  | 'READ_WHEELCHAIR_USE';\n\nexport type LatestDataType =\n  | 'steps'\n  | 'active-calories'\n  | 'total-calories'\n  | 'basal-calories'\n  | 'distance'\n  | 'weight'\n  | 'height'\n  | 'heart-rate'\n  | 'resting-heart-rate'\n  | 'respiratory-rate'\n  | 'oxygen-saturation'\n  | 'blood-glucose'\n  | 'body-temperature'\n  | 'basal-body-temperature'\n  | 'body-fat'\n  | 'flights-climbed'\n  | 'exercise-time'\n  | 'distance-cycling'\n  | 'mindfulness'\n  | 'sleep'\n  | 'hrv'\n  | 'blood-pressure';\n\nexport interface PermissionsRequest {\n  permissions: HealthPermission[];\n}\n\nexport interface PermissionResponse {\n  permissions: Record<HealthPermission, boolean>;\n}\n\nexport interface QueryWorkoutRequest {\n  startDate: string;\n  endDate: string;\n  includeHeartRate: boolean;\n  includeRoute: boolean;\n  includeSteps: boolean;\n}\n\nexport interface HeartRateSample {\n  timestamp: string;\n  bpm: number;\n}\n\nexport interface RouteSample {\n  timestamp: string;\n  lat: number;\n  lng: number;\n  alt?: number;\n}\n\nexport interface QueryWorkoutResponse {\n  workouts: Workout[];\n}\n\nexport interface Workout {\n  startDate: string;\n  endDate: string;\n  workoutType: string;\n  sourceName: string;\n  id?: string;\n  duration: number;\n  distance?: number;\n  steps?: number;\n  calories: number;\n  sourceBundleId: string;\n  route?: RouteSample[];\n  heartRate?: HeartRateSample[];\n}\n\nexport interface QueryAggregatedRequest {\n  startDate: string;\n  endDate: string;\n  dataType:\n    | 'steps'\n    | 'active-calories'\n    | 'total-calories'\n    | 'basal-calories'\n    | 'distance'\n    | 'weight'\n    | 'height'\n    | 'heart-rate'\n    | 'resting-heart-rate'\n    | 'respiratory-rate'\n    | 'oxygen-saturation'\n    | 'blood-glucose'\n    | 'body-temperature'\n    | 'basal-body-temperature'\n    | 'body-fat'\n    | 'flights-climbed'\n    | 'exercise-time'\n    | 'distance-cycling'\n    | 'sleep'\n    | 'mindfulness'\n    | 'hrv'\n    | 'blood-pressure';\n  bucket: string;\n}\n\nexport interface QueryAggregatedResponse {\n  aggregatedData: AggregatedSample[];\n}\n\nexport interface AggregatedSample {\n  startDate: string;\n  endDate: string;\n  value: number;\n  systolic?: number;\n  diastolic?: number;\n  unit?: string;\n}\n\nexport interface QueryLatestSampleResponse {\n  value?: number;\n  systolic?: number;\n  diastolic?: number;\n  timestamp: number;\n  endTimestamp?: number;\n  unit: string;\n  metadata?: Record<string, unknown>;\n}\n\nexport interface CharacteristicsResponse {\n  biologicalSex?: HealthBiologicalSex | null;\n  bloodType?: HealthBloodType | null;\n  dateOfBirth?: string | null;\n  fitzpatrickSkinType?: HealthFitzpatrickSkinType | null;\n  wheelchairUse?: HealthWheelchairUse | null;\n  /**\n   * Indicates whether the platform exposes these characteristics via the plugin (true on iOS, false on Android).\n   */\n  platformSupported?: boolean;\n  /**\n   * Optional platform-specific message; on Android we return a user-facing note explaining that values remain empty unless synced from iOS.\n   */\n  platformMessage?: string;\n}\n\nexport type HealthBiologicalSex = 'female' | 'male' | 'other' | 'not_set' | 'unknown';\n\nexport type HealthBloodType =\n  | 'a-positive'\n  | 'a-negative'\n  | 'b-positive'\n  | 'b-negative'\n  | 'ab-positive'\n  | 'ab-negative'\n  | 'o-positive'\n  | 'o-negative'\n  | 'not_set'\n  | 'unknown';\n\nexport type HealthFitzpatrickSkinType = 'type1' | 'type2' | 'type3' | 'type4' | 'type5' | 'type6' | 'not_set' | 'unknown';\n\nexport type HealthWheelchairUse = 'wheelchair_user' | 'not_wheelchair_user' | 'not_set' | 'unknown';\n"]}
+{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["export interface HealthPlugin {\n  /**\n   * Checks if health API is available.\n   * Android: If false is returned, the Google Health Connect app is probably not installed.\n   * See showHealthConnectInPlayStore()\n   *\n   */\n  isHealthAvailable(): Promise<{ available: boolean }>;\n\n  /**\n   * Android only: Returns for each given permission, if it was granted by the underlying health API\n   * @param permissions permissions to query\n   */\n  checkHealthPermissions(permissions: PermissionsRequest): Promise<PermissionResponse>;\n\n  /**\n   * Requests the permissions from the user.\n   *\n   * Android: Apps can ask only a few times for permissions, after that the user has to grant them manually in\n   * the Health Connect app. See openHealthConnectSettings()\n   *\n   * iOS: If the permissions are already granted or denied, this method will just return without asking the user. In iOS\n   * we can't really detect if a user granted or denied a permission. The return value reflects the assumption that all\n   * permissions were granted.\n   *\n   * @param permissions permissions to request\n   */\n  requestHealthPermissions(permissions: PermissionsRequest): Promise<PermissionResponse>;\n\n  /**\n   * Opens the apps settings, which is kind of wrong, because health permissions are configured under:\n   * Settings > Apps > (Apple) Health > Access and Devices > [app-name]\n   * But we can't go there directly.\n   */\n  openAppleHealthSettings(): Promise<void>;\n\n  /**\n   * Opens the Google Health Connect app\n   */\n  openHealthConnectSettings(): Promise<void>;\n\n  /**\n   * Opens the Google Health Connect app in PlayStore\n   */\n  showHealthConnectInPlayStore(): Promise<void>;\n\n  /**\n   * iOS only: Reads user characteristics such as biological sex, blood type, date of birth, Fitzpatrick skin type, and wheelchair use.\n   * Values are null when unavailable or permission was not granted. Android does not expose these characteristics; it returns `platformSupported: false` and a `platformMessage` for UI hints without emitting null values.\n   */\n  getCharacteristics(): Promise<CharacteristicsResponse>;\n\n  /**\n   * Query aggregated data\n   * - Blood-pressure aggregates return the systolic average in `value` plus `systolic`, `diastolic`, and `unit`.\n   * - `total-calories` is derived as active + basal energy on both iOS and Android for latest samples, aggregated queries, and workouts. We fall back to the platform's total‑calories metric (or active calories) when basal data isn't available or permission is missing. Request both `READ_ACTIVE_CALORIES` and `READ_BASAL_CALORIES` for full totals.\n   * - Weight/height aggregation returns the latest sample per day (no averaging).\n   * - Android aggregation currently supports daily buckets; unsupported buckets will be rejected.\n   * - Android `distance-cycling` aggregates distance recorded during biking exercise sessions (requires distance + workouts permissions).\n   * - Daily `bucket: \"day\"` queries use calendar-day boundaries in the device time zone (start-of-day through the next start-of-day) instead of a trailing 24-hour window. For “today,” send `startDate` at today’s start-of-day and `endDate` at now or tomorrow’s start-of-day.\n   * @param request\n   */\n  queryAggregated(request: QueryAggregatedRequest): Promise<QueryAggregatedResponse>;\n\n  /**\n   * Query workouts\n   * @param request\n   */\n  queryWorkouts(request: QueryWorkoutRequest): Promise<QueryWorkoutResponse>;\n\n  /**\n   * Query latest sample for a specific data type\n   * - Latest sleep sample returns the most recent complete sleep session (asleep states only) from the last ~36 hours; if a longer overnight session exists, shorter naps are ignored.\n   * - `sleep-rem` returns REM duration (minutes) for the latest sleep session; requires iOS 16+ sleep stages and Health Connect REM data on Android.\n   * @param request\n   */\n  queryLatestSample(request: { dataType: LatestDataType }): Promise<QueryLatestSampleResponse>;\n\n  /**\n   * Query latest weight sample\n   */\n  queryWeight(): Promise<QueryLatestSampleResponse>;\n\n  /**\n   * Query latest height sample\n   */\n  queryHeight(): Promise<QueryLatestSampleResponse>;\n\n  /**\n   * Query latest heart rate sample\n   */\n  queryHeartRate(): Promise<QueryLatestSampleResponse>;\n\n  /**\n   * Query latest steps sample\n   */\n  querySteps(): Promise<QueryLatestSampleResponse>;\n\n  /**\n   * Create a workout session with optional totals and route/heart-rate samples.\n   * - iOS stores an `HKWorkout` (activityType mapped from `activityType`) with total energy/distance and optional metadata/route/heart-rate samples.\n   * - Android stores an `ExerciseSessionRecord` plus `ActiveCaloriesBurnedRecord`, `DistanceRecord`, and `HeartRateRecord` when provided. Routes are attached via `ExerciseRoute`.\n   * - Requires matching WRITE_* permissions for the values you include (e.g., WRITE_WORKOUTS + WRITE_ACTIVE_CALORIES + WRITE_DISTANCE + WRITE_HEART_RATE + WRITE_ROUTE).\n   */\n  saveWorkout(request: SaveWorkoutRequest): Promise<SaveWorkoutResponse>;\n}\n\nexport declare type HealthPermission =\n  | 'READ_STEPS'\n  | 'READ_WORKOUTS'\n  | 'WRITE_WORKOUTS'\n  | 'READ_ACTIVE_CALORIES'\n  | 'WRITE_ACTIVE_CALORIES'\n  | 'READ_TOTAL_CALORIES'\n  | 'WRITE_TOTAL_CALORIES'\n  | 'READ_DISTANCE'\n  | 'WRITE_DISTANCE'\n  | 'READ_WEIGHT'\n  | 'READ_HEIGHT'\n  | 'READ_HEART_RATE'\n  | 'WRITE_HEART_RATE'\n  | 'READ_RESTING_HEART_RATE'\n  | 'READ_ROUTE'\n  | 'WRITE_ROUTE'\n  | 'READ_MINDFULNESS'\n  | 'READ_HRV'\n  | 'READ_BLOOD_PRESSURE'\n  | 'READ_BASAL_CALORIES'\n  | 'READ_RESPIRATORY_RATE'\n  | 'READ_OXYGEN_SATURATION'\n  | 'READ_BLOOD_GLUCOSE'\n  | 'READ_BODY_TEMPERATURE'\n  | 'READ_BASAL_BODY_TEMPERATURE'\n  | 'READ_BODY_FAT'\n  | 'READ_FLOORS_CLIMBED'\n  | 'READ_SLEEP'\n  | 'READ_EXERCISE_TIME'\n  | 'READ_BIOLOGICAL_SEX'\n  | 'READ_BLOOD_TYPE'\n  | 'READ_DATE_OF_BIRTH'\n  | 'READ_FITZPATRICK_SKIN_TYPE'\n  | 'READ_WHEELCHAIR_USE';\n\nexport type LatestDataType =\n  | 'steps'\n  | 'active-calories'\n  | 'total-calories'\n  | 'basal-calories'\n  | 'distance'\n  | 'weight'\n  | 'height'\n  | 'heart-rate'\n  | 'resting-heart-rate'\n  | 'respiratory-rate'\n  | 'oxygen-saturation'\n  | 'blood-glucose'\n  | 'body-temperature'\n  | 'basal-body-temperature'\n  | 'body-fat'\n  | 'flights-climbed'\n  | 'exercise-time'\n  | 'distance-cycling'\n  | 'mindfulness'\n  | 'sleep'\n  | 'sleep-rem'\n  | 'hrv'\n  | 'blood-pressure';\n\nexport interface PermissionsRequest {\n  permissions: HealthPermission[];\n}\n\nexport interface PermissionResponse {\n  permissions: Record<HealthPermission, boolean>;\n}\n\nexport interface QueryWorkoutRequest {\n  startDate: string;\n  endDate: string;\n  includeHeartRate: boolean;\n  includeRoute: boolean;\n  includeSteps: boolean;\n}\n\nexport interface HeartRateSample {\n  timestamp: string;\n  bpm: number;\n}\n\nexport interface RouteSample {\n  timestamp: string;\n  lat: number;\n  lng: number;\n  alt?: number;\n}\n\nexport interface QueryWorkoutResponse {\n  workouts: Workout[];\n}\n\nexport type WorkoutActivityType =\n  | 'rock-climbing'\n  | 'climbing'\n  | 'hiking'\n  | 'running'\n  | 'walking'\n  | 'cycling'\n  | 'biking'\n  | 'strength-training'\n  | 'yoga'\n  | 'other';\n\nexport interface SaveWorkoutRequest {\n  activityType: WorkoutActivityType;\n  startDate: string;\n  endDate: string;\n  calories?: number;\n  distance?: number;\n  metadata?: Record<string, any>;\n  route?: RouteSample[];\n  heartRateSamples?: HeartRateSample[];\n}\n\nexport interface SaveWorkoutResponse {\n  success: boolean;\n  id?: string;\n}\n\nexport interface Workout {\n  startDate: string;\n  endDate: string;\n  workoutType: string;\n  sourceName: string;\n  id?: string;\n  duration: number;\n  distance?: number;\n  steps?: number;\n  calories: number;\n  sourceBundleId: string;\n  route?: RouteSample[];\n  heartRate?: HeartRateSample[];\n}\n\nexport interface QueryAggregatedRequest {\n  startDate: string;\n  endDate: string;\n  dataType:\n    | 'steps'\n    | 'active-calories'\n    | 'total-calories'\n    | 'basal-calories'\n    | 'distance'\n    | 'weight'\n    | 'height'\n    | 'heart-rate'\n    | 'resting-heart-rate'\n    | 'respiratory-rate'\n    | 'oxygen-saturation'\n    | 'blood-glucose'\n    | 'body-temperature'\n    | 'basal-body-temperature'\n    | 'body-fat'\n    | 'flights-climbed'\n    | 'exercise-time'\n    | 'distance-cycling'\n    | 'sleep'\n    | 'mindfulness'\n    | 'hrv'\n    | 'blood-pressure';\n  bucket: string;\n}\n\nexport interface QueryAggregatedResponse {\n  aggregatedData: AggregatedSample[];\n}\n\nexport interface AggregatedSample {\n  startDate: string;\n  endDate: string;\n  value: number;\n  systolic?: number;\n  diastolic?: number;\n  unit?: string;\n}\n\nexport interface QueryLatestSampleResponse {\n  value?: number;\n  systolic?: number;\n  diastolic?: number;\n  timestamp: number;\n  endTimestamp?: number;\n  unit: string;\n  metadata?: Record<string, unknown>;\n}\n\nexport interface CharacteristicsResponse {\n  biologicalSex?: HealthBiologicalSex | null;\n  bloodType?: HealthBloodType | null;\n  dateOfBirth?: string | null;\n  fitzpatrickSkinType?: HealthFitzpatrickSkinType | null;\n  wheelchairUse?: HealthWheelchairUse | null;\n  /**\n   * Indicates whether the platform exposes these characteristics via the plugin (true on iOS, false on Android).\n   */\n  platformSupported?: boolean;\n  /**\n   * Optional platform-specific message; on Android we return a user-facing note explaining that values remain empty unless synced from iOS.\n   */\n  platformMessage?: string;\n}\n\nexport type HealthBiologicalSex = 'female' | 'male' | 'other' | 'not_set' | 'unknown';\n\nexport type HealthBloodType =\n  | 'a-positive'\n  | 'a-negative'\n  | 'b-positive'\n  | 'b-negative'\n  | 'ab-positive'\n  | 'ab-negative'\n  | 'o-positive'\n  | 'o-negative'\n  | 'not_set'\n  | 'unknown';\n\nexport type HealthFitzpatrickSkinType = 'type1' | 'type2' | 'type3' | 'type4' | 'type5' | 'type6' | 'not_set' | 'unknown';\n\nexport type HealthWheelchairUse = 'wheelchair_user' | 'not_wheelchair_user' | 'not_set' | 'unknown';\n"]}

package/ios/Sources/HealthPluginPlugin/HealthPlugin.swift

@@ -2,6 +2,7 @@ import Foundation
 import UIKit
 import Capacitor
 import HealthKit
+import CoreLocation
 
 /**
  * Please read the Capacitor iOS Plugin Development Guide
@@ -19,7 +20,8 @@ public class HealthPlugin: CAPPlugin, CAPBridgedPlugin {
         CAPPluginMethod(name: "queryAggregated", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "queryWorkouts", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "queryLatestSample", returnType: CAPPluginReturnPromise),
-        CAPPluginMethod(name: "getCharacteristics", returnType: CAPPluginReturnPromise)
+        CAPPluginMethod(name: "getCharacteristics", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "saveWorkout", returnType: CAPPluginReturnPromise)
     ]
     
     let healthStore = HKHealthStore()
@@ -41,7 +43,7 @@ public class HealthPlugin: CAPPlugin, CAPBridgedPlugin {
         var result: [String: String] = [:]
 
         for permission in permissions {
-            let hkTypes = permissionToHKObjectType(permission)
+            let hkTypes = permissionToHKObjectType(permission) + permissionToHKSampleType(permission)
             for type in hkTypes {
                 let status = healthStore.authorizationStatus(for: type)
 
@@ -69,19 +71,20 @@ public class HealthPlugin: CAPPlugin, CAPBridgedPlugin {
         
         print("⚡️ [HealthPlugin] Requesting permissions: \(permissions)")
         
-        let types: [HKObjectType] = permissions.flatMap { permissionToHKObjectType($0) }
+        let readTypes: [HKObjectType] = permissions.flatMap { permissionToHKObjectType($0) }
+        let shareTypes: [HKSampleType] = permissions.flatMap { permissionToHKSampleType($0) }
         
-        print("⚡️ [HealthPlugin] Mapped to \(types.count) HKObjectTypes")
+        print("⚡️ [HealthPlugin] Mapped to \(readTypes.count) HKObjectTypes (read) and \(shareTypes.count) HKSampleTypes (share)")
         
         // Validate that we have at least one valid permission type
-        guard !types.isEmpty else {
+        guard !readTypes.isEmpty || !shareTypes.isEmpty else {
             let invalidPermissions = permissions.filter { permissionToHKObjectType($0).isEmpty }
             call.reject("No valid permission types found. Invalid permissions: \(invalidPermissions)")
             return
         }
         
         DispatchQueue.main.async {
-            self.healthStore.requestAuthorization(toShare: nil, read: Set(types)) { success, error in
+            self.healthStore.requestAuthorization(toShare: Set(shareTypes), read: Set(readTypes)) { success, error in
                 DispatchQueue.main.async {
                     if success {
                         //we don't know which actual permissions were granted, so we assume all
@@ -349,6 +352,113 @@ public class HealthPlugin: CAPPlugin, CAPBridgedPlugin {
             healthStore.execute(query)
             return
         }
+        // ---- Special handling for REM sleep sessions (category samples) ----
+        if dataTypeString == "sleep-rem" {
+            guard let sleepType = HKObjectType.categoryType(forIdentifier: .sleepAnalysis) else {
+                call.reject("Sleep type not available")
+                return
+            }
+
+            let endDate = Date()
+            let startDate = Calendar.current.date(byAdding: .hour, value: -36, to: endDate) ?? endDate.addingTimeInterval(-36 * 3600)
+            let predicate = HKQuery.predicateForSamples(withStart: startDate, end: endDate, options: .strictEndDate)
+
+            let query = HKSampleQuery(sampleType: sleepType, predicate: predicate, limit: HKObjectQueryNoLimit, sortDescriptors: nil) { _, samples, error in
+                if let error = error {
+                    call.reject("Error fetching latest REM sleep sample", "NO_SAMPLE", error)
+                    return
+                }
+                guard let categorySamples = samples as? [HKCategorySample], !categorySamples.isEmpty else {
+                    call.reject("No REM sleep sample found", "NO_SAMPLE")
+                    return
+                }
+
+                let asleepValues: Set<Int> = {
+                    if #available(iOS 16.0, *) {
+                        return Set([
+                            HKCategoryValueSleepAnalysis.asleepUnspecified.rawValue,
+                            HKCategoryValueSleepAnalysis.asleepCore.rawValue,
+                            HKCategoryValueSleepAnalysis.asleepDeep.rawValue,
+                            HKCategoryValueSleepAnalysis.asleepREM.rawValue
+                        ])
+                    } else {
+                        return Set([HKCategoryValueSleepAnalysis.asleep.rawValue])
+                    }
+                }()
+
+                let remValue: Int? = {
+                    if #available(iOS 16.0, *) {
+                        return HKCategoryValueSleepAnalysis.asleepREM.rawValue
+                    }
+                    return nil
+                }()
+
+                func isAsleep(_ value: Int) -> Bool {
+                    if asleepValues.contains(value) {
+                        return true
+                    }
+                    return value != HKCategoryValueSleepAnalysis.inBed.rawValue &&
+                        value != HKCategoryValueSleepAnalysis.awake.rawValue
+                }
+
+                let asleepSamples = categorySamples
+                    .filter { isAsleep($0.value) }
+                    .sorted { $0.startDate < $1.startDate }
+
+                guard !asleepSamples.isEmpty else {
+                    call.reject("No REM sleep sample found", "NO_SAMPLE")
+                    return
+                }
+
+                let maxGap: TimeInterval = 90 * 60 // 90 minutes separates sessions
+                var sessions: [(start: Date, end: Date, duration: TimeInterval, remDuration: TimeInterval)] = []
+                var currentStart: Date?
+                var currentEnd: Date?
+                var currentDuration: TimeInterval = 0
+                var currentRemDuration: TimeInterval = 0
+
+                for sample in asleepSamples {
+                    if let lastEnd = currentEnd, sample.startDate.timeIntervalSince(lastEnd) > maxGap {
+                        sessions.append((start: currentStart ?? lastEnd, end: lastEnd, duration: currentDuration, remDuration: currentRemDuration))
+                        currentStart = nil
+                        currentEnd = nil
+                        currentDuration = 0
+                        currentRemDuration = 0
+                    }
+                    if currentStart == nil { currentStart = sample.startDate }
+                    currentEnd = sample.endDate
+                    let sampleDuration = sample.endDate.timeIntervalSince(sample.startDate)
+                    currentDuration += sampleDuration
+                    if let remValue = remValue, sample.value == remValue {
+                        currentRemDuration += sampleDuration
+                    }
+                }
+                if let start = currentStart, let end = currentEnd {
+                    sessions.append((start: start, end: end, duration: currentDuration, remDuration: currentRemDuration))
+                }
+
+                guard !sessions.isEmpty else {
+                    call.reject("No REM sleep sample found", "NO_SAMPLE")
+                    return
+                }
+
+                let minSessionDuration: TimeInterval = 3 * 3600 // prefer sessions 3h+
+                let preferredSession = sessions.reversed().first { $0.duration >= minSessionDuration } ?? sessions.last!
+                if preferredSession.remDuration <= 0 {
+                    call.reject("No REM sleep sample found", "NO_SAMPLE")
+                    return
+                }
+
+                call.resolve([
+                    "value": preferredSession.remDuration / 60,
+                    "timestamp": preferredSession.start.timeIntervalSince1970 * 1000,
+                    "endTimestamp": preferredSession.end.timeIntervalSince1970 * 1000,
+                    "unit": "min"
+                ])
+            }
+            healthStore.execute(query)
+            return
+        }
         // ---- Special handling for mindfulness sessions (category samples) ----
         if dataTypeString == "mindfulness" {
             guard let mindfulType = HKObjectType.categoryType(forIdentifier: .mindfulSession) else {
@@ -527,16 +637,29 @@ public class HealthPlugin: CAPPlugin, CAPBridgedPlugin {
                 HKObjectType.quantityType(forIdentifier: .activeEnergyBurned),
                 HKObjectType.quantityType(forIdentifier: .basalEnergyBurned)   // iOS 16+
             ].compactMap { $0 }
+        case "WRITE_TOTAL_CALORIES":
+            return [
+                HKObjectType.quantityType(forIdentifier: .activeEnergyBurned),
+                HKObjectType.quantityType(forIdentifier: .basalEnergyBurned)
+            ].compactMap { $0 }
         case "READ_ACTIVE_CALORIES":
             return [HKObjectType.quantityType(forIdentifier: .activeEnergyBurned)].compactMap{$0}
+        case "WRITE_ACTIVE_CALORIES":
+            return [HKObjectType.quantityType(forIdentifier: .activeEnergyBurned)].compactMap{$0}
         case "READ_WORKOUTS":
             return [HKObjectType.workoutType()].compactMap{$0}
+        case "WRITE_WORKOUTS":
+            return [HKObjectType.workoutType()].compactMap{$0}
         case "READ_HEART_RATE":
             return  [HKObjectType.quantityType(forIdentifier: .heartRate)].compactMap{$0}
+        case "WRITE_HEART_RATE":
+            return  [HKObjectType.quantityType(forIdentifier: .heartRate)].compactMap{$0}
         case "READ_RESTING_HEART_RATE":
             return [HKObjectType.quantityType(forIdentifier: .restingHeartRate)].compactMap { $0 }
         case "READ_ROUTE":
             return  [HKSeriesType.workoutRoute()].compactMap{$0}
+        case "WRITE_ROUTE":
+            return  [HKSeriesType.workoutRoute()].compactMap{$0}
         case "READ_DISTANCE":
             return [
                 HKObjectType.quantityType(forIdentifier: .distanceCycling),
@@ -544,6 +667,13 @@ public class HealthPlugin: CAPPlugin, CAPBridgedPlugin {
                 HKObjectType.quantityType(forIdentifier: .distanceWalkingRunning),
                 HKObjectType.quantityType(forIdentifier: .distanceDownhillSnowSports)
             ].compactMap{$0}
+        case "WRITE_DISTANCE":
+            return [
+                HKObjectType.quantityType(forIdentifier: .distanceCycling),
+                HKObjectType.quantityType(forIdentifier: .distanceSwimming),
+                HKObjectType.quantityType(forIdentifier: .distanceWalkingRunning),
+                HKObjectType.quantityType(forIdentifier: .distanceDownhillSnowSports)
+            ].compactMap{$0}
         case "READ_MINDFULNESS":
             return [HKObjectType.categoryType(forIdentifier: .mindfulSession)!].compactMap{$0}
         case "READ_HRV":
@@ -647,6 +777,34 @@ public class HealthPlugin: CAPPlugin, CAPBridgedPlugin {
         }
     }
 
+    func permissionToHKSampleType(_ permission: String) -> [HKSampleType] {
+        switch permission {
+        case "WRITE_WORKOUTS":
+            return [HKObjectType.workoutType()].compactMap { $0 as? HKSampleType }
+        case "WRITE_ACTIVE_CALORIES":
+            fallthrough
+        case "WRITE_TOTAL_CALORIES":
+            return [
+                HKObjectType.quantityType(forIdentifier: .activeEnergyBurned),
+                HKObjectType.quantityType(forIdentifier: .basalEnergyBurned)
+            ].compactMap { $0 as? HKSampleType }
+        case "WRITE_DISTANCE":
+            return [
+                HKObjectType.quantityType(forIdentifier: .distanceCycling),
+                HKObjectType.quantityType(forIdentifier: .distanceSwimming),
+                HKObjectType.quantityType(forIdentifier: .distanceWalkingRunning),
+                HKObjectType.quantityType(forIdentifier: .distanceDownhillSnowSports)
+            ].compactMap { $0 as? HKSampleType }
+        case "WRITE_HEART_RATE":
+            return [HKObjectType.quantityType(forIdentifier: .heartRate)].compactMap { $0 as? HKSampleType }
+        case "WRITE_ROUTE":
+            return [HKSeriesType.workoutRoute()].compactMap { $0 as? HKSampleType }
+        default:
+            // For convenience, allow read permissions that are sample types to be added to the share set when requested.
+            return permissionToHKObjectType(permission).compactMap { $0 as? HKSampleType }
+        }
+    }
+
     private func mapBiologicalSex(_ biologicalSex: HKBiologicalSex) -> String {
         switch biologicalSex {
         case .female:
@@ -1291,7 +1449,223 @@ public class HealthPlugin: CAPPlugin, CAPBridgedPlugin {
         f.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
         return f
     }()
+
+    private func parseDate(_ value: Any?) -> Date? {
+        if let date = value as? Date {
+            return date
+        }
+        if let str = value as? String {
+            if let parsed = isoDateFormatter.date(from: str) {
+                return parsed
+            }
+            if let millis = Double(str) {
+                return Date(timeIntervalSince1970: millis / 1000)
+            }
+        }
+        if let number = value as? NSNumber {
+            return Date(timeIntervalSince1970: number.doubleValue / 1000)
+        }
+        return nil
+    }
+
+    private func workoutActivityType(from value: String) -> HKWorkoutActivityType? {
+        let normalized = value.lowercased()
+        let mapping: [String: UInt] = [
+            "rock-climbing": 9,
+            "climbing": 9,
+            "hiking": 24,
+            "running": 37,
+            "walking": 52,
+            "cycling": 13,
+            "biking": 13,
+            "strength-training": 50,
+            "strength_training": 50,
+            "traditional-strength-training": 50,
+            "yoga": 57,
+            "other": 3000
+        ]
+
+        if let raw = mapping[normalized] {
+            return HKWorkoutActivityType(rawValue: raw)
+        }
+        return HKWorkoutActivityType.other
+    }
+
+    private func sanitizeMetadata(_ metadata: JSObject?) -> [String: Any]? {
+        guard let metadata = metadata else { return nil }
+        var cleaned: [String: Any] = [:]
+        for (key, value) in metadata {
+            switch value {
+            case let number as NSNumber:
+                cleaned[key] = number
+            case let string as NSString:
+                cleaned[key] = string
+            case let date as Date:
+                cleaned[key] = date
+            case let string as String:
+                cleaned[key] = string
+            default:
+                continue
+            }
+        }
+        return cleaned.isEmpty ? nil : cleaned
+    }
+
+    private func buildRouteLocations(from value: Any?, defaultDate: Date) -> [CLLocation] {
+        guard let routeItems = value as? [Any] else { return [] }
+        var locations: [CLLocation] = []
+
+        for case let point as JSObject in routeItems {
+            guard let lat = point["lat"] as? CLLocationDegrees,
+                  let lng = point["lng"] as? CLLocationDegrees else { continue }
+            let alt = (point["alt"] as? NSNumber)?.doubleValue ?? 0
+            let timestamp = parseDate(point["timestamp"]) ?? defaultDate
+            let location = CLLocation(
+                coordinate: CLLocationCoordinate2D(latitude: lat, longitude: lng),
+                altitude: alt,
+                horizontalAccuracy: kCLLocationAccuracyBest,
+                verticalAccuracy: kCLLocationAccuracyBest,
+                timestamp: timestamp
+            )
+            locations.append(location)
+        }
+
+        return locations.sorted { $0.timestamp < $1.timestamp }
+    }
+
+    private func buildHeartRateSamples(from value: Any?, defaultStart: Date, defaultEnd: Date) -> [HKQuantitySample] {
+        guard let arr = value as? [Any],
+              let type = HKObjectType.quantityType(forIdentifier: .heartRate) else { return [] }
+
+        let unit = HKUnit.count().unitDivided(by: HKUnit.minute())
+        var samples: [HKQuantitySample] = []
+        for case let point as JSObject in arr {
+            guard let bpm = point["bpm"] as? NSNumber else { continue }
+            let timestamp = parseDate(point["timestamp"]) ?? defaultStart
+            let quantity = HKQuantity(unit: unit, doubleValue: bpm.doubleValue)
+            let sample = HKQuantitySample(type: type, quantity: quantity, start: timestamp, end: timestamp)
+            samples.append(sample)
+        }
+
+        // Ensure samples fall within the workout window to avoid HK errors.
+        return samples
+            .filter { $0.startDate >= defaultStart && $0.endDate <= defaultEnd }
+            .sorted { $0.startDate < $1.startDate }
+    }
+    
     
+    @objc func saveWorkout(_ call: CAPPluginCall) {
+        guard HKHealthStore.isHealthDataAvailable() else {
+            call.reject("Health data is unavailable on this device.")
+            return
+        }
+
+        guard let activityTypeString = call.getString("activityType"),
+              let startDateString = call.getString("startDate"),
+              let endDateString = call.getString("endDate"),
+              let startDate = parseDate(startDateString),
+              let endDate = parseDate(endDateString) else {
+            call.reject("Missing or invalid parameters")
+            return
+        }
+
+        guard let activityType = workoutActivityType(from: activityTypeString) else {
+            call.reject("Unsupported activityType: \(activityTypeString)")
+            return
+        }
+
+        guard startDate < endDate else {
+            call.reject("startDate must be before endDate")
+            return
+        }
+
+        let energyQuantity: HKQuantity? = {
+            if let calories = call.getDouble("calories") {
+                return HKQuantity(unit: HKUnit.kilocalorie(), doubleValue: calories)
+            }
+            return nil
+        }()
+        let distanceQuantity: HKQuantity? = {
+            if let distance = call.getDouble("distance") {
+                return HKQuantity(unit: HKUnit.meter(), doubleValue: distance)
+            }
+            return nil
+        }()
+
+        let workout = HKWorkout(
+            activityType: activityType,
+            start: startDate,
+            end: endDate,
+            workoutEvents: nil,
+            totalEnergyBurned: energyQuantity,
+            totalDistance: distanceQuantity,
+            metadata: sanitizeMetadata(call.getObject("metadata"))
+        )
+
+        let routeLocations = buildRouteLocations(from: call.getArray("route"), defaultDate: startDate)
+        let heartRateSamples = buildHeartRateSamples(from: call.getArray("heartRateSamples"), defaultStart: startDate, defaultEnd: endDate)
+
+        healthStore.save(workout) { success, error in
+            DispatchQueue.main.async {
+                if let error = error {
+                    call.reject("Failed to save workout: \(error.localizedDescription)")
+                    return
+                }
+                guard success else {
+                    call.reject("Failed to save workout")
+                    return
+                }
+
+                if routeLocations.isEmpty && heartRateSamples.isEmpty {
+                    call.resolve(["success": true, "id": workout.uuid.uuidString])
+                    return
+                }
+
+                let group = DispatchGroup()
+                var saveError: String?
+
+                if !routeLocations.isEmpty {
+                    group.enter()
+                    let routeBuilder = HKWorkoutRouteBuilder(healthStore: self.healthStore, device: nil)
+                    routeBuilder.insertRouteData(routeLocations) { inserted, insertError in
+                        if let insertError = insertError {
+                            saveError = "Failed to insert route: \(insertError.localizedDescription)"
+                            group.leave()
+                            return
+                        }
+                        routeBuilder.finishRoute(with: workout, metadata: nil) { _, finishError in
+                            if let finishError = finishError {
+                                saveError = "Failed to finish route: \(finishError.localizedDescription)"
+                            } else if !inserted {
+                                saveError = "Failed to insert route"
+                            }
+                            group.leave()
+                        }
+                    }
+                }
+
+                if !heartRateSamples.isEmpty {
+                    group.enter()
+                    self.healthStore.add(heartRateSamples, to: workout) { hrSuccess, hrError in
+                        if let hrError = hrError {
+                            saveError = "Failed to save heart rate samples: \(hrError.localizedDescription)"
+                        } else if !hrSuccess {
+                            saveError = "Failed to save heart rate samples"
+                        }
+                        group.leave()
+                    }
+                }
+
+                group.notify(queue: .main) {
+                    if let saveError = saveError {
+                        call.reject(saveError)
+                    } else {
+                        call.resolve(["success": true, "id": workout.uuid.uuidString])
+                    }
+                }
+            }
+        }
+    }
     
     @objc func queryWorkouts(_ call: CAPPluginCall) {
         guard let startDateString =  call.getString("startDate"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flomentumsolutions/capacitor-health-extended",
-  "version": "0.6.3",
+  "version": "0.7.0",
   "description": "Capacitor plugin for Apple HealthKit and Google Health Connect Platform",
   "main": "dist/plugin.cjs.js",
   "module": "dist/esm/index.js",