@kafitra/react-native-live-tracking 0.1.0

package/src/types.ts

@@ -0,0 +1,252 @@
+/**
+ * TypeScript type definitions for react-native-live-tracking.
+ *
+ * @packageDocumentation
+ */
+
+// ─── Enums ───────────────────────────────────────────────────────────────────
+
+/**
+ * Internal state machine for tracking lifecycle.
+ */
+export enum TrackingState {
+  IDLE = 'idle',
+  CONFIGURED = 'configured',
+  TRACKING = 'tracking',
+  MOTION_SLEEP = 'motion_sleep',
+  PAUSED_GPS = 'paused_gps',
+}
+
+// ─── Configuration Interfaces ────────────────────────────────────────────────
+
+/**
+ * Strategy used by the distance/time filter.
+ * - 'interval': accept when enough time has elapsed
+ * - 'distance': accept when enough distance has been covered
+ * - 'both': accept only when both conditions are met (default)
+ */
+export type OptimizationMode = 'interval' | 'distance' | 'both';
+
+/**
+ * Optimization parameters for location tracking.
+ */
+export interface OptimizationConfig {
+  /** Minimum time interval between location updates in milliseconds. Default: 10000 */
+  intervalMs?: number;
+  /** Minimum distance change in meters to trigger an update. Default: 10 */
+  distanceFilterMeters?: number;
+  /** Whether to reduce GPS accuracy when device is still. Default: true */
+  stopWhenStill?: boolean;
+  /** Filter strategy: 'interval', 'distance', or 'both'. Default: 'both' */
+  mode?: OptimizationMode;
+}
+
+/**
+ * Android foreground service notification configuration.
+ */
+export interface AndroidNotificationConfig {
+  /** Whether to show the foreground service notification. Default: true */
+  enabled?: boolean;
+  /** Notification title */
+  title: string;
+  /** Notification body text */
+  text: string;
+  /** Notification icon resource name */
+  icon?: string;
+  /** Notification channel ID */
+  channelId?: string;
+  /** Notification channel name */
+  channelName?: string;
+}
+
+/**
+ * iOS persistent notification configuration.
+ * Shows a local notification while tracking is active (similar to Android's foreground service notification).
+ */
+export interface IOSNotificationConfig {
+  /** Whether to show the persistent local notification. Default: true */
+  enabled?: boolean;
+  /** Notification title */
+  title: string;
+  /** Notification body text */
+  text: string;
+}
+
+/**
+ * A user-defined sync target specifying a Firebase path, write method,
+ * and optional batching/offline queue settings.
+ */
+export interface SyncTarget {
+  /** Firebase path to write to */
+  path: string;
+  /** Write method: 'set' (overwrite), 'push' (append), 'update' (merge) */
+  method: 'set' | 'push' | 'update';
+  /** Number of points to accumulate before writing. Default: 1 (immediate) */
+  batchSize?: number;
+  /** Whether to persist data offline when device has no connectivity */
+  offlineQueue?: boolean;
+}
+
+/**
+ * Firebase connection and sync target configuration.
+ */
+export interface FirebaseConfig {
+  /** Firebase service type: Realtime Database or Firestore */
+  service: 'RTDB' | 'Firestore';
+  /** Array of sync targets (at least one required) */
+  targets: [SyncTarget, ...SyncTarget[]];
+}
+
+/**
+ * Main configuration object passed to `configure()`.
+ */
+export interface TrackingConfig {
+  /** Optimization settings for battery and update frequency */
+  optimization: OptimizationConfig;
+  /** Android foreground service notification settings (Android only) */
+  androidNotification?: AndroidNotificationConfig;
+  /** iOS persistent notification settings (iOS only) */
+  iosNotification?: IOSNotificationConfig;
+  /** Firebase connection and path configuration */
+  firebase: FirebaseConfig;
+}
+
+// ─── Data Interfaces ─────────────────────────────────────────────────────────
+
+/**
+ * Location data emitted by the library on each valid location update.
+ */
+export interface LocationData {
+  /** Latitude in degrees (-90 to 90) */
+  latitude: number;
+  /** Longitude in degrees (-180 to 180) */
+  longitude: number;
+  /** Unix timestamp in milliseconds */
+  timestamp: number;
+  /** Horizontal accuracy in meters */
+  accuracy: number;
+  /** Speed in meters per second, or null if unavailable */
+  speed: number | null;
+  /** Altitude in meters above sea level, or null if unavailable */
+  altitude: number | null;
+  /** Bearing/heading in degrees (0-360), or null if unavailable */
+  bearing: number | null;
+}
+
+// ─── Error & Status Interfaces ───────────────────────────────────────────────
+
+/**
+ * Error object emitted by the library when tracking issues occur.
+ */
+export interface TrackingError {
+  /** Error code identifier (e.g., 'PERMISSION_DENIED', 'GPS_DISABLED') */
+  code: string;
+  /** Human-readable error message */
+  message: string;
+  /** Whether the error is recoverable (auto-retry or user action can fix) */
+  recoverable: boolean;
+  /** Additional error context */
+  details?: Record<string, unknown>;
+}
+
+/**
+ * Current tracking status snapshot.
+ */
+export interface TrackingStatus {
+  /** Current state of the tracking lifecycle */
+  state: TrackingState;
+  /** Whether the device currently has network connectivity */
+  isOnline: boolean;
+  /** Number of locations waiting in the offline queue */
+  queuedLocations: number;
+  /** Last known location, or null if no location has been received */
+  lastLocation: LocationData | null;
+  /** Current battery optimization mode */
+  batteryOptimization: 'full_accuracy' | 'low_power' | 'disabled';
+}
+
+// ─── Validation Interfaces ───────────────────────────────────────────────────
+
+/**
+ * Single configuration validation error.
+ */
+export interface ConfigError {
+  /** Dot-notation path to the invalid field (e.g., 'firebase.service') */
+  field: string;
+  /** Human-readable description of the validation error */
+  message: string;
+  /** Machine-readable error code */
+  code: string;
+}
+
+/**
+ * Result of configuration validation.
+ */
+export interface ConfigValidationResult {
+  /** Whether the configuration is valid */
+  valid: boolean;
+  /** List of validation errors (empty if valid) */
+  errors: ConfigError[];
+}
+
+// ─── Utility Types ───────────────────────────────────────────────────────────
+
+/**
+ * Subscription handle returned by event listener registrations.
+ * Call `remove()` to unsubscribe from the event.
+ */
+export interface Subscription {
+  /** Unsubscribe from the event */
+  remove(): void;
+}
+
+// ─── Module Interface ────────────────────────────────────────────────────────
+
+/**
+ * Main public API interface for the react-native-live-tracking library.
+ */
+export interface LiveTrackingModule {
+  /**
+   * Configure the tracking library with the given parameters.
+   * Must be called before `start()`.
+   */
+  configure(config: TrackingConfig): Promise<void>;
+
+  /**
+   * Start location tracking. Requires `configure()` to have been called first.
+   */
+  start(): Promise<void>;
+
+  /**
+   * Stop location tracking and clean up resources.
+   */
+  stop(): Promise<void>;
+
+  /**
+   * Register a callback for location updates.
+   * Returns a Subscription that can be used to unsubscribe.
+   */
+  onLocationUpdate(callback: (location: LocationData) => void): Subscription;
+
+  /**
+   * Register a callback for tracking errors.
+   * Returns a Subscription that can be used to unsubscribe.
+   */
+  onError(callback: (error: TrackingError) => void): Subscription;
+
+  /**
+   * Get the current tracking status.
+   */
+  getStatus(): Promise<TrackingStatus>;
+
+  /**
+   * Get the number of locations currently queued for sync.
+   */
+  getQueuedLocations(): Promise<number>;
+
+  /**
+   * Get the number of queued locations per target path.
+   * Returns a record mapping each configured target path to its queued location count.
+   */
+  getQueuedLocationsByTarget(): Promise<Record<string, number>>;
+}

