@cariva-dev/exercise-sdk 2.0.0

package/CarivaExerciseSdk.podspec

@@ -0,0 +1,20 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "CarivaExerciseSdk"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => min_ios_version_supported }
+  s.source       = { :git => "https://github.com/cariva/cariva-exercise-sdk.git", :tag => "#{s.version}" }
+
+  s.source_files = "ios/**/*.{h,m,mm,swift,cpp}"
+  s.private_header_files = "ios/**/*.h"
+
+  install_modules_dependencies(s)
+end

package/README.md

@@ -0,0 +1,374 @@
+# @cariva/exercise-sdk
+
+React Native SDK for reading exercise and activity data from **Android Health Connect**.
+
+## Platform Support
+
+| Platform | Status |
+|----------|--------|
+| Android  | Supported (Health Connect) |
+| iOS      | Out of scope for this release |
+
+---
+
+## Requirements
+
+- React Native **0.68+** (New Architecture / Turbo Module compatible)
+- Android **API level 26+**
+- [Health Connect](https://play.google.com/store/apps/details?id=com.google.android.apps.healthdata) installed on the device (or available through Play Services on Android 14+)
+
+---
+
+## Installation
+
+### 1. Install the package
+
+```sh
+# npm
+npm install @cariva/exercise-sdk
+
+# yarn
+yarn add @cariva/exercise-sdk
+```
+
+### 2. Android — AndroidManifest.xml
+
+The SDK ships its own manifest with Health Connect permissions, but you must also declare **two additional entries** in your app's `AndroidManifest.xml`:
+
+#### 2a. Add the `<queries>` block (package visibility)
+
+Inside the root `<manifest>` element:
+
+```xml
+<queries>
+  <package android:name="com.google.android.apps.healthdata" />
+  <package android:name="com.google.android.healthconnect.controller" />
+</queries>
+```
+
+#### 2b. Add the Health Connect permission rationale activities
+
+Inside the `<application>` element:
+
+```xml
+<!-- Required by Health Connect: shown when user taps "Privacy policy" in permissions dialog -->
+<activity
+  android:name="com.carivaexercisesdk.HealthConnectPermissionsRationaleActivity"
+  android:exported="true">
+  <intent-filter>
+    <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE" />
+  </intent-filter>
+</activity>
+
+<!-- Required by Health Connect: shown from Android Settings > App permissions -->
+<activity
+  android:name="com.carivaexercisesdk.HealthConnectPermissionUsageActivity"
+  android:exported="true"
+  android:permission="android.permission.START_VIEW_PERMISSION_USAGE">
+  <intent-filter>
+    <action android:name="android.intent.action.VIEW_PERMISSION_USAGE" />
+    <category android:name="android.intent.category.HEALTH_PERMISSIONS" />
+  </intent-filter>
+</activity>
+```
+
+> **Note:** These activities are part of the Health Connect compliance requirement. The app will still build without them, but Health Connect permission management will not work correctly.
+
+### 3. iOS
+
+No additional setup is required. The SDK is a no-op on iOS.
+
+---
+
+## Quick Start
+
+```ts
+import {
+  connect,
+  getExerciseData,
+  setAllowDatasource,
+  getAllowDatasource,
+} from '@cariva/exercise-sdk';
+
+// 1. Connect and request permissions
+const status = await connect({
+  onMissingApp: 'status',
+  requestPermission: true,
+  permissionScope: ['steps', 'calories'],
+});
+
+if (!status.ready) {
+  console.log('Next action required:', status.nextAction);
+  // e.g. 'INSTALL_HEALTH_CONNECT' | 'REQUEST_PERMISSION' | ...
+  return;
+}
+
+// 2. Fetch exercise data
+const data = await getExerciseData({
+  sinceMillis: Date.now() - 7 * 24 * 60 * 60 * 1000, // last 7 days
+  untilMillis: Date.now(),
+  type: 'all',
+  bucketPeriod: 'daily',
+});
+
+console.log('Records:', data.records);
+console.log('Total steps:', data.totalSteps);
+```
+
+---
+
+## API Reference
+
+### Migration Notes (v2.0.0)
+
+- `connect()` no longer checks Google Fit installation.
+- `ConnectResult.googleFitInstalled` was removed.
+- `ConnectResult.nextAction` no longer returns `INSTALL_GOOGLE_FIT`.
+- Readiness now depends only on Health Connect:
+  `ready = healthConnectInstalled && healthConnectStatus === 'AVAILABLE' && hasPermissions`.
+
+### `connect(options?)`
+
+Checks Health Connect availability and optionally requests permissions.
+
+```ts
+type ConnectOptions = {
+  onMissingApp?: 'status' | 'open';   // 'open' navigates to Health Connect in Play Store
+  requestPermission?: boolean;          // default: false
+  permissionScope?: Array<'steps' | 'activetimes' | 'calories' | 'distances'>;
+};
+
+type ConnectResult = {
+  ready: boolean;
+  healthConnectInstalled: boolean;
+  healthConnectStatus: 'AVAILABLE' | 'PROVIDER_UPDATE_REQUIRED' | 'UNAVAILABLE' | 'UNKNOWN';
+  hasPermissions: boolean;
+  nextAction:
+    | 'INSTALL_HEALTH_CONNECT'
+    | 'UPDATE_HEALTH_CONNECT'
+    | 'REQUEST_PERMISSION'
+    | 'NONE';
+  requestedPermissions?: string[];
+};
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `onMissingApp` | `'status' \| 'open'` | `'status'` | `'open'` opens Play Store for Health Connect only |
+| `requestPermission` | `boolean` | `false` | Trigger the Health Connect permission dialog |
+| `permissionScope` | `PermissionScope[]` | all scopes | Limit which permissions are requested |
+
+---
+
+### `getExerciseData(options)`
+
+Reads aggregated exercise data from Health Connect.
+
+```ts
+type GetExerciseDataOptions = {
+  sinceMillis: number;
+  untilMillis: number;
+  type?: 'steps' | 'activetimes' | 'calories' | 'distances' | 'all'; // default: 'all'
+  bucketPeriod?: 'hourly' | 'daily';                                    // default: 'hourly'
+  debug?: boolean;                                                       // default: false
+};
+
+type ExerciseData = {
+  totalSteps: number;
+  totalKcal: number;
+  totalDistanceMeters: number;
+  totalActiveTimeMillis: number;
+  totalActiveTime?: number; // deprecated alias for backward compatibility
+  timeZone: string;
+  records: UnifiedIntervalRecord[];
+  warnings?: string[];
+  integrity?: {
+    projectionPreserved: boolean;
+    roundingScale: number;
+  };
+  diagnostics?: {
+    fallbackUsedSegments: number;
+    fallbackSuppressedSegments: number;
+    idleGateSuppressedSegments: number;
+    basalSeedApplied: boolean;
+    seededFromBeforeSince: boolean;
+    basalSeedAgeHours?: number;
+  };
+  debug?: {
+    directActiveCaloriesKcal: number;
+    totalCaloriesKcal: number;
+    basalCaloriesKcal: number;
+    mergedActiveCaloriesKcal: number;
+    fallbackContributionKcal: number;
+    fallbackUsedSegments: number;
+    fallbackSuppressedSegments: number;
+    idleGateSuppressedSegments: number;
+    basalSeedApplied: boolean;
+    seededFromBeforeSince: boolean;
+    basalSeedAgeHours?: number;
+    basalIntervalsCount: number;
+  };
+};
+```
+
+> Periods longer than **90 days** reject with error code `E_INVALID_PERIOD`.
+> Invalid `permissionScope` values reject with error code `E_INVALID_PERMISSION_SCOPE`.
+
+---
+
+### `setAllowDatasource(config)`
+
+Configures which data sources to exclude from results.
+
+```ts
+type DatasourceType = 'manual_input' | 'device' | 'app' | 'unknown';
+
+type DatasourceConfig = {
+  blacklist: DatasourceType[];
+};
+
+// Example: exclude manually-entered data
+await setAllowDatasource({ blacklist: ['manual_input'] });
+```
+
+---
+
+### `getAllowDatasource()`
+
+Returns the current datasource blacklist configuration.
+
+```ts
+const config = await getAllowDatasource();
+// => { blacklist: ['manual_input'] }
+```
+
+---
+
+## Unified Record Schema
+
+Every record in `data.records` follows this shape regardless of the `type` queried:
+
+```ts
+type UnifiedIntervalRecord = {
+  steps: number;
+  activeCalories: number;
+  activeCaloriesUnit: 'kcal';
+  distance: number;
+  distanceUnit: 'km';
+  activeTime: number;
+  activeTimeUnit: 'milliseconds';
+  startDate: string; // ISO offset string, e.g. "2026-02-16T08:00:00+07:00"
+  endDate: string;
+  meta: {
+    source: string;
+    device: string;
+    deviceModel: string;
+    trustLevel: 'trusted' | 'low_confidence';
+  };
+};
+```
+
+Example record:
+
+```json
+{
+  "steps": 1300,
+  "activeCalories": 60.2,
+  "activeCaloriesUnit": "kcal",
+  "distance": 1.0,
+  "distanceUnit": "km",
+  "activeTime": 1200000,
+  "activeTimeUnit": "milliseconds",
+  "startDate": "2026-02-16T08:30:00+07:00",
+  "endDate": "2026-02-16T09:00:00+07:00",
+  "meta": {
+    "source": "device",
+    "device": "com.google.android.apps.healthdata",
+    "deviceModel": "Pixel Watch 2",
+    "trustLevel": "trusted"
+  }
+}
+```
+
+---
+
+## Overlap Handling
+
+The SDK automatically de-duplicates overlapping Health Connect records:
+
+| Metric | Strategy |
+|--------|----------|
+| `steps` | Source priority: `device > app > unknown > manual_input`, then deterministic single-winner tie-break for same-priority overlaps |
+| `activetimes`, `calories`, `distances` | Proportional-by-time allocation |
+
+Bucketized results preserve requested `hourly`/`daily` boundaries and do not merge across bucket edges.
+
+### Trust & Fallback Notes
+
+- `manual_input` with identifiable device metadata is accepted as `low_confidence`.
+- `manual_input` remains the lowest source priority in overlap resolution.
+- `total - basal` fallback is applied only to uncovered windows (gap-fill only); direct active-calorie windows are preserved.
+- Manual-derived movement evidence is excluded from fallback gate checks.
+
+---
+
+## Integrity & Warnings
+
+`data.warnings` is an optional string array that appears when non-fatal anomalies are detected (e.g. value sanitization or boundary guard signals).
+
+`data.integrity` is always present and describes the projection audit:
+
+```ts
+{
+  projectionPreserved: boolean; // true if totals were preserved after overlap correction
+  roundingScale: number;        // rounding precision applied
+}
+```
+
+React Native UI pattern (non-blocking):
+
+```tsx
+const hasWarnings = !!data.warnings?.length;
+
+return (
+  <View>
+    {hasWarnings && <Text>Data warnings available</Text>}
+    <Text>{`Projection preserved: ${data.integrity?.projectionPreserved}`}</Text>
+  </View>
+);
+```
+
+---
+
+## Full Example
+
+```ts
+import { connect, getExerciseData, setAllowDatasource } from '@cariva/exercise-sdk';
+
+async function loadHealthData() {
+  // Exclude manual entries
+  await setAllowDatasource({ blacklist: ['manual_input'] });
+
+  // Connect with minimal permission scope
+  const status = await connect({
+    onMissingApp: 'status',
+    requestPermission: true,
+    permissionScope: ['steps', 'calories'],
+  });
+
+  if (!status.ready) {
+    console.warn('Health Connect not ready. Next action:', status.nextAction);
+    return null;
+  }
+
+  // Query last 24 hours in hourly buckets
+  const data = await getExerciseData({
+    sinceMillis: Date.now() - 24 * 60 * 60 * 1000,
+    untilMillis: Date.now(),
+    type: 'all',
+    bucketPeriod: 'hourly',
+  });
+
+  return data;
+}
+```

package/android/build.gradle

@@ -0,0 +1,66 @@
+buildscript {
+  ext.CarivaExerciseSdk = [
+    kotlinVersion: "2.0.21",
+    minSdkVersion: 24,
+    compileSdkVersion: 36,
+    targetSdkVersion: 36
+  ]
+
+  ext.getExtOrDefault = { prop ->
+    if (rootProject.ext.has(prop)) {
+      return rootProject.ext.get(prop)
+    }
+
+    return CarivaExerciseSdk[prop]
+  }
+
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.7.2"
+    // noinspection DifferentKotlinGradleVersion
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${getExtOrDefault('kotlinVersion')}"
+  }
+}
+
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+
+apply plugin: "com.facebook.react"
+
+android {
+  namespace "com.carivaexercisesdk"
+
+  compileSdkVersion getExtOrDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrDefault("minSdkVersion")
+    targetSdkVersion getExtOrDefault("targetSdkVersion")
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled false
+    }
+  }
+
+  lint {
+    disable "GradleCompatible"
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_1_8
+    targetCompatibility JavaVersion.VERSION_1_8
+  }
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+  implementation "androidx.health.connect:connect-client:1.1.0-alpha10"
+  implementation "androidx.activity:activity-ktx:1.9.3"
+  testImplementation "junit:junit:4.13.2"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,40 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+  <uses-permission android:name="android.permission.health.READ_ACTIVE_CALORIES_BURNED" />
+  <uses-permission android:name="android.permission.health.READ_TOTAL_CALORIES_BURNED" />
+  <uses-permission android:name="android.permission.health.READ_BASAL_METABOLIC_RATE" />
+  <uses-permission android:name="android.permission.health.READ_STEPS" />
+  <uses-permission android:name="android.permission.health.READ_DISTANCE" />
+  <uses-permission android:name="android.permission.health.READ_EXERCISE" />
+
+  <uses-permission android:name="androidx.health.permission.ACTIVE_CALORIES_BURNED_READ" />
+  <uses-permission android:name="androidx.health.permission.TOTAL_CALORIES_BURNED_READ" />
+  <uses-permission android:name="androidx.health.permission.BASAL_METABOLIC_RATE_READ" />
+  <uses-permission android:name="androidx.health.permission.STEPS_READ" />
+  <uses-permission android:name="androidx.health.permission.DISTANCE_READ" />
+  <uses-permission android:name="androidx.health.permission.EXERCISE_READ" />
+
+  <queries>
+    <package android:name="com.google.android.apps.healthdata" />
+    <package android:name="com.google.android.healthconnect.controller" />
+  </queries>
+
+  <application>
+    <activity
+      android:name=".HealthConnectPermissionsRationaleActivity"
+      android:exported="true">
+      <intent-filter>
+        <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE" />
+      </intent-filter>
+    </activity>
+
+    <activity
+      android:name=".HealthConnectPermissionUsageActivity"
+      android:exported="true"
+      android:permission="android.permission.START_VIEW_PERMISSION_USAGE">
+      <intent-filter>
+        <action android:name="android.intent.action.VIEW_PERMISSION_USAGE" />
+        <category android:name="android.intent.category.HEALTH_PERMISSIONS" />
+      </intent-filter>
+    </activity>
+  </application>
+</manifest>

package/android/src/main/java/com/carivaexercisesdk/CarivaExerciseSdkPackage.kt

@@ -0,0 +1,30 @@
+package com.carivaexercisesdk
+
+import com.facebook.react.BaseReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.module.model.ReactModuleInfo
+import com.facebook.react.module.model.ReactModuleInfoProvider
+
+class CarivaExerciseSdkPackage : BaseReactPackage() {
+  override fun getModule(name: String, reactContext: ReactApplicationContext): NativeModule? {
+    return when (name) {
+      HealthConnectModule.NAME -> HealthConnectModule(reactContext)
+      else -> null
+    }
+  }
+
+  override fun getReactModuleInfoProvider() = ReactModuleInfoProvider {
+    mapOf(
+            HealthConnectModule.NAME to
+                    ReactModuleInfo(
+                            name = HealthConnectModule.NAME,
+                            className = HealthConnectModule.NAME,
+                            canOverrideExistingModule = false,
+                            needsEagerInit = false,
+                            isCxxModule = false,
+                            isTurboModule = false
+                    )
+    )
+  }
+}