expo-background-tracking 1.0.0

package/build/Database.d.ts

@@ -0,0 +1,30 @@
+import type { Geofence, Location, LogEntry, SQLQuery } from './types';
+/**
+ * SQLite persistence layer (locations queue, geofences, key/value state, logs).
+ * Mirrors the embedded database of transistorsoft's SDK.
+ */
+export declare class Database {
+    private db;
+    private opening;
+    private open;
+    insertLocation(location: Location): Promise<void>;
+    getLocations(query?: SQLQuery): Promise<Location[]>;
+    getCount(): Promise<number>;
+    destroyLocations(): Promise<void>;
+    destroyLocation(uuid: string): Promise<void>;
+    deleteLocations(uuids: string[]): Promise<void>;
+    /** Purge by retention policy. */
+    prune(maxDays: number, maxRecords: number): Promise<void>;
+    upsertGeofence(geofence: Geofence): Promise<void>;
+    getGeofences(): Promise<Geofence[]>;
+    getGeofence(identifier: string): Promise<Geofence | null>;
+    removeGeofence(identifier: string): Promise<void>;
+    removeGeofences(identifiers?: string[]): Promise<void>;
+    setKV(key: string, value: unknown): Promise<void>;
+    getKV<T>(key: string): Promise<T | null>;
+    insertLog(level: string, message: string): Promise<void>;
+    getLogs(limit?: number): Promise<LogEntry[]>;
+    destroyLogs(): Promise<void>;
+    pruneLogs(maxDays: number): Promise<void>;
+}
+export declare const database: Database;

package/build/Database.js

