@flomentumsolutions/capacitor-health-extended 0.7.4 → 0.7.5

package/README.md

@@ -349,12 +349,16 @@ Opens the Google Health Connect app in PlayStore
 ### getCharacteristics()
 
 ```typescript
-getCharacteristics() => Promise<CharacteristicsResponse>
+getCharacteristics(request?: CharacteristicsRequest) => Promise<CharacteristicsResponse>
 ```
 
-iOS only: Reads user characteristics such as biological sex, blood type, date of birth, Fitzpatrick skin type, and wheelchair use.
+iOS only: Reads user characteristics such as biological sex, blood type, date of birth, Fitzpatrick skin type, and wheelchair use. Pass `fields` to request a single characteristic (e.g., date of birth) and keep permissions narrowly scoped; defaults to all when omitted.
 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.
 
+| Param         | Type                                                                      |
+| ------------- | ------------------------------------------------------------------------- |
+| **`request`** | <code><a href="#characteristicsrequest">CharacteristicsRequest</a></code> |
+
 **Returns:** <code>Promise&lt;<a href="#characteristicsresponse">CharacteristicsResponse</a>&gt;</code>
 
 --------------------
@@ -525,6 +529,13 @@ Save user-provided body metrics to the health platform.
 | **`permissions`** | <code>HealthPermission[]</code> |
 
 
+#### CharacteristicsRequest
+
+| Prop         | Type                                                                 | Description                                                |
+| ------------ | -------------------------------------------------------------------- | ---------------------------------------------------------- |
+| **`fields`** | <code><a href="#characteristicfield">CharacteristicField</a>[]</code> | Characteristics to query; defaults to all when unspecified |
+
+
 #### CharacteristicsResponse
 
 | Prop                      | Type                                                                                    | Description                                                                                                                             |
@@ -684,6 +695,11 @@ Construct a type with a set of properties K of type T
 <code>{
 [P in K]: T;
 }</code>
 
 
+#### CharacteristicField
+
+<code>'biologicalSex' | 'bloodType' | 'dateOfBirth' | 'fitzpatrickSkinType' | 'wheelchairUse'</code>
+
+
 #### HealthPermission
 
 <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' | 'WRITE_WEIGHT' | 'READ_HEIGHT' | 'WRITE_HEIGHT' | 'READ_HEART_RATE' | 'WRITE_HEART_RATE' | 'READ_RESTING_HEART_RATE' | 'WRITE_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' | 'WRITE_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>

package/android/src/main/java/com/flomentumsolutions/capacitor-health-extended/HealthPlugin.kt

