react-native-step-tracker-pro 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 react-native-step-tracker-pro contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,148 @@
+# react-native-step-tracker-pro
+
+Android step tracking for React Native that keeps counting when the app is
+closed, the screen is locked, the process is killed, or the phone reboots.
+Hardware sensor → foreground service → Room → Health Connect.
+
+Android only. iOS has CMPedometer and a completely different permission model;
+wrapping both behind one API produces a bad version of each.
+
+```ts
+import StepTracker from "react-native-step-tracker-pro";
+
+await StepTracker.initialize({ height: 175, weight: 75, dailyGoal: 10000 });
+await StepTracker.requestPermissions();
+await StepTracker.startTracking();
+
+StepTracker.addListener("stepsChanged", (data) => console.log(data.steps));
+```
+
+## What it does
+
+|                |                                                                   |
+| -------------- | ----------------------------------------------------------------- |
+| Sensor         | `TYPE_STEP_COUNTER`, falling back to `TYPE_STEP_DETECTOR`         |
+| Background     | Kotlin foreground service, `health` type, `START_STICKY`          |
+| Storage        | Room — `step_history` + `daily_summary`, 31–35 day retention      |
+| Reboot         | `BootReceiver` restarts the service and re-anchors the counter    |
+| Health Connect | read, write, historical read, idempotent sync                     |
+| Offline        | everything works with no network; remote sync is queued           |
+| Bridge         | Turbo Module with an old-architecture shim, full TypeScript types |
+
+## Install
+
+```sh
+npm install react-native-step-tracker-pro
+cd android && ./gradlew clean
+npx react-native run-android
+```
+
+Requires `minSdk 26`, `compileSdk 35`, RN ≥ 0.74. Full steps, including the
+Gradle overrides for Kotlin 2.x and the manifest entries your app has to add:
+[docs/INSTALLATION.md](docs/INSTALLATION.md).
+
+## Configuration
+
+```ts
+await StepTracker.initialize({
+  height: 175, // cm — drives stride length
+  weight: 75, // kg — drives calories
+  dailyGoal: 10000,
+  historyRetentionDays: 31, // how much history to keep on device
+  notificationTitle: "{steps} steps today",
+  healthConnectEnabled: true,
+  remoteSyncUrl: "https://api.example.com/steps", // optional
+});
+```
+
+Stride length defaults to `height × 0.415` (male) / `0.413` (female) /
+`0.414` (unspecified); pass `strideLength` in metres to override. Calories use
+`0.57 kcal × body mass (kg) × distance (km)`, adjustable via
+`calorieCoefficient`. Both are estimates, and both match the order of magnitude
+Google Fit and Samsung Health report — not their exact numbers, because neither
+publishes its model.
+
+## API
+
+```ts
+initialize(config)            updateConfig(config)      getConfig()
+startTracking()               pauseTracking()           resumeTracking()
+stopTracking()                getTrackingState()        isTracking()
+
+getTodaySteps()               getYesterdaySteps()       getStepsForDate(date)
+getWeeklyStats(options)       getMonthlyStats(options)  getYearlyStats(options)
+getStatsForRange(from, to)    getHistory(from, to)
+
+requestPermissions()          checkPermissions()        getDeviceCapabilities()
+isBatteryOptimizationEnabled()                          requestDisableBatteryOptimization()
+
+getHealthConnectStatus()      requestHealthConnectPermissions()
+readHealthConnectSteps(a, b)  writeHealthConnectSteps(date)   syncWithHealthConnect()
+
+syncNow()                     getPendingSyncCount()
+resetToday()                  clearHistory()            pruneHistory(days)
+```
+
+Events: `stepsChanged`, `goalReached`, `goalProgressChanged`,
+`trackingStateChanged`, `dayChanged`, `syncCompleted`, `error`.
+
+```ts
+const sub = StepTracker.addListener("goalReached", ({ type, goal }) => {});
+sub.remove();
+// or
+StepTracker.removeListener("goalReached");
+```
+
+Signatures and payload shapes: [docs/API.md](docs/API.md).
+
+## Hooks
+
+```tsx
+const { snapshot, state, start, pause, requestPermissions } = useStepTracker({
+  dailyGoal: 10000,
+  autoStart: true,
+});
+
+const { stats } = useStepStats("week");
+```
+
+## How the count survives things
+
+`TYPE_STEP_COUNTER` reports steps since boot, so the day total is
+`anchorSteps + (rawValue − anchorValue)`. The anchor is re-pinned on reboot, on
+an OEM counter reset, and at midnight. Counter state lives in SharedPreferences
+and is written on every sensor batch, so a process kill costs nothing — the
+hardware kept counting while you were dead, and the next sample reconciles.
+
+Details, including why steps between a reboot and the service restarting are
+sometimes dropped on purpose: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+
+## Before you ship
+
+Read [docs/PLAY_STORE_COMPLIANCE.md](docs/PLAY_STORE_COMPLIANCE.md). The three
+things that get apps rejected here are the foreground service declaration, the
+Health Connect permissions form, and asking for a battery optimisation
+exemption without an eligible use case.
+
+## Example app
+
+```sh
+cd example && npm install && npm run android
+```
+
+## Testing
+
+```sh
+cd android && ./gradlew :react-native-step-tracker-pro:connectedAndroidTest
+```
+
+Eleven instrumented tests cover the reboot, midnight, pause and counter-reset
+paths by feeding samples to the engine directly, so they run on an emulator with
+no step hardware. The device-level QA matrix — force-stop recovery, real reboot,
+Doze, Health Connect, OEM battery managers — is in
+[docs/TESTING.md](docs/TESTING.md).
+
+## Licence
+
+MIT
+# react-native-step-tracker-pro

