@mentra/miniapp 0.3.0-dev.0

package/dist/modules/navigation.js

@@ -0,0 +1,386 @@
+/**
+ * NavigationModule — turn-by-turn navigation for miniapps. A thin pass-through over the bridge;
+ * the phone-side daemon owns the trip lifecycle.
+ *
+ * Works on iOS and Android (both back it with the Mapbox Navigation SDK). Every Promise
+ * resolves with an `{ok, error?}` shape; nothing throws, so check `result.ok`.
+ */
+import { MiniappRequestType, MiniappStreamType } from "../protocol";
+import { PivotEngine } from "./pivots/engine";
+export class NavigationModule {
+    constructor(session) {
+        this.session = session;
+        this._pivots = new PivotEngine("walking", undefined);
+        /** Subscriptions owned while a trip is active. Released on stop(). */
+        this._tripUnsubs = [];
+        /** Trip params captured at start() so reroutes can re-issue computeRoute. */
+        this._tripStops = null;
+        this._tripMode = "walking";
+        this._tripAvoid = undefined;
+        /** Bumps per request so a stale reply from before a newer reroute is ignored. */
+        this._computeRouteSeq = 0;
+        /** Latest GPS position, used as the origin for reroute computeRoute calls. */
+        this._lastUserPosition = null;
+        // Reverse-geocode fallback for pivots whose instruction carried no road name.
+        this._pivots.setRoadNameResolver(async (coord) => {
+            try {
+                const result = await this.reverseGeocodeRoad(coord);
+                if (!result.ok)
+                    return null;
+                return result.road ?? null;
+            }
+            catch {
+                return null;
+            }
+        });
+    }
+    /** True iff `LOCATION` is declared in the miniapp's manifest. */
+    get hasPermission() {
+        return this.session._hasManifestPermission("LOCATION");
+    }
+    /**
+     * Trigger the Nav SDK Terms & Conditions dialog up front, before the user hits "start".
+     * Idempotent. Resolves `{ok: false, accepted: false, error}` when LOCATION isn't declared.
+     */
+    requestPermission() {
+        if (!this.hasPermission) {
+            return Promise.resolve({
+                ok: false,
+                accepted: false,
+                error: "LOCATION permission not declared in miniapp.json (required for navigation.requestPermission).",
+            });
+        }
+        return this.session.sendRequest({
+            type: MiniappRequestType.NAVIGATION_REQUEST_PERMISSION,
+        });
+    }
+    /**
+     * Start a navigation session. Pass `{lat, lng}` or `{stops: [...]}`. `{ok: true}` means the
+     * daemon accepted the request, not that a route was built — listen via `onUpdate(...)`.
+     */
+    async start(opts) {
+        if (!this.hasPermission) {
+            return {
+                ok: false,
+                error: "LOCATION permission not declared in miniapp.json (required for navigation.start).",
+            };
+        }
+        const stops = normalizeStops(opts);
+        const mode = opts.mode ?? "driving";
+        this._tripStops = stops.length > 0 ? stops : null;
+        this._tripMode = mode;
+        this._tripAvoid = opts.avoid;
+        // Subscribes the engine to route + location streams. Idempotent — detaches any prior trip first.
+        this._attachPivotTrackingForTrip(mode, opts.pivots);
+        // Every failure return below must release the subscriptions attached just above.
+        const failStart = (error) => {
+            this._detachPivotTracking();
+            return { ok: false, error };
+        };
+        if (stops.length === 0) {
+            return failStart("navigation.start: no stops");
+        }
+        // Origin: live position if known, else a one-shot host fetch. (stops[0] would be the
+        // destination for a single-stop trip — a degenerate origin.)
+        let origin = this._lastUserPosition;
+        if (!origin) {
+            try {
+                const fix = await this.session.location.getOnce();
+                origin = { lat: fix.lat, lng: fix.lng };
+                this._lastUserPosition = origin;
+            }
+            catch (err) {
+                return failStart(`navigation.start: no GPS fix (${err instanceof Error ? err.message : String(err)})`);
+            }
+        }
+        // Source-of-truth route is the host's Routes REST call. If it fails, abort (no native fallback).
+        const restResult = await this.computeRoute({ origin, stops, mode, avoid: opts.avoid });
+        if (!restResult.ok || !restResult.routes || restResult.routes.length === 0) {
+            return failStart(restResult.error ?? "computeRoute failed");
+        }
+        const restRoute = restResult.routes[0];
+        const nativeResult = await this.session.sendRequest({
+            type: MiniappRequestType.NAVIGATION_START,
+            // Keep lat/lng on the wire for hosts not yet upgraded to read `stops`.
+            lat: stops[0]?.lat,
+            lng: stops[0]?.lng,
+            stops,
+            mode,
+            avoid: opts.avoid,
+            simulate: opts.simulate ?? false,
+            speedMultiplier: opts.speedMultiplier ?? 1,
+            missedTurnRerouteMeters: opts.missedTurnRerouteMeters,
+        });
+        if (!nativeResult.ok) {
+            this._detachPivotTracking();
+            return nativeResult;
+        }
+        // Dispatch the REST route through the native route channel so subscribers see step roads now.
+        const syntheticRoute = buildNavRouteFromComputed(restRoute);
+        this.session.events._forwardEvent(MiniappStreamType.NAVIGATION_ROUTE, syntheticRoute);
+        return nativeResult;
+    }
+    /** Stop the active session (no-op if none). Fire-and-forget; also detaches pivot tracking. */
+    stop() {
+        this._detachPivotTracking();
+        this.session.sendOneShot({ type: MiniappRequestType.NAVIGATION_STOP });
+    }
+    /** Dev-only simulator helpers for testing trips. `deviate` works on both platforms;
+     *  a few helpers are Android-only and return `{ok: false}` on iOS. */
+    get dev() {
+        return {
+            /** Nudge the simulator off-route to trigger a reroute. Default 20m. */
+            deviate: (offsetMeters = 20) => {
+                this.session.sendOneShot({ type: MiniappRequestType.NAVIGATION_DEVIATE, offsetMeters });
+            },
+            /** Lock simulated locations to the wrong sidewalk to test along-path pivot triggers. */
+            setWrongSidewalkOffset: (enabled) => {
+                this.session.sendOneShot({ type: MiniappRequestType.NAVIGATION_SET_WRONG_SIDEWALK, enabled });
+            },
+            /** Walk a polyline with crossing micro-steps removed, for missed-turn testing. */
+            setSkipCrossings: (enabled) => {
+                this.session.sendOneShot({ type: MiniappRequestType.NAVIGATION_SET_SKIP_CROSSINGS, enabled });
+            },
+        };
+    }
+    /** Subscribe to live trip events (maneuver / off_route / rerouting / arrived / error). */
+    onUpdate(handler) {
+        return this.session._subscribe(MiniappStreamType.NAVIGATION_UPDATE, handler);
+    }
+    /** Subscribe to the route polyline. Fires once per route build (initial + reroute), full path. */
+    onRoute(handler) {
+        return this.session._subscribe(MiniappStreamType.NAVIGATION_ROUTE, handler);
+    }
+    /** Snapshot of the active trip, or `null` when none is running. Use on mount to hydrate state. */
+    async getState() {
+        const result = await this.session.sendRequest({
+            type: MiniappRequestType.NAVIGATION_GET_STATE,
+        });
+        return result.ok ? (result.state ?? null) : null;
+    }
+    /** Compute a route without starting a trip. Primary route first, alternates after. */
+    computeRoute(opts) {
+        if (!this.hasPermission) {
+            return Promise.resolve({
+                ok: false,
+                error: "LOCATION permission not declared in miniapp.json (required for navigation.computeRoute).",
+            });
+        }
+        return this.session.sendRequest({
+            type: MiniappRequestType.NAVIGATION_COMPUTE_ROUTE,
+            origin: opts.origin,
+            stops: opts.stops,
+            mode: opts.mode ?? "driving",
+            avoid: opts.avoid,
+            alternatives: opts.alternatives ?? 1,
+        });
+    }
+    /**
+     * Reverse-geocode a coordinate into a short road name (`road`) and a full
+     * formatted street address (`address`, e.g. "369 Hayes Street, San Francisco,
+     * California 94102"). `road` backs the pivot engine's fallback; `address`
+     * backs UI labels for dropped pins / POI taps. Each is null when none of that
+     * kind is found near the coordinate; `ok: false` is an actual failure.
+     *
+     * Resolved entirely in the v2 cloud maps service (provider-abstracted, Mapbox
+     * today) via the host bridge — the miniapp never holds a maps token or calls a
+     * provider directly.
+     */
+    reverseGeocodeRoad(coord) {
+        if (!this.hasPermission) {
+            return Promise.resolve({
+                ok: false,
+                error: "LOCATION permission not declared in miniapp.json (required for reverseGeocodeRoad).",
+            });
+        }
+        return this.session.sendRequest({
+            type: MiniappRequestType.NAVIGATION_REVERSE_GEOCODE,
+            lat: coord.lat,
+            lng: coord.lng,
+        });
+    }
+    /**
+     * Type-ahead place search. Returns lightweight suggestions for `query`,
+     * optionally biased toward `near`. Resolved in the v2 cloud maps service
+     * (Mapbox Search Box today) via the host bridge — no maps token in the
+     * miniapp. `sessionToken` should be a stable per-search-box-opening string,
+     * reused on the following `placeDetails` call, then rotated after a pick, so
+     * the keystrokes + the final retrieve bill as one search session.
+     *
+     * Does NOT require LOCATION permission — it's a text search; `near` is only a
+     * ranking bias. Resolves `{ok, suggestions}`; `ok: false` is an actual failure.
+     */
+    placeAutocomplete(opts) {
+        return this.session.sendRequest({
+            type: MiniappRequestType.NAVIGATION_PLACE_AUTOCOMPLETE,
+            query: opts.query,
+            near: opts.near ?? null,
+            sessionToken: opts.sessionToken,
+        });
+    }
+    /**
+     * Resolve a suggestion's `placeId` (from `placeAutocomplete`) to a full place
+     * with coordinates. Pass the SAME `sessionToken` used for the autocomplete so
+     * the provider closes the billing session. Resolved in the v2 cloud maps
+     * service via the host bridge. Resolves `{ok, place}`; `ok: false` is a
+     * failure (including an unresolvable id).
+     */
+    placeDetails(opts) {
+        return this.session.sendRequest({
+            type: MiniappRequestType.NAVIGATION_PLACE_DETAILS,
+            placeId: opts.placeId,
+            sessionToken: opts.sessionToken,
+        });
+    }
+    // Pivots — real turns along the route, fired as approaching / entered / exited as GPS ticks in.
+    /** Subscribe to pivot events. Each pivot fires once per kind; passed pivots aren't re-evaluated. */
+    onPivot(handler) {
+        return this._pivots.subscribe(handler);
+    }
+    /** Full pivot list for the active route. Empty before the first `onRoute`. */
+    getPivots() {
+        return this._pivots.getPivots();
+    }
+    /** The pivot the user is currently inside (between `entered` and `exited`), or `null`. */
+    getActivePivot() {
+        return this._pivots.getActivePivot();
+    }
+    /** The next pivot ahead, or `null` once every pivot has been passed. */
+    getUpcomingPivot() {
+        return this._pivots.getUpcomingPivot();
+    }
+    _attachPivotTrackingForTrip(mode, opts) {
+        this._detachPivotTracking();
+        this._pivots.reset();
+        this._pivots.updateOptions(mode, opts);
+        // Rebuild pivots on every route. Initial start emits a synthetic onRoute with REST steps (build
+        // directly); a native reroute emits no steps (render geometry pivots, then enrich via REST).
+        this._tripUnsubs.push(this.onRoute((route) => {
+            if (route.steps && route.steps.length > 0) {
+                // NavStep carries only the step start; the engine needs endLat/endLng to anchor the turn.
+                // end of step[i] == start of step[i+1]; the final step uses the last polyline vertex.
+                const tail = route.points[route.points.length - 1];
+                const computedSteps = route.steps.map((s, i) => {
+                    const next = route.steps?.[i + 1];
+                    const endLat = next ? next.lat : (tail?.lat ?? s.lat);
+                    const endLng = next ? next.lng : (tail?.lng ?? s.lng);
+                    return {
+                        lat: s.lat,
+                        lng: s.lng,
+                        endLat,
+                        endLng,
+                        distanceMeters: s.distanceMeters,
+                        maneuver: s.maneuver,
+                        road: s.road ?? undefined,
+                    };
+                });
+                this._pivots.setRouteFromComputedSteps(route, computedSteps);
+                return;
+            }
+            this._pivots.setRoute(route, null);
+            const seq = ++this._computeRouteSeq;
+            this._issueComputeRouteForTrip(route)
+                .then((result) => {
+                if (seq !== this._computeRouteSeq)
+                    return; // superseded by a newer reroute
+                const computedSteps = result?.routes?.[0]?.steps;
+                if (computedSteps && computedSteps.length > 0) {
+                    this._pivots.setRouteFromComputedSteps(route, computedSteps);
+                }
+            })
+                .catch((err) => {
+                console.warn("[NavigationModule] computeRoute for pivots failed:", err);
+            });
+        }));
+        // `arrived` resets the engine. `rerouting` is handled natively by the host, so no action here.
+        this._tripUnsubs.push(this.onUpdate((update) => {
+            if (update.kind === "arrived") {
+                this._pivots.reset();
+                return;
+            }
+        }));
+        // Every fix drives the pivot cursor and records the latest position for reroute origin.
+        this._tripUnsubs.push(this.session.location.onUpdate((loc) => {
+            this._lastUserPosition = { lat: loc.lat, lng: loc.lng };
+            this._pivots.onLocationUpdate({ lat: loc.lat, lng: loc.lng });
+        }));
+    }
+    /** computeRoute for the current trip, using the latest position (or route start) as origin. */
+    async _issueComputeRouteForTrip(route) {
+        if (!this._tripStops || this._tripStops.length === 0)
+            return null;
+        const origin = this._lastUserPosition ?? (route?.points && route.points[0] ? { lat: route.points[0].lat, lng: route.points[0].lng } : null);
+        if (!origin)
+            return null;
+        return this.computeRoute({
+            origin,
+            stops: this._tripStops,
+            mode: this._tripMode,
+            avoid: this._tripAvoid,
+        });
+    }
+    // NOTE: client-side reroute was removed in the Mapbox migration — the host reroutes natively and
+    // pushes the new route through `onRoute`. If a future host doesn't, re-add it in `onUpdate`.
+    _detachPivotTracking() {
+        for (const unsub of this._tripUnsubs) {
+            try {
+                unsub();
+            }
+            catch (err) {
+                console.warn("[NavigationModule] pivot-tracking unsubscribe threw:", err);
+            }
+        }
+        this._tripUnsubs = [];
+        this._pivots.reset();
+        // Bumping the sequence is the real guard against a stale in-flight reply; the rest is tidiness.
+        this._tripStops = null;
+        this._tripAvoid = undefined;
+        this._computeRouteSeq++;
+        this._lastUserPosition = null;
+    }
+}
+/** Normalize the `{lat, lng}` shorthand into a `stops` array. */
+function normalizeStops(opts) {
+    if (opts.stops && opts.stops.length > 0) {
+        return opts.stops;
+    }
+    if (typeof opts.lat === "number" && typeof opts.lng === "number") {
+        return [{ lat: opts.lat, lng: opts.lng }];
+    }
+    return [];
+}
+/**
+ * Convert a REST `ComputedRoute` into the wire `NavRoute` shape. Anchors each step to a polyline
+ * vertex (`routeIndex`) by nearest-point search. Steps with no maneuver default to "STRAIGHT".
+ */
+function buildNavRouteFromComputed(computed) {
+    const points = computed.points ?? [];
+    const steps = (computed.steps ?? []).map((s) => {
+        let routeIndex = 0;
+        let best = Infinity;
+        for (let i = 0; i < points.length; i++) {
+            const dLat = points[i].lat - s.lat;
+            const dLng = points[i].lng - s.lng;
+            const d = dLat * dLat + dLng * dLng;
+            if (d < best) {
+                best = d;
+                routeIndex = i;
+            }
+        }
+        return {
+            lat: s.lat,
+            lng: s.lng,
+            routeIndex,
+            road: s.road ?? null,
+            maneuver: s.maneuver ?? "STRAIGHT",
+            distanceMeters: s.distanceMeters,
+        };
+    });
+    return {
+        points,
+        totalDistanceMeters: computed.totalDistanceMeters,
+        totalDurationSeconds: computed.totalDurationSeconds,
+        steps: steps.length > 0 ? steps : undefined,
+    };
+}
+//# sourceMappingURL=navigation.js.map

