feat: native background sync engine for HealthKit

[oakleaf]

Summary

Adds configureBackgroundSync — a fully-native background sync pipeline that runs when HealthKit observer queries fire without the JS bridge available (e.g. after the app has been terminated by iOS).

The library stays consumer-agnostic: you provide the HTTP endpoint (url, method, headers), a list of SyncTypeConfig entries mapping HealthKit identifiers to your own type names and units, and an UpdateFrequency. Records are sent as a { records: [...] } JSON body with fields the consumer defined.

Why

configureBackgroundTypes (merged via #341) solves observer registration at AppDelegate time, but the delivery callback queues events until JS subscribes via subscribeToChanges. For apps that want to forward health data to a backend when the app is terminated, JS never gets a chance to run. configureBackgroundSync closes that gap by doing the sync entirely in native Swift.

How it works

• Cumulative types (steps, distance, calories, active energy, flights, exercise minutes) use HKStatisticsCollectionQuery with .cumulativeSum. Apple deduplicates across iPhone + Watch sources and returns one correct total per day.
• Discrete types (heart rate, weight, HRV, etc.) use HKSampleQuery, one record per sample.
• Records are sent to a caller-configured HTTP endpoint with caller-configured headers — no assumptions about auth, body envelope, or backend shape.

Design choices

• New native file ios/NativeSyncEngine.swift added to the existing companion pod ReactNativeHealthkitBackground — no NitroModules / C++ dependencies, safe to import from AppDelegate on any RN version.
• Setup-time validation — URL well-formedness, HTTP method (POST/PUT/PATCH), non-empty typeConfigs, JSON encodability. Errors surface at configureBackgroundSync() call time rather than failing silently on every background wake.
• 20-second hard timeout per sync event (iOS allows ~30s of background execution; 10s buffer for safety).
• No retry/queue on HTTP failure — if the POST fails, the event is dropped. iOS fires observers again on the next HealthKit change, so backfill happens naturally via subsequent events. Documented prominently in README.
• Content-Type defaults to application/json when not supplied in headers.
• Today-only query window — HealthKit + iOS already handle offline/catch-up via observer queuing. For multi-day backfill, use the foreground APIs.

New TypeScript surface

• configureBackgroundSync(endpoint, typeConfigs, updateFrequency): Promise<boolean>
• clearBackgroundSync(): Promise<boolean>
• BackgroundSyncEndpoint / SyncTypeConfig types

Docs

Added a ## Background Delivery & Native Sync section to the README with:

• Comparison table between configureBackgroundTypes (observer + JS callback) and configureBackgroundSync (native HTTP)
• Full usage example
• Output record field table (type, value, unit, startTime, endTime, recordId, frequency, workoutActivityType, duration)
• Behavior notes (no retry, today-only, 20s budget)

Test plan

• End-to-end tested on iPhone with a consumer backend — steps / distance / calories arriving in the expected format, values matching Apple Health exactly.
• Force-quit behavior verified — HealthKit daemon still relaunches the app for background delivery (Apple design; not subject to normal iOS force-quit rules).
• Background delivery tested over multiple hours without the app being opened.

🤖 Generated with Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: e82a0c6

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@kingstinct/react-native-healthkit	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/kingstinct/react-native-healthkit/@kingstinct/react-native-healthkit@343

commit: e82a0c6

[robertherber]

Love this idea @oakleaf! But would prefer if we exposed all available data, which I don't think is the case here - right?

[oakleaf]

Let me work through that!

[oakleaf]

Superseded by #344 (v2 rewrite with four sample kinds, metadata enrichment, dual-unit hkUnit).