@@ -0,0 +1,206 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.database = exports.Database = void 0;
+const SQLite = __importStar(require("expo-sqlite"));
+const DB_NAME = 'expo_background_tracking.db';
+/**
+ * SQLite persistence layer (locations queue, geofences, key/value state, logs).
+ * Mirrors the embedded database of transistorsoft's SDK.
+ */
+class Database {
+    constructor() {
+        this.db = null;
+        this.opening = null;
+    }
+    async open() {
+        if (this.db)
+            return this.db;
+        if (!this.opening) {
+            this.opening = (async () => {
+                const db = await SQLite.openDatabaseAsync(DB_NAME);
+                await db.execAsync(`
+          PRAGMA journal_mode = WAL;
+          CREATE TABLE IF NOT EXISTS locations (
+            uuid TEXT PRIMARY KEY,
+            timestamp INTEGER NOT NULL,
+            data TEXT NOT NULL,
+            synced INTEGER DEFAULT 0
+          );
+          CREATE INDEX IF NOT EXISTS idx_locations_ts ON locations (timestamp);
+          CREATE TABLE IF NOT EXISTS geofences (
+            identifier TEXT PRIMARY KEY,
+            data TEXT NOT NULL
+          );
+          CREATE TABLE IF NOT EXISTS kv (
+            key TEXT PRIMARY KEY,
+            value TEXT NOT NULL
+          );
+          CREATE TABLE IF NOT EXISTS logs (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            timestamp INTEGER NOT NULL,
+            level TEXT NOT NULL,
+            message TEXT NOT NULL
+          );
+        `);
+                this.db = db;
+                return db;
+            })();
+        }
+        return this.opening;
+    }
+    // --- locations ---------------------------------------------------------
+    async insertLocation(location) {
+        const db = await this.open();
+        await db.runAsync('INSERT OR REPLACE INTO locations (uuid, timestamp, data, synced) VALUES (?, ?, ?, 0)', location.uuid, Date.parse(location.timestamp), JSON.stringify(location));
+    }
+    async getLocations(query) {
+        const db = await this.open();
+        const where = [];
+        const args = [];
+        if (query?.start != null) {
+            where.push('timestamp >= ?');
+            args.push(query.start);
+        }
+        if (query?.end != null) {
+            where.push('timestamp <= ?');
+            args.push(query.end);
+        }
+        const order = query?.order === -1 ? 'DESC' : 'ASC';
+        const limit = query?.limit ? ` LIMIT ${Math.floor(query.limit)}` : '';
+        const sql = `SELECT data FROM locations ${where.length ? 'WHERE ' + where.join(' AND ') : ''} ORDER BY timestamp ${order}${limit}`;
+        const rows = await db.getAllAsync(sql, ...args);
+        return rows.map((r) => JSON.parse(r.data));
+    }
+    async getCount() {
+        const db = await this.open();
+        const row = await db.getFirstAsync('SELECT COUNT(*) as c FROM locations');
+        return row?.c ?? 0;
+    }
+    async destroyLocations() {
+        const db = await this.open();
+        await db.runAsync('DELETE FROM locations');
+    }
+    async destroyLocation(uuid) {
+        const db = await this.open();
+        await db.runAsync('DELETE FROM locations WHERE uuid = ?', uuid);
+    }
+    async deleteLocations(uuids) {
+        if (!uuids.length)
+            return;
+        const db = await this.open();
+        const placeholders = uuids.map(() => '?').join(',');
+        await db.runAsync(`DELETE FROM locations WHERE uuid IN (${placeholders})`, ...uuids);
+    }
+    /** Purge by retention policy. */
+    async prune(maxDays, maxRecords) {
+        const db = await this.open();
+        if (maxDays > 0) {
+            const cutoff = Date.now() - maxDays * 86400000;
+            await db.runAsync('DELETE FROM locations WHERE timestamp < ?', cutoff);
+        }
+        if (maxRecords > 0) {
+            await db.runAsync(`DELETE FROM locations WHERE uuid NOT IN (
+           SELECT uuid FROM locations ORDER BY timestamp DESC LIMIT ?
+         )`, maxRecords);
+        }
+    }
+    // --- geofences ----------------------------------------------------------
+    async upsertGeofence(geofence) {
+        const db = await this.open();
+        await db.runAsync('INSERT OR REPLACE INTO geofences (identifier, data) VALUES (?, ?)', geofence.identifier, JSON.stringify(geofence));
+    }
+    async getGeofences() {
+        const db = await this.open();
+        const rows = await db.getAllAsync('SELECT data FROM geofences');
+        return rows.map((r) => JSON.parse(r.data));
+    }
+    async getGeofence(identifier) {
+        const db = await this.open();
+        const row = await db.getFirstAsync('SELECT data FROM geofences WHERE identifier = ?', identifier);
+        return row ? JSON.parse(row.data) : null;
+    }
+    async removeGeofence(identifier) {
+        const db = await this.open();
+        await db.runAsync('DELETE FROM geofences WHERE identifier = ?', identifier);
+    }
+    async removeGeofences(identifiers) {
+        const db = await this.open();
+        if (!identifiers) {
+            await db.runAsync('DELETE FROM geofences');
+            return;
+        }
+        if (!identifiers.length)
+            return;
+        const placeholders = identifiers.map(() => '?').join(',');
+        await db.runAsync(`DELETE FROM geofences WHERE identifier IN (${placeholders})`, ...identifiers);
+    }
+    // --- key/value (state, odometer, config) --------------------------------
+    async setKV(key, value) {
+        const db = await this.open();
+        await db.runAsync('INSERT OR REPLACE INTO kv (key, value) VALUES (?, ?)', key, JSON.stringify(value));
+    }
+    async getKV(key) {
+        const db = await this.open();
+        const row = await db.getFirstAsync('SELECT value FROM kv WHERE key = ?', key);
+        return row ? JSON.parse(row.value) : null;
+    }
+    // --- logs ----------------------------------------------------------------
+    async insertLog(level, message) {
+        const db = await this.open();
+        await db.runAsync('INSERT INTO logs (timestamp, level, message) VALUES (?, ?, ?)', Date.now(), level, message);
+    }
+    async getLogs(limit = 5000) {
+        const db = await this.open();
+        const rows = await db.getAllAsync('SELECT timestamp, level, message FROM logs ORDER BY id ASC LIMIT ?', limit);
+        return rows.map((r) => ({
+            timestamp: new Date(r.timestamp).toISOString(),
+            level: r.level,
+            message: r.message,
+        }));
+    }
+    async destroyLogs() {
+        const db = await this.open();
+        await db.runAsync('DELETE FROM logs');
+    }
+    async pruneLogs(maxDays) {
+        if (maxDays <= 0)
+            return;
+        const db = await this.open();
+        await db.runAsync('DELETE FROM logs WHERE timestamp < ?', Date.now() - maxDays * 86400000);
+    }
+}
+exports.Database = Database;
+exports.database = new Database();

package/build/EventBus.d.ts