package/dist/modules/navigation.js.map

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

package/dist/modules/permissions.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @fileoverview PermissionsModule — manifest-declared permission introspection.
+ *
+ * Mirrors cloud SDK v3's PermissionsManager surface and semantics:
+ *   permissions.has(type)         — synchronous boolean
+ *   permissions.getAll()          — full PermissionRecord
+ *   permissions.onUpdate(handler) — fires on cache change
+ *   permissions.onPermissionError(handler) — typed handler for the existing
+ *                                            PERMISSION_NOT_DECLARED error
+ *
+ * What "permission" means here. Same as v3: this module tracks
+ * **manifest-declared** permissions. `permissions.has("microphone") === true`
+ * means the miniapp's manifest.json declared MICROPHONE — it does NOT mean
+ * the user actually granted the OS permission. To detect OS-grant state,
+ * observe whether your subscriptions actually deliver events.
+ *
+ * OS-level grant state and `request(...)` are deferred to a future round.
+ * Their additions will land additively on this same module — `isGranted(...)`
+ * / `request(...)` alongside the existing `has(...)` / `getAll(...)` —
+ * without renaming today's surface.
+ */
+import { MiniappSession } from "../session";
+import type { PermissionRecord, PermissionType } from "../session";
+import type { UnsubscribeFn } from "./events";
+export interface PermissionErrorEvent {
+    /** The error code. Always PERMISSION_NOT_DECLARED today; reserved for future codes. */
+    code: string;
+    message: string;
+    /** The manifest permission name (UPPER_CASE) that was missing. */
+    permission?: string;
+    /** The subscription / operation that triggered the rejection. */
+    subscription?: string;
+    operation?: string;
+}
+export declare class PermissionsModule {
+    private readonly session;
+    /** Local handlers for onUpdate. Session emitter handles the fan-out. */
+    constructor(session: MiniappSession);
+    /** True iff the named permission is declared in the miniapp's manifest. */
+    has(type: PermissionType): boolean;
+    /** Full record of declared permissions. Fresh shallow copy. */
+    getAll(): PermissionRecord;
+    /**
+     * Subscribe to declared-permission updates. Fires when the cached record
+     * changes — usually on CONNECT_ACK, or when the phone pushes a
+     * PERMISSIONS_UPDATE (e.g. dev miniapp re-scanned with updated manifest).
+     *
+     * Does NOT fire immediately with the current value — call getAll()
+     * separately if you want the seed.
+     */
+    onUpdate(handler: (perms: PermissionRecord) => void): UnsubscribeFn;
+    /**
+     * Subscribe to typed PERMISSION_NOT_DECLARED errors. Sugar over the
+     * existing session "error" event, filtered to the permission-error code.
+     */
+    onPermissionError(handler: (err: PermissionErrorEvent) => void): UnsubscribeFn;
+}
+//# sourceMappingURL=permissions.d.ts.map

