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 installed on the device (or available through Play Services on Android 14+)

Architecture

The SDK now follows a Clean/Hexagonal structure:

• android/.../domain: core models and algorithm services
• android/.../application: use-cases and ports
• android/.../infrastructure: Health Connect/Android adapters
• android/.../HealthConnectModule.kt: thin React Native bridge/controller
• src/domain, src/application, src/infrastructure: mirrored TypeScript boundary layers

See docs/architecture/clean-hexagonal-migration.md for migration details.

Installation

1. Install the package

# 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:

<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:

<!-- 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

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

connect(options?)

Checks Health Connect availability and optionally requests permissions.

type ConnectOptions = {
  onMissingApp?: 'status' | 'open';   // 'open' navigates to Play Store
  requestPermission?: boolean;          // default: true
  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 the missing app | | requestPermission | boolean | true | Trigger the Health Connect permission dialog | | permissionScope | PermissionScope[] | all scopes | Limit which permissions are requested |

getExerciseData(options)

Reads aggregated exercise data from Health Connect.

type GetExerciseDataOptions = {
  sinceMillis: number;
  untilMillis: number;
  type?: 'steps' | 'activetimes' | 'calories' | 'distances' | 'all'; // default: 'all'
  bucketPeriod?: 'hourly' | 'daily';                                    // default: 'hourly'
};

type ExerciseData = {
  totalSteps: number;
  totalKcal: number;
  totalDistanceMeters: number;
  totalActiveTimeMillis: number;
  timeZone: string;
  records: UnifiedIntervalRecord[];
  warnings?: string[];
  integrity?: {
    projectionPreserved: boolean;
    roundingScale: number;
  };
  diagnostics?: {
    fallbackUsedSegments: number;
    fallbackSuppressedSegments: number;
    idleGateSuppressedSegments: number;
    basalSeedApplied: boolean;
    seededFromBeforeSince: boolean;
    basalSeedAgeHours?: number;
  };
};

Periods longer than 90 days reject with error code E_INVALID_PERIOD.

setAllowDatasource(config)

Configures which data sources to exclude from results.

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.

const config = await getAllowDatasource();
// => { blacklist: ['manual_input'] }

Unified Record Schema

Every record in data.records follows this shape regardless of the type queried:

type UnifiedIntervalRecord = {
  steps: number;
  activeCalories: number;
  activeCaloriesUnit: 'kcal';
  activeCaloriesSource: 'device' | 'app' | 'manual_input' | 'unknown' | 'fallback';
  distance: number;
  distanceUnit: 'km';
  activeTime: number;
  activeTimeUnit: 'milliseconds';
  startDate: string; // ISO offset string, e.g. "2026-02-16T08:00:00+07:00"
  endDate: string;
};

Example record:

{
  "steps": 1300,
  "activeCalories": 60.2,
  "activeCaloriesUnit": "kcal",
  "activeCaloriesSource": "fallback",
  "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"
}

Overlap Handling

The SDK automatically de-duplicates overlapping Health Connect records:

| Metric | Strategy | |--------|----------| | steps | Source priority: device > app > unknown > manual_input | | activetimes, calories, distances | Proportional-by-time allocation |

Calories Fallback (Total - Basal)

When direct active calories are unavailable or lower quality in some windows, the SDK can derive fallback active calories:

active = max(totalCalories - basalCalories, 0)

Policy and guarantees:

• Pre-since basal seed lookup is bounded to 90 days before sinceMillis.
• If basal coverage is missing for a window, fallback is strictly suppressed for that window.
• If the window has no movement/direct evidence, fallback is suppressed (idle gate).
• Direct active-calorie measurement is preferred when present; fallback fills only uncovered windows.
• Merge remains deterministic and avoids double counting across atomic windows.
• Warnings and diagnostics are emitted for auditability.

Typical warning keys:

• calories_fallback_total_minus_basal_used
• calories_fallback_only_used
• calories_fallback_partial_used
• bmr_seed_from_latest_before_since_used
• bmr_missing_for_fallback_window
• fallback_suppressed_due_to_missing_basal
• fallback_suppressed_due_to_idle_window
• fallback_suppressed_due_to_direct_active
• movement_evidence_partially_unavailable_for_fallback_gate

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:

{
  projectionPreserved: boolean; // true if totals were preserved after overlap correction
  roundingScale: number;        // rounding precision applied
}

React Native UI pattern (non-blocking):

const hasWarnings = !!data.warnings?.length;

return (
  <View>
    {hasWarnings && <Text>Data warnings available</Text>}
    <Text>{`Projection preserved: ${data.integrity?.projectionPreserved}`}</Text>
  </View>
);

Full Example

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;
}

Migration (2.0.0)

This release introduces a clean-break connect contract:

• Removed ConnectResult.googleFitInstalled
• Removed nextAction: 'INSTALL_GOOGLE_FIT'
• connect readiness flow is now Health Connect-only

If you previously handled Google Fit branches, delete those checks and rely on:

• INSTALL_HEALTH_CONNECT
• UPDATE_HEALTH_CONNECT
• REQUEST_PERMISSION
• NONE

Calories now may include optional diagnostics for fallback audit details (total - basal path). Unified records now include activeCaloriesSource so consumers can distinguish direct vs fallback contribution at bucket level.