@capgo/capacitor-health 8.5.2 → 8.6.0

package/README.md

@@ -553,11 +553,25 @@ Supported on iOS (HealthKit) and Android (Health Connect).
 | **`sourceId`**          | <code>string</code>                                       |                                                                                                     |
 | **`platformId`**        | <code>string</code>                                       | Platform-specific unique identifier (HealthKit UUID on iOS, Health Connect metadata ID on Android). |
 | **`sleepState`**        | <code><a href="#sleepstate">SleepState</a></code>         | For sleep data, indicates the sleep state (e.g., 'asleep', 'awake', 'rem', 'deep', 'light').        |
+| **`stages`**            | <code>SleepStage[]</code>                                 | For sleep data, individual sleep stages when the platform exposes stage-level data.                 |
+| **`hasStageData`**      | <code>boolean</code>                                      | For sleep data, indicates whether stage-level data was emitted.                                     |
 | **`systolic`**          | <code>number</code>                                       | For blood pressure data, the systolic value in mmHg.                                                |
 | **`diastolic`**         | <code>number</code>                                       | For blood pressure data, the diastolic value in mmHg.                                               |
 | **`measurementMethod`** | <code>number</code>                                       | For VO2 max data on Android, Health Connect's measurement method enum value.                        |
 
 
+#### SleepStage
+
+Stage-level sleep segment emitted for sleep samples when platform data is available.
+
+| Prop                  | Type                                              | Description                                  |
+| --------------------- | ------------------------------------------------- | -------------------------------------------- |
+| **`startDate`**       | <code>string</code>                               | Stage segment start date in ISO 8601 format. |
+| **`endDate`**         | <code>string</code>                               | Stage segment end date in ISO 8601 format.   |
+| **`stage`**           | <code><a href="#sleepstate">SleepState</a></code> | Sleep stage label for this segment.          |
+| **`durationMinutes`** | <code>number</code>                               | Duration of this stage segment in minutes.   |
+
+
 #### QueryOptions
 
 | Prop            | Type                                                      | Description                                                        |

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

@@ -169,7 +169,6 @@ class HealthManager {
                 }
             }
             HealthDataType.SLEEP -> readRecords(client, SleepSessionRecord::class, startTime, endTime, limit) { record ->
-                // For sleep sessions, calculate duration in minutes
                 val durationMinutes = Duration.between(record.startTime, record.endTime).toMinutes().toDouble()
                 val payload = createSamplePayload(
                     dataType,
@@ -178,10 +177,24 @@ class HealthManager {
                     durationMinutes,
                     record.metadata
                 )
-                // Add sleep stage if available (map from sleep session stages)
-                // Note: SleepSessionRecord doesn't have individual stages in the main record
-                // Individual sleep stages would be in SleepStageRecord, but for simplicity
-                // we'll just return the session duration
+                // Expose individual sleep stages when present (Samsung Health, Mi Health,
+                // Apple Health, and other writers typically populate SleepSessionRecord.stages).
+                val stagesArray = JSArray()
+                record.stages.forEach { stage ->
+                    val stageString = mapSleepStageToString(stage.stage) ?: return@forEach
+                    val stageObj = JSObject()
+                    stageObj.put("startDate", formatter.format(stage.startTime))
+                    stageObj.put("endDate", formatter.format(stage.endTime))
+                    stageObj.put("stage", stageString)
+                    stageObj.put("durationMinutes", Duration.between(stage.startTime, stage.endTime).toMinutes().toDouble())
+                    stagesArray.put(stageObj)
+                }
+                val hasNormalizedStages = stagesArray.length() > 0
+                if (hasNormalizedStages) {
+                    payload.put("stages", stagesArray)
+                }
+                payload.put("hasStageData", hasNormalizedStages)
+
                 samples.add(record.startTime to payload)
             }
             HealthDataType.RESPIRATORY_RATE -> readRecords(client, RespiratoryRateRecord::class, startTime, endTime, limit) { record ->
@@ -630,8 +643,18 @@ class HealthManager {
         }
         return Instant.parse(value)
     }
-
-    private fun createSamplePayload(
+private fun mapSleepStageToString(stage: Int): String? {
+        return when (stage) {
+            SleepSessionRecord.STAGE_TYPE_AWAKE -> "awake"
+            SleepSessionRecord.STAGE_TYPE_AWAKE_IN_BED -> "awake"
+            SleepSessionRecord.STAGE_TYPE_SLEEPING -> "asleep"
+            SleepSessionRecord.STAGE_TYPE_LIGHT -> "light"
+            SleepSessionRecord.STAGE_TYPE_DEEP -> "deep"
+            SleepSessionRecord.STAGE_TYPE_REM -> "rem"
+            else -> null  // OUT_OF_BED, UNKNOWN: filtered out by caller
+        }
+    }
+private fun createSamplePayload(
         dataType: HealthDataType,
         startTime: Instant,
         endTime: Instant,

package/dist/docs.json

@@ -405,6 +405,22 @@
           ],
           "type": "SleepState"
         },
+        {
+          "name": "stages",
+          "tags": [],
+          "docs": "For sleep data, individual sleep stages when the platform exposes stage-level data.",
+          "complexTypes": [
+            "SleepStage"
+          ],
+          "type": "SleepStage[] | undefined"
+        },
+        {
+          "name": "hasStageData",
+          "tags": [],
+          "docs": "For sleep data, indicates whether stage-level data was emitted.",
+          "complexTypes": [],
+          "type": "boolean | undefined"
+        },
         {
           "name": "systolic",
           "tags": [],
@@ -428,6 +444,45 @@
         }
       ]
     },