package/dist/modules/permissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../../src/modules/permissions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,EAAC,cAAc,EAAC,MAAM,YAAY,CAAA;AACzC,OAAO,KAAK,EAAC,gBAAgB,EAAE,cAAc,EAAC,MAAM,YAAY,CAAA;AAChE,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,UAAU,CAAA;AAE3C,MAAM,WAAW,oBAAoB;IACnC,uFAAuF;IACvF,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,iEAAiE;IACjE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,qBAAa,iBAAiB;IAEhB,OAAO,CAAC,QAAQ,CAAC,OAAO;IADpC,wEAAwE;gBAC3C,OAAO,EAAE,cAAc;IAEpD,2EAA2E;IAC3E,GAAG,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO;IAIlC,+DAA+D;IAC/D,MAAM,IAAI,gBAAgB;IAI1B;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,GAAG,aAAa;IAInE;;;OAGG;IACH,iBAAiB,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,oBAAoB,KAAK,IAAI,GAAG,aAAa;CAc/E"}

package/dist/modules/permissions.js

@@ -0,0 +1,66 @@
+/**
+ * @fileoverview PermissionsModule — manifest-declared permission introspection.
+ *
+ * Mirrors cloud SDK v3's PermissionsManager surface and semantics:
+ *   permissions.has(type)         — synchronous boolean
+ *   permissions.getAll()          — full PermissionRecord
+ *   permissions.onUpdate(handler) — fires on cache change
+ *   permissions.onPermissionError(handler) — typed handler for the existing
+ *                                            PERMISSION_NOT_DECLARED error
+ *
+ * What "permission" means here. Same as v3: this module tracks
+ * **manifest-declared** permissions. `permissions.has("microphone") === true`
+ * means the miniapp's manifest.json declared MICROPHONE — it does NOT mean
+ * the user actually granted the OS permission. To detect OS-grant state,
+ * observe whether your subscriptions actually deliver events.
+ *
+ * OS-level grant state and `request(...)` are deferred to a future round.
+ * Their additions will land additively on this same module — `isGranted(...)`
+ * / `request(...)` alongside the existing `has(...)` / `getAll(...)` —
+ * without renaming today's surface.
+ */
+import { MiniappErrorCode } from "../protocol";
+export class PermissionsModule {
+    /** Local handlers for onUpdate. Session emitter handles the fan-out. */
+    constructor(session) {
+        this.session = session;
+    }
+    /** True iff the named permission is declared in the miniapp's manifest. */
+    has(type) {
+        return this.session._getPermissions()[type] === true;
+    }
+    /** Full record of declared permissions. Fresh shallow copy. */
+    getAll() {
+        return this.session._getPermissions();
+    }
+    /**
+     * Subscribe to declared-permission updates. Fires when the cached record
+     * changes — usually on CONNECT_ACK, or when the phone pushes a
+     * PERMISSIONS_UPDATE (e.g. dev miniapp re-scanned with updated manifest).
+     *
+     * Does NOT fire immediately with the current value — call getAll()
+     * separately if you want the seed.
+     */
+    onUpdate(handler) {
+        return this.session.on("permissions", handler);
+    }
+    /**
+     * Subscribe to typed PERMISSION_NOT_DECLARED errors. Sugar over the
+     * existing session "error" event, filtered to the permission-error code.
+     */
+    onPermissionError(handler) {
+        return this.session.on("error", (e) => {
+            const maybe = e;
+            if (maybe?.code === MiniappErrorCode.PERMISSION_NOT_DECLARED) {
+                handler({
+                    code: String(maybe.code),
+                    message: String(maybe.message ?? ""),
+                    permission: maybe.permission,
+                    subscription: maybe.subscription,
+                    operation: maybe.operation,
+                });
+            }
+        });
+    }
+}
+//# sourceMappingURL=permissions.js.map