package/src/utils/distance.ts

@@ -0,0 +1,68 @@
+/**
+ * Distance calculation utility using the Haversine formula.
+ *
+ * The Haversine formula determines the great-circle distance between two points
+ * on a sphere given their longitudes and latitudes. This is used by the
+ * Distance/Time Matrix filter to determine if a new location update has moved
+ * far enough from the last known position.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Earth's mean radius in meters.
+ * Used as the sphere radius in the Haversine formula.
+ */
+export const EARTH_RADIUS_METERS = 6371000;
+
+/**
+ * Converts degrees to radians.
+ *
+ * @param degrees - Angle in degrees
+ * @returns Angle in radians
+ */
+function toRadians(degrees: number): number {
+  return degrees * (Math.PI / 180);
+}
+
+/**
+ * Calculates the distance in meters between two geographic coordinates
+ * using the Haversine formula.
+ *
+ * The Haversine formula accounts for the curvature of the Earth and provides
+ * accurate results for short and medium distances. It assumes a spherical Earth
+ * with a mean radius of 6,371,000 meters.
+ *
+ * @param lat1 - Latitude of the first point in degrees (-90 to 90)
+ * @param lng1 - Longitude of the first point in degrees (-180 to 180)
+ * @param lat2 - Latitude of the second point in degrees (-90 to 90)
+ * @param lng2 - Longitude of the second point in degrees (-180 to 180)
+ * @returns Distance between the two points in meters
+ *
+ * @example
+ * ```typescript
+ * // Distance between Jakarta and Bandung (approximately 120 km)
+ * const distance = calculateDistance(-6.2088, 106.8456, -6.9175, 107.6191);
+ * console.log(distance); // ~120,000 meters
+ * ```
+ */
+export function calculateDistance(
+  lat1: number,
+  lng1: number,
+  lat2: number,
+  lng2: number
+): number {
+  const dLat = toRadians(lat2 - lat1);
+  const dLng = toRadians(lng2 - lng1);
+
+  const a =
+    Math.sin(dLat / 2) * Math.sin(dLat / 2) +
+    Math.cos(toRadians(lat1)) *
+      Math.cos(toRadians(lat2)) *
+      Math.sin(dLng / 2) *
+      Math.sin(dLng / 2);
+
+  const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+
+  return EARTH_RADIUS_METERS * c;
+}