+    {
+      "name": "SleepStage",
+      "slug": "sleepstage",
+      "docs": "Stage-level sleep segment emitted for sleep samples when platform data is available.",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "startDate",
+          "tags": [],
+          "docs": "Stage segment start date in ISO 8601 format.",
+          "complexTypes": [],
+          "type": "string"
+        },
+        {
+          "name": "endDate",
+          "tags": [],
+          "docs": "Stage segment end date in ISO 8601 format.",
+          "complexTypes": [],
+          "type": "string"
+        },
+        {
+          "name": "stage",
+          "tags": [],
+          "docs": "Sleep stage label for this segment.",
+          "complexTypes": [
+            "SleepState"
+          ],
+          "type": "SleepState"
+        },
+        {
+          "name": "durationMinutes",
+          "tags": [],
+          "docs": "Duration of this stage segment in minutes.",
+          "complexTypes": [],
+          "type": "number"
+        }
+      ]
+    },
     {
       "name": "QueryOptions",
       "slug": "queryoptions",

package/dist/esm/definitions.d.ts

@@ -31,6 +31,17 @@ export interface QueryOptions {
     ascending?: boolean;
 }
 export type SleepState = 'inBed' | 'asleep' | 'awake' | 'rem' | 'deep' | 'light';
+/** Stage-level sleep segment emitted for sleep samples when platform data is available. */
+export interface SleepStage {
+    /** Stage segment start date in ISO 8601 format. */
+    startDate: string;
+    /** Stage segment end date in ISO 8601 format. */
+    endDate: string;
+    /** Sleep stage label for this segment. */
+    stage: SleepState;
+    /** Duration of this stage segment in minutes. */
+    durationMinutes: number;
+}
 export interface HealthSample {
     dataType: HealthDataType;
     value: number;
@@ -43,6 +54,10 @@ export interface HealthSample {
     platformId?: string;
     /** For sleep data, indicates the sleep state (e.g., 'asleep', 'awake', 'rem', 'deep', 'light'). */
     sleepState?: SleepState;
+    /** For sleep data, individual sleep stages when the platform exposes stage-level data. */
+    stages?: SleepStage[];
+    /** For sleep data, indicates whether stage-level data was emitted. */
+    hasStageData?: boolean;
     /** For blood pressure data, the systolic value in mmHg. */
     systolic?: number;
     /** For blood pressure data, the diastolic value in mmHg. */

package/dist/esm/definitions.js.map

@@ -1 +1 @@
-{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["export type HealthDataType =\n  | 'steps'\n  | 'distance'\n  | 'calories'\n  | 'heartRate'\n  | 'weight'\n  | 'sleep'\n  | 'respiratoryRate'\n  | 'oxygenSaturation'\n  | 'restingHeartRate'\n  | 'heartRateVariability'\n  | 'vo2Max'\n  | 'bloodPressure'\n  | 'bloodGlucose'\n  | 'bodyTemperature'\n  | 'height'\n  | 'flightsClimbed'\n  | 'exerciseTime'\n  | 'distanceCycling'\n  | 'bodyFat'\n  | 'basalBodyTemperature'\n  | 'basalCalories'\n  | 'totalCalories'\n  | 'mindfulness'\n  | 'workouts';\n\nexport type HealthUnit =\n  | 'count'\n  | 'meter'\n  | 'kilocalorie'\n  | 'bpm'\n  | 'kilogram'\n  | 'minute'\n  | 'percent'\n  | 'millisecond'\n  | 'mL/min/kg'\n  | 'mmHg'\n  | 'mg/dL'\n  | 'celsius'\n  | 'fahrenheit'\n  | 'centimeter';\n\nexport interface AuthorizationOptions {\n  /** Data types that should be readable after authorization. */\n  read?: HealthDataType[];\n  /** Data types that should be writable after authorization. */\n  write?: HealthDataType[];\n}\n\nexport interface AuthorizationStatus {\n  readAuthorized: HealthDataType[];\n  readDenied: HealthDataType[];\n  writeAuthorized: HealthDataType[];\n  writeDenied: HealthDataType[];\n}\n\nexport interface AvailabilityResult {\n  available: boolean;\n  /** Platform specific details (for debugging/diagnostics). */\n  platform?: 'ios' | 'android' | 'web';\n  reason?: string;\n}\n\nexport interface QueryOptions {\n  /** The type of data to retrieve from the health store. */\n  dataType: HealthDataType;\n  /** Inclusive ISO 8601 start date (defaults to now - 1 day). */\n  startDate?: string;\n  /** Exclusive ISO 8601 end date (defaults to now). */\n  endDate?: string;\n  /** Maximum number of samples to return (defaults to 100). */\n  limit?: number;\n  /** Return results sorted ascending by start date (defaults to false). */\n  ascending?: boolean;\n}\n\nexport type SleepState = 'inBed' | 'asleep' | 'awake' | 'rem' | 'deep' | 'light';\n\nexport interface HealthSample {\n  dataType: HealthDataType;\n  value: number;\n  unit: HealthUnit;\n  startDate: string;\n  endDate: string;\n  sourceName?: string;\n  sourceId?: string;\n  /** Platform-specific unique identifier (HealthKit UUID on iOS, Health Connect metadata ID on Android). */\n  platformId?: string;\n  /** For sleep data, indicates the sleep state (e.g., 'asleep', 'awake', 'rem', 'deep', 'light'). */\n  sleepState?: SleepState;\n  /** For blood pressure data, the systolic value in mmHg. */\n  systolic?: number;\n  /** For blood pressure data, the diastolic value in mmHg. */\n  diastolic?: number;\n  /** For VO2 max data on Android, Health Connect's measurement method enum value. */\n  measurementMethod?: number;\n}\n\nexport interface ReadSamplesResult {\n  samples: HealthSample[];\n}\n\nexport type WorkoutType =\n  // Common types (supported on both platforms)\n  | 'americanFootball'\n  | 'australianFootball'\n  | 'badminton'\n  | 'baseball'\n  | 'basketball'\n  | 'bowling'\n  | 'boxing'\n  | 'climbing'\n  | 'cricket'\n  | 'crossTraining'\n  | 'curling'\n  | 'cycling'\n  | 'dance'\n  | 'elliptical'\n  | 'fencing'\n  | 'functionalStrengthTraining'\n  | 'golf'\n  | 'gymnastics'\n  | 'handball'\n  | 'hiking'\n  | 'hockey'\n  | 'jumpRope'\n  | 'kickboxing'\n  | 'lacrosse'\n  | 'martialArts'\n  | 'pilates'\n  | 'racquetball'\n  | 'rowing'\n  | 'rugby'\n  | 'running'\n  | 'sailing'\n  | 'skatingSports'\n  | 'skiing'\n  | 'snowboarding'\n  | 'soccer'\n  | 'softball'\n  | 'squash'\n  | 'stairClimbing'\n  | 'strengthTraining'\n  | 'surfing'\n  | 'swimming'\n  | 'swimmingPool'\n  | 'swimmingOpenWater'\n  | 'tableTennis'\n  | 'tennis'\n  | 'trackAndField'\n  | 'traditionalStrengthTraining'\n  | 'volleyball'\n  | 'walking'\n  | 'waterFitness'\n  | 'waterPolo'\n  | 'waterSports'\n  | 'weightlifting'\n  | 'wheelchair'\n  | 'yoga'\n  // iOS specific types\n  | 'archery'\n  | 'barre'\n  | 'cooldown'\n  | 'coreTraining'\n  | 'crossCountrySkiing'\n  | 'discSports'\n  | 'downhillSkiing'\n  | 'equestrianSports'\n  | 'fishing'\n  | 'fitnessGaming'\n  | 'flexibility'\n  | 'handCycling'\n  | 'highIntensityIntervalTraining'\n  | 'hunting'\n  | 'mindAndBody'\n  | 'mixedCardio'\n  | 'paddleSports'\n  | 'pickleball'\n  | 'play'\n  | 'preparationAndRecovery'\n  | 'snowSports'\n  | 'stairs'\n  | 'stepTraining'\n  | 'surfingSports'\n  | 'taiChi'\n  | 'transition'\n  | 'underwaterDiving'\n  | 'wheelchairRunPace'\n  | 'wheelchairWalkPace'\n  | 'wrestling'\n  | 'cardioDance'\n  | 'socialDance'\n  // Android specific types\n  | 'backExtension'\n  | 'barbellShoulderPress'\n  | 'benchPress'\n  | 'benchSitUp'\n  | 'bikingStationary'\n  | 'bootCamp'\n  | 'burpee'\n  | 'calisthenics'\n  | 'crunch'\n  | 'dancing'\n  | 'deadlift'\n  | 'dumbbellCurlLeftArm'\n  | 'dumbbellCurlRightArm'\n  | 'dumbbellFrontRaise'\n  | 'dumbbellLateralRaise'\n  | 'dumbbellTricepsExtensionLeftArm'\n  | 'dumbbellTricepsExtensionRightArm'\n  | 'dumbbellTricepsExtensionTwoArm'\n  | 'exerciseClass'\n  | 'forwardTwist'\n  | 'frisbeedisc'\n  | 'guidedBreathing'\n  | 'iceHockey'\n  | 'iceSkating'\n  | 'jumpingJack'\n  | 'latPullDown'\n  | 'lunge'\n  | 'meditation'\n  | 'paddling'\n  | 'paraGliding'\n  | 'plank'\n  | 'rockClimbing'\n  | 'rollerHockey'\n  | 'rowingMachine'\n  | 'runningTreadmill'\n  | 'scubaDiving'\n  | 'skating'\n  | 'snowshoeing'\n  | 'stairClimbingMachine'\n  | 'stretching'\n  | 'upperTwist'\n  | 'other';\n\nexport interface QueryWorkoutsOptions {\n  /** Optional workout type filter. If omitted, all workout types are returned. */\n  workoutType?: WorkoutType;\n  /** Inclusive ISO 8601 start date (defaults to now - 1 day). */\n  startDate?: string;\n  /** Exclusive ISO 8601 end date (defaults to now). */\n  endDate?: string;\n  /** Maximum number of workouts to return (defaults to 100). */\n  limit?: number;\n  /** Return results sorted ascending by start date (defaults to false). */\n  ascending?: boolean;\n  /**\n   * Anchor for pagination. Use the anchor returned from a previous query to continue from that point.\n   * On iOS, this is the ISO 8601 cursor returned by the previous query. On Android, this uses\n   * Health Connect's pageToken.\n   * Omit this parameter to start from the beginning.\n   */\n  anchor?: string;\n}\n\nexport interface Workout {\n  /** The type of workout. */\n  workoutType: WorkoutType;\n  /** Duration of the workout in seconds. */\n  duration: number;\n  /** Total energy burned in kilocalories (if available). */\n  totalEnergyBurned?: number;\n  /** Total distance in meters (if available). */\n  totalDistance?: number;\n  /** ISO 8601 start date of the workout. */\n  startDate: string;\n  /** ISO 8601 end date of the workout. */\n  endDate: string;\n  /** Source name that recorded the workout. */\n  sourceName?: string;\n  /** Source bundle identifier. */\n  sourceId?: string;\n  /** Platform-specific unique identifier (HealthKit UUID on iOS, Health Connect metadata ID on Android). */\n  platformId?: string;\n  /** Additional metadata (if available). */\n  metadata?: Record<string, string>;\n}\n\nexport interface QueryWorkoutsResult {\n  workouts: Workout[];\n  /**\n   * Anchor for the next page of results. Pass this value as the anchor parameter in the next query\n   * to continue pagination. If undefined or null, there are no more results.\n   */\n  anchor?: string;\n}\n\nexport interface WriteSampleOptions {\n  dataType: HealthDataType;\n  value: number;\n  /**\n   * Optional unit override. If omitted, the default unit for the data type is used\n   * (count for `steps`, meter for `distance`, kilocalorie for `calories`, bpm for `heartRate`, kilogram for `weight`).\n   */\n  unit?: HealthUnit;\n  /** ISO 8601 start date for the sample. Defaults to now. */\n  startDate?: string;\n  /** ISO 8601 end date for the sample. Defaults to startDate. */\n  endDate?: string;\n  /** Metadata key-value pairs forwarded to the native APIs where supported. */\n  metadata?: Record<string, string>;\n  /** For blood pressure data, the systolic value in mmHg. Required when dataType is 'bloodPressure'. */\n  systolic?: number;\n  /** For blood pressure data, the diastolic value in mmHg. Required when dataType is 'bloodPressure'. */\n  diastolic?: number;\n}\n\nexport type BucketType = 'hour' | 'day' | 'week' | 'month';\n\nexport type AggregationType = 'sum' | 'average' | 'min' | 'max';\n\nexport interface QueryAggregatedOptions {\n  /** The type of data to aggregate from the health store. */\n  dataType: HealthDataType;\n  /** Inclusive ISO 8601 start date (defaults to now - 1 day). */\n  startDate?: string;\n  /** Exclusive ISO 8601 end date (defaults to now). */\n  endDate?: string;\n  /** Time bucket for aggregation (defaults to 'day'). */\n  bucket?: BucketType;\n  /** Aggregation operation to perform (defaults to 'sum'). */\n  aggregation?: AggregationType;\n}\n\nexport interface AggregatedSample {\n  /** ISO 8601 start date of the bucket. */\n  startDate: string;\n  /** ISO 8601 end date of the bucket. */\n  endDate: string;\n  /** Aggregated value for the bucket. */\n  value: number;\n  /** Unit of the aggregated value. */\n  unit: HealthUnit;\n}\n\nexport interface QueryAggregatedResult {\n  samples: AggregatedSample[];\n}\n\nexport interface HealthPlugin {\n  /** Returns whether the current platform supports the native health SDK. */\n  isAvailable(): Promise<AvailabilityResult>;\n  /** Requests read/write access to the provided data types. */\n  requestAuthorization(options: AuthorizationOptions): Promise<AuthorizationStatus>;\n  /** Checks authorization status for the provided data types without prompting the user. */\n  checkAuthorization(options: AuthorizationOptions): Promise<AuthorizationStatus>;\n  /** Reads samples for the given data type within the specified time frame. */\n  readSamples(options: QueryOptions): Promise<ReadSamplesResult>;\n  /** Writes a single sample to the native health store. */\n  saveSample(options: WriteSampleOptions): Promise<void>;\n\n  /**\n   * Get the native Capacitor plugin version\n   *\n   * @returns {Promise<{ version: string }>} a Promise with version for this device\n   * @throws An error if something went wrong\n   */\n  getPluginVersion(): Promise<{ version: string }>;\n\n  /**\n   * Opens the Health Connect settings screen (Android only).\n   * On iOS, this method does nothing.\n   *\n   * Use this to direct users to manage their Health Connect permissions\n   * or to install Health Connect if not available.\n   *\n   * @throws An error if Health Connect settings cannot be opened\n   */\n  openHealthConnectSettings(): Promise<void>;\n\n  /**\n   * Shows the app's privacy policy for Health Connect (Android only).\n   * On iOS, this method does nothing.\n   *\n   * This displays the same privacy policy screen that Health Connect shows\n   * when the user taps \"Privacy policy\" in the permissions dialog.\n   *\n   * The privacy policy URL can be configured by adding a string resource\n   * named \"health_connect_privacy_policy_url\" in your app's strings.xml,\n   * or by placing an HTML file at www/privacypolicy.html in your assets.\n   *\n   * @throws An error if the privacy policy cannot be displayed\n   */\n  showPrivacyPolicy(): Promise<void>;\n\n  /**\n   * Queries workout sessions from the native health store.\n   * Supported on iOS (HealthKit) and Android (Health Connect).\n   *\n   * @param options Query options including optional workout type filter, date range, limit, and sort order\n   * @returns A promise that resolves with the workout sessions\n   * @throws An error if something went wrong\n   */\n  queryWorkouts(options: QueryWorkoutsOptions): Promise<QueryWorkoutsResult>;\n\n  /**\n   * Queries aggregated health data from the native health store.\n   * Aggregates data into time buckets (hour, day, week, month) with operations like sum, average, min, or max.\n   * This is more efficient than fetching individual samples for large date ranges.\n   *\n   * Supported on iOS (HealthKit) and Android (Health Connect).\n   *\n   * @param options Query options including data type, date range, bucket size, and aggregation type\n   * @returns A promise that resolves with the aggregated samples\n   * @throws An error if something went wrong\n   */\n  queryAggregated(options: QueryAggregatedOptions): Promise<QueryAggregatedResult>;\n}\n"]}
+{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["export type HealthDataType =\n  | 'steps'\n  | 'distance'\n  | 'calories'\n  | 'heartRate'\n  | 'weight'\n  | 'sleep'\n  | 'respiratoryRate'\n  | 'oxygenSaturation'\n  | 'restingHeartRate'\n  | 'heartRateVariability'\n  | 'vo2Max'\n  | 'bloodPressure'\n  | 'bloodGlucose'\n  | 'bodyTemperature'\n  | 'height'\n  | 'flightsClimbed'\n  | 'exerciseTime'\n  | 'distanceCycling'\n  | 'bodyFat'\n  | 'basalBodyTemperature'\n  | 'basalCalories'\n  | 'totalCalories'\n  | 'mindfulness'\n  | 'workouts';\n\nexport type HealthUnit =\n  | 'count'\n  | 'meter'\n  | 'kilocalorie'\n  | 'bpm'\n  | 'kilogram'\n  | 'minute'\n  | 'percent'\n  | 'millisecond'\n  | 'mL/min/kg'\n  | 'mmHg'\n  | 'mg/dL'\n  | 'celsius'\n  | 'fahrenheit'\n  | 'centimeter';\n\nexport interface AuthorizationOptions {\n  /** Data types that should be readable after authorization. */\n  read?: HealthDataType[];\n  /** Data types that should be writable after authorization. */\n  write?: HealthDataType[];\n}\n\nexport interface AuthorizationStatus {\n  readAuthorized: HealthDataType[];\n  readDenied: HealthDataType[];\n  writeAuthorized: HealthDataType[];\n  writeDenied: HealthDataType[];\n}\n\nexport interface AvailabilityResult {\n  available: boolean;\n  /** Platform specific details (for debugging/diagnostics). */\n  platform?: 'ios' | 'android' | 'web';\n  reason?: string;\n}\n\nexport interface QueryOptions {\n  /** The type of data to retrieve from the health store. */\n  dataType: HealthDataType;\n  /** Inclusive ISO 8601 start date (defaults to now - 1 day). */\n  startDate?: string;\n  /** Exclusive ISO 8601 end date (defaults to now). */\n  endDate?: string;\n  /** Maximum number of samples to return (defaults to 100). */\n  limit?: number;\n  /** Return results sorted ascending by start date (defaults to false). */\n  ascending?: boolean;\n}\n\nexport type SleepState = 'inBed' | 'asleep' | 'awake' | 'rem' | 'deep' | 'light';\n\n/** Stage-level sleep segment emitted for sleep samples when platform data is available. */\nexport interface SleepStage {\n  /** Stage segment start date in ISO 8601 format. */\n  startDate: string;\n  /** Stage segment end date in ISO 8601 format. */\n  endDate: string;\n  /** Sleep stage label for this segment. */\n  stage: SleepState;\n  /** Duration of this stage segment in minutes. */\n  durationMinutes: number;\n}\n\nexport interface HealthSample {\n  dataType: HealthDataType;\n  value: number;\n  unit: HealthUnit;\n  startDate: string;\n  endDate: string;\n  sourceName?: string;\n  sourceId?: string;\n  /** Platform-specific unique identifier (HealthKit UUID on iOS, Health Connect metadata ID on Android). */\n  platformId?: string;\n  /** For sleep data, indicates the sleep state (e.g., 'asleep', 'awake', 'rem', 'deep', 'light'). */\n  sleepState?: SleepState;\n  /** For sleep data, individual sleep stages when the platform exposes stage-level data. */\n  stages?: SleepStage[];\n  /** For sleep data, indicates whether stage-level data was emitted. */\n  hasStageData?: boolean;\n  /** For blood pressure data, the systolic value in mmHg. */\n  systolic?: number;\n  /** For blood pressure data, the diastolic value in mmHg. */\n  diastolic?: number;\n  /** For VO2 max data on Android, Health Connect's measurement method enum value. */\n  measurementMethod?: number;\n}\n\nexport interface ReadSamplesResult {\n  samples: HealthSample[];\n}\n\nexport type WorkoutType =\n  // Common types (supported on both platforms)\n  | 'americanFootball'\n  | 'australianFootball'\n  | 'badminton'\n  | 'baseball'\n  | 'basketball'\n  | 'bowling'\n  | 'boxing'\n  | 'climbing'\n  | 'cricket'\n  | 'crossTraining'\n  | 'curling'\n  | 'cycling'\n  | 'dance'\n  | 'elliptical'\n  | 'fencing'\n  | 'functionalStrengthTraining'\n  | 'golf'\n  | 'gymnastics'\n  | 'handball'\n  | 'hiking'\n  | 'hockey'\n  | 'jumpRope'\n  | 'kickboxing'\n  | 'lacrosse'\n  | 'martialArts'\n  | 'pilates'\n  | 'racquetball'\n  | 'rowing'\n  | 'rugby'\n  | 'running'\n  | 'sailing'\n  | 'skatingSports'\n  | 'skiing'\n  | 'snowboarding'\n  | 'soccer'\n  | 'softball'\n  | 'squash'\n  | 'stairClimbing'\n  | 'strengthTraining'\n  | 'surfing'\n  | 'swimming'\n  | 'swimmingPool'\n  | 'swimmingOpenWater'\n  | 'tableTennis'\n  | 'tennis'\n  | 'trackAndField'\n  | 'traditionalStrengthTraining'\n  | 'volleyball'\n  | 'walking'\n  | 'waterFitness'\n  | 'waterPolo'\n  | 'waterSports'\n  | 'weightlifting'\n  | 'wheelchair'\n  | 'yoga'\n  // iOS specific types\n  | 'archery'\n  | 'barre'\n  | 'cooldown'\n  | 'coreTraining'\n  | 'crossCountrySkiing'\n  | 'discSports'\n  | 'downhillSkiing'\n  | 'equestrianSports'\n  | 'fishing'\n  | 'fitnessGaming'\n  | 'flexibility'\n  | 'handCycling'\n  | 'highIntensityIntervalTraining'\n  | 'hunting'\n  | 'mindAndBody'\n  | 'mixedCardio'\n  | 'paddleSports'\n  | 'pickleball'\n  | 'play'\n  | 'preparationAndRecovery'\n  | 'snowSports'\n  | 'stairs'\n  | 'stepTraining'\n  | 'surfingSports'\n  | 'taiChi'\n  | 'transition'\n  | 'underwaterDiving'\n  | 'wheelchairRunPace'\n  | 'wheelchairWalkPace'\n  | 'wrestling'\n  | 'cardioDance'\n  | 'socialDance'\n  // Android specific types\n  | 'backExtension'\n  | 'barbellShoulderPress'\n  | 'benchPress'\n  | 'benchSitUp'\n  | 'bikingStationary'\n  | 'bootCamp'\n  | 'burpee'\n  | 'calisthenics'\n  | 'crunch'\n  | 'dancing'\n  | 'deadlift'\n  | 'dumbbellCurlLeftArm'\n  | 'dumbbellCurlRightArm'\n  | 'dumbbellFrontRaise'\n  | 'dumbbellLateralRaise'\n  | 'dumbbellTricepsExtensionLeftArm'\n  | 'dumbbellTricepsExtensionRightArm'\n  | 'dumbbellTricepsExtensionTwoArm'\n  | 'exerciseClass'\n  | 'forwardTwist'\n  | 'frisbeedisc'\n  | 'guidedBreathing'\n  | 'iceHockey'\n  | 'iceSkating'\n  | 'jumpingJack'\n  | 'latPullDown'\n  | 'lunge'\n  | 'meditation'\n  | 'paddling'\n  | 'paraGliding'\n  | 'plank'\n  | 'rockClimbing'\n  | 'rollerHockey'\n  | 'rowingMachine'\n  | 'runningTreadmill'\n  | 'scubaDiving'\n  | 'skating'\n  | 'snowshoeing'\n  | 'stairClimbingMachine'\n  | 'stretching'\n  | 'upperTwist'\n  | 'other';\n\nexport interface QueryWorkoutsOptions {\n  /** Optional workout type filter. If omitted, all workout types are returned. */\n  workoutType?: WorkoutType;\n  /** Inclusive ISO 8601 start date (defaults to now - 1 day). */\n  startDate?: string;\n  /** Exclusive ISO 8601 end date (defaults to now). */\n  endDate?: string;\n  /** Maximum number of workouts to return (defaults to 100). */\n  limit?: number;\n  /** Return results sorted ascending by start date (defaults to false). */\n  ascending?: boolean;\n  /**\n   * Anchor for pagination. Use the anchor returned from a previous query to continue from that point.\n   * On iOS, this is the ISO 8601 cursor returned by the previous query. On Android, this uses\n   * Health Connect's pageToken.\n   * Omit this parameter to start from the beginning.\n   */\n  anchor?: string;\n}\n\nexport interface Workout {\n  /** The type of workout. */\n  workoutType: WorkoutType;\n  /** Duration of the workout in seconds. */\n  duration: number;\n  /** Total energy burned in kilocalories (if available). */\n  totalEnergyBurned?: number;\n  /** Total distance in meters (if available). */\n  totalDistance?: number;\n  /** ISO 8601 start date of the workout. */\n  startDate: string;\n  /** ISO 8601 end date of the workout. */\n  endDate: string;\n  /** Source name that recorded the workout. */\n  sourceName?: string;\n  /** Source bundle identifier. */\n  sourceId?: string;\n  /** Platform-specific unique identifier (HealthKit UUID on iOS, Health Connect metadata ID on Android). */\n  platformId?: string;\n  /** Additional metadata (if available). */\n  metadata?: Record<string, string>;\n}\n\nexport interface QueryWorkoutsResult {\n  workouts: Workout[];\n  /**\n   * Anchor for the next page of results. Pass this value as the anchor parameter in the next query\n   * to continue pagination. If undefined or null, there are no more results.\n   */\n  anchor?: string;\n}\n\nexport interface WriteSampleOptions {\n  dataType: HealthDataType;\n  value: number;\n  /**\n   * Optional unit override. If omitted, the default unit for the data type is used\n   * (count for `steps`, meter for `distance`, kilocalorie for `calories`, bpm for `heartRate`, kilogram for `weight`).\n   */\n  unit?: HealthUnit;\n  /** ISO 8601 start date for the sample. Defaults to now. */\n  startDate?: string;\n  /** ISO 8601 end date for the sample. Defaults to startDate. */\n  endDate?: string;\n  /** Metadata key-value pairs forwarded to the native APIs where supported. */\n  metadata?: Record<string, string>;\n  /** For blood pressure data, the systolic value in mmHg. Required when dataType is 'bloodPressure'. */\n  systolic?: number;\n  /** For blood pressure data, the diastolic value in mmHg. Required when dataType is 'bloodPressure'. */\n  diastolic?: number;\n}\n\nexport type BucketType = 'hour' | 'day' | 'week' | 'month';\n\nexport type AggregationType = 'sum' | 'average' | 'min' | 'max';\n\nexport interface QueryAggregatedOptions {\n  /** The type of data to aggregate from the health store. */\n  dataType: HealthDataType;\n  /** Inclusive ISO 8601 start date (defaults to now - 1 day). */\n  startDate?: string;\n  /** Exclusive ISO 8601 end date (defaults to now). */\n  endDate?: string;\n  /** Time bucket for aggregation (defaults to 'day'). */\n  bucket?: BucketType;\n  /** Aggregation operation to perform (defaults to 'sum'). */\n  aggregation?: AggregationType;\n}\n\nexport interface AggregatedSample {\n  /** ISO 8601 start date of the bucket. */\n  startDate: string;\n  /** ISO 8601 end date of the bucket. */\n  endDate: string;\n  /** Aggregated value for the bucket. */\n  value: number;\n  /** Unit of the aggregated value. */\n  unit: HealthUnit;\n}\n\nexport interface QueryAggregatedResult {\n  samples: AggregatedSample[];\n}\n\nexport interface HealthPlugin {\n  /** Returns whether the current platform supports the native health SDK. */\n  isAvailable(): Promise<AvailabilityResult>;\n  /** Requests read/write access to the provided data types. */\n  requestAuthorization(options: AuthorizationOptions): Promise<AuthorizationStatus>;\n  /** Checks authorization status for the provided data types without prompting the user. */\n  checkAuthorization(options: AuthorizationOptions): Promise<AuthorizationStatus>;\n  /** Reads samples for the given data type within the specified time frame. */\n  readSamples(options: QueryOptions): Promise<ReadSamplesResult>;\n  /** Writes a single sample to the native health store. */\n  saveSample(options: WriteSampleOptions): Promise<void>;\n\n  /**\n   * Get the native Capacitor plugin version\n   *\n   * @returns {Promise<{ version: string }>} a Promise with version for this device\n   * @throws An error if something went wrong\n   */\n  getPluginVersion(): Promise<{ version: string }>;\n\n  /**\n   * Opens the Health Connect settings screen (Android only).\n   * On iOS, this method does nothing.\n   *\n   * Use this to direct users to manage their Health Connect permissions\n   * or to install Health Connect if not available.\n   *\n   * @throws An error if Health Connect settings cannot be opened\n   */\n  openHealthConnectSettings(): Promise<void>;\n\n  /**\n   * Shows the app's privacy policy for Health Connect (Android only).\n   * On iOS, this method does nothing.\n   *\n   * This displays the same privacy policy screen that Health Connect shows\n   * when the user taps \"Privacy policy\" in the permissions dialog.\n   *\n   * The privacy policy URL can be configured by adding a string resource\n   * named \"health_connect_privacy_policy_url\" in your app's strings.xml,\n   * or by placing an HTML file at www/privacypolicy.html in your assets.\n   *\n   * @throws An error if the privacy policy cannot be displayed\n   */\n  showPrivacyPolicy(): Promise<void>;\n\n  /**\n   * Queries workout sessions from the native health store.\n   * Supported on iOS (HealthKit) and Android (Health Connect).\n   *\n   * @param options Query options including optional workout type filter, date range, limit, and sort order\n   * @returns A promise that resolves with the workout sessions\n   * @throws An error if something went wrong\n   */\n  queryWorkouts(options: QueryWorkoutsOptions): Promise<QueryWorkoutsResult>;\n\n  /**\n   * Queries aggregated health data from the native health store.\n   * Aggregates data into time buckets (hour, day, week, month) with operations like sum, average, min, or max.\n   * This is more efficient than fetching individual samples for large date ranges.\n   *\n   * Supported on iOS (HealthKit) and Android (Health Connect).\n   *\n   * @param options Query options including data type, date range, bucket size, and aggregation type\n   * @returns A promise that resolves with the aggregated samples\n   * @throws An error if something went wrong\n   */\n  queryAggregated(options: QueryAggregatedOptions): Promise<QueryAggregatedResult>;\n}\n"]}

package/ios/Sources/HealthPlugin/Health.swift

@@ -892,11 +892,19 @@ final class Health {
                     ) else {
                         return nil
                     }
-                    
-                    // Map HKCategoryValueSleepAnalysis to sleep state
+
                     let sleepState = self.sleepStateFromValue(sleepValue)
                     if let sleepState = sleepState {
                         payload["sleepState"] = sleepState
+                        payload["stages"] = [[
+                            "startDate": self.isoFormatter.string(from: sample.startDate),
+                            "endDate": self.isoFormatter.string(from: sample.endDate),
+                            "stage": sleepState,
+                            "durationMinutes": durationMinutes
+                        ]]
+                        payload["hasStageData"] = true
+                    } else {
+                        payload["hasStageData"] = false
                     }
 
                     self.addSampleMetadata(sample, to: &payload)

package/ios/Sources/HealthPlugin/HealthPlugin.swift

@@ -3,7 +3,7 @@ import Capacitor
 
 @objc(HealthPlugin)
 public class HealthPlugin: CAPPlugin, CAPBridgedPlugin {
-    private let pluginVersion: String = "8.5.2"
+    private let pluginVersion: String = "8.6.0"
     public let identifier = "HealthPlugin"
     public let jsName = "Health"
     public let pluginMethods: [CAPPluginMethod] = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capgo/capacitor-health",
-  "version": "8.5.2",
+  "version": "8.6.0",
   "description": "Capacitor plugin to interact with data from Apple HealthKit and Health Connect",
   "main": "dist/plugin.cjs.js",
   "module": "dist/esm/index.js",