package/dist/modules/permissions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.js","sourceRoot":"","sources":["../../src/modules/permissions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAC,gBAAgB,EAAC,MAAM,aAAa,CAAA;AAiB5C,MAAM,OAAO,iBAAiB;IAC5B,wEAAwE;IACxE,YAA6B,OAAuB;QAAvB,YAAO,GAAP,OAAO,CAAgB;IAAG,CAAC;IAExD,2EAA2E;IAC3E,GAAG,CAAC,IAAoB;QACtB,OAAO,IAAI,CAAC,OAAO,CAAC,eAAe,EAAE,CAAC,IAAI,CAAC,KAAK,IAAI,CAAA;IACtD,CAAC;IAED,+DAA+D;IAC/D,MAAM;QACJ,OAAO,IAAI,CAAC,OAAO,CAAC,eAAe,EAAE,CAAA;IACvC,CAAC;IAED;;;;;;;OAOG;IACH,QAAQ,CAAC,OAA0C;QACjD,OAAO,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,aAAa,EAAE,OAAO,CAAC,CAAA;IAChD,CAAC;IAED;;;OAGG;IACH,iBAAiB,CAAC,OAA4C;QAC5D,OAAO,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE;YACpC,MAAM,KAAK,GAAG,CAAmE,CAAA;YACjF,IAAI,KAAK,EAAE,IAAI,KAAK,gBAAgB,CAAC,uBAAuB,EAAE,CAAC;gBAC7D,OAAO,CAAC;oBACN,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC;oBACxB,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,IAAI,EAAE,CAAC;oBACpC,UAAU,EAAE,KAAK,CAAC,UAAgC;oBAClD,YAAY,EAAE,KAAK,CAAC,YAAkC;oBACtD,SAAS,EAAE,KAAK,CAAC,SAA+B;iBACjD,CAAC,CAAA;YACJ,CAAC;QACH,CAAC,CAAC,CAAA;IACJ,CAAC;CACF"}

