react-native-step-tracker-pro 1.0.0

package/src/hooks/useStepTracker.ts

@@ -0,0 +1,167 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { AppState } from 'react-native';
+import StepTracker, { isSupported } from '../StepTracker';
+import type {
+  GoalReachedEvent,
+  StepSnapshot,
+  StepTrackerConfig,
+  TrackingState,
+} from '../types';
+
+export interface UseStepTrackerOptions extends StepTrackerConfig {
+  /** Initialise and start tracking as soon as permissions allow. Default false. */
+  autoStart?: boolean;
+  /** Refetch the snapshot when the app returns to the foreground. Default true. */
+  refreshOnForeground?: boolean;
+  onGoalReached?: (event: GoalReachedEvent) => void;
+}
+
+export interface UseStepTrackerResult {
+  snapshot: StepSnapshot | null;
+  state: TrackingState;
+  ready: boolean;
+  error: Error | null;
+  start: () => Promise<void>;
+  pause: () => Promise<void>;
+  resume: () => Promise<void>;
+  stop: () => Promise<void>;
+  refresh: () => Promise<void>;
+  requestPermissions: () => Promise<boolean>;
+}
+
+/**
+ * Wires the tracker into a component: initialises once, subscribes to
+ * `stepsChanged`, and re-reads the snapshot when the app is foregrounded.
+ */
+export function useStepTracker(
+  options: UseStepTrackerOptions = {}
+): UseStepTrackerResult {
+  const {
+    autoStart = false,
+    refreshOnForeground = true,
+    onGoalReached,
+    ...config
+  } = options;
+
+  const [snapshot, setSnapshot] = useState<StepSnapshot | null>(null);
+  const [state, setState] = useState<TrackingState>('idle');
+  const [ready, setReady] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const configRef = useRef(config);
+  configRef.current = config;
+  const goalRef = useRef(onGoalReached);
+  goalRef.current = onGoalReached;
+
+  const refresh = useCallback(async () => {
+    if (!isSupported()) return;
+    try {
+      setSnapshot(await StepTracker.getTodaySteps());
+      setState(await StepTracker.getTrackingState());
+    } catch (e) {
+      setError(e as Error);
+    }
+  }, []);
+
+  useEffect(() => {
+    let cancelled = false;
+    if (!isSupported()) {
+      setState('unsupported');
+      setReady(true);
+      return;
+    }
+
+    (async () => {
+      try {
+        const initial = await StepTracker.initialize(configRef.current);
+        if (cancelled) return;
+        setSnapshot(initial);
+        setState(initial.state);
+        if (autoStart) {
+          const perms = await StepTracker.checkPermissions();
+          if (perms.allGranted) {
+            const started = await StepTracker.startTracking();
+            if (!cancelled) {
+              setSnapshot(started);
+              setState(started.state);
+            }
+          }
+        }
+      } catch (e) {
+        if (!cancelled) setError(e as Error);
+      } finally {
+        if (!cancelled) setReady(true);
+      }
+    })();
+
+    const stepsSub = StepTracker.addListener('stepsChanged', (payload) => {
+      setSnapshot(payload);
+    });
+    const stateSub = StepTracker.addListener('trackingStateChanged', (payload) => {
+      setState(payload.state);
+    });
+    const goalSub = StepTracker.addListener('goalReached', (payload) => {
+      goalRef.current?.(payload);
+    });
+    const daySub = StepTracker.addListener('dayChanged', () => {
+      void refresh();
+    });
+
+    return () => {
+      cancelled = true;
+      stepsSub.remove();
+      stateSub.remove();
+      goalSub.remove();
+      daySub.remove();
+    };
+  }, [autoStart, refresh]);
+
+  useEffect(() => {
+    if (!refreshOnForeground) return;
+    const sub = AppState.addEventListener('change', (next) => {
+      if (next === 'active') void refresh();
+    });
+    return () => sub.remove();
+  }, [refresh, refreshOnForeground]);
+
+  // Each action is memoised separately. Building them inline in the returned
+  // object handed callers a new function identity on every render, which loops
+  // any `useEffect` that lists one in its dependency array.
+  const run = useCallback(async (fn: () => Promise<StepSnapshot>) => {
+    try {
+      const result = await fn();
+      setSnapshot(result);
+      setState(result.state);
+    } catch (e) {
+      setError(e as Error);
+    }
+  }, []);
+
+  const start = useCallback(() => run(() => StepTracker.startTracking()), [run]);
+  const pause = useCallback(() => run(() => StepTracker.pauseTracking()), [run]);
+  const resume = useCallback(() => run(() => StepTracker.resumeTracking()), [run]);
+  const stop = useCallback(() => run(() => StepTracker.stopTracking()), [run]);
+
+  const requestPermissions = useCallback(async () => {
+    try {
+      const result = await StepTracker.requestPermissions();
+      return result.allGranted;
+    } catch (e) {
+      setError(e as Error);
+      return false;
+    }
+  }, []);
+
+  return {
+    snapshot,
+    state,
+    ready,
+    error,
+    refresh,
+    start,
+    pause,
+    resume,
+    stop,
+    requestPermissions,
+  };
+}

