@kafitra/react-native-live-tracking 0.1.0

package/src/EventEmitter.ts

@@ -0,0 +1,118 @@
+/**
+ * Event listener system for react-native-live-tracking.
+ *
+ * Wraps NativeEventEmitter to provide typed event subscriptions
+ * for location updates and tracking errors.
+ *
+ * @packageDocumentation
+ */
+
+import { DeviceEventEmitter } from 'react-native';
+import type { LocationData, TrackingError, Subscription } from './types';
+
+/**
+ * Directly use the global device event emitter.
+ *
+ * NativeEventEmitter's constructor accesses Platform.OS, which requires the
+ * PlatformConstants native module. In a broken or partially-initialised binary
+ * that module can be missing and crash the app before we can even report that
+ * LiveTracking is unavailable. DeviceEventEmitter avoids that dependency
+ * entirely while still delivering native events emitted by the LiveTracking
+ * RCTEventEmitter.
+ */
+
+/**
+ * Register a callback for location updates.
+ *
+ * The callback is invoked each time a valid location update is emitted
+ * from the native layer after passing the Distance/Time Matrix filter.
+ *
+ * @param callback - Function called with LocationData on each update
+ * @returns Subscription with `remove()` method to unsubscribe
+ *
+ * @example
+ * ```ts
+ * const subscription = onLocationUpdate((location) => {
+ *   console.log(location.latitude, location.longitude);
+ * });
+ * // Later: unsubscribe
+ * subscription.remove();
+ * ```
+ */
+export function onLocationUpdate(
+  callback: (location: LocationData) => void
+): Subscription {
+  const nativeSubscription = DeviceEventEmitter.addListener(
+    'onLocationUpdate',
+    (event: Record<string, unknown>) => {
+      const location: LocationData = {
+        latitude: event.latitude as number,
+        longitude: event.longitude as number,
+        timestamp: event.timestamp as number,
+        accuracy: event.accuracy as number,
+        speed: (event.speed as number | null) ?? null,
+        altitude: (event.altitude as number | null) ?? null,
+        bearing: (event.bearing as number | null) ?? null,
+      };
+      callback(location);
+    }
+  );
+
+  return {
+    remove: () => {
+      nativeSubscription.remove();
+    },
+  };
+}
+
+/**
+ * Register a callback for tracking errors.
+ *
+ * The callback is invoked when an error occurs during tracking
+ * (e.g., permission denied, GPS disabled, Firebase write failure).
+ *
+ * @param callback - Function called with TrackingError on each error event
+ * @returns Subscription with `remove()` method to unsubscribe
+ *
+ * @example
+ * ```ts
+ * const subscription = onError((error) => {
+ *   console.error(`[${error.code}] ${error.message}`);
+ * });
+ * // Later: unsubscribe
+ * subscription.remove();
+ * ```
+ */
+export function onError(
+  callback: (error: TrackingError) => void
+): Subscription {
+  const nativeSubscription = DeviceEventEmitter.addListener(
+    'onTrackingError',
+    (event: Record<string, unknown>) => {
+      const error: TrackingError = {
+        code: event.code as string,
+        message: event.message as string,
+        recoverable: (event.recoverable as boolean) ?? true,
+        details: (event.details as Record<string, unknown>) ?? undefined,
+      };
+      callback(error);
+    }
+  );
+
+  return {
+    remove: () => {
+      nativeSubscription.remove();
+    },
+  };
+}
+
+/**
+ * Remove all event listeners registered through this module.
+ *
+ * Useful for cleanup when the tracking module is being torn down
+ * or when all subscriptions need to be cleared at once.
+ */
+export function removeAllListeners(): void {
+  DeviceEventEmitter.removeAllListeners('onLocationUpdate');
+  DeviceEventEmitter.removeAllListeners('onTrackingError');
+}

package/src/LiveTracking.ts