package/src/utils/retry.ts

@@ -0,0 +1,75 @@
+/**
+ * Exponential backoff retry utilities for Firebase write operations.
+ *
+ * Used by the Firebase Sync Engine to determine delay between retry attempts
+ * when writes fail due to network issues or transient errors.
+ *
+ * @module utils/retry
+ */
+
+/** Default base delay in milliseconds for exponential backoff */
+export const DEFAULT_BASE_DELAY = 1000;
+
+/** Default maximum jitter in milliseconds (±) to avoid thundering herd */
+export const DEFAULT_MAX_JITTER = 200;
+
+/** Maximum retry attempts for sync targets using 'set' or 'update' write methods */
+export const MAX_RETRIES_SET_UPDATE = 3;
+
+/** Maximum retry attempts for sync targets using 'push' write method */
+export const MAX_RETRIES_PUSH = 5;
+
+/**
+ * Calculates the delay before the next retry attempt using exponential backoff
+ * with random jitter.
+ *
+ * Formula: delay = baseDelay × 2^(attempt - 1) + random(-maxJitter, +maxJitter)
+ *
+ * The result is clamped to a minimum of 0 to prevent negative delays.
+ *
+ * @param attempt - The retry attempt number (1-indexed, first retry = 1)
+ * @param baseDelay - The base delay in milliseconds (default: 1000ms)
+ * @param maxJitter - The maximum jitter offset in milliseconds (default: 200ms).
+ *   A random value between -maxJitter and +maxJitter is added to the delay.
+ * @returns The calculated delay in milliseconds (never negative)
+ *
+ * @example
+ * ```typescript
+ * // First retry: ~1000ms ± 200ms
+ * const delay1 = calculateBackoffDelay(1);
+ *
+ * // Second retry: ~2000ms ± 200ms
+ * const delay2 = calculateBackoffDelay(2);
+ *
+ * // Third retry: ~4000ms ± 200ms
+ * const delay3 = calculateBackoffDelay(3);
+ * ```
+ */
+export function calculateBackoffDelay(
+  attempt: number,
+  baseDelay: number = DEFAULT_BASE_DELAY,
+  maxJitter: number = DEFAULT_MAX_JITTER
+): number {
+  const exponentialDelay = baseDelay * Math.pow(2, attempt - 1);
+  const jitter = (Math.random() * 2 - 1) * maxJitter;
+  return Math.max(0, exponentialDelay + jitter);
+}
+
+/**
+ * Determines whether a retry should be attempted based on the current attempt
+ * number and the maximum allowed retries.
+ *
+ * @param attempt - The current attempt number (1-indexed)
+ * @param maxRetries - The maximum number of retries allowed
+ * @returns `true` if the attempt is within the allowed retry limit, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * shouldRetry(1, 3); // true - first retry is allowed
+ * shouldRetry(3, 3); // true - third retry is allowed
+ * shouldRetry(4, 3); // false - exceeds max retries
+ * ```
+ */
+export function shouldRetry(attempt: number, maxRetries: number): boolean {
+  return attempt <= maxRetries;
+}