@robono/location-react-native 0.0.0-stage → 0.1.0

package/dist/expo.d.ts

@@ -0,0 +1,65 @@
+import { LocationClient, type Position } from "@robono/location";
+export interface TrackingContext {
+    sessionId: string;
+    expiresAt: string;
+    intervalSeconds: number;
+    stopping?: boolean;
+    nextAttemptAt?: number;
+}
+export interface TrackingStore {
+    load: () => Promise<TrackingContext | null>;
+    save: (value: TrackingContext | null) => Promise<void>;
+}
+export declare class LocationPermissionError extends Error {
+    permission: "foreground" | "background";
+    canAskAgain: boolean;
+    constructor(permission: "foreground" | "background", canAskAgain: boolean);
+}
+/** Locate the viewer for map framing only. This does not publish or retain a position. */
+export declare function getForegroundPosition(signal?: AbortSignal): Promise<Position>;
+/** User-requested high accuracy. Emits real fixes immediately and refines for at
+ * most 12 seconds. The returned radius is the provider's estimate, never inches
+ * inferred from coordinates. GPS stops on completion, cancellation or error. */
+export declare function getPrecisePosition(options?: {
+    signal?: AbortSignal;
+    onPosition?: (position: Position) => void;
+    timeoutMs?: number;
+    targetAccuracyMeters?: number;
+}): Promise<Position>;
+/** Register once at module scope. Store only session metadata, never a network or provider API key. */
+export declare function defineLocationTask(options: {
+    taskName: string;
+    store: TrackingStore;
+    getClient: () => Promise<Pick<LocationClient, "update" | "stop">>;
+    createId: () => string;
+    onError?: (error: unknown) => void;
+    onPrecision?: (position: Position) => void;
+}): void;
+export declare function stopLocationTask(taskName: string, store: TrackingStore, clear?: boolean): Promise<void>;
+/** GPS starts only after explicit user action. Hosts persist auth independently of sharing metadata. */
+export declare function createExpoLocationSharing(options: {
+    client: Pick<LocationClient, "start" | "update" | "stop">;
+    startWithPosition?: (input: {
+        grantId: string;
+        mode: "pin" | "live" | "ongoing";
+        durationMinutes?: number;
+    }, position: Position, requestId: string) => ReturnType<LocationClient["start"]>;
+    createId: () => string;
+    taskName?: string;
+    store?: TrackingStore;
+    notificationTitle?: string;
+    notificationBody?: string;
+    onError?: (error: unknown) => void;
+    onPrecision?: (position: Position) => void;
+}): {
+    start(input: {
+        grantId: string;
+        mode: "pin" | "live" | "ongoing";
+        durationMinutes?: number;
+        intervalSeconds: number;
+        background?: boolean;
+        precise?: boolean;
+    }): Promise<import("@robono/location").LocationStart>;
+    stop(): Promise<void>;
+    dispose(): void;
+};

package/dist/expo.js

