@interval-health/capacitor-health 1.0.2 → 1.0.3

package/README.md

@@ -1,324 +1,861 @@
-# @capgo/capacitor-health
- <a href="https://capgo.app/"><img src='https://raw.githubusercontent.com/Cap-go/capgo/main/assets/capgo_banner.png' alt='Capgo - Instant updates for capacitor'/></a>
+# @interval-health/capacitor-health
 
-<div align="center">
-  <h2><a href="https://capgo.app/?ref=plugin_health"> ➡️ Get Instant updates for your App with Capgo</a></h2>
-  <h2><a href="https://capgo.app/consulting/?ref=plugin_health"> Missing a feature? We’ll build the plugin for you 💪</a></h2>
-</div>
+A Capacitor plugin to interact with health data from **Apple HealthKit** (iOS) and **Health Connect** (Android). This plugin provides a unified JavaScript API to read and write health and fitness data across both platforms.
 
-Capacitor plugin to read and write health metrics via Apple HealthKit (iOS) and Health Connect (Android). The TypeScript API keeps the same data types and units across platforms so you can build once and deploy everywhere.
+---
 
-## Why Capacitor Health?
+## 📦 Installation
 
-The only **free**, **unified** health data plugin for Capacitor supporting the latest native APIs:
+```bash
+npm install @interval-health/capacitor-health
+```
+
+After installation, sync your native projects:
+
+```bash
+npx cap sync
+```
 
-- **Health Connect (Android)** - Uses Google's newest health platform (replaces deprecated Google Fit)
-- **HealthKit (iOS)** - Full integration with Apple's health framework
-- **Unified API** - Same TypeScript interface across platforms with consistent units
-- **Multiple metrics** - Steps, distance, calories, heart rate, weight
-- **Read & Write** - Query historical data and save new health entries
-- **Modern standards** - Supports Android 8.0+ and iOS 14+
-- **Modern package management** - Supports both Swift Package Manager (SPM) and CocoaPods (SPM-ready for Capacitor 8)
+---
 
-Perfect for fitness apps, health trackers, wellness platforms, and medical applications.
+## 🚀 Supported Platforms
 
-## Documentation
+| Platform | Implementation | Minimum Version |
+|----------|---------------|-----------------|
+| **iOS** | Apple HealthKit | iOS 13.0+ |
+| **Android** | Health Connect | Android 9.0+ (API 28) |
+| **Web** | Not supported | - |
 
-The most complete doc is available here: https://capgo.app/docs/plugins/health/
+### Platform Requirements
 
-## Install
+#### iOS
+- Xcode 14.0 or later
+- iOS deployment target: 13.0+
+- You must add the required usage descriptions to your `Info.plist`
 
-```bash
-npm install @capgo/capacitor-health
-npx cap sync
-```
+#### Android
+- Android Studio Arctic Fox or later
+- Minimum SDK: 28 (Android 9.0)
+- Target SDK: 34+
+- Health Connect app must be installed on the device
 
-## iOS Setup
+---
 
