@asiriindatissa/capacitor-health 8.2.1 → 8.3.0

package/README.md

@@ -8,7 +8,7 @@ The only **free**, **unified** health data plugin for Capacitor supporting the l
 
 - **Health Connect (Android)** - Uses Google's newest health platform (replaces deprecated Google Fit)
 - **Unified API** - TypeScript interface with consistent units
-- **Multiple metrics** - Steps, distance, calories, heart rate, weight
+- **Multiple metrics** - Steps, distance, calories, heart rate, weight, height
 - **Read & Write** - Query historical data and save new health entries
 - **Modern standards** - Supports Android 8.0+
 
@@ -26,7 +26,7 @@ npx cap sync
 This plugin now uses [Health Connect](https://developer.android.com/health-and-fitness/guides/health-connect) instead of Google Fit. Make sure your app meets the requirements below:
 
 1. **Min SDK 26+.** Health Connect is only available on Android 8.0 (API 26) and above. The plugin's Gradle setup already targets this level.
-2. **Declare Health permissions.** The plugin manifest ships with the required `<uses-permission>` declarations (`READ_/WRITE_STEPS`, `READ_/WRITE_DISTANCE`, `READ_/WRITE_ACTIVE_CALORIES_BURNED`, `READ_/WRITE_HEART_RATE`, `READ_/WRITE_WEIGHT`). Your app does not need to duplicate them, but you must surface a user-facing rationale because the permissions are considered health sensitive.
+2. **Declare Health permissions.** The plugin manifest ships with the required `<uses-permission>` declarations (`READ_/WRITE_STEPS`, `READ_/WRITE_DISTANCE`, `READ_/WRITE_ACTIVE_CALORIES_BURNED`, `READ_/WRITE_HEART_RATE`, `READ_/WRITE_WEIGHT`, `READ_/WRITE_HEIGHT`). Your app does not need to duplicate them, but you must surface a user-facing rationale because the permissions are considered health sensitive.
 3. **Ensure Health Connect is installed.** Devices on Android 14+ include it by default. For earlier versions the user must install _Health Connect by Android_ from the Play Store. The `Health.isAvailable()` helper exposes the current status so you can prompt accordingly.
 4. **Request runtime access.** The plugin opens the Health Connect permission UI when you call `requestAuthorization`. You should still handle denial flows (e.g., show a message if `checkAuthorization` reports missing scopes).
 5. **Provide a Privacy Policy.** Health Connect requires apps to display a privacy policy explaining how health data is used. See the [Privacy Policy Setup](#privacy-policy-setup) section below.
@@ -124,6 +124,7 @@ await Health.saveSample({
 | `calories`  | `kilocalorie` | Active energy burned       |
 | `heartRate` | `bpm`         | Beats per minute           |
 | `weight`    | `kilogram`    | Body mass                  |
+| `height`    | `meter`       | Body height                |
 
 All write operations expect the default unit shown above. On Android the `metadata` option is currently ignored by Health Connect.
 
@@ -352,14 +353,14 @@ Queries workout sessions from the native health store on Android (Health Connect
 
 #### WriteSampleOptions
 
-| Prop            | Type                                                            | Description                                                                                                                                                                                       |
-| --------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **`dataType`**  | <code><a href="#healthdatatype">HealthDataType</a></code>       |                                                                                                                                                                                                   |
-| **`value`**     | <code>number</code>                                             |                                                                                                                                                                                                   |
-| **`unit`**      | <code><a href="#healthunit">HealthUnit</a></code>               | Optional unit override. If omitted, the default unit for the data type is used (count for `steps`, meter for `distance`, kilocalorie for `calories`, bpm for `heartRate`, kilogram for `weight`). |
-| **`startDate`** | <code>string</code>                                             | ISO 8601 start date for the sample. Defaults to now.                                                                                                                                              |
-| **`endDate`**   | <code>string</code>                                             | ISO 8601 end date for the sample. Defaults to startDate.                                                                                                                                          |
-| **`metadata`**  | <code><a href="#record">Record</a>&lt;string, string&gt;</code> | Metadata key-value pairs forwarded to the native APIs where supported.                                                                                                                            |
+| Prop            | Type                                                            | Description                                                                                                                                                                                                           |
+| --------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`dataType`**  | <code><a href="#healthdatatype">HealthDataType</a></code>       |                                                                                                                                                                                                                       |
+| **`value`**     | <code>number</code>                                             |                                                                                                                                                                                                                       |
+| **`unit`**      | <code><a href="#healthunit">HealthUnit</a></code>               | Optional unit override. If omitted, the default unit for the data type is used (count for `steps`, meter for `distance`, kilocalorie for `calories`, bpm for `heartRate`, kilogram for `weight`, meter for `height`). |
+| **`startDate`** | <code>string</code>                                             | ISO 8601 start date for the sample. Defaults to now.                                                                                                                                                                  |
+| **`endDate`**   | <code>string</code>                                             | ISO 8601 end date for the sample. Defaults to startDate.                                                                                                                                                              |
+| **`metadata`**  | <code><a href="#record">Record</a>&lt;string, string&gt;</code> | Metadata key-value pairs forwarded to the native APIs where supported.                                                                                                                                                |
 
 
 #### QueryWorkoutsResult
@@ -400,7 +401,7 @@ Queries workout sessions from the native health store on Android (Health Connect
 
 #### HealthDataType
 
-<code>'steps' | 'distance' | 'calories' | 'heartRate' | 'weight'</code>
+<code>'steps' | 'distance' | 'calories' | 'heartRate' | 'weight' | 'height'</code>
 
 
 #### HealthUnit

package/android/src/main/AndroidManifest.xml

@@ -9,6 +9,8 @@
     <uses-permission android:name="android.permission.health.WRITE_HEART_RATE" />
     <uses-permission android:name="android.permission.health.READ_WEIGHT" />
     <uses-permission android:name="android.permission.health.WRITE_WEIGHT" />
+    <uses-permission android:name="android.permission.health.READ_HEIGHT" />
+    <uses-permission android:name="android.permission.health.WRITE_HEIGHT" />
 
     <!-- Query for Health Connect availability -->
     <queries>

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

@@ -4,6 +4,7 @@ import androidx.health.connect.client.permission.HealthPermission
 import androidx.health.connect.client.records.ActiveCaloriesBurnedRecord
 import androidx.health.connect.client.records.DistanceRecord
 import androidx.health.connect.client.records.HeartRateRecord
+import androidx.health.connect.client.records.HeightRecord
 import androidx.health.connect.client.records.Record
 import androidx.health.connect.client.records.StepsRecord
 import androidx.health.connect.client.records.WeightRecord
@@ -18,7 +19,8 @@ enum class HealthDataType(
     DISTANCE("distance", DistanceRecord::class, "meter"),
     CALORIES("calories", ActiveCaloriesBurnedRecord::class, "kilocalorie"),
     HEART_RATE("heartRate", HeartRateRecord::class, "bpm"),
-    WEIGHT("weight", WeightRecord::class, "kilogram");
+    WEIGHT("weight", WeightRecord::class, "kilogram"),
+    HEIGHT("height", HeightRecord::class, "meter");
 
     val readPermission: String
         get() = HealthPermission.getReadPermission(recordClass)

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

@@ -7,6 +7,7 @@ import androidx.health.connect.client.records.ActiveCaloriesBurnedRecord
 import androidx.health.connect.client.records.DistanceRecord
 import androidx.health.connect.client.records.ExerciseSessionRecord
 import androidx.health.connect.client.records.HeartRateRecord
+import androidx.health.connect.client.records.HeightRecord
 import androidx.health.connect.client.records.Record
 import androidx.health.connect.client.records.StepsRecord
 import androidx.health.connect.client.records.WeightRecord
@@ -147,6 +148,16 @@ class HealthManager {
                     samples.add(sample.time to payload)
                 }
             }
+            HealthDataType.HEIGHT -> readRecords(client, HeightRecord::class, startTime, endTime, limit) { record ->
+                val payload = createSamplePayload(
+                    dataType,
+                    record.time,
+                    record.time,
+                    record.height.inMeters,
+                    record.metadata
+                )
+                samples.add(record.time to payload)
+            }
         }
 
         val sorted = samples.sortedBy { it.first }
@@ -245,6 +256,14 @@ class HealthManager {
                 )
                 client.insertRecords(listOf(record))
             }
+            HealthDataType.HEIGHT -> {
+                val record = HeightRecord(
+                    time = startTime,
+                    zoneOffset = zoneOffset(startTime),
+                    height = Length.meters(value)
+                )
+                client.insertRecords(listOf(record))
+            }
         }
     }
 

package/dist/docs.json

@@ -431,7 +431,7 @@
         {
           "name": "unit",
           "tags": [],
-          "docs": "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`).",
+          "docs": "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`, meter for `height`).",
           "complexTypes": [
             "HealthUnit"
           ],
@@ -629,6 +629,10 @@
         {
           "text": "'weight'",
           "complexTypes": []
+        },
+        {
+          "text": "'height'",
+          "complexTypes": []
         }
       ]
     },

package/dist/esm/definitions.d.ts

@@ -1,4 +1,4 @@
-export type HealthDataType = 'steps' | 'distance' | 'calories' | 'heartRate' | 'weight';
+export type HealthDataType = 'steps' | 'distance' | 'calories' | 'heartRate' | 'weight' | 'height';
 export type HealthUnit = 'count' | 'meter' | 'kilocalorie' | 'bpm' | 'kilogram';
 export interface AuthorizationOptions {
     /** Data types that should be readable after authorization. */
@@ -83,7 +83,7 @@ export interface WriteSampleOptions {
     value: number;
     /**
      * Optional unit override. If omitted, the default unit for the data type is used
-     * (count for `steps`, meter for `distance`, kilocalorie for `calories`, bpm for `heartRate`, kilogram for `weight`).
+     * (count for `steps`, meter for `distance`, kilocalorie for `calories`, bpm for `heartRate`, kilogram for `weight`, meter for `height`).
      */
     unit?: HealthUnit;
     /** ISO 8601 start date for the sample. Defaults to now. */

package/dist/esm/definitions.js.map

@@ -1 +1 @@
-{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["export type HealthDataType = 'steps' | 'distance' | 'calories' | 'heartRate' | 'weight';\n\nexport type HealthUnit = 'count' | 'meter' | 'kilocalorie' | 'bpm' | 'kilogram';\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?: '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 interface HealthSample {\n  dataType: HealthDataType;\n  value: number;\n  unit: HealthUnit;\n  startDate: string;\n  endDate: string;\n  sourceName?: string;\n  sourceId?: string;\n}\n\nexport interface ReadSamplesResult {\n  samples: HealthSample[];\n}\n\nexport type WorkoutType =\n  | 'running'\n  | 'cycling'\n  | 'walking'\n  | 'swimming'\n  | 'yoga'\n  | 'strengthTraining'\n  | 'hiking'\n  | 'tennis'\n  | 'basketball'\n  | 'soccer'\n  | 'americanFootball'\n  | 'baseball'\n  | 'crossTraining'\n  | 'elliptical'\n  | 'rowing'\n  | 'stairClimbing'\n  | 'traditionalStrengthTraining'\n  | 'waterFitness'\n  | 'waterPolo'\n  | 'waterSports'\n  | 'wrestling'\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\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  /** Additional metadata (if available). */\n  metadata?: Record<string, string>;\n}\n\nexport interface QueryWorkoutsResult {\n  workouts: Workout[];\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}\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.\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.\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 on 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"]}
+{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["export type HealthDataType = 'steps' | 'distance' | 'calories' | 'heartRate' | 'weight' | 'height';\n\nexport type HealthUnit = 'count' | 'meter' | 'kilocalorie' | 'bpm' | 'kilogram';\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?: '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 interface HealthSample {\n  dataType: HealthDataType;\n  value: number;\n  unit: HealthUnit;\n  startDate: string;\n  endDate: string;\n  sourceName?: string;\n  sourceId?: string;\n}\n\nexport interface ReadSamplesResult {\n  samples: HealthSample[];\n}\n\nexport type WorkoutType =\n  | 'running'\n  | 'cycling'\n  | 'walking'\n  | 'swimming'\n  | 'yoga'\n  | 'strengthTraining'\n  | 'hiking'\n  | 'tennis'\n  | 'basketball'\n  | 'soccer'\n  | 'americanFootball'\n  | 'baseball'\n  | 'crossTraining'\n  | 'elliptical'\n  | 'rowing'\n  | 'stairClimbing'\n  | 'traditionalStrengthTraining'\n  | 'waterFitness'\n  | 'waterPolo'\n  | 'waterSports'\n  | 'wrestling'\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\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  /** Additional metadata (if available). */\n  metadata?: Record<string, string>;\n}\n\nexport interface QueryWorkoutsResult {\n  workouts: Workout[];\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`, meter for `height`).\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}\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.\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.\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 on 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"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asiriindatissa/capacitor-health",
-  "version": "8.2.1",
+  "version": "8.3.0",
   "description": "Capacitor plugin to interact with data from Health Connect on Android",
   "main": "dist/plugin.cjs.js",
   "module": "dist/esm/index.js",