npm package: @robinhealth/health-sdk
Description: Unified health data SDK for React Native — HealthKit (iOS) and Health Connect (Android)
Latest version: 0.8.2

# @robin/health-sdk

Unified health data SDK for React Native — HealthKit (iOS) and Health Connect (Android).

One API, both platforms. Query steps, heart rate, sleep, workouts, body composition, and more without writing platform-specific code.

## Features

- **19 health data types** — activity, vitals, sleep, body composition, hydration
- **79 workout types** — from running and cycling to pickleball and underwater diving
- **Sleep sessions** — full stage breakdowns (awake, light, deep, REM)
- **Aggregations** — sum, average, min, max over any date range
- **Permission management** — persistent state tracking via expo-sqlite
- **Type-safe** — full TypeScript definitions

## Install

```bash
npm install @robin/health-sdk
```

Then install the platform-specific peer dependencies you need:

```bash
# iOS
npm install @kingstinct/react-native-healthkit

# Android
npm install react-native-health-connect

# Permission persistence (recommended)
npm install expo-sqlite
```

## Platform Setup

### iOS (Expo)

Add the HealthKit plugin to your `app.json`:

```json
{
  "expo": {
    "plugins": [
      [
        "@kingstinct/react-native-healthkit",
        {
          "NSHealthShareUsageDescription": "This app needs access to your health data."
        }
      ]
    ]
  }
}
```

### iOS (Bare React Native)

1. Enable the **HealthKit** capability in Xcode
2. Add `NSHealthShareUsageDescription` to `Info.plist`
3. Run `pod install`

### Android (Expo)

Add the Health Connect plugin to your `app.json`:

```json
{
  "expo": {
    "plugins": [
      [
        "expo-health-connect",
        {
          "permissions": [
            "android.permission.health.READ_STEPS",
            "android.permission.health.READ_HEART_RATE"
          ]
        }
      ]
    ]
  }
}
```

Requires `minSdkVersion` 28+.

### Android (Bare React Native)

1. Set `minSdkVersion` 28+ in `build.gradle`
2. Declare health permissions in `AndroidManifest.xml`
3. Add the `ViewPermissionUsageActivity` alias for the permissions rationale screen

See [docs/INTEGRATION.md](docs/INTEGRATION.md) for full setup instructions.

## Quick Start

```typescript
import {
  createHealthProvider,
  HealthDataType,
} from 'robin-health-sdk';

const provider = createHealthProvider();

// Check availability
const available = await provider.isAvailable();

// Request permissions
await provider.requestAuthorization([
  HealthDataType.Steps,
  HealthDataType.HeartRate,
  HealthDataType.SleepAnalysis,
]);

// Query samples
const now = new Date();
const yesterday = new Date(now.getTime() - 24 * 60 * 60 * 1000);

const heartRateSamples = await provider.querySamples(
  HealthDataType.HeartRate,
  yesterday,
  now,
);

// Get aggregated stats
const stepTotal = await provider.queryAggregated(
  HealthDataType.Steps,
  yesterday,
  now,
);
console.log(`Steps: ${stepTotal.sum}`);

// Query workouts
const workouts = await provider.queryWorkouts(yesterday, now);

// Query sleep sessions with stage breakdowns
const sleep = await provider.querySleepSessions(yesterday, now);
```

## Supported Data Types

| Category | Type | Unit |
|----------|------|------|
| **Activity** | Steps | count |
| | DistanceWalkingRunning | meters |
| | ActiveEnergyBurned | kcal |
| | FlightsClimbed | count |
| **Vitals** | HeartRate | bpm |
| | RestingHeartRate | bpm |
| | BloodPressureSystolic | mmHg |
| | BloodPressureDiastolic | mmHg |
| | BloodOxygen | % |
| | RespiratoryRate | breaths/min |
| **Sleep** | SleepAnalysis | hours |
| **Body** | BodyFatPercentage | % |
| | BodyMassIndex | kg/m² |
| | BasalEnergyBurned | kcal |
| **Hydration** | Water | mL |

## API

### `createHealthProvider(): HealthProvider`

Returns a platform-specific health provider (HealthKit on iOS, Health Connect on Android).

### `HealthProvider`

| Method | Description |
|--------|-------------|
| `isAvailable()` | Check if health data is available on this device |
| `shouldRequestAuthorization(types)` | Check if permissions need to be requested |
| `requestAuthorization(types)` | Request read access for the given data types |
| `getPermissionStatus()` | Get current permission status |
| `querySamples(type, start, end)` | Get individual readings in a date range |
| `queryAggregated(type, start, end)` | Get aggregated stats (sum, avg, min, max) |
| `queryWorkouts(start, end)` | Get workout sessions with metadata |
| `querySleepSessions(start, end)` | Get sleep sessions with stage breakdowns |

See [docs/API.md](docs/API.md) for the full API reference with type definitions and platform notes.

## Requirements

- Node >= 16
- React >= 18.0.0
- React Native >= 0.72.0
- iOS 13+ / Android SDK 28+

## License

MIT — see [LICENSE](LICENSE) for details.