expo-background-tracking 1.0.0

package/src/HttpService.ts

@@ -0,0 +1,232 @@
+import * as Network from 'expo-network';
+import { database } from './Database';
+import { logger } from './Logger';
+import type { EventBus } from './EventBus';
+import type {
+  Authorization,
+  AuthorizationEvent,
+  Config,
+  HttpEvent,
+  Location,
+} from './types';
+
+/**
+ * HTTP upload service: autoSync, batchSync, templates, JWT refresh,
+ * offline queue with re-sync on reconnect. Pure `fetch` — no Firebase.
+ */
+export class HttpService {
+  private config: Config = {};
+  private syncing = false;
+  private connectivityTimer: ReturnType<typeof setInterval> | null = null;
+  private lastConnected: boolean | null = null;
+
+  constructor(private bus: EventBus) {}
+
+  setConfig(config: Config): void {
+    this.config = config;
+  }
+
+  startConnectivityMonitoring(intervalMs = 10_000): void {
+    this.stopConnectivityMonitoring();
+    this.connectivityTimer = setInterval(() => {
+      void this.checkConnectivity();
+    }, intervalMs);
+    void this.checkConnectivity();
+  }
+
+  stopConnectivityMonitoring(): void {
+    if (this.connectivityTimer) {
+      clearInterval(this.connectivityTimer);
+      this.connectivityTimer = null;
+    }
+  }
+
+  private async checkConnectivity(): Promise<void> {
+    try {
+      const state = await Network.getNetworkStateAsync();
+      const connected = !!(state.isConnected && state.isInternetReachable !== false);
+      if (this.lastConnected !== null && connected !== this.lastConnected) {
+        this.bus.emit('connectivitychange', { connected });
+        if (connected && this.config.autoSync !== false) {
+          void this.sync();
+        }
+      }
+      this.lastConnected = connected;
+    } catch {
+      /* ignore */
+    }
+  }
+
+  /** Called after each persisted location when autoSync is enabled. */
+  async autoSync(): Promise<void> {
+    if (!this.config.url || this.config.autoSync === false) return;
+    const threshold = this.config.autoSyncThreshold ?? 0;
+    if (threshold > 0) {
+      const count = await database.getCount();
+      if (count < threshold) return;
+    }
+    await this.sync();
+  }
+
+  /** Upload all queued locations. Resolves with the uploaded records. */
+  async sync(): Promise<Location[]> {
+    if (!this.config.url) {
+      throw new Error('sync() requires config.url');
+    }
+    if (this.syncing) return [];
+    this.syncing = true;
+    try {
+      const queue = await database.getLocations({ order: 1 });
+      if (!queue.length) return [];
+
+      const batchSync = this.config.batchSync === true;
+      const maxBatch = this.config.maxBatchSize && this.config.maxBatchSize > 0
+        ? this.config.maxBatchSize
+        : Infinity;
+
+      if (batchSync) {
+        let i = 0;
+        while (i < queue.length) {
+          const batch = queue.slice(i, i + (isFinite(maxBatch) ? maxBatch : queue.length));
+          const ok = await this.upload(batch);
+          if (!ok) break;
+          await database.deleteLocations(batch.map((l) => l.uuid));
+          i += batch.length;
+        }
+      } else {
+        for (const location of queue) {
+          const ok = await this.upload([location]);
+          if (!ok) break;
+          await database.destroyLocation(location.uuid);
+        }
+      }
+      return queue;
+    } finally {
+      this.syncing = false;
+    }
+  }
+
+  private renderTemplate(template: string, location: Location): string {
+    return template.replace(/<%=?\s*([\w.]+)\s*%>/g, (_m, path: string) => {
+      const flat: Record<string, unknown> = {
+        ...location.coords,
+        uuid: location.uuid,
+        timestamp: location.timestamp,
+        odometer: location.odometer,
+        is_moving: location.is_moving,
+        activity: location.activity?.activity,
+        'activity.type': location.activity?.activity,
+        'activity.confidence': location.activity?.confidence,
+        'battery.level': location.battery?.level,
+        'battery.is_charging': location.battery?.is_charging,
+      };
+      const v = flat[path];
+      return v === undefined ? 'null' : JSON.stringify(v);
+    });
+  }
+
+  private buildBody(locations: Location[]): unknown {
+    const template = this.config.locationTemplate;
+    const extras = this.config.extras ?? {};
+    const records = locations.map((l) => {
+      if (template) {
+        try {
+          return JSON.parse(this.renderTemplate(template, l));
+        } catch {
+          return { ...l, extras: { ...extras, ...l.extras } };
+        }
+      }
+      return { ...l, extras: { ...extras, ...l.extras } };
+    });
+    const root = this.config.httpRootProperty ?? 'location';
+    const payload = locations.length === 1 && !this.config.batchSync ? records[0] : records;
+    if (root === '.') return payload;
+    return { [root]: payload, ...(this.config.params ?? {}) };
+  }
+
+  private async authHeaders(): Promise<Record<string, string>> {
+    const auth = this.config.authorization;
+    if (!auth?.accessToken) return {};
+    return { Authorization: `Bearer ${auth.accessToken}` };
+  }
+
+  private async refreshToken(auth: Authorization): Promise<boolean> {
+    if (!auth.refreshUrl || !auth.refreshToken) return false;
+    try {
+      const payload: Record<string, string> = {};
+      const tpl = auth.refreshPayload ?? { refresh_token: '{refreshToken}' };
+      for (const [k, v] of Object.entries(tpl)) {
+        payload[k] = v.replace('{refreshToken}', auth.refreshToken);
+      }
+      const res = await fetch(auth.refreshUrl, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', ...(auth.refreshHeaders ?? {}) },
+        body: JSON.stringify(payload),
+      });
+      const json = (await res.json().catch(() => ({}))) as Record<string, unknown>;
+      const event: AuthorizationEvent = res.ok
+        ? { success: true, status: res.status, response: json }
+        : { success: false, status: res.status, error: 'refresh failed' };
+      if (res.ok) {
+        const token =
+          (json.access_token as string) ?? (json.accessToken as string) ?? null;
+        const refresh =
+          (json.refresh_token as string) ?? (json.refreshToken as string) ?? null;
+        if (token) auth.accessToken = token;
+        if (refresh) auth.refreshToken = refresh;
+      }
+      this.bus.emit('authorization', event);
+      return res.ok;
+    } catch (e) {
+      this.bus.emit('authorization', {
+        success: false,
+        error: String(e),
+      } satisfies AuthorizationEvent);
+      return false;
+    }
+  }
+
+  private async upload(locations: Location[], retried = false): Promise<boolean> {
+    const url = this.config.url!;
+    const method = this.config.method ?? 'POST';
+    const timeout = this.config.httpTimeout ?? 60_000;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeout);
+    try {
+      const res = await fetch(url, {
+        method,
+        headers: {
+          'Content-Type': 'application/json',
+          ...(this.config.headers ?? {}),
+          ...(await this.authHeaders()),
+        },
+        body: JSON.stringify(this.buildBody(locations)),
+        signal: controller.signal,
+      });
+      const text = await res.text().catch(() => '');
+      const event: HttpEvent = {
+        success: res.ok,
+        status: res.status,
+        responseText: text,
+      };
+      this.bus.emit('http', event);
+
+      if (res.status === 401 && !retried && this.config.authorization) {
+        const refreshed = await this.refreshToken(this.config.authorization);
+        if (refreshed) return this.upload(locations, true);
+      }
+      if (!res.ok) logger.warn(`HTTP ${res.status}: ${text.slice(0, 200)}`);
+      return res.ok;
+    } catch (e) {
+      logger.warn(`HTTP error: ${String(e)}`);
+      this.bus.emit('http', {
+        success: false,
+        status: 0,
+        responseText: String(e),
+      } satisfies HttpEvent);
+      return false;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+}

