@appeeky/expo-healthkit 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+## 0.1.0
+
+### New features
+
+- Initial Expo Modules API wrapper for Apple HealthKit
+- Android Health Connect backend behind the same identifier-based JS API
+- Generic quantity, category, workout, statistics, and anchored queries
+- ECG, activity rings, clinical records, audiograms, and workout GPS route queries
+- Blood pressure / food correlations (`queryCorrelations`, `saveCorrelation`) and heartbeat series
+- Authorization, characteristics, observers, and background delivery
+- Config plugin for HealthKit entitlements, usage descriptions, Health Connect permissions, and Android `minSdk` 26
+
+### Fixes
+
+- Request Health Connect permissions via the Android 14+ runtime permission APIs instead of `startActivityForResult`, which throws `ActivityNotFoundException`
+- Convert HealthKit `NSException` crashes (invalid predicates, missing calendars) into `ERR_HEALTHKIT_NATIVE` promise rejections so the JS app can show the error instead of aborting
+
+### Packaging
+
+- Published as [`@appeeky/expo-healthkit`](https://www.npmjs.com/package/@appeeky/expo-healthkit)
+- npm-ready `exports`, `.npmignore`, and `prepublishOnly` build
+- App Store privacy manifest (`PrivacyInfo.xcprivacy`)
+- GitHub Actions for lint, typecheck, tests with coverage thresholds, and pack contents
+- [PolyForm Shield 1.0.0](./LICENSE) (source-available; apps may use the SDK, competing SDKs may not)

package/LICENSE

@@ -0,0 +1,92 @@
+# PolyForm Shield License 1.0.0
+
+https://polyformproject.org/licenses/shield/1.0.0
+
+Required Notice: Copyright 2026 Erencan Arica (https://github.com/Eronred)
+Licensor Line of Business: expo-healthkit HealthKit and Health Connect SDK for Expo and React Native (https://github.com/appeeky/expo-healthkit)
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose. However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software. Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software. For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncompete
+
+Any purpose is a permitted purpose, except for providing any product that competes with the software or any product the licensor or any of its affiliates provides using the software.
+
+## Competition
+
+Goods and services compete even when they provide functionality through different kinds of interfaces or for different technical platforms. Applications can compete with services, libraries with plugins, frameworks with development tools, and so on, even if they're written in different programming languages or for different computer architectures. Goods and services compete even when provided free of charge. If you market a product as a practical substitute for the software or another product, it definitely competes.
+
+## New Products
+
+If you are using the software to provide a product that does not compete, but the licensor or any of its affiliates brings your product into competition by providing a new version of the software or another product using the software, you may continue using versions of the software available under these terms beforehand to provide your competing product, but not any later versions.
+
+## Discontinued Products
+
+You may begin using the software to compete with a product or service that the licensor or any of its affiliates has stopped providing, unless the licensor includes a plain-text line beginning with `Licensor Line of Business:` with the software that mentions that line of business. For example:
+
+> Licensor Line of Business: YoyodyneCMS Content Management System (http://example.com/cms)
+
+## Sales of Business
+
+If the licensor or any of its affiliates sells a line of business developing the software or using the software to provide a product, the buyer can also enforce [Noncompete](#noncompete) for that product.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else. These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice. Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+A **product** can be a good or service, or a combination of them.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all its affiliates.
+
+**Affiliates** means the other organizations than an organization has control over, is under the control of, or is under common control with.
+
+**Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise. Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

package/README.md

@@ -0,0 +1,453 @@
+![HealthKit and Health Connect for Expo](https://raw.githubusercontent.com/appeeky/expo-healthkit/main/docs/banner.jpg)
+
+# @appeeky/expo-healthkit
+
+Apple [HealthKit](https://developer.apple.com/documentation/healthkit) and Android [Health Connect](https://developer.android.com/health-and-fitness/guides/health-connect) for [Expo](https://expo.dev) and React Native, built on the [Expo Modules API](https://docs.expo.dev/modules/overview/).
+
+One JavaScript API on both platforms. You pass Apple HealthKit type identifiers (`HKQuantityTypeIdentifierStepCount`, …), query or save samples, and the native layer talks to HealthKit on iOS and Health Connect on Android.
+
+
+|              | iOS                                       | Android                                          |
+| ------------ | ----------------------------------------- | ------------------------------------------------ |
+| Backend      | HealthKit                                 | Health Connect                                   |
+| App code     | Same identifiers and methods              | Same identifiers and methods                     |
+| Availability | `isAvailable()` when HealthKit is present | `isAvailable()` when Health Connect is installed |
+
+
+- Expo SDK 53+ / New Architecture (tested on SDK 57)
+- Promise-based TypeScript API
+- Config plugin for HealthKit entitlements **and** Health Connect permissions (`minSdk` 26)
+- iOS 16.4+, Android 8+ (API 26+). Web reports `isAvailable() === false`
+
+> Health data APIs cannot run in Expo Go. Use a development build (`npx expo run:ios` or `npx expo run:android`).
+
+
+
+## 📋 Requirements
+
+- Expo SDK 53 or later and a **development build** (not Expo Go)
+- iOS 16.4+, physical iPhone or Simulator, with the HealthKit capability enabled on the App ID in the [Apple Developer portal](https://developer.apple.com/account)
+- Android 8+ with [Health Connect](https://play.google.com/store/apps/details?id=com.google.android.apps.healthdata) (built-in on Android 14+)
+
+
+
+## 📦 Install
+
+```sh
+npx expo install @appeeky/expo-healthkit
+```
+
+From GitHub, if you are tracking `main` before a release:
+
+```sh
+npx expo install github:appeeky/expo-healthkit
+```
+
+Add the config plugin in `app.json` / `app.config.ts`:
+
+```json
+{
+  "expo": {
+    "plugins": [
+      [
+        "@appeeky/expo-healthkit",
+        {
+          "healthSharePermission": "Allow $(PRODUCT_NAME) to read your health data",
+          "healthUpdatePermission": "Allow $(PRODUCT_NAME) to write health data",
+          "isBackgroundDeliveryEnabled": true
+        }
+      ]
+    ],
+    "ios": {
+      "bundleIdentifier": "com.example.app"
+    }
+  }
+}
+```
+
+Then rebuild native code:
+
+```sh
+npx expo prebuild --clean
+npx expo run:ios
+# or
+npx expo run:android
+```
+
+Enable the **HealthKit** capability on the App ID in the Apple Developer portal. The plugin writes the entitlement into the generated Xcode project; the capability still has to be allowed for that bundle ID.
+
+On Android, install [Health Connect](https://play.google.com/store/apps/details?id=com.google.android.apps.healthdata) if the OS does not already include it (built-in on Android 14+). The plugin declares the Health Connect permissions and raises `minSdk` to 26.
+
+## ⚡️ Quick start
+
+```ts
+import * as HealthKit from '@appeeky/expo-healthkit';
+
+if (!HealthKit.isAvailable()) {
+  return;
+}
+
+await HealthKit.requestAuthorization({
+  toRead: [
+    HealthKit.QuantityType.stepCount,
+    HealthKit.QuantityType.heartRate,
+    HealthKit.CategoryType.sleepAnalysis,
+    HealthKit.WorkoutType.workout,
+  ],
+  toShare: [HealthKit.QuantityType.stepCount],
+});
+
+const today = new Date();
+today.setHours(0, 0, 0, 0);
+
+const steps = await HealthKit.queryStatistics({
+  type: HealthKit.QuantityType.stepCount,
+  unit: HealthKit.Unit.count,
+  from: today,
+  to: new Date(),
+  options: HealthKit.StatisticsOption.cumulativeSum,
+});
+
+const heartRate = await HealthKit.queryQuantitySamples({
+  type: HealthKit.QuantityType.heartRate,
+  unit: HealthKit.Unit.countPerMinute,
+  from: today,
+  to: new Date(),
+  limit: 20,
+  ascending: false,
+});
+```
+
+
+
+## 📚 API
+
+
+
+### 🔐 Availability and permissions
+
+
+| Method                                                  | Notes                                                                                            |
+| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `isAvailable()`                                         | `true` on iOS when HealthKit is present, and on Android when Health Connect is installed         |
+| `requestAuthorization({ toRead, toShare })`             | Shows the system permission sheet (HealthKit or Health Connect)                                  |
+| `getAuthorizationStatus(type)`                          | iOS: reliable for **write** types. Android: reflects granted Health Connect read or write access |
+| `getRequestStatusForAuthorization({ toRead, toShare })` | Whether you still need to prompt                                                                 |
+
+
+On iOS, read authorization is intentionally opaque: `getAuthorizationStatus` returning `notDetermined` / `sharingDenied` does **not** mean the user blocked reads.
+
+### 📊 Samples and statistics
+
+
+|     | Method                                                                    | Use for                                                       |
+| --- | ------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| ❤️  | `queryQuantitySamples({ type, unit, from, to, limit, ascending })`        | Heart rate, weight, glucose, …                                |
+| 😴  | `queryCategorySamples({ type, from, to, limit, ascending })`              | Sleep, mindful sessions, …                                    |
+| 🏃  | `queryWorkouts({ from, to, limit, ascending, activityType })`             | Workouts                                                      |
+| 🫀  | `queryElectrocardiograms({ from, to, limit, ascending, includeVoltage })` | ECG samples. Voltage is omitted unless `includeVoltage: true` |
+| 🔴  | `queryActivitySummaries({ from, to })`                                    | Move / Exercise / Stand rings                                 |
+| 🏥  | `queryClinicalRecords({ type, from, to, limit, ascending })`              | FHIR clinical records. Needs `isClinicalDataEnabled`          |
+| 👂  | `queryAudiograms({ from, to, limit, ascending })`                         | Hearing-test audiograms                                       |
+| 📍  | `queryWorkoutRoute({ workoutUUID })`                                      | GPS locations for a workout                                   |
+| 🩺  | `queryCorrelations({ type, from, to, limit, ascending })`                 | Blood pressure and food correlations                          |
+| 💓  | `queryHeartbeatSeries({ from, to, limit, ascending, includeBeats })`      | Beat-to-beat series used for HRV                              |
+| 📈  | `queryStatistics({ type, unit, from, to, options })`                      | Totals / min / max / average for a range                      |
+| 📅  | `queryStatisticsCollection({ type, unit, from, to, interval, options })`  | Daily (or hourly) buckets                                     |
+| 🔄  | `queryAnchored({ type, unit, from, to, limit, anchor })`                  | Incremental sync. Store `anchor` and pass it back             |
+
+
+`limit` defaults to HealthKit's unlimited query. Dates accept `Date` or ISO-8601 strings. Units are HealthKit unit strings (`count`, `count/min`, `kcal`, `kg`, `m`, `%`, …) also exported as `Unit`.
+
+ECG, activity rings, clinical records, audiograms, workout GPS routes, heartbeat series, and correlations are not quantity/category/workout samples. Request the matching identifier in `toRead`:
+
+```ts
+await HealthKit.requestAuthorization({
+  toRead: [
+    HealthKit.ElectrocardiogramType.electrocardiogram,
+    HealthKit.ActivitySummaryType.activitySummary,
+    HealthKit.ClinicalType.allergyRecord,
+    HealthKit.AudiogramType.audiogram,
+    HealthKit.WorkoutType.workout,
+    HealthKit.SeriesType.workoutRoute,
+    HealthKit.SeriesType.heartbeat,
+    HealthKit.CorrelationType.bloodPressure,
+    HealthKit.CorrelationType.food,
+  ],
+});
+
+const rings = await HealthKit.queryActivitySummaries({ from: today });
+const [workout] = await HealthKit.queryWorkouts({ limit: 1 });
+const routes = workout
+  ? await HealthKit.queryWorkoutRoute({ workoutUUID: workout.uuid })
+  : [];
+const pressure = await HealthKit.queryCorrelations({
+  type: HealthKit.CorrelationType.bloodPressure,
+  limit: 20,
+});
+```
+
+Clinical reads also need `isClinicalDataEnabled: true` on the config plugin.
+
+### ✍️ Write / delete
+
+```ts
+await HealthKit.saveQuantitySample({
+  type: HealthKit.QuantityType.stepCount,
+  unit: HealthKit.Unit.count,
+  value: 100,
+  startDate: new Date(Date.now() - 60_000),
+  endDate: new Date(),
+});
+
+await HealthKit.saveCategorySample({
+  type: HealthKit.CategoryType.sleepAnalysis,
+  value: HealthKit.SleepAnalysisValue.asleepCore,
+  startDate,
+  endDate,
+});
+
+await HealthKit.saveWorkout({
+  activityType: HealthKit.WorkoutActivityType.running,
+  startDate,
+  endDate,
+  energyBurned: 400,
+  energyBurnedUnit: HealthKit.Unit.kilocalorie,
+  distance: 5000,
+  distanceUnit: HealthKit.Unit.meter,
+});
+
+await HealthKit.saveCorrelation({
+  type: HealthKit.CorrelationType.bloodPressure,
+  startDate: new Date(),
+  objects: [
+    {
+      type: HealthKit.QuantityType.bloodPressureSystolic,
+      unit: HealthKit.Unit.millimeterOfMercury,
+      value: 120,
+    },
+    {
+      type: HealthKit.QuantityType.bloodPressureDiastolic,
+      unit: HealthKit.Unit.millimeterOfMercury,
+      value: 80,
+    },
+  ],
+});
+
+await HealthKit.deleteObjects({
+  type: HealthKit.QuantityType.stepCount,
+  uuid,
+});
+```
+
+
+
+### 👤 Characteristics
+
+`getBiologicalSex()`, `getBloodType()`, `getDateOfBirth()`, `getFitzpatrickSkinType()`, `getWheelchairUse()`. These are read-only HealthKit characteristics; include the matching `CharacteristicType` in `toRead`.
+
+### 🔔 Background updates
+
+```ts
+await HealthKit.observe([HealthKit.QuantityType.stepCount]);
+
+const subscription = HealthKit.addUpdateListener(({ type }) => {
+  // Re-query that type
+});
+
+await HealthKit.enableBackgroundDelivery(
+  HealthKit.QuantityType.stepCount,
+  HealthKit.UpdateFrequency.hourly
+);
+```
+
+`useHealthKitUpdates()` is a React hook around the same event.
+
+Background delivery needs `isBackgroundDeliveryEnabled: true` on the config plugin and the HealthKit background mode.
+
+## 🏷️ Identifiers
+
+Pass Apple's raw identifier strings. Named constants are provided for autocomplete; unknown identifiers still work if HealthKit knows them.
+
+```ts
+HealthKit.QuantityType.stepCount
+// 'HKQuantityTypeIdentifierStepCount'
+
+HealthKit.queryQuantitySamples({
+  type: 'HKQuantityTypeIdentifierStepCount',
+  unit: 'count',
+});
+```
+
+App code should keep using Apple identifier strings on both platforms. See [Cross-platform](#cross-platform) for what Health Connect maps, what stays iOS-only, and how to handle those APIs without `Platform.OS` forks.
+
+## 🌍 Cross-platform
+
+JavaScript always speaks HealthKit. You never pass Health Connect record class names from app code. The native layer chooses the backend:
+
+```mermaid
+flowchart LR
+  App["App JS<br/>QuantityType.stepCount"] --> API["@appeeky/expo-healthkit"]
+  API --> iOS["iOS<br/>HealthKit"]
+  API --> Android["Android<br/>Health Connect"]
+```
+
+Mapped types (steps, heart rate, sleep, workouts, weight, blood pressure, nutrition, …) use the **same method and identifier** on both platforms. Unmapped identifiers are skipped in Android `requestAuthorization`. Calling an Apple-only method on Android throws `ERR_HEALTH_CONNECT_UNSUPPORTED` instead of requiring `if (Platform.OS === 'ios')` on every query.
+
+Hide Apple-only UI by catching that code:
+
+```ts
+try {
+  const rings = await HealthKit.queryActivitySummaries({ from: today });
+} catch (error) {
+  if (error instanceof Error && 'code' in error && error.code === 'ERR_HEALTH_CONNECT_UNSUPPORTED') {
+    return;
+  }
+  throw error;
+}
+```
+
+### What works on both
+
+| Area | Identifiers / methods |
+| --- | --- |
+| Activity | `QuantityType.stepCount`, walking/running/cycling/swimming/wheelchair distance, `flightsClimbed`, `pushCount`, `activeEnergyBurned`, `basalEnergyBurned` |
+| Heart | `heartRate`, `restingHeartRate`, `heartRateVariabilitySDNN`, `vo2Max`, `oxygenSaturation`, `respiratoryRate` |
+| Body | `bodyMass`, `height`, `bodyFatPercentage`, `leanBodyMass`, `bodyTemperature`, `bloodGlucose` |
+| Blood pressure | `CorrelationType.bloodPressure` plus systolic / diastolic quantities |
+| Nutrition | `CorrelationType.food`, `dietaryWater`, other `HKQuantityTypeIdentifierDietary*` types |
+| Sleep | `CategoryType.sleepAnalysis` |
+| Workouts | `queryWorkouts` / `saveWorkout` (`WorkoutActivityType` mapped onto Health Connect exercise types) |
+| Aggregates | `queryStatistics`, `queryStatisticsCollection`, `queryAnchored` |
+| Writes | `saveQuantitySample`, `saveCategorySample`, `saveCorrelation`, `deleteObjects` |
+
+### iOS-only
+
+These throw `ERR_HEALTH_CONNECT_UNSUPPORTED` on Android. Health Connect has no equivalent (or no stable mapping yet):
+
+| API | Why |
+| --- | --- |
+| `queryElectrocardiograms` | Apple Watch ECG |
+| `queryActivitySummaries` | Move / Exercise / Stand rings |
+| `queryClinicalRecords` | FHIR health records |
+| `queryAudiograms` | Hearing-test charts |
+| `queryWorkoutRoute` | Workout GPS polylines |
+| `queryHeartbeatSeries` | Beat-to-beat series |
+| `getBiologicalSex`, `getBloodType`, `getDateOfBirth`, `getFitzpatrickSkinType`, `getWheelchairUse` | HealthKit characteristics |
+| `observe`, `enableBackgroundDelivery` | HealthKit observer queries / background delivery |
+
+### Behavioral differences
+
+| | iOS | Android |
+| --- | --- | --- |
+| Backend | HealthKit | Health Connect (`connect-client` 1.1) |
+| `isAvailable()` | HealthKit present | Health Connect installed (built-in on Android 14+; otherwise the Health Connect app) |
+| Read permission | Apple does **not** disclose read grants | `getAuthorizationStatus` reflects granted Health Connect read or write |
+| Unmapped types in `requestAuthorization` | Forwarded if HealthKit knows them | Skipped |
+| History window | Granted samples, any age | Often last **30 days** unless the user also grants history access (the SDK requests it) |
+| Anchored sync | `HKQueryAnchor` (opaque string) | Health Connect changes token (opaque string). Do not reuse an iOS anchor on Android |
+| HRV | SDNN | Mapped to Health Connect RMSSD on the same `heartRateVariabilitySDNN` identifier — not the same statistic |
+| Workout GPS | `queryWorkoutRoute` | Unsupported |
+| `minSdk` | iOS 16.4 | API 26 (plugin raises it) |
+
+Do **not** fork mapped queries per platform. Fork only when you need different UI for an Apple-only feature.
+
+## 🔌 Config plugin
+
+
+| Prop                              | Default                                            | Purpose                                                         |
+| --------------------------------- | -------------------------------------------------- | --------------------------------------------------------------- |
+| `healthSharePermission`           | `"Allow $(PRODUCT_NAME) to read your health data"` | `NSHealthShareUsageDescription`                                 |
+| `healthUpdatePermission`          | `"Allow $(PRODUCT_NAME) to write health data"`     | `NSHealthUpdateUsageDescription`                                |
+| `healthClinicalRecordsPermission` | clinical default                                   | Used when `isClinicalDataEnabled` is true                       |
+| `isBackgroundDeliveryEnabled`     | `false`                                            | HealthKit background delivery entitlement + `UIBackgroundModes` |
+| `isClinicalDataEnabled`           | `false`                                            | `health-records` access                                         |
+| `healthConnectPrivacyPolicyUrl`   | —                                                  | Shown on the Health Connect permission rationale screen         |
+
+
+The plugin also sets `android.minSdkVersion` to 26 (Health Connect’s floor) unless the project already uses a higher value.
+
+Set a permission string to `false` to skip writing that Info.plist key (if you manage it yourself).
+
+## 📱 Example app
+
+```sh
+cd example
+npm install
+npx expo run:ios
+# or
+npx expo run:android
+```
+
+The example is an Expo SDK 57 app that autolinks this module on **iOS and Android**. It will not work in Expo Go.
+
+## 🤖 Agent skills
+
+Coding agents (Cursor, Claude Code, Copilot, and similar) should load the bundled skill.
+
+Copy [`.cursor/skills/expo-healthkit/`](https://github.com/appeeky/expo-healthkit/tree/main/.cursor/skills/expo-healthkit) into your app’s `.cursor/skills/expo-healthkit/` (or the agent’s skills folder):
+
+| File | What agents get |
+| --- | --- |
+| [`SKILL.md`](https://github.com/appeeky/expo-healthkit/blob/main/.cursor/skills/expo-healthkit/SKILL.md) | When to use which query, auth rules, and plugin flags |
+| [`reference.md`](https://github.com/appeeky/expo-healthkit/blob/main/.cursor/skills/expo-healthkit/reference.md) | Method signatures, units, identifiers |
+| [`examples.md`](https://github.com/appeeky/expo-healthkit/blob/main/.cursor/skills/expo-healthkit/examples.md) | Copy-paste flows (steps, sleep, rings, blood pressure, food) |
+
+The skill tells the agent to pass Apple identifier strings through one query/save API on iOS and Android, request every type in `toRead`, and rebuild native code after Swift, Kotlin, or plugin changes.
+
+## 🤝 Contributing
+
+Issues and pull requests are welcome. Contributions are licensed under [PolyForm Shield 1.0.0](./LICENSE).
+
+### Checks
+
+CI on `main` and every PR runs lint, typecheck, Jest, and an `npm pack` contents check (`.github/workflows/ci.yml`). Run the same locally before opening a PR:
+
+```sh
+npm ci
+npm run lint
+npm run typecheck
+npm test -- --watchAll=false
+npm run test:coverage
+```
+
+`npm test` opens Jest watch mode on a TTY. Pass `--watchAll=false` (as CI does) for a single run. `test:coverage` writes an HTML report to `coverage/` and must stay green for the JavaScript that tests already cover (`src/identifiers.ts`, `src/errors.ts`, `src/dates.ts`).
+
+### What to test
+
+| Change | Expected coverage |
+| --- | --- |
+| Identifiers, errors, date helpers, public JS types | Add or extend Jest in `src/__tests__/`. Keep `npm run test:coverage` passing |
+| Config plugin | Typecheck `plugin/`; if you add pure helpers, put Jest next to them |
+| Kotlin Health Connect mapping | Update the [Cross-platform](#cross-platform) tables **and** `.cursor/skills/expo-healthkit/`. Run the example on an Android device with Health Connect |
+| Swift HealthKit | Same skill/README update. Run the example on Simulator or a device with the HealthKit capability |
+| Example UI | `cd example && npx expo run:ios` / `npx expo run:android`. Health APIs do not run in Expo Go |
+
+Native HealthKit / Health Connect cannot run in Node. Device or Simulator verification is the coverage for Swift and Kotlin. Do not add `Platform.OS` branches in `example/` for types that already map.
+
+### Native rebuild
+
+Metro reload is not enough after Swift, Kotlin, or plugin edits:
+
+```sh
+npx expo prebuild --clean
+npx expo run:ios
+# or
+npx expo run:android
+```
+
+### Docs
+
+If the public API or Android mapping changes, update `README.md`, `CHANGELOG.md`, and `.cursor/skills/expo-healthkit/` (`SKILL.md`, `reference.md`, `examples.md`) in the same PR.
+
+## 🔒 Privacy
+
+Health data stays on-device unless your app uploads it. Request only the types you need, explain why in the iOS usage strings, declare the matching Health Connect data types in Play Console, and follow Apple HealthKit and Google Health Connect review guidelines. Android reads are often limited to the last 30 days unless the user also grants history access.
+
+## 📄 License
+
+[PolyForm Shield 1.0.0](./LICENSE). See [`LICENSE`](./LICENSE) for the full terms.
+
+You **can** install and use this SDK inside your own Expo / React Native apps, including commercial products.
+
+You **cannot** copy this SDK and sell, publish, or otherwise offer a competing HealthKit / Health Connect library based on it.

package/android/build.gradle

@@ -0,0 +1,22 @@
+plugins {
+  id 'com.android.library'
+  id 'expo-module-gradle-plugin'
+}
+
+group = 'expo.modules.healthkit'
+version = '0.1.0'
+
+android {
+  namespace "expo.modules.healthkit"
+  defaultConfig {
+    versionCode 1
+    versionName "0.1.0"
+  }
+  lintOptions {
+    abortOnError false
+  }
+}
+
+dependencies {
+  implementation "androidx.health.connect:connect-client:1.1.0"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,74 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+  <queries>
+    <package android:name="com.google.android.apps.healthdata" />
+  </queries>
+
+  <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_TOTAL_CALORIES_BURNED" />
+  <uses-permission android:name="android.permission.health.WRITE_TOTAL_CALORIES_BURNED" />
+  <uses-permission android:name="android.permission.health.READ_FLOORS_CLIMBED" />
+  <uses-permission android:name="android.permission.health.WRITE_FLOORS_CLIMBED" />
+  <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_RESTING_HEART_RATE" />
+  <uses-permission android:name="android.permission.health.WRITE_RESTING_HEART_RATE" />
+  <uses-permission android:name="android.permission.health.READ_HEART_RATE_VARIABILITY" />
+  <uses-permission android:name="android.permission.health.WRITE_HEART_RATE_VARIABILITY" />
+  <uses-permission android:name="android.permission.health.READ_OXYGEN_SATURATION" />
+  <uses-permission android:name="android.permission.health.WRITE_OXYGEN_SATURATION" />
+  <uses-permission android:name="android.permission.health.READ_RESPIRATORY_RATE" />
+  <uses-permission android:name="android.permission.health.WRITE_RESPIRATORY_RATE" />
+  <uses-permission android:name="android.permission.health.READ_BODY_TEMPERATURE" />
+  <uses-permission android:name="android.permission.health.WRITE_BODY_TEMPERATURE" />
+  <uses-permission android:name="android.permission.health.READ_BLOOD_GLUCOSE" />
+  <uses-permission android:name="android.permission.health.WRITE_BLOOD_GLUCOSE" />
+  <uses-permission android:name="android.permission.health.READ_BLOOD_PRESSURE" />
+  <uses-permission android:name="android.permission.health.WRITE_BLOOD_PRESSURE" />
+  <uses-permission android:name="android.permission.health.READ_VO2_MAX" />
+  <uses-permission android:name="android.permission.health.WRITE_VO2_MAX" />
+  <uses-permission android:name="android.permission.health.READ_HEIGHT" />
+  <uses-permission android:name="android.permission.health.WRITE_HEIGHT" />
+  <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_BODY_FAT" />
+  <uses-permission android:name="android.permission.health.WRITE_BODY_FAT" />
+  <uses-permission android:name="android.permission.health.READ_LEAN_BODY_MASS" />
+  <uses-permission android:name="android.permission.health.WRITE_LEAN_BODY_MASS" />
+  <uses-permission android:name="android.permission.health.READ_SLEEP" />
+  <uses-permission android:name="android.permission.health.WRITE_SLEEP" />
+  <uses-permission android:name="android.permission.health.READ_EXERCISE" />
+  <uses-permission android:name="android.permission.health.WRITE_EXERCISE" />
+  <uses-permission android:name="android.permission.health.READ_NUTRITION" />
+  <uses-permission android:name="android.permission.health.WRITE_NUTRITION" />
+  <uses-permission android:name="android.permission.health.READ_HYDRATION" />
+  <uses-permission android:name="android.permission.health.WRITE_HYDRATION" />
+  <uses-permission android:name="android.permission.health.READ_WHEELCHAIR_PUSHES" />
+  <uses-permission android:name="android.permission.health.WRITE_WHEELCHAIR_PUSHES" />
+  <uses-permission android:name="android.permission.health.READ_HEALTH_DATA_HISTORY" />
+
+  <application>
+    <activity
+      android:name="expo.modules.healthkit.HealthConnectRationaleActivity"
+      android:exported="true"
+      android:theme="@android:style/Theme.DeviceDefault.Light.Dialog.NoActionBar">
+      <intent-filter>
+        <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE" />
+      </intent-filter>
+    </activity>
+    <activity-alias
+      android:name="ViewPermissionUsageActivity"
+      android:exported="true"
+      android:permission="android.permission.START_VIEW_PERMISSION_USAGE"
+      android:targetActivity="expo.modules.healthkit.HealthConnectRationaleActivity">
+      <intent-filter>
+        <action android:name="android.intent.action.VIEW_PERMISSION_USAGE" />
+        <category android:name="android.intent.category.HEALTH_PERMISSIONS" />
+      </intent-filter>
+    </activity-alias>
+  </application>
+</manifest>