@@ -0,0 +1,159 @@
+/**
+ * JavaScript LiveTracking module that wraps NativeModule calls.
+ *
+ * Provides the public API for configuring, starting, and stopping
+ * location tracking, with validation and state management.
+ *
+ * @packageDocumentation
+ */
+
+import NativeLiveTracking from './NativeLiveTracking';
+import {
+  onLocationUpdate as emitterOnLocationUpdate,
+  onError as emitterOnError,
+} from './EventEmitter';
+import type {
+  TrackingConfig,
+  TrackingStatus,
+  LocationData,
+  TrackingError,
+  Subscription,
+  LiveTrackingModule,
+} from './types';
+import { validateConfig, applyDefaults } from './validation';
+
+/**
+ * Returns the native module or throws a descriptive error if not linked.
+ * Using a function accessor (rather than assertNative) keeps TypeScript
+ * happy since it can't narrow an imported binding via assertion functions.
+ */
+function native(): NonNullable<typeof NativeLiveTracking> {
+  if (!NativeLiveTracking) {
+    throw new Error(
+      "[@kafitra/react-native-live-tracking] Native module 'LiveTracking' is not registered. " +
+        'Make sure you ran `pod install` and rebuilt the app from Xcode.'
+    );
+  }
+  return NativeLiveTracking;
+}
+
+/**
+ * Tracks whether configure() has been successfully called.
+ * Used to guard queue methods that require configuration.
+ */
+let isConfigured = false;
+
+/**
+ * Resets the configured state. Only for use in tests.
+ * @internal
+ */
+export function _resetConfiguredStateForTesting(): void {
+  isConfigured = false;
+}
+
+/**
+ * LiveTracking module implementation.
+ *
+ * Wraps native module calls with validation, serialization,
+ * and state management on the JavaScript side.
+ */
+const LiveTracking: LiveTrackingModule = {
+  /**
+   * Configure the tracking library with the given parameters.
+   * Validates the config, applies defaults, and passes to native layer.
+   */
+  async configure(config: TrackingConfig): Promise<void> {
+    const validationResult = validateConfig(config);
+    if (!validationResult.valid) {
+      const errorMessages = validationResult.errors
+        .map((e) => `[${e.field}]: ${e.message}`)
+        .join('; ');
+      throw new Error(`Invalid configuration: ${errorMessages}`);
+    }
+
+    const finalConfig = applyDefaults(config);
+    const jsonString = JSON.stringify(finalConfig);
+
+    const MAX_PAYLOAD_BYTES = 1024 * 1024; // 1 MB
+    if (jsonString.length > MAX_PAYLOAD_BYTES) {
+      throw new Error(
+        'Configuration payload is too large: serialized JSON exceeds 1 MB'
+      );
+    }
+
+    await native().configure(jsonString);
+    isConfigured = true;
+  },
+
+  /**
+   * Start location tracking.
+   * Requires `configure()` to have been called first.
+   */
+  async start(): Promise<void> {
+    await native().start();
+  },
+
+  /**
+   * Stop location tracking and clean up resources.
+   */
+  async stop(): Promise<void> {
+    await native().stop();
+  },
+
+  /**
+   * Register a callback for location updates.
+   */
+  onLocationUpdate(callback: (location: LocationData) => void): Subscription {
+    return emitterOnLocationUpdate(callback);
+  },
+
+  /**
+   * Register a callback for tracking errors.
+   */
+  onError(callback: (error: TrackingError) => void): Subscription {
+    return emitterOnError(callback);
+  },
+
+  /**
+   * Get the current tracking status.
+   */
+  async getStatus(): Promise<TrackingStatus> {
+    const jsonString = await native().getStatus();
+    return JSON.parse(jsonString) as TrackingStatus;
+  },
+
+  /**
+   * Get the total number of locations currently queued for sync.
+   *
+   * @throws Error with code NOT_CONFIGURED if called before configure()
+   */
+  async getQueuedLocations(): Promise<number> {
+    if (!isConfigured) {
+      const error = new Error(
+        'LiveTracking is not configured. Call configure() before getQueuedLocations().'
+      );
+      (error as any).code = 'NOT_CONFIGURED';
+      throw error;
+    }
+    return native().getQueuedLocations();
+  },
+
+  /**
+   * Get the number of queued locations per target path.
+   *
+   * @throws Error with code NOT_CONFIGURED if called before configure()
+   */
+  async getQueuedLocationsByTarget(): Promise<Record<string, number>> {
+    if (!isConfigured) {
+      const error = new Error(
+        'LiveTracking is not configured. Call configure() before getQueuedLocationsByTarget().'
+      );
+      (error as any).code = 'NOT_CONFIGURED';
+      throw error;
+    }
+    const jsonString = await native().getQueuedLocationsByTarget();
+    return JSON.parse(jsonString);
+  },
+};
+
+export default LiveTracking;

