@flomentumsolutions/capacitor-health-extended 0.7.6 → 0.8.0

package/README.md

@@ -227,6 +227,38 @@ class PermissionsRationaleActivity : AppCompatActivity() {
 
 This setup ensures your WebView will load HTTPS content securely and complies with Android's default network security policy.
 
+## iOS read-permission UX hint
+
+On iOS, `checkHealthPermissions` is optimistic for read sample permissions because HealthKit does not distinguish
+denied access from empty data. If a query returns no results, prompt the user to verify Apple Health settings.
+
+```typescript
+import { Health, type HealthPermission } from '@flomentumsolutions/capacitor-health-extended';
+
+const NO_DATA_HINT =
+  'No data found. If you believe this is an error, please verify your settings in Apple Health.';
+
+export async function queryWithHealthEmptyHint<T>(
+  permission: HealthPermission,
+  query: () => Promise<T>,
+  isEmpty: (result: T) => boolean,
+  showHint: (message: string) => void
+): Promise<T | null> {
+  const { permissions } = await Health.checkHealthPermissions({ permissions: [permission] });
+  if (!permissions[permission]) {
+    return null;
+  }
+
+  const result = await query();
+
+  if (isEmpty(result)) {
+    showHint(NO_DATA_HINT);
+  }
+
+  return result;
+}
+```
+
 ## API
 ```
 <docgen-index>
@@ -237,7 +269,7 @@ This setup ensures your WebView will load HTTPS content securely and complies wi
 * [`openAppleHealthSettings()`](#openapplehealthsettings)
 * [`openHealthConnectSettings()`](#openhealthconnectsettings)
 * [`showHealthConnectInPlayStore()`](#showhealthconnectinplaystore)
-* [`getCharacteristics()`](#getcharacteristics)
+* [`getCharacteristics(...)`](#getcharacteristics)
 * [`queryAggregated(...)`](#queryaggregated)
 * [`queryWorkouts(...)`](#queryworkouts)
 * [`queryLatestSample(...)`](#querylatestsample)
@@ -276,7 +308,12 @@ See showHealthConnectInPlayStore()
 checkHealthPermissions(permissions: PermissionsRequest) => Promise<PermissionResponse>
 ```
 
-Android only: Returns for each given permission, if it was granted by the underlying health API
+Returns whether each permission is granted.
+Android: Uses Health Connect grant state.
+iOS: Write permissions are strict. Read permissions for sample types are optimistic because HealthKit does not
+distinguish denied vs no data; this returns false only when the read permission is not determined. For
+characteristics, this probes access and returns false when denied.
+UX tip: If this returns true but a query yields no results, show a hint to check Apple Health settings.
 
 | Param             | Type                                                              | Description          |
 | ----------------- | ----------------------------------------------------------------- | -------------------- |
@@ -331,6 +368,7 @@ openHealthConnectSettings() => Promise<void>
 ```
 
 Opens the Google Health Connect app
+iOS: Aliases openAppleHealthSettings().
 
 --------------------
 
@@ -342,19 +380,22 @@ showHealthConnectInPlayStore() => Promise<void>
 ```
 
 Opens the Google Health Connect app in PlayStore
+iOS: Resolves without action.
 
 --------------------
 
 
-### getCharacteristics()
+### getCharacteristics(...)
 
 ```typescript
-getCharacteristics(request?: CharacteristicsRequest) => Promise<CharacteristicsResponse>
+getCharacteristics(request?: CharacteristicsRequest | undefined) => Promise<CharacteristicsResponse>
 ```
 
-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.
+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.
+
 | Param         | Type                                                                      |
 | ------------- | ------------------------------------------------------------------------- |
 | **`request`** | <code><a href="#characteristicsrequest">CharacteristicsRequest</a></code> |
@@ -430,6 +471,7 @@ queryWeight() => Promise<QueryLatestSampleResponse>
 ```
 
 Query latest weight sample
+Convenience wrapper around queryLatestSample({ dataType: 'weight' }).
 
 **Returns:** <code>Promise&lt;<a href="#querylatestsampleresponse">QueryLatestSampleResponse</a>&gt;</code>
 
@@ -443,6 +485,7 @@ queryHeight() => Promise<QueryLatestSampleResponse>
 ```
 
 Query latest height sample
+Convenience wrapper around queryLatestSample({ dataType: 'height' }).
 
 **Returns:** <code>Promise&lt;<a href="#querylatestsampleresponse">QueryLatestSampleResponse</a>&gt;</code>
 
@@ -456,6 +499,7 @@ queryHeartRate() => Promise<QueryLatestSampleResponse>
 ```
 
 Query latest heart rate sample
+Convenience wrapper around queryLatestSample({ dataType: 'heart-rate' }).
 
 **Returns:** <code>Promise&lt;<a href="#querylatestsampleresponse">QueryLatestSampleResponse</a>&gt;</code>
 
@@ -469,6 +513,7 @@ querySteps() => Promise<QueryLatestSampleResponse>
 ```
 
 Query latest steps sample
+Convenience wrapper around queryLatestSample({ dataType: 'steps' }).
 
 **Returns:** <code>Promise&lt;<a href="#querylatestsampleresponse">QueryLatestSampleResponse</a>&gt;</code>
 
@@ -529,13 +574,6 @@ 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                                                                                                                             |
@@ -549,6 +587,13 @@ Save user-provided body metrics to the health platform.
 | **`platformMessage`**     | <code>string</code>                                                                     | Optional platform-specific message; on Android we return a user-facing note explaining that values remain empty unless synced from iOS. |
 
 
+#### CharacteristicsRequest
+
+| Prop         | Type                               | Description                                                             |
+| ------------ | ---------------------------------- | ----------------------------------------------------------------------- |
+| **`fields`** | <code>CharacteristicField[]</code> | Characteristics to query. Defaults to all characteristics when omitted. |
+
+
 #### QueryAggregatedResponse
 
 | Prop                 | Type                            |
@@ -695,11 +740,6 @@ 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>
@@ -725,6 +765,11 @@ Construct a type with a set of properties K of type T
 <code>'wheelchair_user' | 'not_wheelchair_user' | 'not_set' | 'unknown'</code>
 
 
+#### CharacteristicField
+
+<code>'biologicalSex' | 'bloodType' | 'dateOfBirth' | 'fitzpatrickSkinType' | 'wheelchairUse'</code>
+
+
 #### LatestDataType
 
 <code>'steps' | 'active-calories' | 'total-calories' | 'basal-calories' | 'distance' | 'weight' | 'height' | 'heart-rate' | 'resting-heart-rate' | 'respiratory-rate' | 'oxygen-saturation' | 'blood-glucose' | 'body-temperature' | 'basal-body-temperature' | 'body-fat' | 'flights-climbed' | 'exercise-time' | 'distance-cycling' | 'mindfulness' | 'sleep' | 'sleep-rem' | 'hrv' | 'blood-pressure'</code>

package/dist/esm/definitions.d.ts

@@ -9,7 +9,12 @@ export interface HealthPlugin {
         available: boolean;
     }>;
     /**
-     * Android only: Returns for each given permission, if it was granted by the underlying health API
+     * Returns whether each permission is granted.
+     * Android: Uses Health Connect grant state.
+     * iOS: Write permissions are strict. Read permissions for sample types are optimistic because HealthKit does not
+     * distinguish denied vs no data; this returns false only when the read permission is not determined. For
+     * characteristics, this probes access and returns false when denied.
+     * UX tip: If this returns true but a query yields no results, show a hint to check Apple Health settings.
      * @param permissions permissions to query
      */
     checkHealthPermissions(permissions: PermissionsRequest): Promise<PermissionResponse>;
@@ -34,10 +39,12 @@ export interface HealthPlugin {
     openAppleHealthSettings(): Promise<void>;
     /**
      * Opens the Google Health Connect app
+     * iOS: Aliases openAppleHealthSettings().
      */
     openHealthConnectSettings(): Promise<void>;
     /**
      * Opens the Google Health Connect app in PlayStore
+     * iOS: Resolves without action.
      */
     showHealthConnectInPlayStore(): Promise<void>;
     /**
@@ -74,18 +81,22 @@ export interface HealthPlugin {
     }): Promise<QueryLatestSampleResponse>;
     /**
      * Query latest weight sample
+     * Convenience wrapper around queryLatestSample({ dataType: 'weight' }).
      */
     queryWeight(): Promise<QueryLatestSampleResponse>;
     /**
      * Query latest height sample
+     * Convenience wrapper around queryLatestSample({ dataType: 'height' }).
      */
     queryHeight(): Promise<QueryLatestSampleResponse>;
     /**
      * Query latest heart rate sample
+     * Convenience wrapper around queryLatestSample({ dataType: 'heart-rate' }).
      */
     queryHeartRate(): Promise<QueryLatestSampleResponse>;
     /**
      * Query latest steps sample
+     * Convenience wrapper around queryLatestSample({ dataType: 'steps' }).
      */
     querySteps(): Promise<QueryLatestSampleResponse>;
     /**

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   * 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"]}
+{"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   * Returns whether each permission is granted.\n   * Android: Uses Health Connect grant state.\n   * iOS: Write permissions are strict. Read permissions for sample types are optimistic because HealthKit does not\n   * distinguish denied vs no data; this returns false only when the read permission is not determined. For\n   * characteristics, this probes access and returns false when denied.\n   * UX tip: If this returns true but a query yields no results, show a hint to check Apple Health settings.\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   * iOS: Aliases openAppleHealthSettings().\n   */\n  openHealthConnectSettings(): Promise<void>;\n\n  /**\n   * Opens the Google Health Connect app in PlayStore\n   * iOS: Resolves without action.\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   * Convenience wrapper around queryLatestSample({ dataType: 'weight' }).\n   */\n  queryWeight(): Promise<QueryLatestSampleResponse>;\n\n  /**\n   * Query latest height sample\n   * Convenience wrapper around queryLatestSample({ dataType: 'height' }).\n   */\n  queryHeight(): Promise<QueryLatestSampleResponse>;\n\n  /**\n   * Query latest heart rate sample\n   * Convenience wrapper around queryLatestSample({ dataType: 'heart-rate' }).\n   */\n  queryHeartRate(): Promise<QueryLatestSampleResponse>;\n\n  /**\n   * Query latest steps sample\n   * Convenience wrapper around queryLatestSample({ dataType: 'steps' }).\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

@@ -17,9 +17,15 @@ public class HealthPlugin: CAPPlugin, CAPBridgedPlugin {
         CAPPluginMethod(name: "checkHealthPermissions", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "requestHealthPermissions", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "openAppleHealthSettings", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "openHealthConnectSettings", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "showHealthConnectInPlayStore", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "queryAggregated", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "queryWorkouts", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "queryLatestSample", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "queryWeight", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "queryHeight", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "queryHeartRate", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "querySteps", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "getCharacteristics", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "saveMetrics", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "saveWorkout", returnType: CAPPluginReturnPromise)
@@ -64,28 +70,94 @@ public class HealthPlugin: CAPPlugin, CAPBridgedPlugin {
             return
         }
 
-        var result: [String: String] = [:]
+        var result: [String: Bool] = [:]
 
         for permission in permissions {
-            let hkTypes = permissionToHKObjectType(permission) + permissionToHKSampleType(permission)
-            for type in hkTypes {
-                let status = healthStore.authorizationStatus(for: type)
+            // Resolve Mappings
+            let readTypes = permissionToHKObjectType(permission)
+            let shareTypes = permissionToHKSampleType(permission)
+            
+            // Prevent invalid/typo permissions from defaulting to "true"
+            if readTypes.isEmpty && shareTypes.isEmpty {
+                print("⚡️ [HealthPlugin] Warning: Permission '\(permission)' is not mapped to any HealthKit types.")
+                result[permission] = false
+                continue
+            }
 
-                switch status {
-                case .notDetermined:
-                    result[permission] = "notDetermined"
-                case .sharingDenied:
-                    result[permission] = "denied"
-                case .sharingAuthorized:
-                    result[permission] = "authorized"
-                @unknown default:
-                    result[permission] = "unknown"
+            // Determine Intent (Write vs Read)
+            // If the permission maps to any shareable types, treat it as a Write request.
+            let isWriteRequest = !shareTypes.isEmpty
+            
+            var isGranted = true
+
+            if isWriteRequest {
+                // WRITE LOGIC: Strict
+                // Multi-type permissions must be All-or-Nothing for data integrity.
+                for type in shareTypes {
+                    if healthStore.authorizationStatus(for: type) != .sharingAuthorized {
+                        isGranted = false
+                        break
+                    }
+                }
+            } else {
+                // READ LOGIC: Hybrid (Strict Characteristic / Optimistic Sample)
+                for type in readTypes {
+                    if let charType = type as? HKCharacteristicType {
+                        // Characteristics: Strict Probe
+                        // We strictly check these because they throw explicit errors on denial.
+                        if !isCharacteristicAuthorized(charType) {
+                            isGranted = false
+                            break
+                        }
+                    } else {
+                        // Sample Types: Optimistic Check
+                        // Strategy:
+                        // - If .notDetermined: We definitely need to ask. Return false.
+                        // - If .sharingDenied: User explicitly denied OR it's a read-only masking. 
+                        //   We MUST return 'true' here. If we return 'false', the app will loop 
+                        //   requests forever because we cannot distinguish Denied from "No Data".
+                        if healthStore.authorizationStatus(for: type) == .notDetermined {
+                            isGranted = false
+                            break
+                        }
+                    }
                 }
             }
+            
+            result[permission] = isGranted
         }
 
         call.resolve(["permissions": result])
     }
+
+    // Helper: Accurately checks Characteristic read access by attempting a fetch.
+    private func isCharacteristicAuthorized(_ type: HKCharacteristicType) -> Bool {
+        do {
+            switch type.identifier {
+            case HKCharacteristicTypeIdentifier.biologicalSex.rawValue:
+                _ = try healthStore.biologicalSex()
+            case HKCharacteristicTypeIdentifier.bloodType.rawValue:
+                _ = try healthStore.bloodType()
+            case HKCharacteristicTypeIdentifier.dateOfBirth.rawValue:
+                _ = try healthStore.dateOfBirthComponents()
+            case HKCharacteristicTypeIdentifier.fitzpatrickSkinType.rawValue:
+                _ = try healthStore.fitzpatrickSkinType()
+            case HKCharacteristicTypeIdentifier.wheelchairUse.rawValue:
+                _ = try healthStore.wheelchairUse()
+            default:
+                // Unknown characteristic identifiers should default to false to surface errors.
+                print("⚡️ [HealthPlugin] Warning: Unknown characteristic type probed: \(type.identifier)")
+                return false
+            }
+            return true
+        } catch let error as HKError {
+            // If the system explicitly says "Authorization Denied", we know for sure.
+            return error.code != .errorAuthorizationDenied
+        } catch {
+            // Other errors (device not supported, etc) implies we can't read it.
+            return false
+        }
+    }
     
     @objc func requestHealthPermissions(_ call: CAPPluginCall) {
         guard let permissions = call.getArray("permissions") as? [String] else {
@@ -264,7 +336,27 @@ public class HealthPlugin: CAPPlugin, CAPBridgedPlugin {
             call.reject("Missing data type")
             return
         }
-        
+
+        queryLatestSample(for: dataTypeString, call: call)
+    }
+
+    @objc func queryWeight(_ call: CAPPluginCall) {
+        queryLatestSample(for: "weight", call: call)
+    }
+
+    @objc func queryHeight(_ call: CAPPluginCall) {
+        queryLatestSample(for: "height", call: call)
+    }
+
+    @objc func queryHeartRate(_ call: CAPPluginCall) {
+        queryLatestSample(for: "heart-rate", call: call)
+    }
+
+    @objc func querySteps(_ call: CAPPluginCall) {
+        queryLatestSample(for: "steps", call: call)
+    }
+
+    private func queryLatestSample(for dataTypeString: String, call: CAPPluginCall) {
         print("⚡️ [HealthPlugin] Querying latest sample for data type: \(dataTypeString)")
         // ---- Special handling for blood‑pressure correlation ----
         if dataTypeString == "blood-pressure" {
@@ -670,6 +762,14 @@ public class HealthPlugin: CAPPlugin, CAPBridgedPlugin {
         healthStore.execute(query)
     }
     
+    @objc func openHealthConnectSettings(_ call: CAPPluginCall) {
+        openAppleHealthSettings(call)
+    }
+
+    @objc func showHealthConnectInPlayStore(_ call: CAPPluginCall) {
+        call.resolve()
+    }
+
     @objc func openAppleHealthSettings(_ call: CAPPluginCall) {
         if let url = URL(string: UIApplication.openSettingsURLString) {
             DispatchQueue.main.async {

package/package.json

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