@mentra/engine 0.1.0-beta.0

package/build/services/NavigationService.d.ts

@@ -0,0 +1,254 @@
+/**
+ * NavigationService
+ *
+ * Thin singleton wrapper around the native Google Navigation SDK exposed
+ * by the `crust` Expo module.
+ *
+ * Mini apps will eventually subscribe through the mini app SDK, which
+ * routes via LocalMiniappRuntime and ultimately calls into here. For now,
+ * this is also called directly by the developer-settings test button.
+ *
+ * Works on both Android and iOS via the native GoogleNavigation SDK.
+ */
+export type NavManeuver = {
+    kind: "maneuver";
+    /**
+     * Categorical type of the upcoming maneuver. One of: STRAIGHT,
+     * SLIGHT_LEFT, SLIGHT_RIGHT, TURN_LEFT, TURN_RIGHT, SHARP_LEFT,
+     * SHARP_RIGHT, U_TURN, ARRIVE.
+     */
+    maneuverType: string;
+    distanceMeters: number;
+    /** Road the user is currently on. Null if the SDK didn't supply one. */
+    fromRoad?: string | null;
+    /** Road the user will be on after the maneuver. Null if the SDK didn't supply one. */
+    toRoad?: string | null;
+    distanceToDestinationMeters?: number;
+    timeToDestinationSeconds?: number;
+    currentSpeedMps?: number | null;
+    speedLimitMps?: number | null;
+    routeHeadingDeg?: number | null;
+};
+export type NavOffRoute = {
+    kind: "off_route";
+    offRouteDistanceMeters: number;
+};
+export type NavRerouting = {
+    kind: "rerouting";
+};
+export type NavArrived = {
+    kind: "arrived";
+};
+export type NavError = {
+    kind: "error";
+    message: string;
+};
+export type NavUpdate = NavManeuver | NavOffRoute | NavRerouting | NavArrived | NavError;
+export type NavListener = (update: NavUpdate) => void;
+export type NavLocation = {
+    lat: number;
+    lng: number;
+    accuracy: number | null;
+    timestamp: number;
+};
+export type NavLocationListener = (loc: NavLocation) => void;
+export type NavRouteStep = {
+    lat: number;
+    lng: number;
+    routeIndex: number;
+    road: string | null;
+    maneuver: string;
+    distanceMeters: number;
+};
+export type NavRoute = {
+    points: Array<{
+        lat: number;
+        lng: number;
+    }>;
+    steps?: NavRouteStep[];
+};
+export type NavRouteListener = (route: NavRoute) => void;
+export type NavState = "idle" | "navigating" | "rerouting" | "arrived";
+/**
+ * Snapshot of the active trip — fed to miniapps that open mid-trip via
+ * `navigation.getState()`. Mirrors the SDK's NavState shape closely; the
+ * runtime keeps it strictly in sync as nav events arrive.
+ */
+export type NavTripSnapshot = {
+    active: boolean;
+    mode?: string;
+    stops?: Array<{
+        lat: number;
+        lng: number;
+    }>;
+    currentStopIndex?: number;
+    route?: NavRoute;
+    maneuver?: NavManeuver;
+    distanceToDestinationMeters?: number;
+    timeToDestinationSeconds?: number;
+    currentSpeedMps?: number | null;
+    speedLimitMps?: number | null;
+};
+declare class NavigationService {
+    private static instance;
+    private listeners;
+    private locationListeners;
+    private routeListeners;
+    private subs;
+    private state;
+    /** Last emitted route — replayed to late subscribers so they get the
+     *  current geometry immediately. */
+    private lastRoute;
+    /** Last maneuver event observed — used to hydrate getState() on mid-trip mount. */
+    private lastManeuver;
+    /** Trip configuration captured at start(), surfaced via getState(). */
+    private tripStops;
+    private tripMode;
+    private constructor();
+    static getInstance(): NavigationService;
+    getState(): NavState;
+    addListener(listener: NavListener): () => void;
+    /**
+     * Subscribe to the Google Nav SDK's road-snapped location stream. Only
+     * fires while a nav session is active. Returns an unsubscribe fn.
+     */
+    addLocationListener(listener: NavLocationListener): () => void;
+    /**
+     * Subscribe to the active route's polyline. Fires once per route build
+     * (initial + after every reroute). Late subscribers get the current
+     * route replayed on subscribe so the UI can render immediately.
+     */
+    addRouteListener(listener: NavRouteListener): () => void;
+    private noListeners;
+    start(coords: {
+        lat: number;
+        lng: number;
+    }, options?: {
+        simulate?: boolean;
+        speedMultiplier?: number;
+        stops?: Array<{
+            lat: number;
+            lng: number;
+        }>;
+        mode?: string;
+        avoid?: {
+            highways?: boolean;
+            tolls?: boolean;
+            ferries?: boolean;
+        };
+        missedTurnRerouteMeters?: number;
+    }): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    /**
+     * Snapshot of the active trip for `navigation.getState()`. Returns null
+     * when no trip is running. The snapshot is built from in-memory state
+     * fed by the existing native event stream — no extra IPC.
+     */
+    getSnapshot(): NavTripSnapshot | null;
+    stop(): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    /**
+     * Trigger the Google Nav SDK Terms & Conditions dialog if the user
+     * hasn't accepted yet. Resolves immediately when acceptance is already
+     * on file, so it's safe (and intended) to call eagerly on mount.
+     */
+    requestPermission(): Promise<{
+        ok: boolean;
+        accepted: boolean;
+        error?: string;
+    }>;
+    resetPermission(): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    /**
+     * Dev-only: nudge the simulator off-route to trigger an actual reroute
+     * from the Nav SDK. Useful for verifying the rerouting pipeline (UI
+     * flips to "Rebuilding route…", route polyline updates, glasses display
+     * mirrors the new path). No-op on iOS or with real GPS fixes.
+     */
+    simulateDeviation(offsetMeters?: number): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    /**
+     * Dev toggle: lock simulated locations onto the wrong sidewalk
+     * (perpendicular-right of the route bearing by ~8m). Used to verify
+     * the SDK's along-path pivot trigger fires even when the user never
+     * comes within the 7m radius of a pivot point. Android-only today; iOS
+     * is a no-op stub.
+     */
+    setWrongSidewalkOffset(enabled: boolean): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    /**
+     * Dev toggle: take over from the Google simulator and walk the user
+     * along a modified polyline that skips crossing micro-steps. Lets us
+     * reproduce the wrong-sidewalk-then-missed-the-turn scenario for
+     * pivot trigger testing. Android-only today; iOS is a no-op stub.
+     */
+    setSkipCrossings(enabled: boolean): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    /**
+     * @deprecated Route computation moved to the v2 cloud maps service
+     * (cloud.runtime.maps.directions), which holds the provider token
+     * server-side and caches results. The miniapp bridge now routes
+     * NAVIGATION_COMPUTE_ROUTE to NavigationHandlers -> cloud.maps; this direct
+     * Mapbox path is no longer reached from miniapps. Kept only as reference /
+     * for any non-bridge caller; do not add new callers.
+     *
+     * Compute one or more routes without starting a trip. Implemented by
+     * calling Mapbox's Directions API (REST) so we don't disturb the active
+     * Navigator. Returns `{ok: false}` plus an error string when the engine
+     * can't produce a route — mirrors the SDK's ComputeRouteResult shape so
+     * the host can pass it back to miniapps unchanged.
+     */
+    computeRoute(payload: Record<string, unknown>): Promise<{
+        ok: boolean;
+        error?: string;
+        routes?: Array<{
+            points: Array<{
+                lat: number;
+                lng: number;
+            }>;
+            totalDistanceMeters: number;
+            totalDurationSeconds: number;
+            summary?: string;
+        }>;
+    }>;
+    /**
+     * @deprecated Reverse geocoding moved to the v2 cloud maps service
+     * (cloud.runtime.maps.reverseGeocode). The miniapp bridge now routes
+     * NAVIGATION_REVERSE_GEOCODE to NavigationHandlers -> cloud.maps; this direct
+     * Mapbox path is no longer reached from miniapps. Kept only as reference; do
+     * not add new callers.
+     *
+     * Reverse-geocode a coordinate into a short road/route name via
+     * Mapbox's Geocoding REST API. Backs the SDK pivot engine's
+     * last-resort fallback when a Routes-API instruction didn't carry a
+     * parseable road. Returns `{ok: true, road: null}` when the
+     * coordinate is genuinely off-grid (mid-park, water) — that's a
+     * successful query with no road component, distinct from a failure.
+     */
+    reverseGeocodeRoad(coord: {
+        lat: number;
+        lng: number;
+    }): Promise<{
+        ok: boolean;
+        road?: string | null;
+        error?: string;
+    }>;
+    private attachNativeSubs;
+    private detachNativeSubs;
+    private fanout;
+}
+declare const navigationService: NavigationService;
+export default navigationService;
+//# sourceMappingURL=NavigationService.d.ts.map

package/build/services/NavigationService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NavigationService.d.ts","sourceRoot":"","sources":["../../src/services/NavigationService.ts"],"names":[],"mappings":"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"}