package/src/NativeLiveTracking.ts

@@ -0,0 +1,29 @@
+/**
+ * Codegen spec for react-native-live-tracking.
+ *
+ * Uses TurboModuleRegistry.get (not getEnforcing) so that a missing or
+ * not-yet-registered module returns null instead of throwing synchronously.
+ * A top-level throw would corrupt the module graph and leave upstream
+ * importers (TrackingProvider, AppNavigator) with undefined module records.
+ *
+ * File must be named Native*.ts and live in the codegenConfig.jsSrcsDir
+ * for RN's codegen to pick it up.
+ */
+
+import type { TurboModule } from 'react-native';
+import { TurboModuleRegistry, NativeModules } from 'react-native';
+
+export interface Spec extends TurboModule {
+  configure(config: string): Promise<void>;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  getStatus(): Promise<string>;
+  getQueuedLocations(): Promise<number>;
+  getQueuedLocationsByTarget(): Promise<string>;
+  addListener(eventName: string): void;
+  removeListeners(count: number): void;
+}
+
+// Try TurboModule first (new arch with codegen), fall back to Bridge (old arch / interop)
+export default (TurboModuleRegistry.get<Spec>('LiveTracking') ??
+  NativeModules.LiveTracking) as Spec | null;

package/src/filters/distanceTimeFilter.ts

@@ -0,0 +1,75 @@
+/**
+ * Distance/Time Matrix filter for location updates.
+ *
+ * This filter implements the battery optimization strategy that accepts a new
+ * location update based on the selected mode:
+ * - 'both' (default): BOTH time and distance conditions must be met
+ * - 'interval': only the time condition must be met
+ * - 'distance': only the distance condition must be met
+ *
+ * @packageDocumentation
+ */
+
+import { calculateDistance } from '../utils/distance';
+import type { LocationData, OptimizationConfig } from '../types';
+
+/**
+ * Configuration subset required by the distance/time filter.
+ */
+export type DistanceTimeFilterConfig = Required<
+  Pick<OptimizationConfig, 'intervalMs' | 'distanceFilterMeters'>
+> & {
+  /** Filter strategy. Defaults to 'both' if not provided. */
+  mode?: 'interval' | 'distance' | 'both';
+};
+
+/**
+ * Determines whether a new location should be accepted based on the
+ * Distance/Time Matrix filter criteria.
+ *
+ * The filtering strategy depends on `config.mode`:
+ * - 'both': accepted only if both time and distance conditions are met
+ * - 'interval': accepted only if enough time has elapsed
+ * - 'distance': accepted only if enough distance has been covered
+ *
+ * @param lastLocation - The most recently accepted location
+ * @param newLocation - The candidate location to evaluate
+ * @param config - Filter configuration with intervalMs, distanceFilterMeters, and mode
+ * @returns `true` if the new location should be accepted, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * const accepted = shouldAcceptLocation(
+ *   { latitude: -6.2088, longitude: 106.8456, timestamp: 1700000000000, accuracy: 5, speed: null, altitude: null, bearing: null },
+ *   { latitude: -6.2090, longitude: 106.8460, timestamp: 1700000015000, accuracy: 5, speed: 1.2, altitude: null, bearing: null },
+ *   { intervalMs: 10000, distanceFilterMeters: 10, mode: 'both' }
+ * );
+ * ```
+ */
+export function shouldAcceptLocation(
+  lastLocation: LocationData,
+  newLocation: LocationData,
+  config: DistanceTimeFilterConfig
+): boolean {
+  const mode = config.mode ?? 'both';
+  const timeDiff = newLocation.timestamp - lastLocation.timestamp;
+  const distance = calculateDistance(
+    lastLocation.latitude,
+    lastLocation.longitude,
+    newLocation.latitude,
+    newLocation.longitude
+  );
+
+  const timeMet = timeDiff >= config.intervalMs;
+  const distanceMet = distance >= config.distanceFilterMeters;
+
+  switch (mode) {
+    case 'interval':
+      return timeMet;
+    case 'distance':
+      return distanceMet;
+    case 'both':
+    default:
+      return timeMet && distanceMet;
+  }
+}