@@ -0,0 +1,425 @@
+import * as Location from "expo-location";
+import * as TaskManager from "expo-task-manager";
+import { createPositionPublisher, LocationError, validatePosition, bestPosition, } from "@robono/location";
+function fix(value) {
+    return validatePosition({
+        latitude: value.coords.latitude,
+        longitude: value.coords.longitude,
+        accuracyMeters: value.coords.accuracy ?? 10000,
+        capturedAt: new Date(value.timestamp).toISOString(),
+        speedMps: value.coords.speed != null && value.coords.speed >= 0
+            ? value.coords.speed
+            : null,
+        headingDegrees: value.coords.heading != null && value.coords.heading >= 0
+            ? value.coords.heading
+            : null,
+    });
+}
+// A fixed pin needs a recent usable fix, not an indefinite high-accuracy GPS lock.
+function currentPinPosition() {
+    let cancel = () => { };
+    const promise = new Promise((resolve, reject) => {
+        let settled = false;
+        let watch;
+        const finish = (error, position) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            watch?.remove();
+            if (error)
+                reject(error);
+            else
+                resolve(position);
+        };
+        const timer = setTimeout(() => finish(Error("Could not get a precise location. Please try again.")), 10000);
+        cancel = () => finish(Error("Location sharing was cancelled."));
+        const accept = (value) => {
+            if (!value || settled)
+                return;
+            const age = Date.now() - value.timestamp;
+            if (age < -1000 || age > 10000 || value.coords.accuracy == null || value.coords.accuracy > 100)
+                return;
+            try {
+                finish(undefined, fix(value));
+            }
+            catch { /* Wait for a valid fix. */ }
+        };
+        void (async () => {
+            try {
+                accept(await Location.getLastKnownPositionAsync({ maxAge: 10000, requiredAccuracy: 100 }));
+            }
+            catch { /* A missing cached fix should still allow a fresh one. */ }
+            if (settled)
+                return;
+            try {
+                watch = await Location.watchPositionAsync({
+                    accuracy: Location.Accuracy.Balanced,
+                    timeInterval: 1000,
+                    distanceInterval: 0,
+                }, accept, () => finish(Error("Could not get your location. Please try again.")));
+                // Some platforms deliver the first fix before returning the subscription.
+                if (settled)
+                    watch.remove();
+            }
+            catch {
+                finish(Error("Could not get your location. Please try again."));
+            }
+        })();
+    });
+    return { promise, cancel: () => cancel() };
+}
+export class LocationPermissionError extends Error {
+    permission;
+    canAskAgain;
+    constructor(permission, canAskAgain) {
+        super(permission === "background"
+            ? "Allow background location to keep sharing when you leave the app or lock your phone."
+            : "Allow location access to share your location.");
+        this.permission = permission;
+        this.canAskAgain = canAskAgain;
+        this.name = "LocationPermissionError";
+    }
+}
+async function permission(background) {
+    const foreground = await Location.requestForegroundPermissionsAsync();
+    if (foreground.status !== "granted") {
+        throw new LocationPermissionError("foreground", foreground.canAskAgain);
+    }
+    if (background) {
+        const result = await Location.requestBackgroundPermissionsAsync();
+        if (result.status !== "granted") {
+            throw new LocationPermissionError("background", result.canAskAgain);
+        }
+    }
+}
+/** Locate the viewer for map framing only. This does not publish or retain a position. */
+export async function getForegroundPosition(signal) {
+    if (signal?.aborted)
+        throw Error("Location request was cancelled.");
+    await permission(false);
+    if (signal?.aborted)
+        throw Error("Location request was cancelled.");
+    const pending = currentPinPosition();
+    const abort = () => pending.cancel();
+    signal?.addEventListener("abort", abort, { once: true });
+    try {
+        return await pending.promise;
+    }
+    finally {
+        signal?.removeEventListener("abort", abort);
+    }
+}
+/** User-requested high accuracy. Emits real fixes immediately and refines for at
+ * most 12 seconds. The returned radius is the provider's estimate, never inches
+ * inferred from coordinates. GPS stops on completion, cancellation or error. */
+export async function getPrecisePosition(options = {}) {
+    const timeoutMs = options.timeoutMs ?? 12000, target = options.targetAccuracyMeters ?? 3;
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 1000 || timeoutMs > 30000 || !Number.isFinite(target) || target <= 0 || target > 100)
+        throw Error('Invalid precision request.');
+    if (options.signal?.aborted)
+        throw Error('Location request was cancelled.');
+    await permission(false);
+    if (options.signal?.aborted)
+        throw Error('Location request was cancelled.');
+    return new Promise((resolve, reject) => {
+        let closed = false, watch;
+        const samples = [];
+        const finish = (error) => { if (closed)
+            return; closed = true; clearTimeout(timer); watch?.remove(); options.signal?.removeEventListener('abort', abort); const best = bestPosition(samples); if (error)
+            reject(error);
+        else if (best)
+            resolve(best);
+        else
+            reject(Error('A recent location is unavailable. Try again outdoors.')); };
+        const abort = () => finish(Error('Location request was cancelled.'));
+        const timer = setTimeout(() => finish(), timeoutMs);
+        options.signal?.addEventListener('abort', abort, { once: true });
+        void Location.watchPositionAsync({ accuracy: Location.Accuracy.BestForNavigation, timeInterval: 500, distanceInterval: 0 }, value => {
+            if (closed)
+                return;
+            try {
+                const p = fix(value);
+                samples.push(p);
+                if (samples.length > 100)
+                    samples.shift();
+                const best = bestPosition(samples);
+                if (best) {
+                    options.onPosition?.(best);
+                    if (best.accuracyMeters <= target)
+                        finish();
+                }
+            }
+            catch { /* Await a usable fix. */ }
+        }, () => finish()).then(value => { watch = value; if (closed)
+            value.remove(); }).catch(() => finish(Error('Could not obtain your location.')));
+    });
+}
+/** Register once at module scope. Store only session metadata, never a network or provider API key. */
+export function defineLocationTask(options) {
+    if (TaskManager.isTaskDefined(options.taskName)) {
+        throw Error("This location task is already registered.");
+    }
+    TaskManager.defineTask(options.taskName, async ({ data, error }) => {
+        if (error) {
+            options.onError?.(error);
+            return;
+        }
+        const context = await options.store.load();
+        if (!context || Date.parse(context.expiresAt) <= Date.now()) {
+            await stopLocationTask(options.taskName, options.store);
+            return;
+        }
+        if (context.nextAttemptAt && context.nextAttemptAt > Date.now())
+            return;
+        if (context.stopping) {
+            try {
+                await (await options.getClient()).stop(context.sessionId);
+                await options.store.save(null);
+            }
+            catch (e) {
+                options.onError?.(e);
+            }
+            return;
+        }
+        const last = data?.locations?.at(-1);
+        if (!last)
+            return;
+        try {
+            const client = await options.getClient();
+            const current = await options.store.load();
+            if (current?.sessionId !== context.sessionId || current.stopping) {
+                return;
+            }
+            const response = await client.update(context.sessionId, fix(last), options.createId());
+            if (response?.stopped)
+                await stopLocationTask(options.taskName, options.store);
+        }
+        catch (e) {
+            if (e instanceof LocationError && [401, 403, 404, 410].includes(e.status))
+                await stopLocationTask(options.taskName, options.store);
+            else if (e instanceof LocationError && e.retryAfterMs) {
+                const current = await options.store.load();
+                if (current?.sessionId === context.sessionId && !current.stopping) {
+                    await options.store.save({
+                        ...current,
+                        nextAttemptAt: Date.now() + e.retryAfterMs,
+                    });
+                }
+            }
+            options.onError?.(e);
+        }
+    });
+}
+export async function stopLocationTask(taskName, store, clear = true) {
+    try {
+        if (await Location.hasStartedLocationUpdatesAsync(taskName)) {
+            await Location.stopLocationUpdatesAsync(taskName);
+        }
+    }
+    finally {
+        if (clear)
+            await store.save(null);
+    }
+}
+/** GPS starts only after explicit user action. Hosts persist auth independently of sharing metadata. */
+export function createExpoLocationSharing(options) {
+    let subscription, publisher, sessionId, pendingStop, busy = false, epoch = 0;
+    let pendingPin;
+    let precisionAbort;
+    const endGps = () => {
+        precisionAbort?.abort();
+        precisionAbort = undefined;
+        pendingPin?.cancel();
+        pendingPin = undefined;
+        subscription?.remove();
+        subscription = undefined;
+        publisher?.stop();
+        publisher = undefined;
+    };
+    return {
+        async start(input) {
+            if (busy || sessionId)
+                throw Error("Location sharing is already active.");
+            busy = true;
+            const run = ++epoch;
+            const check = () => {
+                if (run !== epoch)
+                    throw Error("Location sharing was cancelled.");
+            };
+            try {
+                const previous = await options.store?.load();
+                if (previous?.stopping || pendingStop) {
+                    await options.client.stop(pendingStop ?? previous.sessionId);
+                    pendingStop = undefined;
+                    await options.store?.save(null);
+                }
+                else if (previous && Date.parse(previous.expiresAt) > Date.now()) {
+                    throw Error("Location sharing is already active.");
+                }
+                check();
+                const background = !!input.background && input.mode !== "pin";
+                if (background &&
+                    (!options.taskName || !options.store ||
+                        !TaskManager.isTaskDefined(options.taskName))) {
+                    throw Error("Register the background location task before starting sharing.");
+                }
+                await permission(background);
+                check();
+                let first;
+                if (input.precise) {
+                    precisionAbort = new AbortController();
+                    try {
+                        first = await getPrecisePosition({ onPosition: options.onPrecision, signal: precisionAbort.signal });
+                    }
+                    finally {
+                        precisionAbort = undefined;
+                    }
+                }
+                else if (input.mode === "pin") {
+                    pendingPin = currentPinPosition();
+                    first = await pendingPin.promise;
+                    pendingPin = undefined;
+                }
+                else {
+                    first = fix(await Location.getCurrentPositionAsync({ accuracy: Location.Accuracy.High }));
+                }
+                check();
+                const requestId = options.createId();
+                const result = options.startWithPosition
+                    ? await options.startWithPosition(input, first, requestId)
+                    : await options.client.start(input.grantId, input.mode, requestId, input.durationMinutes);
+                if (result.stopped)
+                    throw Error("This location share has ended.");
+                sessionId = result.sessionId;
+                check();
+                if (!options.startWithPosition)
+                    await options.client.update(sessionId, first, options.createId());
+                check();
+                if (input.mode === "pin") {
+                    sessionId = undefined;
+                    return result;
+                }
+                if (background) {
+                    await options.store.save({
+                        sessionId: sessionId,
+                        expiresAt: result.expiresAt,
+                        intervalSeconds: input.intervalSeconds,
+                    });
+                    await Location.startLocationUpdatesAsync(options.taskName, {
+                        accuracy: Location.Accuracy.Balanced,
+                        timeInterval: Math.max(5000, input.intervalSeconds * 1000),
+                        distanceInterval: 0,
+                        deferredUpdatesInterval: Math.max(5000, input.intervalSeconds * 1000),
+                        pausesUpdatesAutomatically: false,
+                        showsBackgroundLocationIndicator: true,
+                        foregroundService: {
+                            notificationTitle: options.notificationTitle ??
+                                "Location sharing is active",
+                            notificationBody: options.notificationBody ??
+                                "Open the app to stop sharing.",
+                            killServiceOnDestroy: true,
+                        },
+                    });
+                }
+                else {
+                    publisher = createPositionPublisher({ update: async (...args) => {
+                            const result = await options.client.update(...args);
+                            if (result?.stopped) {
+                                endGps();
+                                sessionId = undefined;
+                                await options.store?.save(null);
+                            }
+                            return result;
+                        } }, {
+                        sessionId: sessionId,
+                        intervalMs: input.intervalSeconds * 1000,
+                        createId: options.createId,
+                        onError: (e) => {
+                            if (e instanceof LocationError &&
+                                [401, 403, 404, 410].includes(e.status)) {
+                                endGps();
+                                sessionId = undefined;
+                            }
+                            options.onError?.(e);
+                        },
+                    });
+                    subscription = await Location.watchPositionAsync({
+                        accuracy: Location.Accuracy.Balanced,
+                        timeInterval: Math.max(5000, input.intervalSeconds * 1000),
+                        distanceInterval: 0,
+                    }, (value) => {
+                        if (Date.parse(result.expiresAt) <= Date.now()) {
+                            endGps();
+                            sessionId = undefined;
+                            return;
+                        }
+                        try {
+                            publisher?.push(fix(value));
+                        }
+                        catch (e) {
+                            options.onError?.(e);
+                        }
+                    }, (message) => options.onError?.(Error(message)));
+                }
+                check();
+                return result;
+            }
+            catch (e) {
+                endGps();
+                const failed = sessionId;
+                sessionId = undefined;
+                if (failed && options.taskName && options.store) {
+                    await stopLocationTask(options.taskName, options.store).catch(() => { });
+                }
+                if (failed) {
+                    try {
+                        await options.client.stop(failed);
+                    }
+                    catch {
+                        pendingStop = failed;
+                        await options.store?.save({
+                            sessionId: failed,
+                            expiresAt: new Date(Date.now() + 86400000).toISOString(),
+                            intervalSeconds: 15,
+                            stopping: true,
+                        });
+                    }
+                }
+                throw e;
+            }
+            finally {
+                busy = false;
+            }
+        },
+        async stop() {
+            epoch++;
+            endGps();
+            if (options.taskName && options.store) {
+                await stopLocationTask(options.taskName, options.store, false);
+            }
+            const saved = await options.store?.load();
+            const current = sessionId ?? pendingStop ?? saved?.sessionId;
+            sessionId = undefined;
+            pendingStop = current;
+            if (current && options.store) {
+                await options.store.save({
+                    ...saved,
+                    sessionId: current,
+                    expiresAt: saved?.expiresAt ??
+                        new Date(Date.now() + 86400000).toISOString(),
+                    intervalSeconds: saved?.intervalSeconds ?? 15,
+                    stopping: true,
+                });
+            }
+            if (current) {
+                await options.client.stop(current);
+                pendingStop = undefined;
+                await options.store?.save(null);
+            }
+        },
+        dispose() {
+            endGps();
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { LocationMessage, LocationScreen, type LocationScreenProps, } from "./LocationScreen.js";
+export { RobonoMapView } from "./MapView.js";
+export { type GeofenceDraft, GeofenceEditor } from "./GeofenceEditor.js";
+export { AvatarLocationMap } from './AvatarLocationMap.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { LocationMessage, LocationScreen, } from "./LocationScreen.js";
+export { RobonoMapView } from "./MapView.js";
+export { GeofenceEditor } from "./GeofenceEditor.js";
+export { AvatarLocationMap } from './AvatarLocationMap.js';

package/dist/motion.d.ts

@@ -0,0 +1,16 @@
+import { createMovementSharing, type MotionReading } from '@robono/location';
+/** Explicitly start after the person enables movement sharing. Raw readings stay
+ * on the device. Foreground only: stale/missing readings must display unavailable. */
+export declare function observeDeviceMovement(options: {
+    onReading: (reading: MotionReading) => void;
+    onError?: (error: Error) => void;
+}): Promise<{
+    stop(): void;
+}>;
+/** Ready-to-use publisher with explicit consent and durable stop recovery. */
+export { finishPendingMovementStop } from '@robono/location';
+export declare function createExpoMovementSharing(options: Omit<Parameters<typeof createMovementSharing>[0], 'observe'>): {
+    stop: () => Promise<void>;
+    recover: () => Promise<void>;
+    start(id: string): Promise<void>;
+};

package/dist/motion.js

@@ -0,0 +1,45 @@
+import { AppState } from 'react-native';
+import { DeviceMotion } from 'expo-sensors';
+import { createMovementSharing, classifyMotion } from '@robono/location';
+/** Explicitly start after the person enables movement sharing. Raw readings stay
+ * on the device. Foreground only: stale/missing readings must display unavailable. */
+export async function observeDeviceMovement(options) {
+    if (!await DeviceMotion.isAvailableAsync())
+        throw Error('Movement sensors are unavailable on this device.');
+    if (!(await DeviceMotion.requestPermissionsAsync()).granted)
+        throw Error('Movement access was not granted.');
+    let stopped = false, samples = [], subscription, last = 0;
+    const pause = () => { subscription?.remove(); subscription = undefined; samples = []; last = 0; };
+    const start = () => {
+        if (stopped || AppState.currentState !== 'active' || subscription)
+            return;
+        DeviceMotion.setUpdateInterval(100);
+        subscription = DeviceMotion.addListener(value => {
+            if (!value.acceleration || !value.rotationRate)
+                return;
+            const now = Date.now(), a = value.acceleration, r = value.rotationRate;
+            samples.push({ timestampMs: now, acceleration: { x: a.x, y: a.y, z: a.z }, rotationRate: { x: r.beta, y: r.gamma, z: r.alpha } });
+            samples = samples.filter(s => now - s.timestampMs <= 5000).slice(-100);
+            if (samples.length >= 30 && now - last >= 5000) {
+                last = now;
+                try {
+                    options.onReading(classifyMotion(samples));
+                }
+                catch (e) {
+                    options.onError?.(e instanceof Error ? e : Error(String(e)));
+                }
+            }
+        });
+    };
+    const state = AppState.addEventListener('change', value => { pause(); if (value === 'active')
+        start();
+    else
+        options.onReading(classifyMotion([])); });
+    start();
+    return { stop() { stopped = true; pause(); state.remove(); } };
+}
+/** Ready-to-use publisher with explicit consent and durable stop recovery. */
+export { finishPendingMovementStop } from '@robono/location';
+export function createExpoMovementSharing(options) {
+    return createMovementSharing({ ...options, observe: observeDeviceMovement });
+}