package/android/build.gradle

@@ -0,0 +1,119 @@
+buildscript {
+    // Consumers can override any of these in the app's root build.gradle:
+    //   ext { kotlinVersion = "2.0.21"; kspVersion = "2.0.21-1.0.25"; roomVersion = "2.7.1" }
+    ext.stp_kotlinVersion = rootProject.ext.has("kotlinVersion")
+            ? rootProject.ext.get("kotlinVersion") : "1.9.24"
+    ext.stp_kspVersion = rootProject.ext.has("kspVersion")
+            ? rootProject.ext.get("kspVersion") : "1.9.24-1.0.20"
+
+    repositories {
+        google()
+        mavenCentral()
+        gradlePluginPortal()
+    }
+    dependencies {
+        classpath "com.android.tools.build:gradle:8.6.0"
+        // Bare references, not ${ext.…}: inside a nested dependencies{} block
+        // `ext` resolves to the buildscript's own extra properties, not the
+        // project's, so the ext-qualified form fails to resolve at all.
+        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$stp_kotlinVersion"
+        classpath "com.google.devtools.ksp:com.google.devtools.ksp.gradle.plugin:$stp_kspVersion"
+    }
+}
+
+def isNewArchitectureEnabled() {
+    return project.hasProperty("newArchEnabled") && project.newArchEnabled == "true"
+}
+
+apply plugin: "com.android.library"
+apply plugin: "org.jetbrains.kotlin.android"
+apply plugin: "com.google.devtools.ksp"
+if (isNewArchitectureEnabled()) {
+    apply plugin: "com.facebook.react"
+}
+
+def safeExtGet(prop, fallback) {
+    rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+}
+
+def roomVersion = safeExtGet("roomVersion", "2.6.1")
+// 1.1.0 stable requires compileSdk 36 and AGP 8.9.1+, which React Native did
+// not ship until long after 0.76 - depending on it would silently break every
+// consumer inside the react-native range peerDependencies claims to support.
+// 1.1.0-beta01 is the newest release that still builds against compileSdk 35
+// and carries the same Metadata API. Consumers on a newer toolchain can opt up
+// with ext.healthConnectVersion.
+def healthConnectVersion = safeExtGet("healthConnectVersion", "1.1.0-beta01")
+def workVersion = safeExtGet("workVersion", "2.9.1")
+
+android {
+    namespace "com.steptrackerpro"
+    compileSdk safeExtGet("compileSdkVersion", 35)
+
+    defaultConfig {
+        // 26 is the floor for java.time and for the Health Connect client.
+        minSdk safeExtGet("minSdkVersion", 26)
+        targetSdk safeExtGet("targetSdkVersion", 35)
+        consumerProguardFiles "consumer-rules.pro"
+        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
+        buildConfigField "boolean", "IS_NEW_ARCHITECTURE_ENABLED", isNewArchitectureEnabled().toString()
+    }
+
+    buildFeatures {
+        buildConfig true
+    }
+
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_17
+        targetCompatibility JavaVersion.VERSION_17
+    }
+
+    kotlinOptions {
+        jvmTarget = "17"
+        freeCompilerArgs += ["-Xjvm-default=all"]
+    }
+
+    sourceSets {
+        main {
+            if (isNewArchitectureEnabled()) {
+                java.srcDirs += ["src/newarch/java", "${project.buildDir}/generated/source/codegen/java"]
+            } else {
+                java.srcDirs += ["src/oldarch/java"]
+            }
+        }
+    }
+
+    lint {
+        abortOnError false
+    }
+}
+
+ksp {
+    arg("room.schemaLocation", "$projectDir/schemas")
+    arg("room.incremental", "true")
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+dependencies {
+    implementation "com.facebook.react:react-android"
+
+    implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.8.1"
+    implementation "androidx.core:core-ktx:1.13.1"
+    implementation "androidx.lifecycle:lifecycle-service:2.8.4"
+    implementation "androidx.activity:activity-ktx:1.9.2"
+
+    implementation "androidx.room:room-runtime:$roomVersion"
+    implementation "androidx.room:room-ktx:$roomVersion"
+    ksp "androidx.room:room-compiler:$roomVersion"
+
+    implementation "androidx.work:work-runtime-ktx:$workVersion"
+    implementation "androidx.health.connect:connect-client:$healthConnectVersion"
+
+    androidTestImplementation "androidx.test:core-ktx:1.6.1"
+    androidTestImplementation "androidx.test:runner:1.6.2"
+    androidTestImplementation "androidx.test.ext:junit:1.2.1"
+}

package/android/consumer-rules.pro

@@ -0,0 +1,13 @@
+# Room generated implementations are reflected on at runtime.
+-keep class com.steptrackerpro.db.** { *; }
+-keep class androidx.room.RoomDatabase { *; }
+-dontwarn androidx.room.paging.**
+
+# Health Connect record classes are resolved by name.
+-keep class androidx.health.connect.client.records.** { *; }
+-dontwarn androidx.health.connect.client.**
+
+# Service, receiver and activity entry points referenced from the manifest.
+-keep class com.steptrackerpro.service.** { *; }
+-keep class com.steptrackerpro.health.HealthPermissionActivity { *; }
+-keep class com.steptrackerpro.sync.** { *; }

package/android/gradle.properties

@@ -0,0 +1,3 @@
+android.useAndroidX=true
+android.enableJetifier=false
+org.gradle.jvmargs=-Xmx2048m -XX:MaxMetaspaceSize=512m

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,78 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:tools="http://schemas.android.com/tools">
+
+    <!-- Step sensors. Runtime permission from API 29. -->
+    <uses-permission android:name="android.permission.ACTIVITY_RECOGNITION" />
+    <uses-permission
+        android:name="com.google.android.gms.permission.ACTIVITY_RECOGNITION"
+        android:maxSdkVersion="28" />
+
+    <!-- Foreground service. FOREGROUND_SERVICE_HEALTH is required from API 34. -->
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_HEALTH" />
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+    <!-- Used by WorkManager to hold the CPU awake while a sync job runs. -->
+    <uses-permission android:name="android.permission.WAKE_LOCK" />
+    <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
+
+    <!--
+      Only needed if you call requestDisableBatteryOptimization(). Remove this
+      line and use openBatteryOptimizationSettings() instead if you do not have
+      an eligible Play Console use case. See docs/PLAY_STORE_COMPLIANCE.md.
+    -->
+    <uses-permission
+        android:name="android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS"
+        tools:node="merge" />
+
+    <!-- Health Connect. Remove the pairs you do not use. -->
+    <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_TOTAL_CALORIES_BURNED" />
+    <uses-permission android:name="android.permission.health.WRITE_TOTAL_CALORIES_BURNED" />
+
+    <uses-feature
+        android:name="android.hardware.sensor.stepcounter"
+        android:required="false" />
+    <uses-feature
+        android:name="android.hardware.sensor.stepdetector"
+        android:required="false" />
+
+    <queries>
+        <package android:name="com.google.android.apps.healthdata" />
+    </queries>
+
+    <application>
+        <service
+            android:name="com.steptrackerpro.service.StepTrackerService"
+            android:enabled="true"
+            android:exported="false"
+            android:foregroundServiceType="health"
+            android:stopWithTask="false" />
+
+        <receiver
+            android:name="com.steptrackerpro.service.BootReceiver"
+            android:enabled="true"
+            android:exported="true"
+            android:directBootAware="false">
+            <intent-filter android:priority="1000">
+                <action android:name="android.intent.action.BOOT_COMPLETED" />
+                <action android:name="android.intent.action.QUICKBOOT_POWERON" />
+                <action android:name="android.intent.action.MY_PACKAGE_REPLACED" />
+            </intent-filter>
+        </receiver>
+
+        <receiver
+            android:name="com.steptrackerpro.service.NotificationActionReceiver"
+            android:enabled="true"
+            android:exported="false" />
+
+        <activity
+            android:name="com.steptrackerpro.health.HealthPermissionActivity"
+            android:exported="false"
+            android:excludeFromRecents="true"
+            android:launchMode="singleTop"
+            android:theme="@style/StepTrackerPro.Transparent" />
+    </application>
+</manifest>