package/src/Logger.ts

@@ -0,0 +1,52 @@
+import { database } from './Database';
+import { LogLevel } from './types';
+
+/** SQLite-backed logger, mirrors BackgroundGeolocation.logger. */
+export class Logger {
+  level: LogLevel = LogLevel.INFO;
+  debug = false;
+
+  private write(level: LogLevel, tag: string, message: string): void {
+    if (level > this.level) return;
+    const line = `[${tag}] ${message}`;
+    if (this.debug || level <= LogLevel.WARNING) {
+      const fn =
+        level === LogLevel.ERROR
+          ? console.error
+          : level === LogLevel.WARNING
+          ? console.warn
+          : console.log;
+      fn(`[expo-background-tracking]${line}`);
+    }
+    database.insertLog(LogLevel[level], line).catch(() => undefined);
+  }
+
+  error(message: string): void {
+    this.write(LogLevel.ERROR, 'ERROR', message);
+  }
+  warn(message: string): void {
+    this.write(LogLevel.WARNING, 'WARN', message);
+  }
+  info(message: string): void {
+    this.write(LogLevel.INFO, 'INFO', message);
+  }
+  debugLog(message: string): void {
+    this.write(LogLevel.DEBUG, 'DEBUG', message);
+  }
+  notice(message: string): void {
+    this.write(LogLevel.INFO, 'NOTICE', message);
+  }
+
+  async getLog(): Promise<string> {
+    const entries = await database.getLogs();
+    return entries
+      .map((e) => `${e.timestamp} ${e.level} ${e.message}`)
+      .join('\n');
+  }
+
+  async destroyLog(): Promise<void> {
+    await database.destroyLogs();
+  }
+}
+
+export const logger = new Logger();