package/src/index.ts

@@ -0,0 +1,51 @@
+/**
+ * react-native-live-tracking
+ *
+ * Real-time location tracking library for React Native with Firebase synchronization.
+ * Supports both TurboModules (new architecture) and Bridge (old architecture).
+ *
+ * @packageDocumentation
+ */
+
+import LiveTracking from './LiveTracking';
+
+export default LiveTracking;
+export { default as LiveTracking } from './LiveTracking';
+
+// Re-export all types
+export { TrackingState } from './types';
+export type {
+  SyncTarget,
+  OptimizationConfig,
+  OptimizationMode,
+  AndroidNotificationConfig,
+  IOSNotificationConfig,
+  FirebaseConfig,
+  TrackingConfig,
+  LocationData,
+  TrackingError,
+  TrackingStatus,
+  ConfigError,
+  ConfigValidationResult,
+  Subscription,
+  LiveTrackingModule,
+} from './types';
+
+// Event listener functions
+export { onLocationUpdate, onError, removeAllListeners } from './EventEmitter';
+
+// Configuration validation utilities
+export { validateConfig, applyDefaults } from './validation';
+
+// Distance calculation utility
+export { calculateDistance } from './utils/distance';
+
+// Distance/Time Matrix filter
+export { shouldAcceptLocation } from './filters/distanceTimeFilter';
+
+// Location serialization for Firebase
+export { serializeLocationForTarget } from './serialization/locationSerializer';
+export type { TargetLocationPayload } from './serialization/locationSerializer';
+
+// Retry/backoff utilities
+export { calculateBackoffDelay, shouldRetry } from './utils/retry';

package/src/serialization/locationSerializer.ts

@@ -0,0 +1,57 @@
+/**
+ * Location serialization for Firebase sync targets.
+ *
+ * Transforms LocationData into a generic payload suitable for any
+ * sync target, regardless of write method (set, push, update).
+ *
+ * @packageDocumentation
+ */
+
+import type { LocationData } from '../types';
+
+// ─── Payload Interface ───────────────────────────────────────────────────────
+
+/**
+ * Serialized location payload for any sync target.
+ *
+ * Contains required fields (latitude, longitude, timestamp, accuracy)
+ * and optional sensor fields (speed, heading, altitude) which are
+ * included as `null` when unavailable from the device sensor.
+ * Placeholder values (0, -1) are never used for unavailable fields.
+ */
+export interface TargetLocationPayload {
+  latitude: number;
+  longitude: number;
+  timestamp: number;
+  accuracy: number;
+  speed: number | null;
+  heading: number | null;
+  altitude: number | null;
+}
+
+// ─── Serialization Function ──────────────────────────────────────────────────
+
+/**
+ * Serialize a LocationData object for a generic Firebase sync target.
+ *
+ * Produces a payload containing all required location fields and optional
+ * sensor fields. When optional fields (speed, heading/bearing, altitude)
+ * are unavailable from the device sensor, they are included as `null`.
+ * Default placeholder values (0, -1) are never written for unavailable fields.
+ *
+ * @param location - The location data to serialize
+ * @returns Serialized payload for the sync target
+ */
+export function serializeLocationForTarget(
+  location: LocationData
+): TargetLocationPayload {
+  return {
+    latitude: location.latitude,
+    longitude: location.longitude,
+    timestamp: location.timestamp,
+    accuracy: location.accuracy,
+    speed: location.speed,
+    heading: location.bearing,
+    altitude: location.altitude,
+  };
+}