@@ -0,0 +1,10 @@
+import type { EventName, Subscription } from './types';
+type Listener = (event: unknown) => void;
+/** Minimal dependency-free event emitter. */
+export declare class EventBus {
+    private listeners;
+    on(name: EventName, fn: Listener): Subscription;
+    emit(name: EventName, event: unknown): void;
+    removeAll(name?: EventName): void;
+}
+export {};

package/build/EventBus.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventBus = void 0;
+/** Minimal dependency-free event emitter. */
+class EventBus {
+    constructor() {
+        this.listeners = new Map();
+    }
+    on(name, fn) {
+        if (!this.listeners.has(name))
+            this.listeners.set(name, new Set());
+        const set = this.listeners.get(name);
+        set.add(fn);
+        return { remove: () => set.delete(fn) };
+    }
+    emit(name, event) {
+        const set = this.listeners.get(name);
+        if (!set)
+            return;
+        for (const fn of [...set]) {
+            try {
+                fn(event);
+            }
+            catch (e) {
+                // listener errors must never break the tracking pipeline
+                console.warn(`[expo-background-tracking] listener error (${name})`, e);
+            }
+        }
+    }
+    removeAll(name) {
+        if (name)
+            this.listeners.delete(name);
+        else
+            this.listeners.clear();
+    }
+}
+exports.EventBus = EventBus;

package/build/GeofenceManager.d.ts

@@ -0,0 +1,42 @@
+import type { EventBus } from './EventBus';
+import type { Geofence, Location } from './types';
+export declare const GEOFENCE_TASK = "expo-background-tracking.geofence";
+/**
+ * Unlimited geofencing (circular + polygon) with software proximity
+ * management, like transistorsoft: only nearby geofences are registered
+ * with the OS; the rest are monitored as the device approaches.
+ * In Expo Go, evaluation is fully software-based from the foreground stream.
+ */
+export declare class GeofenceManager {
+    private bus;
+    private runtime;
+    private proximityRadius;
+    private started;
+    constructor(bus: EventBus);
+    setProximityRadius(metres: number): void;
+    add(geofence: Geofence): Promise<boolean>;
+    addMany(geofences: Geofence[]): Promise<boolean>;
+    private validate;
+    remove(identifier: string): Promise<boolean>;
+    removeAll(identifiers?: string[]): Promise<boolean>;
+    getGeofences(): Promise<Geofence[]>;
+    getGeofence(identifier: string): Promise<Geofence | null>;
+    exists(identifier: string): Promise<boolean>;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /**
+     * Register nearby circular geofences with the OS (dev build only).
+     * Polygon geofences are always evaluated in software.
+     */
+    private refreshNative;
+    /** Software evaluation — called for every location fix. */
+    evaluate(location: Location): Promise<void>;
+    /** Native OS geofence event (from TaskManager, dev build). */
+    onNativeEvent(identifier: string, action: 'ENTER' | 'EXIT', location: Location): Promise<void>;
+    private fire;
+    /** Useful for polygon geofences: approximate center for native registration. */
+    static centerOf(g: Geofence): {
+        latitude: number;
+        longitude: number;
+    };
+}

package/build/GeofenceManager.js