package/src/MotionDetector.ts

@@ -0,0 +1,149 @@
+import { Accelerometer } from 'expo-sensors';
+import type { ActivityChangeEvent, MotionActivityType } from './types';
+
+export interface MotionDetectorOptions {
+  /** Minutes of stillness before declaring stationary (stopTimeout). */
+  stopTimeoutMinutes: number;
+  /** ms of sustained motion before declaring moving (motionTriggerDelay). */
+  motionTriggerDelayMs: number;
+  /** Disable accelerometer sampling (disableMotionActivityUpdates). */
+  disabled: boolean;
+  onMotionChange: (isMoving: boolean) => void;
+  onActivityChange: (activity: ActivityChangeEvent) => void;
+}
+
+/**
+ * Battery-conscious motion intelligence:
+ * - accelerometer variance → moving / stationary transitions
+ * - GPS speed + accelerometer → activity classification
+ *   (still, on_foot, walking, running, on_bicycle, in_vehicle)
+ */
+export class MotionDetector {
+  private sub: { remove(): void } | null = null;
+  private samples: number[] = [];
+  private isMoving = false;
+  private stillSince: number | null = null;
+  private movingSince: number | null = null;
+  private lastActivity: MotionActivityType = 'still';
+  private lastSpeed = 0;
+  private opts: MotionDetectorOptions;
+
+  // m/s² variance thresholds (device acceleration, gravity removed approx.)
+  private static MOTION_THRESHOLD = 0.05;
+
+  constructor(opts: MotionDetectorOptions) {
+    this.opts = opts;
+  }
+
+  setOptions(opts: Partial<MotionDetectorOptions>): void {
+    this.opts = { ...this.opts, ...opts };
+  }
+
+  get moving(): boolean {
+    return this.isMoving;
+  }
+
+  /** Force pace (changePace). */
+  setMoving(isMoving: boolean): void {
+    if (this.isMoving === isMoving) return;
+    this.isMoving = isMoving;
+    this.stillSince = null;
+    this.movingSince = null;
+    this.opts.onMotionChange(isMoving);
+  }
+
+  /** Feed GPS speed (m/s) for activity classification. */
+  feedSpeed(speed: number | null): void {
+    if (speed == null || speed < 0) return;
+    this.lastSpeed = speed;
+    this.classify();
+    // GPS speed is also strong evidence of motion
+    if (speed > 1 && !this.isMoving) this.noteMotion(true);
+  }
+
+  async start(): Promise<void> {
+    if (this.opts.disabled) return;
+    try {
+      const available = await Accelerometer.isAvailableAsync();
+      if (!available) return;
+    } catch {
+      return;
+    }
+    Accelerometer.setUpdateInterval(1000);
+    this.sub = Accelerometer.addListener(({ x, y, z }) => {
+      const magnitude = Math.abs(Math.sqrt(x * x + y * y + z * z) - 1); // gravity-normalized
+      this.samples.push(magnitude);
+      if (this.samples.length > 10) this.samples.shift();
+      if (this.samples.length >= 5) this.evaluate();
+    });
+  }
+
+  stop(): void {
+    this.sub?.remove();
+    this.sub = null;
+    this.samples = [];
+    this.stillSince = null;
+    this.movingSince = null;
+  }
+
+  private evaluate(): void {
+    const mean = this.samples.reduce((a, b) => a + b, 0) / this.samples.length;
+    const variance =
+      this.samples.reduce((a, b) => a + (b - mean) ** 2, 0) / this.samples.length;
+    const active =
+      variance > MotionDetector.MOTION_THRESHOLD ||
+      mean > MotionDetector.MOTION_THRESHOLD * 2;
+    this.noteMotion(active);
+    this.classify();
+  }
+
+  private noteMotion(active: boolean): void {
+    const now = Date.now();
+    if (active) {
+      this.stillSince = null;
+      if (!this.isMoving) {
+        if (this.movingSince == null) this.movingSince = now;
+        if (now - this.movingSince >= this.opts.motionTriggerDelayMs) {
+          this.isMoving = true;
+          this.movingSince = null;
+          this.opts.onMotionChange(true);
+        }
+      }
+    } else {
+      this.movingSince = null;
+      if (this.isMoving) {
+        if (this.stillSince == null) this.stillSince = now;
+        if (now - this.stillSince >= this.opts.stopTimeoutMinutes * 60_000) {
+          this.isMoving = false;
+          this.stillSince = null;
+          this.opts.onMotionChange(false);
+        }
+      }
+    }
+  }
+
+  private classify(): void {
+    const speed = this.lastSpeed;
+    let activity: MotionActivityType;
+    let confidence = 75;
+    if (!this.isMoving && speed < 0.5) {
+      activity = 'still';
+      confidence = 90;
+    } else if (speed < 2) {
+      activity = 'walking';
+    } else if (speed < 3.5) {
+      activity = 'running';
+      confidence = 60;
+    } else if (speed < 8) {
+      activity = 'on_bicycle';
+      confidence = 55;
+    } else {
+      activity = 'in_vehicle';
+      confidence = 85;
+    }
+    if (activity !== this.lastActivity) {
+      this.lastActivity = activity;
+      this.opts.onActivityChange({ activity, confidence });
+    }
+  }
+}