-1. Open your Capacitor application's Xcode workspace and enable the **HealthKit** capability.
-2. Provide usage descriptions in `Info.plist` (update the copy for your product):
+## 🔐 Permissions & Setup
+
+### iOS Setup
+
+Add the following keys to your `ios/App/App/Info.plist` file:
 
 ```xml
 <key>NSHealthShareUsageDescription</key>
-<string>This app reads your health data to personalise your experience.</string>
+<string>This app needs access to read your health data.</string>
 <key>NSHealthUpdateUsageDescription</key>
-<string>This app writes new health entries that you explicitly create.</string>
+<string>This app needs access to write health data.</string>
+```
+
+Enable the **HealthKit** capability in your Xcode project:
+1. Open your project in Xcode
+2. Select your app target
+3. Go to **Signing & Capabilities**
+4. Click **+ Capability** and add **HealthKit**
+
+### Android Setup
+
+Add the Health Connect permissions to your `android/app/src/main/AndroidManifest.xml`:
+
+```xml
+<manifest>
+    <!-- Health Connect permissions -->
+    <uses-permission android:name="android.permission.health.READ_STEPS"/>
+    <uses-permission android:name="android.permission.health.WRITE_STEPS"/>
+    <uses-permission android:name="android.permission.health.READ_DISTANCE"/>
+    <uses-permission android:name="android.permission.health.WRITE_DISTANCE"/>
+    <uses-permission android:name="android.permission.health.READ_ACTIVE_CALORIES_BURNED"/>
+    <uses-permission android:name="android.permission.health.WRITE_ACTIVE_CALORIES_BURNED"/>
+    <uses-permission android:name="android.permission.health.READ_HEART_RATE"/>
+    <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_SLEEP"/>
+    <uses-permission android:name="android.permission.health.WRITE_SLEEP"/>
+
+    <application>
+        <!-- Required for Health Connect integration -->
+        <activity-alias
+            android:name="ViewPermissionUsageActivity"
+            android:exported="true"
+            android:targetActivity=".MainActivity"
+            android:permission="android.permission.START_VIEW_PERMISSION_USAGE">
+            <intent-filter>
+                <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE" />
+            </intent-filter>
+        </activity-alias>
+    </application>
+</manifest>
+```
+
+**Note**: Users must have the **Health Connect** app installed on their Android device. If not installed, the plugin will report that health data is unavailable.
+
+---
+
+## 📖 Usage Guide
+
+### Import the Plugin
+
+```typescript
+import { Health } from '@interval-health/capacitor-health';
+```
+
+### Complete Workflow Example
+
+Here's a typical flow for working with health data:
+
+```typescript
+import { Health } from '@interval-health/capacitor-health';
+
+async function setupHealthData() {
+  // 1. Check if health services are available
+  const availability = await Health.isAvailable();
+  
+  if (!availability.available) {
+    console.error('Health data unavailable:', availability.reason);
+    return;
+  }
+
+  // 2. Request authorization for data types
+  const authStatus = await Health.requestAuthorization({
+    read: ['steps', 'heartRate', 'weight', 'sleep'],
+    write: ['steps', 'weight']
+  });
+
+  console.log('Authorized to read:', authStatus.readAuthorized);
+  console.log('Denied to read:', authStatus.readDenied);
+
+  // 3. Read health samples
+  const stepsData = await Health.readSamples({
+    dataType: 'steps',
+    startDate: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString(), // 7 days ago
+    endDate: new Date().toISOString(),
+    limit: 100,
+    ascending: false
+  });
+
+  console.log('Steps data:', stepsData.samples);
+
+  // 4. Write a health sample
+  await Health.saveSample({
+    dataType: 'weight',
+    value: 70.5,
+    startDate: new Date().toISOString()
+  });
+
+  console.log('Weight saved successfully!');
+}
+```
+
+---
+
+## 📚 API Reference
+
+### Health Data Types
+
+The plugin supports the following health data types:
+
+```typescript
+export type HealthDataType = 
+  | 'steps' 
+  | 'distance' 
+  | 'calories' 
+  | 'heartRate' 
+  | 'weight' 
+  | 'sleep' 
+  | 'mobility' 
+  | 'activity' 
+  | 'heart' 
+  | 'body';
 ```
 
-## Android Setup
+| Data Type | Description | Unit | iOS | Android | Read | Write |
+|-----------|-------------|------|-----|---------|------|-------|
+| `steps` | Step count | count | ✅ | ✅ | ✅ | ✅ |
+| `distance` | Walking/running distance | meter | ✅ | ✅ | ✅ | ✅ |
+| `calories` | Active calories burned | kilocalorie | ✅ | ✅ | ✅ | ✅ |
+| `heartRate` | Heart rate | bpm (beats per minute) | ✅ | ✅ | ✅ | ✅ |
+| `weight` | Body weight | kilogram | ✅ | ✅ | ✅ | ✅ |
+| `sleep` | Sleep duration and stages | minute | ✅ | ❌ | ✅ | ✅ |
+| `mobility` | Mobility metrics | mixed | ✅ | ❌ | ✅ | ❌ |
+| `activity` | Activity metrics | mixed | ✅ | ❌ | ✅ | ❌ |
+| `heart` | Heart health metrics | mixed | ✅ | ❌ | ✅ | ❌ |
+| `body` | Body measurements | mixed | ✅ | ❌ | ✅ | ❌ |
+
+**Platform Support Notes**:
+- **iOS** supports all 10 data types
+- **Android** supports only 5 basic data types: `steps`, `distance`, `calories`, `heartRate`, and `weight`
+- The `sleep`, `mobility`, `activity`, `heart`, and `body` types are **iOS-only** and not available on Android
+- Composite types (`mobility`, `activity`, `heart`, `body`) are **read-only** on iOS
+
+### Sleep States
+
+When reading sleep data, each sample may include a `sleepState` property:
+
+| State | Description |
+|-------|-------------|
+| `inBed` | User is in bed but not necessarily asleep |
+| `asleep` | General sleep state (when specific stage unknown) |
+| `awake` | User is awake during sleep period |
+| `asleepCore` | Core/light sleep stage |
+| `asleepDeep` | Deep sleep stage |
+| `asleepREM` | REM (Rapid Eye Movement) sleep stage |
+| `unknown` | Sleep state could not be determined |
+
+---
+
+## 🔧 Methods
+
+### isAvailable()
 