@@ -350,11 +350,15 @@ class HealthPlugin : Plugin() {
 
     @PluginMethod
     fun getCharacteristics(call: PluginCall) {
+        val requestedFields = call.getArray("fields")
+            ?.toList<String>()
+            ?.filter { it.isNotBlank() }
+            ?: emptyList()
         val result = JSObject()
         result.put("platformSupported", false)
         result.put(
             "platformMessage",
-            "Health Connect does not expose characteristics; this section stays empty unless synced from an iOS device."
+            "Health Connect does not expose characteristics; this section stays empty unless synced from an iOS device.${if (requestedFields.isEmpty()) "" else " Requested fields: ${requestedFields.joinToString(\", \")}."}"
         )
         call.resolve(result)
     }

package/dist/esm/definitions.d.ts

@@ -43,8 +43,10 @@ export interface HealthPlugin {
     /**
      * iOS only: Reads user characteristics such as biological sex, blood type, date of birth, Fitzpatrick skin type, and wheelchair use.
      * 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.
+     *
+     * Passing `fields` lets you request only specific characteristics (e.g., date of birth) to keep permissions scoped narrowly. Defaults to all characteristics when omitted.
      */
-    getCharacteristics(): Promise<CharacteristicsResponse>;
+    getCharacteristics(request?: CharacteristicsRequest): Promise<CharacteristicsResponse>;
     /**
      * Query aggregated data
      * - Blood-pressure aggregates return the systolic average in `value` plus `systolic`, `diastolic`, and `unit`.
@@ -206,6 +208,13 @@ export interface CharacteristicsResponse {
      */
     platformMessage?: string;
 }
+export type CharacteristicField = 'biologicalSex' | 'bloodType' | 'dateOfBirth' | 'fitzpatrickSkinType' | 'wheelchairUse';
+export interface CharacteristicsRequest {
+    /**
+     * Characteristics to query. Defaults to all characteristics when omitted.
+     */
+    fields?: CharacteristicField[];
+}
 export type HealthBiologicalSex = 'female' | 'male' | 'other' | 'not_set' | 'unknown';
 export type HealthBloodType = 'a-positive' | 'a-negative' | 'b-positive' | 'b-negative' | 'ab-positive' | 'ab-negative' | 'o-positive' | 'o-negative' | 'not_set' | 'unknown';
 export type HealthFitzpatrickSkinType = 'type1' | 'type2' | 'type3' | 'type4' | 'type5' | 'type6' | 'not_set' | 'unknown';

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   * - `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  /**\n   * Save user-provided body metrics to the health platform.\n   */\n  saveMetrics(request: SaveMetricsRequest): Promise<SaveMetricsResponse>;\n}\n\nexport 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' | 'WRITE_WEIGHT' | 'READ_HEIGHT' | 'WRITE_HEIGHT' | 'READ_HEART_RATE' | 'WRITE_HEART_RATE' | 'READ_RESTING_HEART_RATE' | 'WRITE_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' | 'WRITE_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';\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 SaveMetricsRequest {\n    weightKg?: number;\n    heightCm?: number;\n    bodyFatPercent?: number;\n    restingHeartRate?: number;\n}\n\nexport interface SaveMetricsResponse {\n    success: boolean;\n    inserted?: number;\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   * Passing `fields` lets you request only specific characteristics (e.g., date of birth) to keep permissions scoped narrowly. Defaults to all characteristics when omitted.\n   */\n  getCharacteristics(request?: CharacteristicsRequest): 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  /**\n   * Save user-provided body metrics to the health platform.\n   */\n  saveMetrics(request: SaveMetricsRequest): Promise<SaveMetricsResponse>;\n}\n\nexport 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' | 'WRITE_WEIGHT' | 'READ_HEIGHT' | 'WRITE_HEIGHT' | 'READ_HEART_RATE' | 'WRITE_HEART_RATE' | 'READ_RESTING_HEART_RATE' | 'WRITE_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' | 'WRITE_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';\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 SaveMetricsRequest {\n    weightKg?: number;\n    heightCm?: number;\n    bodyFatPercent?: number;\n    restingHeartRate?: number;\n}\n\nexport interface SaveMetricsResponse {\n    success: boolean;\n    inserted?: number;\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 CharacteristicField =\n  | 'biologicalSex'\n  | 'bloodType'\n  | 'dateOfBirth'\n  | 'fitzpatrickSkinType'\n  | 'wheelchairUse';\n\nexport interface CharacteristicsRequest {\n  /**\n   * Characteristics to query. Defaults to all characteristics when omitted.\n   */\n  fields?: CharacteristicField[];\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

@@ -29,6 +29,29 @@ public class HealthPlugin: CAPPlugin, CAPBridgedPlugin {
     
     /// Serial queue to make route‑location mutations thread‑safe without locks
     private let routeSyncQueue = DispatchQueue(label: "com.flomentumsolutions.capacitorhealthextended.routeSync")
+
+    private enum CharacteristicField: String, CaseIterable {
+        case biologicalSex
+        case bloodType
+        case dateOfBirth
+        case fitzpatrickSkinType
+        case wheelchairUse
+
+        var hkObjectType: HKObjectType? {
+            switch self {
+            case .biologicalSex:
+                return HKObjectType.characteristicType(forIdentifier: .biologicalSex)
+            case .bloodType:
+                return HKObjectType.characteristicType(forIdentifier: .bloodType)
+            case .dateOfBirth:
+                return HKObjectType.characteristicType(forIdentifier: .dateOfBirth)
+            case .fitzpatrickSkinType:
+                return HKObjectType.characteristicType(forIdentifier: .fitzpatrickSkinType)
+            case .wheelchairUse:
+                return HKObjectType.characteristicType(forIdentifier: .wheelchairUse)
+            }
+        }
+    }
     
     @objc func isHealthAvailable(_ call: CAPPluginCall) {
         let isAvailable = HKHealthStore.isHealthDataAvailable()
@@ -114,65 +137,99 @@ public class HealthPlugin: CAPPlugin, CAPBridgedPlugin {
             return
         }
 
-        let characteristicTypes: [HKObjectType] = [
-            HKObjectType.characteristicType(forIdentifier: .biologicalSex),
-            HKObjectType.characteristicType(forIdentifier: .bloodType),
-            HKObjectType.characteristicType(forIdentifier: .dateOfBirth),
-            HKObjectType.characteristicType(forIdentifier: .fitzpatrickSkinType),
-            HKObjectType.characteristicType(forIdentifier: .wheelchairUse)
-        ].compactMap { $0 }
+        let requestedFields = call.getArray("fields") as? [String] ?? []
+        let fieldsToLoad: [CharacteristicField]
+        if requestedFields.isEmpty {
+            fieldsToLoad = CharacteristicField.allCases
+        } else {
+            var normalized: [CharacteristicField] = []
+            var invalid: [String] = []
+
+            for name in requestedFields {
+                if let field = CharacteristicField(rawValue: name) {
+                    if !normalized.contains(field) {
+                        normalized.append(field)
+                    }
+                } else {
+                    invalid.append(name)
+                }
+            }
+
+            if !invalid.isEmpty {
+                let validFields = CharacteristicField.allCases.map { $0.rawValue }.joined(separator: ", ")
+                call.reject("Invalid characteristic field(s): \(invalid.joined(separator: ", ")). Valid fields are: \(validFields)")
+                return
+            }
+
+            fieldsToLoad = normalized.isEmpty ? CharacteristicField.allCases : normalized
+        }
+
+        let characteristicTypes: [HKObjectType] = fieldsToLoad.compactMap { $0.hkObjectType }
+
+        if characteristicTypes.count != fieldsToLoad.count {
+            let missing = fieldsToLoad.filter { $0.hkObjectType == nil }.map { $0.rawValue }
+            let missingList = missing.joined(separator: ", ")
+            let message = missing.isEmpty ? "HealthKit characteristics are unavailable on this device." : "Requested characteristics are unavailable on this device: \(missingList)"
+            call.reject(message)
+            return
+        }
 
         guard !characteristicTypes.isEmpty else {
             call.reject("HealthKit characteristics are unavailable on this device.")
             return
         }
 
-        func resolveCharacteristics() {
+        func resolveCharacteristics(for fields: [CharacteristicField]) {
             var result: [String: Any] = [:]
 
-            func setValue(_ key: String, _ value: String?) {
-                result[key] = value ?? NSNull()
-            }
-
-            if let biologicalSexObject = try? healthStore.biologicalSex() {
-                setValue("biologicalSex", mapBiologicalSex(biologicalSexObject.biologicalSex))
-            } else {
-                setValue("biologicalSex", nil)
+            func setValue(_ key: CharacteristicField, _ value: String?) {
+                result[key.rawValue] = value ?? NSNull()
             }
 
-            if let bloodTypeObject = try? healthStore.bloodType() {
-                setValue("bloodType", mapBloodType(bloodTypeObject.bloodType))
-            } else {
-                setValue("bloodType", nil)
-            }
-
-            if let dateComponents = try? healthStore.dateOfBirthComponents() {
-                setValue("dateOfBirth", isoBirthDateString(from: dateComponents))
-            } else {
-                setValue("dateOfBirth", nil)
-            }
-
-            if let fitzpatrickObject = try? healthStore.fitzpatrickSkinType() {
-                setValue("fitzpatrickSkinType", mapFitzpatrickSkinType(fitzpatrickObject.skinType))
-            } else {
-                setValue("fitzpatrickSkinType", nil)
-            }
-
-            if let wheelchairUseObject = try? healthStore.wheelchairUse() {
-                setValue("wheelchairUse", mapWheelchairUse(wheelchairUseObject.wheelchairUse))
-            } else {
-                setValue("wheelchairUse", nil)
+            for field in fields {
+                switch field {
+                case .biologicalSex:
+                    if let biologicalSexObject = try? healthStore.biologicalSex() {
+                        setValue(field, mapBiologicalSex(biologicalSexObject.biologicalSex))
+                    } else {
+                        setValue(field, nil)
+                    }
+                case .bloodType:
+                    if let bloodTypeObject = try? healthStore.bloodType() {
+                        setValue(field, mapBloodType(bloodTypeObject.bloodType))
+                    } else {
+                        setValue(field, nil)
+                    }
+                case .dateOfBirth:
+                    if let dateComponents = try? healthStore.dateOfBirthComponents() {
+                        setValue(field, isoBirthDateString(from: dateComponents))
+                    } else {
+                        setValue(field, nil)
+                    }
+                case .fitzpatrickSkinType:
+                    if let fitzpatrickObject = try? healthStore.fitzpatrickSkinType() {
+                        setValue(field, mapFitzpatrickSkinType(fitzpatrickObject.skinType))
+                    } else {
+                        setValue(field, nil)
+                    }
+                case .wheelchairUse:
+                    if let wheelchairUseObject = try? healthStore.wheelchairUse() {
+                        setValue(field, mapWheelchairUse(wheelchairUseObject.wheelchairUse))
+                    } else {
+                        setValue(field, nil)
+                    }
+                }
             }
 
             result["platformSupported"] = true
             call.resolve(result)
         }
 
-        func requestCharacteristicsAccess() {
-            self.healthStore.requestAuthorization(toShare: nil, read: Set(characteristicTypes)) { success, error in
+        func requestCharacteristicsAccess(for fields: [CharacteristicField], types: [HKObjectType]) {
+            self.healthStore.requestAuthorization(toShare: nil, read: Set(types)) { success, error in
                 DispatchQueue.main.async {
                     if success {
-                        resolveCharacteristics()
+                        resolveCharacteristics(for: fields)
                     } else if let error = error {
                         call.reject("Authorization failed: \(error.localizedDescription)")
                     } else {
@@ -194,9 +251,9 @@ public class HealthPlugin: CAPPlugin, CAPBridgedPlugin {
 
                 switch status {
                 case .shouldRequest, .unknown:
-                    requestCharacteristicsAccess()
+                    requestCharacteristicsAccess(for: fieldsToLoad, types: characteristicTypes)
                 default:
-                    resolveCharacteristics()
+                    resolveCharacteristics(for: fieldsToLoad)
                 }
             }
         }

package/package.json

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