package/src/Scheduler.ts

@@ -0,0 +1,90 @@
+import { logger } from './Logger';
+import type { ScheduleItem } from './types';
+
+interface ParsedSchedule {
+  days: Set<number>; // 1=Mon … 7=Sun
+  startMinutes: number;
+  endMinutes: number;
+}
+
+/**
+ * Weekly schedule engine — "1-5 09:00-17:00" style entries
+ * (same syntax as transistorsoft). JS timer-based: evaluated every
+ * 30 s while the app runs; state re-evaluated on resume.
+ */
+export class Scheduler {
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private schedules: ParsedSchedule[] = [];
+  private lastShouldBeEnabled: boolean | null = null;
+
+  constructor(
+    private onScheduleChange: (enabled: boolean) => void
+  ) {}
+
+  get enabled(): boolean {
+    return this.timer != null;
+  }
+
+  setSchedule(items: ScheduleItem[]): void {
+    this.schedules = items
+      .map((s) => this.parse(s))
+      .filter((s): s is ParsedSchedule => s != null);
+  }
+
+  start(): void {
+    if (this.timer) return;
+    if (!this.schedules.length) {
+      logger.warn('startSchedule: no schedule configured');
+      return;
+    }
+    this.timer = setInterval(() => this.evaluate(), 30_000);
+    this.evaluate();
+    logger.info('Schedule started');
+  }
+
+  stop(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    this.lastShouldBeEnabled = null;
+    logger.info('Schedule stopped');
+  }
+
+  private evaluate(): void {
+    const now = new Date();
+    const isoDay = now.getDay() === 0 ? 7 : now.getDay();
+    const minutes = now.getHours() * 60 + now.getMinutes();
+    const shouldBeEnabled = this.schedules.some(
+      (s) =>
+        s.days.has(isoDay) && minutes >= s.startMinutes && minutes < s.endMinutes
+    );
+    if (shouldBeEnabled !== this.lastShouldBeEnabled) {
+      this.lastShouldBeEnabled = shouldBeEnabled;
+      this.onScheduleChange(shouldBeEnabled);
+    }
+  }
+
+  private parse(item: string): ParsedSchedule | null {
+    // "1-5 09:00-17:00" | "7 10:00-12:00" | "1,3,5 08:30-18:00"
+    const m = item.trim().match(/^([\d,\-]+)\s+(\d{1,2}):(\d{2})-(\d{1,2}):(\d{2})$/);
+    if (!m) {
+      logger.warn(`Invalid schedule item: "${item}"`);
+      return null;
+    }
+    const days = new Set<number>();
+    for (const part of m[1].split(',')) {
+      const range = part.split('-').map(Number);
+      if (range.length === 2) {
+        for (let d = range[0]; d <= range[1]; d++) days.add(d);
+      } else {
+        days.add(range[0]);
+      }
+    }
+    return {
+      days,
+      startMinutes: Number(m[2]) * 60 + Number(m[3]),
+      endMinutes: Number(m[4]) * 60 + Number(m[5]),
+    };
+  }
+}