package/dist/modules/phone.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @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.{on, hasPermission, stop}
+ *   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 { MiniappSession } from "../session";
+import type { BatteryData, CalendarEventData, NotificationDismissedData, PhoneNotificationData, UnsubscribeFn } from "./events";
+declare class TrackedSubs {
+    private readonly unsubs;
+    protected track(unsub: UnsubscribeFn): UnsubscribeFn;
+    stop(): void;
+}
+export declare class PhoneNotificationsModule extends TrackedSubs {
+    private readonly session;
+    constructor(session: MiniappSession);
+    on(handler: (data: PhoneNotificationData) => void): UnsubscribeFn;
+    /**
+     * 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: (data: NotificationDismissedData) => void): UnsubscribeFn;
+    /** True iff `READ_NOTIFICATIONS` is declared in the miniapp's manifest. */
+    get hasPermission(): boolean;
+}
+export declare class PhoneCalendarModule extends TrackedSubs {
+    private readonly session;
+    constructor(session: MiniappSession);
+    on(handler: (data: CalendarEventData) => void): UnsubscribeFn;
+    /** True iff `CALENDAR` is declared in the miniapp's manifest. */
+    get hasPermission(): boolean;
+}
+export declare class PhoneModule {
+    private readonly session;
+    readonly notifications: PhoneNotificationsModule;
+    readonly calendar: PhoneCalendarModule;
+    constructor(session: MiniappSession);
+    /**
+     * Phone battery events. Stays flat (not sub-namespaced) — single event,
+     * no extra surface.
+     */
+    onBattery(handler: (data: BatteryData) => void): UnsubscribeFn;
+}
+export {};
+//# sourceMappingURL=phone.d.ts.map

