@mentra/miniapp 0.3.0-beta.0

package/dist/modules/phone.js

@@ -0,0 +1,110 @@
+/**
+ * @fileoverview PhoneModule — phone device-state events.
+ *
+ * Mirrors cloud SDK v3's PhoneManager structure. Sub-namespaced by concern:
+ *
+ *   session.phone.notifications.{on, hasPermission, stop}
+ *   session.phone.calendar.{listEvents, hasPermission}
+ *   session.phone.onBattery(...)                          // stays flat
+ *
+ * Imperative phone-OS calls (share, openUrl, copyToClipboard, download) live
+ * on `session.system` — different shape (one-shot calls vs. event subs) so
+ * we don't conflate them.
+ *
+ * `phone.notifications.onDismissed` is Android-only. iOS doesn't expose
+ * notification-dismiss callbacks to apps (Apple privacy restriction);
+ * subscribing on iOS is a no-op even though the API is present.
+ */
+import { MiniappRequestType, MiniappStreamType } from "../protocol";
+class TrackedSubs {
+    constructor() {
+        this.unsubs = new Set();
+    }
+    track(unsub) {
+        this.unsubs.add(unsub);
+        return () => {
+            this.unsubs.delete(unsub);
+            unsub();
+        };
+    }
+    stop() {
+        for (const u of this.unsubs) {
+            try {
+                u();
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        this.unsubs.clear();
+    }
+}
+export class PhoneNotificationsModule extends TrackedSubs {
+    constructor(session) {
+        super();
+        this.session = session;
+    }
+    on(handler) {
+        return this.track(this.session._subscribe(MiniappStreamType.PHONE_NOTIFICATION, handler));
+    }
+    /**
+     * Subscribe to dismiss events for phone notifications. Fires when the user
+     * dismisses (swipes away or clears) a notification.
+     *
+     * **Android only.** iOS does not expose dismiss callbacks to apps (Apple
+     * privacy restriction); subscribing on iOS succeeds but no events ever
+     * fire. The matching `notifications.on()` post-event still works on both
+     * platforms.
+     */
+    onDismissed(handler) {
+        return this.track(this.session._subscribe(MiniappStreamType.PHONE_NOTIFICATION_DISMISSED, handler));
+    }
+    /** True iff `READ_NOTIFICATIONS` is declared in the miniapp's manifest. */
+    get hasPermission() {
+        return this.session._hasManifestPermission("READ_NOTIFICATIONS");
+    }
+}
+export class PhoneCalendarModule {
+    constructor(session) {
+        this.session = session;
+    }
+    /**
+     * Read calendar events in a bounded window. CALENDAR must be declared in
+     * miniapp.json and granted before the miniapp opens.
+     */
+    listEvents(options) {
+        const startsAt = normalizeCalendarDate(options?.startsAt, "startsAt");
+        const endsAt = normalizeCalendarDate(options?.endsAt, "endsAt");
+        return this.session.sendRequest({
+            type: MiniappRequestType.CALENDAR_LIST_EVENTS,
+            startsAt,
+            endsAt,
+            ...(options.limit === undefined ? {} : { limit: options.limit }),
+        });
+    }
+    /** True iff `CALENDAR` is declared in the miniapp's manifest. */
+    get hasPermission() {
+        return this.session._hasManifestPermission("CALENDAR");
+    }
+}
+function normalizeCalendarDate(value, field) {
+    const date = value instanceof Date ? value : new Date(value ?? "");
+    if (Number.isNaN(date.getTime()))
+        throw new TypeError(`${field} must be a valid Date or ISO 8601 string`);
+    return date.toISOString();
+}
+export class PhoneModule {
+    constructor(session) {
+        this.session = session;
+        this.notifications = new PhoneNotificationsModule(session);
+        this.calendar = new PhoneCalendarModule(session);
+    }
+    /**
+     * Phone battery events. Stays flat (not sub-namespaced) — single event,
+     * no extra surface.
+     */
+    onBattery(handler) {
+        return this.session._subscribe(MiniappStreamType.PHONE_BATTERY, handler);
+    }
+}
+//# sourceMappingURL=phone.js.map

package/dist/modules/phone.js.map

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

package/dist/modules/pivots/engine.d.ts

@@ -0,0 +1,169 @@
+/**
+ * @fileoverview Pivot engine — internal to NavigationModule.
+ *
+ * Owns the per-trip pivot list and the cursor that walks it as GPS
+ * ticks come in. Public consumers of the SDK never touch this class
+ * directly — they go through `navigation.onPivot()` / `getPivots()` /
+ * `getActivePivot()` / `getUpcomingPivot()`.
+ *
+ * Lifecycle:
+ *   - `reset()` on `navigation.start()`. Clears pivot list, cursor,
+ *     all subscribers stay attached.
+ *   - `setRoute(route)` on the first `onRoute` after start, and on
+ *     every subsequent reroute. Rebuilds the pivot list from
+ *     scratch.
+ *   - `onLocationUpdate(coords)` on every GPS fix. Computes which
+ *     events to fire and emits them to subscribers.
+ *   - `reset()` on `stop()` / `arrived`.
+ *
+ * The engine doesn't subscribe to GPS itself — `NavigationModule`
+ * owns that, calling `onLocationUpdate(coords)` from its own GPS
+ * subscription. Keeps this class pure-state with no side effects.
+ */
+import type { LatLng, ManeuverKind, NavRoute, Pivot, PivotEvent, PivotOptions, TravelMode } from "../navigation";
+import { bearingDeg, haversineMeters, signedAngleDiff } from "./geometry";
+type Subscriber = (event: PivotEvent) => void;
+export declare class PivotEngine {
+    private opts;
+    private pivots;
+    private states;
+    /** Index of the next pivot we expect the user to encounter. */
+    private cursor;
+    /** Pivot currently between `entered` and `exited`, or null. */
+    private activePivotIndex;
+    /**
+     * Latest route polyline + its cumulative-distance array. Retained
+     * after `setRoute()` so `onLocationUpdate` can project the user onto
+     * the path and compare along-path distance to each pivot's
+     * `distanceAlongRouteMeters`. This is what makes a pedestrian on the
+     * wrong sidewalk still trigger the upcoming turn — straight-line
+     * distance to the pivot point would miss it.
+     */
+    private points;
+    private cumulative;
+    /**
+     * Async road-name resolver injected by NavigationModule. Backs the
+     * engine's last-resort fallback: when a pivot's `fromRoad` or
+     * `toRoad` is null after Routes-API instruction parsing, the
+     * engine samples a coordinate ~SAMPLE_OFFSET_M behind/ahead along
+     * the polyline and asks the host to reverse-geocode it. Patched
+     * onto the pivot in place when the response lands. Null when no
+     * resolver is wired — the engine simply leaves the field null.
+     */
+    private roadNameResolver;
+    /**
+     * Generation counter bumped on every route rebuild. Geocode
+     * responses from a stale route are discarded by comparing the
+     * generation captured at request time against the current value.
+     * Without this, a slow geocode reply from a previous route can
+     * stamp a fresh route's pivot with the wrong road name.
+     */
+    private routeGeneration;
+    private subscribers;
+    constructor(mode: TravelMode, opts: PivotOptions | undefined);
+    /** Replace the trip-level options. Used if `start()` is called
+     *  with new options without a full reset. */
+    updateOptions(mode: TravelMode, opts: PivotOptions | undefined): void;
+    /**
+     * Install the host-backed reverse-geocode resolver. NavigationModule
+     * calls this once after constructing the engine, wiring through to
+     * the host's Geocoding REST adapter. When unset, the engine simply
+     * leaves null road names in place — geocoding is a best-effort
+     * enhancement, not a requirement.
+     */
+    setRoadNameResolver(resolver: ((coord: LatLng) => Promise<string | null>) | null): void;
+    /**
+     * Clear all pivot state. Pivots = []. Cursor reset. Active pivot
+     * cleared. Subscribers stay attached so the next `setRoute` can
+     * fire events.
+     */
+    reset(): void;
+    /**
+     * Rebuild the pivot list from a Routes-API computed step list. This
+     * is the high-accuracy path used during live trips: `instruction`
+     * strings on each step name the road being entered unambiguously
+     * ("Turn left onto Octavia Blvd"), and the explicit `endLat/endLng`
+     * gives us the exact corner location without polyline-walking math.
+     *
+     * NavigationModule calls this once per route lifecycle — at trip
+     * start (after firing NAVIGATION_COMPUTE_ROUTE), and again on every
+     * reroute. The cursor + state machinery (approaching / entered /
+     * exited) is identical to `setRoute` — only the pivot construction
+     * differs.
+     *
+     * If the computed-step list is empty or no pivots survive the
+     * filters in `extractPivotsFromComputedSteps`, this falls back to
+     * `setRoute(route)` so the geometry-derived pivots are still
+     * available. That keeps the engine working on platforms that don't
+     * yet have Routes API plumbing.
+     */
+    setRouteFromComputedSteps(route: NavRoute, computedSteps: Array<{
+        lat: number;
+        lng: number;
+        endLat: number;
+        endLng: number;
+        distanceMeters: number;
+        maneuver?: ManeuverKind;
+        instruction?: string;
+        /** Host-resolved road name (Phase 1). Optional for backward
+         *  compat with callers that only supply `instruction`. */
+        road?: string | null;
+    }> | undefined): void;
+    /**
+     * Rebuild the pivot list from a fresh route. Called on every
+     * `onRoute` event. Any prior pivot list is discarded; cursor
+     * resets to 0.
+     */
+    setRoute(route: NavRoute, _userPosition: LatLng | null): void;
+    /**
+     * For every pivot in the current list that has a missing road
+     * label, fill it in. Two-stage strategy:
+     *
+     *   1. **Inherit from neighbors.** Adjacent pivots on the route
+     *      share roads by definition: between pivot N and pivot N+1
+     *      there are no turns, so pivot N's toRoad == pivot N+1's
+     *      fromRoad. If one side is known, copy it. This is free
+     *      (no network) and avoids the geocode-mismatch class of bug
+     *      where two different sample points return two different
+     *      strings for what is conceptually the same road.
+     *
+     *   2. **Reverse-geocode the remainder.** For any field still
+     *      null after inheritance, sample a coordinate ~18m behind
+     *      (fromRoad) or ahead (toRoad) along the polyline and ask
+     *      the host to reverse-geocode it. Best-effort — failures
+     *      leave the field null.
+     *
+     * The `generation` guard rejects geocode replies arriving after
+     * a fresh route rebuild superseded them.
+     */
+    private _resolveMissingRoadNames;
+    /**
+     * Drive the cursor with a new GPS fix. Fires `approaching` /
+     * `entered` / `exited` as thresholds are crossed.
+     *
+     * Two distance metrics are used:
+     *
+     *   1. **Along-path distance** — the user's projected position on the
+     *      route polyline gives `userAlong`; each pivot's
+     *      `distanceAlongRouteMeters` is its `pivotAlong`. The signed
+     *      delta `pivotAlong - userAlong` says how far the user still has
+     *      to walk to reach the pivot's perpendicular line (positive =
+     *      ahead, negative = past). This is the primary metric for
+     *      pedestrians, because it doesn't care which sidewalk they're on
+     *      — only that they've crossed the pivot's latitude/longitude
+     *      band.
+     *
+     *   2. **Straight-line distance** — fallback when the user is more
+     *      than ON_ROUTE_PERP_TOLERANCE_M from the polyline (they've
+     *      really wandered off, not just onto the wrong sidewalk). Keeps
+     *      the legacy behavior for that case.
+     */
+    onLocationUpdate(coords: LatLng): void;
+    subscribe(fn: Subscriber): () => void;
+    getPivots(): Pivot[];
+    getActivePivot(): Pivot | null;
+    getUpcomingPivot(): Pivot | null;
+    private emit;
+}
+export { bearingDeg, haversineMeters, signedAngleDiff };
+//# sourceMappingURL=engine.d.ts.map

package/dist/modules/pivots/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../src/modules/pivots/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAW,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAC,MAAM,eAAe,CAAA;AACvH,OAAO,EACL,UAAU,EAGV,eAAe,EACf,eAAe,EAEhB,MAAM,YAAY,CAAA;AAkDnB,KAAK,UAAU,GAAG,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAA;AAY7C,qBAAa,WAAW;IACtB,OAAO,CAAC,IAAI,CAAiB;IAC7B,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,MAAM,CAAmB;IACjC,+DAA+D;IAC/D,OAAO,CAAC,MAAM,CAAI;IAClB,+DAA+D;IAC/D,OAAO,CAAC,gBAAgB,CAAsB;IAC9C;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,UAAU,CAAe;IACjC;;;;;;;;OAQG;IACH,OAAO,CAAC,gBAAgB,CAA2D;IACnF;;;;;;OAMG;IACH,OAAO,CAAC,eAAe,CAAI;IAE3B,OAAO,CAAC,WAAW,CAAwB;gBAE/B,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,YAAY,GAAG,SAAS;IAI5D;iDAC6C;IAC7C,aAAa,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,YAAY,GAAG,SAAS,GAAG,IAAI;IAQrE;;;;;;OAMG;IACH,mBAAmB,CAAC,QAAQ,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC,GAAG,IAAI,GAAG,IAAI;IAIvF;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAeb;;;;;;;;;;;;;;;;;;OAkBG;IACH,yBAAyB,CACvB,KAAK,EAAE,QAAQ,EACf,aAAa,EACT,KAAK,CAAC;QACJ,GAAG,EAAE,MAAM,CAAA;QACX,GAAG,EAAE,MAAM,CAAA;QACX,MAAM,EAAE,MAAM,CAAA;QACd,MAAM,EAAE,MAAM,CAAA;QACd,cAAc,EAAE,MAAM,CAAA;QACtB,QAAQ,CAAC,EAAE,YAAY,CAAA;QACvB,WAAW,CAAC,EAAE,MAAM,CAAA;QACpB;kEAC0D;QAC1D,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KACrB,CAAC,GACF,SAAS,GACZ,IAAI;IA2FP;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IA0E7D;;;;;;;;;;;;;;;;;;;;OAoBG;YACW,wBAAwB;IAiGtC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IA2FtC,SAAS,CAAC,EAAE,EAAE,UAAU,GAAG,MAAM,IAAI;IAOrC,SAAS,IAAI,KAAK,EAAE;IAIpB,cAAc,IAAI,KAAK,GAAG,IAAI;IAK9B,gBAAgB,IAAI,KAAK,GAAG,IAAI;IAUhC,OAAO,CAAC,IAAI;CASb;AAuND,OAAO,EAAC,UAAU,EAAE,eAAe,EAAE,eAAe,EAAC,CAAA"}