package/src/environment.ts

@@ -0,0 +1,22 @@
+import Constants from 'expo-constants';
+
+/** True when running inside the Expo Go sandbox app. */
+export function isExpoGo(): boolean {
+  try {
+    return (
+      (Constants as { executionEnvironment?: string } | undefined)
+        ?.executionEnvironment === 'storeClient'
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Background location (expo-task-manager location tasks) requires a
+ * development build — it is not available inside Expo Go.
+ * https://docs.expo.dev/versions/latest/sdk/location/
+ */
+export function isBackgroundCapable(): boolean {
+  return !isExpoGo();
+}

package/src/geo.ts

@@ -0,0 +1,57 @@
+/** Geodesic helpers. */
+
+const R = 6_371_000; // earth radius, metres
+
+export function haversine(
+  lat1: number,
+  lon1: number,
+  lat2: number,
+  lon2: number
+): number {
+  const toRad = (d: number) => (d * Math.PI) / 180;
+  const dLat = toRad(lat2 - lat1);
+  const dLon = toRad(lon2 - lon1);
+  const a =
+    Math.sin(dLat / 2) ** 2 +
+    Math.cos(toRad(lat1)) * Math.cos(toRad(lat2)) * Math.sin(dLon / 2) ** 2;
+  return 2 * R * Math.asin(Math.sqrt(a));
+}
+
+/** Point-in-polygon (ray casting) — vertices as [lat, lon]. */
+export function pointInPolygon(
+  lat: number,
+  lon: number,
+  vertices: Array<[number, number]>
+): boolean {
+  let inside = false;
+  for (let i = 0, j = vertices.length - 1; i < vertices.length; j = i++) {
+    const [yi, xi] = vertices[i];
+    const [yj, xj] = vertices[j];
+    if (yi > lat !== yj > lat && lon < ((xj - xi) * (lat - yi)) / (yj - yi) + xi) {
+      inside = !inside;
+    }
+  }
+  return inside;
+}
+
+/** Centroid of a polygon's vertices ([lat, lon]). */
+export function centroid(
+  vertices: Array<[number, number]>
+): { latitude: number; longitude: number } {
+  const n = vertices.length || 1;
+  let lat = 0;
+  let lon = 0;
+  for (const [vLat, vLon] of vertices) {
+    lat += vLat;
+    lon += vLon;
+  }
+  return { latitude: lat / n, longitude: lon / n };
+}
+
+export function uuidv4(): string {
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+    const r = (Math.random() * 16) | 0;
+    const v = c === 'x' ? r : (r & 0x3) | 0x8;
+    return v.toString(16);
+  });
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export { BackgroundGeolocation, LOCATION_TASK } from './BackgroundGeolocation';
+export { GEOFENCE_TASK } from './GeofenceManager';
+export { isExpoGo, isBackgroundCapable } from './environment';
+export * from './types';
+
+import { BackgroundGeolocation } from './BackgroundGeolocation';
+export default BackgroundGeolocation;