@@ -0,0 +1,281 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GeofenceManager = exports.GEOFENCE_TASK = void 0;
+const ExpoLocation = __importStar(require("expo-location"));
+const Database_1 = require("./Database");
+const Logger_1 = require("./Logger");
+const geo_1 = require("./geo");
+const environment_1 = require("./environment");
+exports.GEOFENCE_TASK = 'expo-background-tracking.geofence';
+/**
+ * Unlimited geofencing (circular + polygon) with software proximity
+ * management, like transistorsoft: only nearby geofences are registered
+ * with the OS; the rest are monitored as the device approaches.
+ * In Expo Go, evaluation is fully software-based from the foreground stream.
+ */
+class GeofenceManager {
+    constructor(bus) {
+        this.bus = bus;
+        this.runtime = new Map();
+        this.proximityRadius = 1000;
+        this.started = false;
+    }
+    setProximityRadius(metres) {
+        this.proximityRadius = metres;
+    }
+    async add(geofence) {
+        this.validate(geofence);
+        await Database_1.database.upsertGeofence(geofence);
+        this.runtime.set(geofence.identifier, {
+            inside: false,
+            enteredAt: null,
+            dwellFired: false,
+            active: false,
+        });
+        if (this.started)
+            await this.refreshNative(null);
+        return true;
+    }
+    async addMany(geofences) {
+        for (const g of geofences) {
+            this.validate(g);
+            await Database_1.database.upsertGeofence(g);
+            this.runtime.set(g.identifier, {
+                inside: false,
+                enteredAt: null,
+                dwellFired: false,
+                active: false,
+            });
+        }
+        if (this.started)
+            await this.refreshNative(null);
+        return true;
+    }
+    validate(g) {
+        if (!g.identifier)
+            throw new Error('Geofence requires identifier');
+        const circular = g.latitude != null && g.longitude != null && g.radius != null;
+        const polygon = !!g.vertices?.length;
+        if (!circular && !polygon) {
+            throw new Error(`Geofence "${g.identifier}" requires latitude/longitude/radius or vertices`);
+        }
+    }
+    async remove(identifier) {
+        await Database_1.database.removeGeofence(identifier);
+        this.runtime.delete(identifier);
+        if (this.started)
+            await this.refreshNative(null);
+        return true;
+    }
+    async removeAll(identifiers) {
+        await Database_1.database.removeGeofences(identifiers);
+        if (identifiers)
+            identifiers.forEach((id) => this.runtime.delete(id));
+        else
+            this.runtime.clear();
+        if (this.started)
+            await this.refreshNative(null);
+        return true;
+    }
+    getGeofences() {
+        return Database_1.database.getGeofences();
+    }
+    getGeofence(identifier) {
+        return Database_1.database.getGeofence(identifier);
+    }
+    async exists(identifier) {
+        return (await Database_1.database.getGeofence(identifier)) != null;
+    }
+    async start() {
+        this.started = true;
+        const geofences = await Database_1.database.getGeofences();
+        for (const g of geofences) {
+            if (!this.runtime.has(g.identifier)) {
+                this.runtime.set(g.identifier, {
+                    inside: false,
+                    enteredAt: null,
+                    dwellFired: false,
+                    active: false,
+                });
+            }
+        }
+        await this.refreshNative(null);
+    }
+    async stop() {
+        this.started = false;
+        if ((0, environment_1.isBackgroundCapable)()) {
+            try {
+                const registered = await ExpoLocation.hasStartedGeofencingAsync(exports.GEOFENCE_TASK);
+                if (registered)
+                    await ExpoLocation.stopGeofencingAsync(exports.GEOFENCE_TASK);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+    /**
+     * Register nearby circular geofences with the OS (dev build only).
+     * Polygon geofences are always evaluated in software.
+     */
+    async refreshNative(position) {
+        if (!(0, environment_1.isBackgroundCapable)())
+            return; // Expo Go → software-only
+        try {
+            const geofences = await Database_1.database.getGeofences();
+            const circular = geofences.filter((g) => g.latitude != null && g.longitude != null && g.radius != null);
+            let selected = circular;
+            const changed = { on: [], off: [] };
+            if (position && circular.length > 19) {
+                selected = circular
+                    .map((g) => ({
+                    g,
+                    d: (0, geo_1.haversine)(position.latitude, position.longitude, g.latitude, g.longitude),
+                }))
+                    .filter(({ g, d }) => d <= this.proximityRadius + (g.radius ?? 0))
+                    .sort((a, b) => a.d - b.d)
+                    .slice(0, 19)
+                    .map(({ g }) => g);
+            }
+            const selectedIds = new Set(selected.map((g) => g.identifier));
+            for (const g of circular) {
+                const rt = this.runtime.get(g.identifier);
+                if (!rt)
+                    continue;
+                const nowActive = selectedIds.has(g.identifier);
+                if (nowActive && !rt.active)
+                    changed.on.push(g);
+                if (!nowActive && rt.active)
+                    changed.off.push(g.identifier);
+                rt.active = nowActive;
+            }
+            if (changed.on.length || changed.off.length) {
+                this.bus.emit('geofenceschange', changed);
+            }
+            if (selected.length) {
+                await ExpoLocation.startGeofencingAsync(exports.GEOFENCE_TASK, selected.map((g) => ({
+                    identifier: g.identifier,
+                    latitude: g.latitude,
+                    longitude: g.longitude,
+                    radius: g.radius,
+                    notifyOnEnter: g.notifyOnEntry !== false,
+                    notifyOnExit: g.notifyOnExit !== false,
+                })));
+            }
+            else {
+                const registered = await ExpoLocation.hasStartedGeofencingAsync(exports.GEOFENCE_TASK);
+                if (registered)
+                    await ExpoLocation.stopGeofencingAsync(exports.GEOFENCE_TASK);
+            }
+        }
+        catch (e) {
+            Logger_1.logger.warn(`Native geofencing unavailable: ${String(e)}`);
+        }
+    }
+    /** Software evaluation — called for every location fix. */
+    async evaluate(location) {
+        const { latitude, longitude } = location.coords;
+        const geofences = await Database_1.database.getGeofences();
+        const now = Date.now();
+        for (const g of geofences) {
+            let rt = this.runtime.get(g.identifier);
+            if (!rt) {
+                rt = { inside: false, enteredAt: null, dwellFired: false, active: false };
+                this.runtime.set(g.identifier, rt);
+            }
+            let inside;
+            if (g.vertices?.length) {
+                inside = (0, geo_1.pointInPolygon)(latitude, longitude, g.vertices);
+            }
+            else {
+                const d = (0, geo_1.haversine)(latitude, longitude, g.latitude, g.longitude);
+                inside = d <= (g.radius ?? 200);
+            }
+            if (inside && !rt.inside) {
+                rt.inside = true;
+                rt.enteredAt = now;
+                rt.dwellFired = false;
+                if (g.notifyOnEntry !== false)
+                    this.fire(g, 'ENTER', location);
+            }
+            else if (!inside && rt.inside) {
+                rt.inside = false;
+                rt.enteredAt = null;
+                rt.dwellFired = false;
+                if (g.notifyOnExit !== false)
+                    this.fire(g, 'EXIT', location);
+            }
+            else if (inside &&
+                rt.inside &&
+                g.notifyOnDwell &&
+                !rt.dwellFired &&
+                rt.enteredAt != null &&
+                now - rt.enteredAt >= (g.loiteringDelay ?? 300000)) {
+                rt.dwellFired = true;
+                this.fire(g, 'DWELL', location);
+            }
+        }
+        await this.refreshNative({ latitude, longitude });
+    }
+    /** Native OS geofence event (from TaskManager, dev build). */
+    async onNativeEvent(identifier, action, location) {
+        const g = await Database_1.database.getGeofence(identifier);
+        if (!g)
+            return;
+        const rt = this.runtime.get(identifier);
+        if (rt) {
+            rt.inside = action === 'ENTER';
+            rt.enteredAt = action === 'ENTER' ? Date.now() : null;
+        }
+        this.fire(g, action, location);
+    }
+    fire(g, action, location) {
+        Logger_1.logger.info(`Geofence ${action}: ${g.identifier}`);
+        this.bus.emit('geofence', {
+            identifier: g.identifier,
+            action,
+            location: { ...location, event: 'geofence' },
+            extras: g.extras,
+        });
+    }
+    /** Useful for polygon geofences: approximate center for native registration. */
+    static centerOf(g) {
+        if (g.vertices?.length)
+            return (0, geo_1.centroid)(g.vertices);
+        return { latitude: g.latitude, longitude: g.longitude };
+    }
+}
+exports.GeofenceManager = GeofenceManager;

package/build/HttpService.d.ts

@@ -0,0 +1,27 @@
+import type { EventBus } from './EventBus';
+import type { Config, Location } from './types';
+/**
+ * HTTP upload service: autoSync, batchSync, templates, JWT refresh,
+ * offline queue with re-sync on reconnect. Pure `fetch` — no Firebase.
+ */
+export declare class HttpService {
+    private bus;
+    private config;
+    private syncing;
+    private connectivityTimer;
+    private lastConnected;
+    constructor(bus: EventBus);
+    setConfig(config: Config): void;
+    startConnectivityMonitoring(intervalMs?: number): void;
+    stopConnectivityMonitoring(): void;
+    private checkConnectivity;
+    /** Called after each persisted location when autoSync is enabled. */
+    autoSync(): Promise<void>;
+    /** Upload all queued locations. Resolves with the uploaded records. */
+    sync(): Promise<Location[]>;
+    private renderTemplate;
+    private buildBody;
+    private authHeaders;
+    private refreshToken;
+    private upload;
+}