-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:
+Check if health services are available on the current platform.
 
-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.
-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).
+```typescript
+Health.isAvailable(): Promise<AvailabilityResult>
+```
 
-If you already used Google Fit in your project you can remove the associated dependencies (`play-services-fitness`, `play-services-auth`, OAuth configuration, etc.).
+**Returns**: `Promise<AvailabilityResult>`
 
-## Usage
+**Example**:
+```typescript
+const result = await Health.isAvailable();
 
-```ts
-import { Health } from '@capgo/capacitor-health';
+if (result.available) {
+  console.log('Health services available on:', result.platform);
+} else {
+  console.log('Unavailable reason:', result.reason);
+}
+```
 
-// Verify that the native health SDK is present on this device
-const availability = await Health.isAvailable();
-if (!availability.available) {
-  console.warn('Health access unavailable:', availability.reason);
+**Response Example**:
+```typescript
+{
+  available: true,
+  platform: 'ios' // or 'android'
 }
 
-// Ask for separate read/write access scopes
-await Health.requestAuthorization({
-  read: ['steps', 'heartRate', 'weight', 'sleep'],
-  write: ['weight', 'sleep'],
+// When unavailable:
+{
+  available: false,
+  platform: 'android',
+  reason: 'Health Connect is unavailable on this device.'
+}
+```
+
+---
+
+### requestAuthorization()
+
+Request permission to read and/or write specific health data types. This will show the platform's native permission dialog.
+
+```typescript
+Health.requestAuthorization(options: AuthorizationOptions): Promise<AuthorizationStatus>
+```
+
+**Parameters**:
+- `options.read` (optional): Array of data types you want to read
+- `options.write` (optional): Array of data types you want to write
+
+**Returns**: `Promise<AuthorizationStatus>`
+
+**Example**:
+```typescript
+const status = await Health.requestAuthorization({
+  read: ['steps', 'heartRate', 'sleep'],
+  write: ['steps', 'weight']
+});
+
+console.log('Read authorized:', status.readAuthorized);
+console.log('Read denied:', status.readDenied);
+console.log('Write authorized:', status.writeAuthorized);
+console.log('Write denied:', status.writeDenied);
+```
+
+**Response Example**:
+```typescript
+{
+  readAuthorized: ['steps', 'heartRate'],
+  readDenied: ['sleep'],
+  writeAuthorized: ['steps', 'weight'],
+  writeDenied: []
+}
+```
+
+**Important Notes**:
+- On **iOS**, the HealthKit API doesn't reveal whether the user granted or denied read permission (for privacy reasons). The `readAuthorized` array will contain all requested types, even if some were denied.
+- On **Android**, Health Connect provides accurate permission status.
+- You must call this method before reading or writing health data.
+
+---
+
+### checkAuthorization()
+
+Check the current authorization status without prompting the user.
+
+```typescript
+Health.checkAuthorization(options: AuthorizationOptions): Promise<AuthorizationStatus>
+```
+
+**Parameters**: Same as `requestAuthorization()`
+
+**Returns**: `Promise<AuthorizationStatus>`
+
+**Example**:
+```typescript
+const status = await Health.checkAuthorization({
+  read: ['steps', 'heartRate'],
+  write: ['weight']
 });
 
-// Query the last 50 step samples from the past 24 hours
-const { samples } = await Health.readSamples({
+if (status.readAuthorized.includes('steps')) {
+  // We have permission to read steps
+  await readStepsData();
+}
+```
+
+**Response Example**: Same structure as `requestAuthorization()`
+
+---
+
+### readSamples()
+
+Read health samples for a specific data type within a time range.
+
+```typescript
+Health.readSamples(options: QueryOptions): Promise<ReadSamplesResult>
+```
+
+**Parameters**:
+- `options.dataType` (required): The type of health data to retrieve
+- `options.startDate` (optional): ISO 8601 start date (inclusive). Defaults to 24 hours ago
+- `options.endDate` (optional): ISO 8601 end date (exclusive). Defaults to now
+- `options.limit` (optional): Maximum number of samples to return. Defaults to 100
+- `options.ascending` (optional): Sort results by start date ascending. Defaults to false (descending)
+
+**Returns**: `Promise<ReadSamplesResult>`
+
+**Example**:
+```typescript
+// Read last 7 days of step data
+const result = await Health.readSamples({
   dataType: 'steps',
-  startDate: new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString(),
+  startDate: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString(),
   endDate: new Date().toISOString(),
   limit: 50,
+  ascending: false
 });
 
-// Persist a new body-weight entry (kilograms by default)
-await Health.saveSample({
-  dataType: 'weight',
-  value: 74.3,
+result.samples.forEach(sample => {
+  console.log(`${sample.value} ${sample.unit} on ${sample.startDate}`);
 });
+```
 
-// Query sleep data from the past week
-const { samples: sleepSamples } = await Health.readSamples({
+**Response Example**:
+```typescript
+{
+  samples: [
+    {
+      dataType: 'steps',
+      value: 8543,
+      unit: 'count',
+      startDate: '2025-12-17T00:00:00.000Z',
+      endDate: '2025-12-17T23:59:59.999Z',
+      sourceName: 'Apple Watch',
+      sourceId: 'com.apple.health'
+    },
+    {
+      dataType: 'steps',
+      value: 12032,
+      unit: 'count',
+      startDate: '2025-12-16T00:00:00.000Z',
+      endDate: '2025-12-16T23:59:59.999Z',
+      sourceName: 'iPhone',
+      sourceId: 'com.apple.health'
+    }
+  ]
+}
+```
+
+**Sleep Data Example**:
+```typescript
+const sleepResult = await Health.readSamples({
   dataType: 'sleep',
-  startDate: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString(),
-  endDate: new Date().toISOString(),
+  startDate: '2025-12-16T00:00:00.000Z',
+  endDate: '2025-12-17T00:00:00.000Z'
 });
-// Each sleep sample includes: value (duration in minutes), sleepState (stage), startDate, endDate
-```
 
-### Supported data types
+// Sleep samples include sleepState information
+sleepResult.samples.forEach(sample => {
+  console.log(`Sleep: ${sample.value} ${sample.unit}, State: ${sample.sleepState}`);
+});
+```
 
-| Identifier | Default unit  | Notes |
-| ---------- | ------------- | ----- |
-| `steps`    | `count`       | Step count deltas |
-| `distance` | `meter`       | Walking / running distance |
-| `calories` | `kilocalorie` | Active energy burned |
-| `heartRate`| `bpm`         | Beats per minute |
-| `weight`   | `kilogram`    | Body mass |
-| `sleep`    | `minute`      | Sleep sessions with stages (inBed, asleep, awake, asleepCore, asleepDeep, asleepREM) |
+**Response Example for Sleep**:
+```typescript
+{
+  samples: [
+    {
+      dataType: 'sleep',
+      value: 450,
+      unit: 'minute',
+      startDate: '2025-12-16T22:30:00.000Z',
+      endDate: '2025-12-17T06:00:00.000Z',
+      sleepState: 'asleepDeep',
+      sourceName: 'Sleep App'
+    }
+  ]
+}
+```
 
-All write operations expect the default unit shown above. On Android the `metadata` option is currently ignored by Health Connect.
+---
 
-## API
+### saveSample()
 
-<docgen-index>
+Write a single health sample to the native health store.
 
-* [`isAvailable()`](#isavailable)
-* [`requestAuthorization(...)`](#requestauthorization)
-* [`checkAuthorization(...)`](#checkauthorization)
-* [`readSamples(...)`](#readsamples)
-* [`saveSample(...)`](#savesample)
-* [`getPluginVersion()`](#getpluginversion)
-* [Interfaces](#interfaces)
-* [Type Aliases](#type-aliases)
+```typescript
+Health.saveSample(options: WriteSampleOptions): Promise<void>
+```
 
-</docgen-index>
+**Parameters**:
+- `options.dataType` (required): The type of health data to save
+- `options.value` (required): The numeric value
+- `options.unit` (optional): Unit override (must match the data type's expected unit)
+- `options.startDate` (optional): ISO 8601 start date. Defaults to now
+- `options.endDate` (optional): ISO 8601 end date. Defaults to startDate
+- `options.metadata` (optional): Additional key-value metadata (platform support varies)
 
-<docgen-api>
-<!--Update the source file JSDoc comments and rerun docgen to update the docs below-->
+**Returns**: `Promise<void>`
 
-### isAvailable()
+**Example - Save Weight**:
+```typescript
+await Health.saveSample({
+  dataType: 'weight',
+  value: 72.5,
+  startDate: new Date().toISOString()
+});
+```
 
+**Example - Save Steps with Time Range**:
 ```typescript
-isAvailable() => Promise<AvailabilityResult>
+const workoutStart = new Date('2025-12-17T10:00:00.000Z');
+const workoutEnd = new Date('2025-12-17T11:30:00.000Z');
+
+await Health.saveSample({
+  dataType: 'steps',
+  value: 5000,
+  startDate: workoutStart.toISOString(),
+  endDate: workoutEnd.toISOString(),
+  metadata: {
+    'workout': 'morning run',
+    'location': 'park'
+  }
+});
 ```
 
-Returns whether the current platform supports the native health SDK.
+**Example - Save Heart Rate**:
+```typescript
+await Health.saveSample({
+  dataType: 'heartRate',
+  value: 75,
+  unit: 'bpm',
+  startDate: new Date().toISOString()
+});
+```
 
-**Returns:** <code>Promise&lt;<a href="#availabilityresult">AvailabilityResult</a>&gt;</code>
+**Unit Validation**: The plugin validates that the provided unit matches the expected unit for the data type. For example:
+- `steps` expects `count`
+- `distance` expects `meter`
+- `calories` expects `kilocalorie`
+- `heartRate` expects `bpm`
+- `weight` expects `kilogram`
 
---------------------
+---
 
+### getPluginVersion()
 
-### requestAuthorization(...)
+Get the current version of the native plugin.
 
 ```typescript
-requestAuthorization(options: AuthorizationOptions) => Promise<AuthorizationStatus>
+Health.getPluginVersion(): Promise<{ version: string }>
 ```
 
-Requests read/write access to the provided data types.
-
-| Param         | Type                                                                  |
-| ------------- | --------------------------------------------------------------------- |
-| **`options`** | <code><a href="#authorizationoptions">AuthorizationOptions</a></code> |
+**Returns**: `Promise<{ version: string }>`
 
-**Returns:** <code>Promise&lt;<a href="#authorizationstatus">AuthorizationStatus</a>&gt;</code>
+**Example**:
+```typescript
+const { version } = await Health.getPluginVersion();
+console.log('Plugin version:', version);
+```
 
---------------------
+---
 
+## 💡 Common Usage Patterns
 
-### checkAuthorization(...)
+### 1. Displaying Daily Step Count
 
 ```typescript
-checkAuthorization(options: AuthorizationOptions) => Promise<AuthorizationStatus>
+async function getDailySteps() {
+  const today = new Date();
+  today.setHours(0, 0, 0, 0);
+  
+  const result = await Health.readSamples({
+    dataType: 'steps',
+    startDate: today.toISOString(),
+    endDate: new Date().toISOString()
+  });
+
+  const totalSteps = result.samples.reduce((sum, sample) => sum + sample.value, 0);
+  console.log('Steps today:', totalSteps);
+  
+  return totalSteps;
+}
 ```
 
-Checks authorization status for the provided data types without prompting the user.
-
-| Param         | Type                                                                  |
-| ------------- | --------------------------------------------------------------------- |
-| **`options`** | <code><a href="#authorizationoptions">AuthorizationOptions</a></code> |
+### 2. Weekly Activity Summary
 
-**Returns:** <code>Promise&lt;<a href="#authorizationstatus">AuthorizationStatus</a>&gt;</code>
+```typescript
+async function getWeeklySummary() {
+  const weekAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
+  
+  const [steps, distance, calories] = await Promise.all([
+    Health.readSamples({
+      dataType: 'steps',
+      startDate: weekAgo.toISOString(),
+      limit: 500
+    }),
+    Health.readSamples({
+      dataType: 'distance',
+      startDate: weekAgo.toISOString(),
+      limit: 500
+    }),
+    Health.readSamples({
+      dataType: 'calories',
+      startDate: weekAgo.toISOString(),
+      limit: 500
+    })
+  ]);
+
+  return {
+    totalSteps: steps.samples.reduce((sum, s) => sum + s.value, 0),
+    totalDistance: distance.samples.reduce((sum, s) => sum + s.value, 0),
+    totalCalories: calories.samples.reduce((sum, s) => sum + s.value, 0)
+  };
+}
+```
 
---------------------
+### 3. Logging Weight Over Time
 
+```typescript
+async function getWeightHistory(days: number = 30) {
+  const startDate = new Date(Date.now() - days * 24 * 60 * 60 * 1000);
+  
+  const result = await Health.readSamples({
+    dataType: 'weight',
+    startDate: startDate.toISOString(),
+    ascending: true
+  });
+
+  return result.samples.map(sample => ({
+    date: new Date(sample.startDate).toLocaleDateString(),
+    weight: sample.value,
+    unit: sample.unit
+  }));
+}
+```
 
-### readSamples(...)
+### 4. Sleep Analysis
 
 ```typescript
-readSamples(options: QueryOptions) => Promise<ReadSamplesResult>
+async function getLastNightSleep() {
+  const yesterday = new Date();
+  yesterday.setDate(yesterday.getDate() - 1);
+  yesterday.setHours(18, 0, 0, 0); // Start from 6 PM yesterday
+  
+  const result = await Health.readSamples({
+    dataType: 'sleep',
+    startDate: yesterday.toISOString(),
+    endDate: new Date().toISOString()
+  });
+
+  // Calculate total sleep time and breakdown by stage
+  const sleepByStage: Record<string, number> = {};
+  let totalSleep = 0;
+
+  result.samples.forEach(sample => {
+    const state = sample.sleepState || 'unknown';
+    sleepByStage[state] = (sleepByStage[state] || 0) + sample.value;
+    totalSleep += sample.value;
+  });
+
+  return {
+    totalMinutes: totalSleep,
+    totalHours: (totalSleep / 60).toFixed(1),
+    breakdown: sleepByStage
+  };
+}
 ```
 
-Reads samples for the given data type within the specified time frame.
+### 5. Recording a Workout
 
-| Param         | Type                                                  |
-| ------------- | ----------------------------------------------------- |
-| **`options`** | <code><a href="#queryoptions">QueryOptions</a></code> |
-
-**Returns:** <code>Promise&lt;<a href="#readsamplesresult">ReadSamplesResult</a>&gt;</code>
+```typescript
+async function recordWorkout() {
+  const workoutStart = new Date(Date.now() - 45 * 60 * 1000); // 45 minutes ago
+  const workoutEnd = new Date();
+
+  // Save multiple metrics from the workout
+  await Promise.all([
+    Health.saveSample({
+      dataType: 'steps',
+      value: 4500,
+      startDate: workoutStart.toISOString(),
+      endDate: workoutEnd.toISOString()
+    }),
+    Health.saveSample({
+      dataType: 'distance',
+      value: 3500, // 3.5 km in meters
+      startDate: workoutStart.toISOString(),
+      endDate: workoutEnd.toISOString()
+    }),
+    Health.saveSample({
+      dataType: 'calories',
+      value: 320,
+      startDate: workoutStart.toISOString(),
+      endDate: workoutEnd.toISOString()
+    })
+  ]);
+
+  console.log('Workout recorded successfully!');
+}
+```
 
---------------------
+---
 
+## ⚠️ Error Handling
 
-### saveSample(...)
+### Common Errors and Solutions
 
 ```typescript
-saveSample(options: WriteSampleOptions) => Promise<void>
+async function safeHealthRead() {
+  try {
+    // Check availability first
+    const availability = await Health.isAvailable();
+    if (!availability.available) {
+      throw new Error(`Health unavailable: ${availability.reason}`);
+    }
+
+    // Request authorization
+    const authStatus = await Health.requestAuthorization({
+      read: ['steps']
+    });
+
+    if (authStatus.readDenied.includes('steps')) {
+      throw new Error('User denied permission to read steps');
+    }
+
+    // Read data
+    const result = await Health.readSamples({
+      dataType: 'steps',
+      startDate: new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString()
+    });
+
+    return result.samples;
+
+  } catch (error) {
+    console.error('Health data error:', error);
+    
+    // Handle specific error cases
+    if (error.message.includes('unavailable')) {
+      alert('Please install Health Connect (Android) or enable HealthKit (iOS)');
+    } else if (error.message.includes('permission')) {
+      alert('Please grant health data permissions in settings');
+    } else if (error.message.includes('Unsupported data type')) {
+      alert('This health metric is not supported on your device');
+    } else {
+      alert('Unable to access health data. Please try again.');
+    }
+    
+    return [];
+  }
+}
 ```
 
-Writes a single sample to the native health store.
+### Error Types
 
-| Param         | Type                                                              |
-| ------------- | ----------------------------------------------------------------- |
-| **`options`** | <code><a href="#writesampleoptions">WriteSampleOptions</a></code> |
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `Health data is not available` | HealthKit/Health Connect not available | Check device compatibility |
+| `Unsupported data type` | Invalid dataType parameter | Use one of the supported data types |
+| `dataType is required` | Missing required parameter | Provide dataType in options |
+| `value is required` | Missing value for saveSample | Provide numeric value |
+| `Invalid ISO 8601 date` | Malformed date string | Use proper ISO 8601 format: `new Date().toISOString()` |
+| `endDate must be greater than startDate` | Invalid date range | Ensure endDate >= startDate |
+| `Health Connect needs an update` | Outdated Health Connect app | Update Health Connect from Play Store |
+| `Unsupported unit` | Wrong unit for data type | Use the correct unit or omit to use default |
 
---------------------
+---
 
+## 🔒 Privacy & Security
 
-### getPluginVersion()
+### iOS Privacy Considerations
 
-```typescript
-getPluginVersion() => Promise<{ version: string; }>
-```
+- **HealthKit data never leaves the device** unless explicitly shared by your app
+- Apple's HealthKit restricts read authorization status for privacy—your app cannot definitively know if read permission was denied
+- Always provide clear explanations in your usage description strings
+- Consider implementing fallback flows if users deny permissions
+
+### Android Privacy Considerations
 
-Get the native Capacitor plugin version
+- Health Connect provides transparent permission management
+- Users can revoke permissions at any time through system settings
+- Your app should handle permission changes gracefully
+- Health Connect shows users which apps access their data
 
-**Returns:** <code>Promise&lt;{ version: string; }&gt;</code>
+### Best Practices
 
---------------------
+1. **Request only what you need**: Don't request access to all data types if you only need steps
+2. **Explain before asking**: Show UI explaining why you need health data before calling `requestAuthorization()`
+3. **Handle denials gracefully**: Provide alternative functionality if permissions are denied
+4. **Respect user privacy**: Don't store sensitive health data on external servers without explicit consent
+5. **Test permission flows**: Test your app's behavior when permissions are denied or revoked
 
+---
 
-### Interfaces
+## 🐛 Known Limitations & Issues
 
+### iOS Limitations
 
-#### AvailabilityResult
+1. **Read Authorization Status**: HealthKit doesn't reveal whether users denied read permissions (privacy feature)
+2. **Background Access**: Reading health data in the background requires additional setup with Background Modes capability
+3. **Composite Types**: `mobility`, `activity`, `heart`, and `body` are iOS-only aggregate types that return data from multiple HealthKit sources
+4. **Write Authorization**: Apps can only write data types they created or have explicit write permission for
 
-| Prop            | Type                                     | Description                                            |
-| --------------- | ---------------------------------------- | ------------------------------------------------------ |
-| **`available`** | <code>boolean</code>                     |                                                        |
-| **`platform`**  | <code>'ios' \| 'android' \| 'web'</code> | Platform specific details (for debugging/diagnostics). |
-| **`reason`**    | <code>string</code>                      |                                                        |
+### Android Limitations
 
+1. **Health Connect Required**: Users must have the Health Connect app installed (available on Android 9+)
+2. **Device Support**: Not all Android devices support Health Connect (mainly newer devices)
+3. **Limited Data Types**: Android implementation supports fewer composite types than iOS
+4. **API Level**: Requires minimum API level 28 (Android 9.0)
 
-#### AuthorizationStatus
+### General Limitations
 
-| Prop                  | Type                          |
-| --------------------- | ----------------------------- |
-| **`readAuthorized`**  | <code>HealthDataType[]</code> |
-| **`readDenied`**      | <code>HealthDataType[]</code> |
-| **`writeAuthorized`** | <code>HealthDataType[]</code> |
-| **`writeDenied`**     | <code>HealthDataType[]</code> |
+1. **No Web Support**: This plugin does not work on web platforms (browser)
+2. **Data Sync Delays**: Health data may take time to sync between devices/apps
+3. **Source Variability**: Different apps and devices may report the same metrics differently
+4. **Historical Data**: Very old data (>1 year) may not be available depending on device settings
+5. **Unit Conversions**: The plugin uses specific units for each data type—unit conversion must be done in your app code
 
+---
 
-#### AuthorizationOptions
+## 📱 Platform-Specific Notes
 
-| Prop        | Type                          | Description                                             |
-| ----------- | ----------------------------- | ------------------------------------------------------- |
-| **`read`**  | <code>HealthDataType[]</code> | Data types that should be readable after authorization. |
-| **`write`** | <code>HealthDataType[]</code> | Data types that should be writable after authorization. |
+### iOS (HealthKit)
 
+- Requires physical iOS device for testing (Simulator has limited support)
+- Some health metrics require specific hardware (Apple Watch for certain heart rate measurements)
+- Sleep data quality depends on the user's sleep tracking app (Apple Watch, third-party apps)
+- HealthKit automatically aggregates data from multiple sources
 
-#### ReadSamplesResult
+### Android (Health Connect)
 
-| Prop          | Type                        |
-| ------------- | --------------------------- |
-| **`samples`** | <code>HealthSample[]</code> |
+- Health Connect must be installed separately on devices with Android 13 or lower
+- Android 14+ includes Health Connect as a system service
+- Health Connect serves as a centralized hub for health data from multiple apps
+- Not all Android OEMs enable Health Connect on their devices
+- Users control which apps can access Health Connect through system settings
 
+---
 
-#### HealthSample
+## 🧪 Testing
 
-| Prop             | Type                                                      | Description                                         |
-| ---------------- | --------------------------------------------------------- | --------------------------------------------------- |
-| **`dataType`**   | <code><a href="#healthdatatype">HealthDataType</a></code> |                                                     |
-| **`value`**      | <code>number</code>                                       |                                                     |
-| **`unit`**       | <code><a href="#healthunit">HealthUnit</a></code>         |                                                     |
-| **`startDate`**  | <code>string</code>                                       |                                                     |
-| **`endDate`**    | <code>string</code>                                       |                                                     |
-| **`sourceName`** | <code>string</code>                                       |                                                     |
-| **`sourceId`**   | <code>string</code>                                       |                                                     |
-| **`sleepState`** | <code><a href="#sleepstate">SleepState</a></code>         | Sleep state (only present when dataType is 'sleep') |
+### Testing on iOS
 
+1. Use a physical device (Simulator has limited HealthKit support)
+2. Generate sample health data using the Health app or third-party apps
+3. Test with Apple Watch if testing watch-specific metrics
 
-#### QueryOptions
+### Testing on Android
 
-| Prop            | Type                                                      | Description                                                        |
-| --------------- | --------------------------------------------------------- | ------------------------------------------------------------------ |
-| **`dataType`**  | <code><a href="#healthdatatype">HealthDataType</a></code> | The type of data to retrieve from the health store.                |
-| **`startDate`** | <code>string</code>                                       | Inclusive ISO 8601 start date (defaults to now - 1 day).           |
-| **`endDate`**   | <code>string</code>                                       | Exclusive ISO 8601 end date (defaults to now).                     |
-| **`limit`**     | <code>number</code>                                       | Maximum number of samples to return (defaults to 100).             |
-| **`ascending`** | <code>boolean</code>                                      | Return results sorted ascending by start date (defaults to false). |
+1. Install Health Connect from the Play Store (if not pre-installed)
+2. Use Health Connect's test data generator or third-party health apps
+3. Test permission flows thoroughly—users can grant/deny per-data-type
+4. Test on multiple Android versions (9, 10, 13, 14) for compatibility
 
+---
 
-#### WriteSampleOptions
+## 🤝 Contributing
 
-| 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`, minute for `sleep`). |
-| **`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.                                                                                                                                                |
+Contributions are welcome! Please follow these guidelines:
 
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes with clear commit messages
+4. Test on both iOS and Android
+5. Submit a pull request
 
-### Type Aliases
+Please ensure your code follows the existing code style and includes appropriate error handling.
 
+---
 
-#### HealthDataType
+## 📄 License
 
-<code>'steps' | 'distance' | 'calories' | 'heartRate' | 'weight' | 'sleep'</code>
+This project is licensed under the **MPL-2.0 License** (Mozilla Public License 2.0).
 
+See the [LICENSE](LICENSE) file for details.
 
-#### HealthUnit
+---
 
-<code>'count' | 'meter' | 'kilocalorie' | 'bpm' | 'kilogram' | 'minute'</code>
+## 🔗 Links
 
+- **GitHub Repository**: [https://github.com/sandip-3008/capacitor-health](https://github.com/sandip-3008/capacitor-health)
+- **npm Package**: [@interval-health/capacitor-health](https://www.npmjs.com/package/@interval-health/capacitor-health)
+- **Issues & Bug Reports**: [GitHub Issues](https://github.com/sandip-3008/capacitor-health/issues)
 
-#### SleepState
+---
 
-<code>'inBed' | 'asleep' | 'awake' | 'asleepCore' | 'asleepDeep' | 'asleepREM' | 'unknown'</code>
+## 📞 Support
 
+For questions, issues, or feature requests:
 
-#### Record
+1. Check the [documentation](#-api-reference) and [common patterns](#-common-usage-patterns)
+2. Search [existing issues](https://github.com/sandip-3008/capacitor-health/issues)
+3. Open a new issue with detailed information about your problem
 
-Construct a type with a set of properties K of type T
+**Note**: When reporting issues, please include:
+- Platform (iOS/Android)
+- OS version
+- Plugin version
+- Code sample demonstrating the issue
+- Error messages or logs
 
-<code>{
 [P in K]: T;
 }</code>
+---
 
-</docgen-api>
+## 📋 TypeScript Types
+
+The plugin is written in TypeScript and includes full type definitions. Import types directly:
+
+```typescript
+import {
+  Health,
+  HealthDataType,
+  HealthUnit,
+  SleepState,
+  AuthorizationOptions,
+  AuthorizationStatus,
+  QueryOptions,
+  HealthSample,
+  ReadSamplesResult,
+  WriteSampleOptions
+} from '@interval-health/capacitor-health';
+```
 
-### Credits:
+---
 
-this plugin was inspired by the work of https://github.com/perfood/capacitor-healthkit/ for ios and https://github.com/perfood/capacitor-google-fit for Android
+**Made with ❤️ for the Capacitor community**