package/dist/modules/phone.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"phone.d.ts","sourceRoot":"","sources":["../../src/modules/phone.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,EAAC,cAAc,EAAC,MAAM,YAAY,CAAA;AACzC,OAAO,KAAK,EACV,WAAW,EACX,iBAAiB,EACjB,yBAAyB,EACzB,qBAAqB,EACrB,aAAa,EACd,MAAM,UAAU,CAAA;AAEjB,cAAM,WAAW;IACf,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA2B;IAElD,SAAS,CAAC,KAAK,CAAC,KAAK,EAAE,aAAa,GAAG,aAAa;IAQpD,IAAI,IAAI,IAAI;CAUb;AAED,qBAAa,wBAAyB,SAAQ,WAAW;IAC3C,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,cAAc;IAIpD,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,qBAAqB,KAAK,IAAI,GAAG,aAAa;IAMjE;;;;;;;;OAQG;IACH,WAAW,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,yBAAyB,KAAK,IAAI,GAAG,aAAa;IAS9E,2EAA2E;IAC3E,IAAI,aAAa,IAAI,OAAO,CAE3B;CACF;AAED,qBAAa,mBAAoB,SAAQ,WAAW;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,cAAc;IAIpD,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,iBAAiB,KAAK,IAAI,GAAG,aAAa;IAM7D,iEAAiE;IACjE,IAAI,aAAa,IAAI,OAAO,CAE3B;CACF;AAED,qBAAa,WAAW;IAIV,OAAO,CAAC,QAAQ,CAAC,OAAO;IAHpC,SAAgB,aAAa,EAAE,wBAAwB,CAAA;IACvD,SAAgB,QAAQ,EAAE,mBAAmB,CAAA;gBAEhB,OAAO,EAAE,cAAc;IAKpD;;;OAGG;IACH,SAAS,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,GAAG,aAAa;CAG/D"}