package/src/index.ts

@@ -0,0 +1,27 @@
+export { StepTracker, StepTracker as default, isSupported } from './StepTracker';
+export { StepTrackerError } from './errors';
+export type { StepTrackerErrorCode } from './errors';
+export { DEFAULT_CONFIG, STRIDE_COEFFICIENT } from './constants';
+export * from './hooks';
+export type {
+  DayChangedEvent,
+  DayRecord,
+  DeviceCapabilities,
+  EventSubscription,
+  GoalProgressEvent,
+  GoalReachedEvent,
+  HealthConnectStatus,
+  PermissionStatus,
+  RangeOptions,
+  RangeStats,
+  SensorSource,
+  Sex,
+  StepSnapshot,
+  StepTrackerConfig,
+  StepTrackerEvent,
+  StepTrackerEventMap,
+  StepsChangedEvent,
+  SyncEvent,
+  TrackingState,
+  TrackingStateEvent,
+} from './types';

package/src/types.ts

@@ -0,0 +1,203 @@
+/**
+ * Public type definitions for react-native-step-tracker-pro.
+ */
+
+/** Biological sex is only used to pick a stride-length coefficient. */
+export type Sex = 'male' | 'female' | 'unspecified';
+
+/** Which hardware sensor the service ended up using. */
+export type SensorSource = 'step_counter' | 'step_detector' | 'none';
+
+export type TrackingState =
+  | 'idle'
+  | 'running'
+  | 'paused'
+  | 'stopped'
+  | 'unsupported';
+
+export interface StepTrackerConfig {
+  /** Height in centimetres. Used for stride length. Default 170. */
+  height?: number;
+  /** Weight in kilograms. Used for calorie estimation. Default 70. */
+  weight?: number;
+  /**
+   * Overrides the derived stride length, in metres. Leave unset to derive it
+   * from `height` and `sex`.
+   */
+  strideLength?: number;
+  sex?: Sex;
+  /** Steps. Default 10000. */
+  dailyGoal?: number;
+  /** Steps. Defaults to dailyGoal * 7. */
+  weeklyGoal?: number;
+  /** Steps. Defaults to dailyGoal * 30. */
+  monthlyGoal?: number;
+  /** kcal per kg per km of walking. Default 0.57. */
+  calorieCoefficient?: number;
+  /** How many days of history to keep on device. Default 35. */
+  historyRetentionDays?: number;
+  /** Notification title. Supports {steps}, {goal}, {percent}, {distance}, {calories}. */
+  notificationTitle?: string;
+  notificationText?: string;
+  /** Drawable name in the host app, e.g. 'ic_stat_steps'. Falls back to a bundled icon. */
+  notificationIcon?: string;
+  /** Notification channel name shown in Android settings. */
+  notificationChannelName?: string;
+  /** Show Pause/Resume actions on the notification. Default true. */
+  notificationActions?: boolean;
+  /** Minimum ms between notification redraws. Default 1000. */
+  notificationThrottleMs?: number;
+  /** Minimum ms between JS `stepsChanged` events. Default 500. */
+  eventThrottleMs?: number;
+  /** Persist to SQLite after this many steps. Default 10. */
+  persistEveryNSteps?: number;
+  /** Mirror data into Health Connect when permissions are granted. Default true. */
+  healthConnectEnabled?: boolean;
+  /** Auto-write today's totals to Health Connect every N minutes. Default 30. 0 disables. */
+  healthConnectSyncIntervalMinutes?: number;
+  /** Optional HTTPS endpoint that unsynced day records get POSTed to. */
+  remoteSyncUrl?: string;
+  remoteSyncHeaders?: Record<string, string>;
+  /** Restart tracking automatically after device reboot. Default true. */
+  autoStartOnBoot?: boolean;
+}
+
+export interface StepSnapshot {
+  /** yyyy-MM-dd in the device timezone. */
+  date: string;
+  steps: number;
+  /** Metres. */
+  distance: number;
+  /** Kilocalories. */
+  calories: number;
+  dailyGoal: number;
+  /** 0..1, clamped. */
+  goalProgress: number;
+  goalReached: boolean;
+  state: TrackingState;
+  source: SensorSource;
+  /** Epoch ms of the last sensor sample. */
+  timestamp: number;
+}
+
+export interface DayRecord {
+  date: string;
+  steps: number;
+  distance: number;
+  calories: number;
+  /** Mirrored into Health Connect. */
+  synced: boolean;
+  /** Uploaded to `remoteSyncUrl`. Always false when no endpoint is configured. */
+  syncedRemote: boolean;
+}
+
+export interface RangeStats {
+  /** Inclusive yyyy-MM-dd. */
+  startDate: string;
+  /** Inclusive yyyy-MM-dd. */
+  endDate: string;
+  totalSteps: number;
+  totalDistance: number;
+  totalCalories: number;
+  averageSteps: number;
+  /** Days with at least one recorded step. */
+  activeDays: number;
+  bestDay: DayRecord | null;
+  /** Every day in the range, zero-filled, ascending. */
+  days: DayRecord[];
+  /** Present for weekly/monthly windows when a goal is configured. */
+  goal?: number;
+  goalProgress?: number;
+}
+
+export interface RangeOptions {
+  /**
+   * 'calendar' snaps to the current week (Mon–Sun), month or year.
+   * 'rolling' uses the last 7 / 30 / 365 days ending today.
+   * Default 'calendar'.
+   */
+  mode?: 'calendar' | 'rolling';
+  /** 0 = current period, 1 = previous period, and so on. Only for 'calendar'. */
+  offset?: number;
+}
+
+export interface PermissionStatus {
+  activityRecognition: boolean;
+  postNotifications: boolean;
+  /** True on API < 34 where the permission does not exist. */
+  foregroundServiceHealth: boolean;
+  /** All permissions required to start tracking are granted. */
+  allGranted: boolean;
+}
+
+export interface HealthConnectStatus {
+  /** Health Connect SDK is available on the device. */
+  available: boolean;
+  /** The user must install or update the Health Connect provider. */
+  requiresUpdate: boolean;
+  granted: boolean;
+  grantedPermissions: string[];
+}
+
+export interface DeviceCapabilities {
+  hasStepCounter: boolean;
+  hasStepDetector: boolean;
+  supported: boolean;
+  sdkInt: number;
+  manufacturer: string;
+  model: string;
+}
+
+export interface StepsChangedEvent extends StepSnapshot {}
+
+export interface GoalReachedEvent {
+  type: 'daily' | 'weekly' | 'monthly';
+  goal: number;
+  steps: number;
+  date: string;
+  timestamp: number;
+}
+
+export interface GoalProgressEvent {
+  type: 'daily' | 'weekly' | 'monthly';
+  goal: number;
+  steps: number;
+  progress: number;
+  date: string;
+}
+
+export interface TrackingStateEvent {
+  state: TrackingState;
+  source: SensorSource;
+  reason?: string;
+}
+
+export interface SyncEvent {
+  target: 'health_connect' | 'remote';
+  syncedRecords: number;
+  failedRecords: number;
+  success: boolean;
+  error?: string;
+}
+
+export interface DayChangedEvent {
+  previousDate: string;
+  currentDate: string;
+  previousDaySteps: number;
+}
+
+export interface StepTrackerEventMap {
+  stepsChanged: StepsChangedEvent;
+  goalReached: GoalReachedEvent;
+  goalProgressChanged: GoalProgressEvent;
+  trackingStateChanged: TrackingStateEvent;
+  dayChanged: DayChangedEvent;
+  syncCompleted: SyncEvent;
+  error: { code: string; message: string };
+}
+
+export type StepTrackerEvent = keyof StepTrackerEventMap;
+
+export interface EventSubscription {
+  remove(): void;
+}