@mentra/sdk 2.1.31-beta.5 → 3.0.0-alpha.1

package/dist/session/managers/CameraManager.d.ts

@@ -0,0 +1,198 @@
+/**
+ * CameraManager — v3 SDK Camera API
+ *
+ * Covers:
+ * - photo capture
+ * - externally-triggered photo events
+ * - unmanaged RTMP streaming
+ * - managed stream orchestration/status
+ */
+import { type ManagedStreamStatus, type RestreamDestination, type StreamStatus, type AudioConfig, type StreamConfig, type VideoConfig } from "../../types";
+export interface PhotoOptions {
+    size?: "small" | "medium" | "large" | "full";
+    compression?: "none" | "medium" | "heavy";
+    saveToGallery?: boolean;
+    sound?: boolean;
+    timeout?: number;
+}
+export interface PhotoData {
+    url: string;
+    width: number;
+    height: number;
+    timestamp: number;
+    savedToGallery: boolean;
+}
+/**
+ * Options for session.camera.startStream().
+ *
+ * Three modes:
+ * - No options → managed relay (default, best for most apps)
+ * - `destinations` → managed relay + fan out to external services
+ * - `direct` → glasses connect straight to this URL, no relay
+ */
+export interface StreamOptions {
+    /** Direct stream URL. Glasses connect to this URL directly, bypassing the cloud relay.
+     *  Supports srt://, rtmp://, rtmps://, and https:// (WHIP) protocols.
+     *  When set, the cloud relay is not used. No viewer URLs are returned.
+     *  Most apps should NOT use this — use the default managed relay instead. */
+    direct?: string;
+    /** Restream destinations. The cloud relay fans out to these URLs.
+     *  Only works with managed streaming (when `direct` is not set).
+     *  Each URL is an RTMP or SRT ingest endpoint (YouTube, Twitch, etc.) */
+    destinations?: string[];
+    /** Stream quality. Only applies to managed streaming. */
+    quality?: "720p" | "1080p";
+    /** Enable WebRTC playback URL. Only applies to managed streaming. Default: true. */
+    enableWebRTC?: boolean;
+    /** Video configuration (resolution, bitrate, fps) */
+    video?: VideoConfig;
+    /** Audio configuration (bitrate, sample rate) */
+    audio?: AudioConfig;
+    /** Stream transport configuration */
+    stream?: StreamConfig;
+    /** Controls stream start/stop sounds on the glasses. Default: true. */
+    sound?: boolean;
+}
+export interface StreamResult {
+    hlsUrl: string;
+    dashUrl: string;
+    webrtcUrl?: string;
+    previewUrl?: string;
+    thumbnailUrl?: string;
+    streamId: string;
+}
+/** @deprecated Use StreamOptions instead */
+export interface RtmpStreamOptions {
+    rtmpUrl: string;
+    video?: VideoConfig;
+    audio?: AudioConfig;
+    stream?: StreamConfig;
+    sound?: boolean;
+}
+/** @deprecated Use StreamOptions with destinations instead */
+export interface ManagedStreamOptions {
+    quality?: "720p" | "1080p";
+    enableWebRTC?: boolean;
+    video?: VideoConfig;
+    audio?: AudioConfig;
+    stream?: StreamConfig;
+    restreamDestinations?: RestreamDestination[];
+    sound?: boolean;
+}
+/** @deprecated Use StreamResult instead */
+export type ManagedStreamResult = StreamResult;
+export interface ExistingStreamInfo {
+    hasActiveStream: boolean;
+    streamInfo?: {
+        type: "managed" | "unmanaged";
+        streamId: string;
+        status: string;
+        createdAt: Date;
+        hlsUrl?: string;
+        dashUrl?: string;
+        webrtcUrl?: string;
+        previewUrl?: string;
+        thumbnailUrl?: string;
+        activeViewers?: number;
+        rtmpUrl?: string;
+        requestingAppId?: string;
+    };
+}
+export type StreamStatusHandler = (status: StreamStatus) => void;
+export interface CameraManagerDeps {
+    router: {
+        on(key: string, handler: (streamType: string, data: any, message: any) => void): () => void;
+    };
+    messageHandlers: {
+        register(type: string, handler: (msg: any) => void): () => void;
+    };
+    addSubscription: (stream: string) => void;
+    removeSubscription: (stream: string) => void;
+    sendMessage: (message: any) => void;
+    logger: {
+        debug(...args: any[]): void;
+        info(...args: any[]): void;
+        warn(...args: any[]): void;
+        error(...args: any[]): void;
+    };
+    getPackageName: () => string;
+    getSessionId: () => string;
+}
+export declare class CameraManager {
+    private readonly deps;
+    private readonly events;
+    private readonly handlerCleanups;
+    private pendingRequests;
+    private pendingStreamChecks;
+    private pendingManagedStreamRequest;
+    private _hasPermission;
+    private isStreaming;
+    private currentStreamUrl?;
+    private currentStreamState?;
+    private isManagedStreaming;
+    private currentManagedStreamId?;
+    private currentManagedStreamUrls?;
+    private managedStreamStatus?;
+    constructor(deps: CameraManagerDeps);
+    takePhoto(opts?: PhotoOptions): Promise<PhotoData>;
+    onPhotoTaken(handler: (photo: PhotoData) => void): () => void;
+    /**
+     * Start a video stream from the glasses.
+     *
+     * Three modes:
+     * - `startStream()` — managed relay (default). Cloud handles quality, reconnection, viewer URLs.
+     * - `startStream({ destinations: [...] })` — managed relay + fan out to YouTube/Twitch/etc.
+     * - `startStream({ direct: "srt://..." })` — glasses connect straight to your URL, no relay.
+     *
+     * @example
+     * ```ts
+     * // Default — managed relay
+     * const stream = await session.camera.startStream();
+     * console.log(stream.hlsUrl, stream.webrtcUrl);
+     *
+     * // Managed relay + restream to YouTube
+     * const stream = await session.camera.startStream({
+     *   destinations: ["rtmp://youtube.com/live/your-key"],
+     * });
+     *
+     * // Direct — glasses → your server, no relay
+     * await session.camera.startStream({ direct: "srt://192.168.1.100:4201" });
+     * ```
+     */
+    startStream(options?: StreamOptions): Promise<StreamResult | void>;
+    /**
+     * Stop any active stream (managed or direct).
+     */
+    stopStream(): Promise<void>;
+    /**
+     * Subscribe to stream status updates (works for both managed and direct).
+     */
+    onStreamStatus(handler: StreamStatusHandler): () => void;
+    isCurrentlyStreaming(): boolean;
+    getCurrentStreamUrl(): string | undefined;
+    getStreamStatus(): StreamStatus | undefined;
+    getStreamUrls(): StreamResult | undefined;
+    private _startDirectStream;
+    private _startManagedStream;
+    /** @deprecated Use startStream({ direct: url }) instead */
+    startDirectStream(options: RtmpStreamOptions): Promise<void>;
+    /** @deprecated Use startStream() or startStream({ destinations: [...] }) instead */
+    startManagedStream(options?: ManagedStreamOptions): Promise<StreamResult>;
+    /** @deprecated Use stopStream() instead */
+    stopManagedStream(): Promise<void>;
+    /** @deprecated Use onStreamStatus() instead */
+    onManagedStreamStatus(handler: (status: ManagedStreamStatus) => void): () => void;
+    /** @deprecated Use isCurrentlyStreaming() instead */
+    isManagedStreamActive(): boolean;
+    /** @deprecated Use getStreamUrls() instead */
+    getManagedStreamUrls(): StreamResult | undefined;
+    getManagedStreamStatus(): ManagedStreamStatus | undefined;
+    checkExistingStream(): Promise<ExistingStreamInfo>;
+    get hasPermission(): boolean;
+    handlePhotoResponse(message: any): void;
+    private handleStreamStatus;
+    private handleManagedStreamStatus;
+    private handleStreamCheckResponse;
+    destroy(): void;
+}
+//# sourceMappingURL=CameraManager.d.ts.map

package/dist/session/managers/CameraManager.d.ts.map

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

package/dist/session/managers/DashboardManager.d.ts

@@ -0,0 +1,131 @@
+/**
+ * 📊 DashboardManager — v3 SDK Dashboard Content API
+ *
+ * Thin wrapper that sends dashboard content updates to the cloud.
+ * Provides a simplified two-method API: {@link showText} and {@link clear}.
+ *
+ * Wire format is identical to v2 DashboardContentManager:
+ * ```json
+ * {
+ *   "type": "dashboard_content_update",
+ *   "packageName": "<packageName>",
+ *   "sessionId": "<sessionId>-<packageName>",
+ *   "content": "<text>",
+ *   "modes": ["main"],
+ *   "timestamp": "<ISO date>"
+ * }
+ * ```
+ *
+ * The `sessionId` field in dashboard messages uses the composite format
+ * `"<sessionId>-<packageName>"` to match the v2 wire format exactly.
+ *
+ * @module
+ */
+/**
+ * Dependencies injected by MentraSession.
+ *
+ * Structural type — no concrete imports so the manager stays unit-testable
+ * with plain stubs.
+ */
+export interface DashboardManagerDeps {
+    /** DataStreamRouter — register for DATA_STREAM messages by streamType key. */
+    router: {
+        on(key: string, handler: (streamType: string, data: any, message: any) => void): () => void;
+    };
+    /** MessageHandlerRegistry — register for top-level message types. */
+    messageHandlers: {
+        register(type: string, handler: (msg: any) => void): () => void;
+    };
+    /** Add a subscription string (triggers SUBSCRIPTION_UPDATE to cloud). */
+    addSubscription: (stream: string) => void;
+    /** Remove a subscription string. */
+    removeSubscription: (stream: string) => void;
+    /** Send an arbitrary JSON message over the WebSocket. */
+    sendMessage: (message: any) => void;
+    /** Structured logger. */
+    logger: {
+        debug(...args: any[]): void;
+        info(...args: any[]): void;
+        warn(...args: any[]): void;
+        error(...args: any[]): void;
+    };
+    /** Package name for outgoing messages. */
+    getPackageName: () => string;
+    /** Current session ID. */
+    getSessionId: () => string;
+}
+/**
+ * Controls the dashboard content displayed for this app on the user's glasses.
+ *
+ * Dashboard content is a text overlay shown in the main dashboard view.
+ * The {@link showText} method sends content targeting the `MAIN` dashboard
+ * mode by default. Use {@link clear} to remove any displayed content.
+ *
+ * All methods are fire-and-forget — the messages are sent immediately and
+ * no response is awaited.
+ *
+ * @example
+ * ```ts
+ * const session = await mentra.connect();
+ *
+ * // Show a single line of text
+ * session.dashboard.showText("Meeting in 5 minutes");
+ *
+ * // Show multiple lines
+ * session.dashboard.showText(["Line 1", "Line 2", "Line 3"]);
+ *
+ * // Clear the dashboard
+ * session.dashboard.clear();
+ * ```
+ */
+export declare class DashboardManager {
+    private readonly deps;
+    constructor(deps: DashboardManagerDeps);
+    /**
+     * Show text content on the dashboard.
+     *
+     * Sends a `dashboard_content_update` message targeting the `MAIN`
+     * dashboard mode. Accepts either a single string or an array of
+     * pre-wrapped lines — when an array is provided the lines are joined
+     * with newlines before sending.
+     *
+     * @param text - A string or array of strings to display on the dashboard.
+     *
+     * @example
+     * ```ts
+     * // Single string
+     * session.dashboard.showText("Status: Connected");
+     *
+     * // Pre-wrapped lines
+     * session.dashboard.showText([
+     *   "Temperature: 72°F",
+     *   "Humidity: 45%",
+     *   "Wind: 5 mph",
+     * ]);
+     * ```
+     */
+    showText(text: string | string[]): void;
+    /**
+     * Clear the dashboard content.
+     *
+     * Sends an empty `dashboard_content_update` message targeting the
+     * `MAIN` dashboard mode, which removes any currently displayed content
+     * for this app.
+     *
+     * @example
+     * ```ts
+     * session.dashboard.clear();
+     * ```
+     */
+    clear(): void;
+    /**
+     * Clean up resources.
+     *
+     * Called by MentraSession during disconnect/cleanup. Dashboard commands
+     * are fire-and-forget so there is no pending state to drain.
+     *
+     * @internal
+     */
+    destroy(): void;
+}
+//# sourceMappingURL=DashboardManager.d.ts.map

package/dist/session/managers/DashboardManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DashboardManager.d.ts","sourceRoot":"","sources":["../../../src/session/managers/DashboardManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAOH;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,8EAA8E;IAC9E,MAAM,EAAE;QACN,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;KAC7F,CAAC;IACF,qEAAqE;IACrE,eAAe,EAAE;QACf,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;KACjE,CAAC;IACF,yEAAyE;IACzE,eAAe,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1C,oCAAoC;IACpC,kBAAkB,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7C,yDAAyD;IACzD,WAAW,EAAE,CAAC,OAAO,EAAE,GAAG,KAAK,IAAI,CAAC;IACpC,yBAAyB;IACzB,MAAM,EAAE;QACN,KAAK,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;QAC5B,IAAI,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;QAC3B,IAAI,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;QAC3B,KAAK,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;KAC7B,CAAC;IACF,0CAA0C;IAC1C,cAAc,EAAE,MAAM,MAAM,CAAC;IAC7B,0BAA0B;IAC1B,YAAY,EAAE,MAAM,MAAM,CAAC;CAC5B;AAID;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAuB;gBAEhC,IAAI,EAAE,oBAAoB;IAMtC;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI;IAiBvC;;;;;;;;;;;OAWG;IACH,KAAK,IAAI,IAAI;IAiBb;;;;;;;OAOG;IACH,OAAO,IAAI,IAAI;CAGhB"}

package/dist/session/managers/DeviceManager.d.ts

@@ -0,0 +1,348 @@
+/**
+ * DeviceManager — Consolidated Device State, Hardware Events & Capabilities
+ *
+ * Owns all device-related concerns for a MentraSession:
+ *
+ * - **Reactive state** — Observable properties for connection, battery, WiFi,
+ *   hotspot, and case status (mirrors the legacy DeviceState pattern).
+ * - **Hardware events** — Button presses, head position, touch gestures,
+ *   battery updates, and VPS coordinates, all routed from the DataStreamRouter.
+ * - **Capabilities** — Device capability profile received at connection time
+ *   and updated mid-session when the glasses model changes.
+ * - **Actions** — Outbound commands like `requestWifiSetup`.
+ *
+ * All handler registrations return a cleanup function. Subscriptions are
+ * managed automatically — `addSubscription` is called when the first handler
+ * for a stream is registered, and `removeSubscription` when the last is removed.
+ *
+ * @example
+ * ```ts
+ * // Reactive state
+ * device.state.batteryLevel.onChange((level) => {
+ *   console.log("Battery:", level, "%");
+ * });
+ *
+ * // Hardware events
+ * const stop = device.onButtonPress((e) => {
+ *   console.log(e.buttonId, e.pressType);
+ * });
+ *
+ * // Filtered touch events
+ * device.onTouchEvent("double_tap", (e) => {
+ *   console.log("Double tap!", e);
+ * });
+ *
+ * // Capabilities
+ * device.onCapabilitiesChange((caps) => {
+ *   console.log("Device supports camera:", !!caps?.camera);
+ * });
+ *
+ * // Actions
+ * device.requestWifiSetup("App needs internet for sync");
+ *
+ * // Cleanup
+ * stop();
+ * ```
+ *
+ * @module
+ */
+import { Observable } from "../../utils/Observable";
+import type { PermissionsManager } from "./PermissionsManager";
+/**
+ * Button press event from the glasses hardware.
+ */
+export interface ButtonPressEvent {
+    /** Identifier of the button that was pressed. */
+    buttonId: string;
+    /** Whether the press was short or long. */
+    pressType: "short" | "long";
+}
+/**
+ * Head position event from the IMU.
+ */
+export interface HeadPositionEvent {
+    /** Current head position. */
+    position: "up" | "down";
+}
+/**
+ * Normalised touch/gesture event from the glasses touchpad.
+ *
+ * Raw wire fields (`gesture_name`, `device_model`) are normalised to
+ * `gesture` and `model` for a cleaner developer experience.
+ */
+export interface TouchEventData {
+    /** Normalised gesture name (e.g. "double_tap", "forward_swipe"). */
+    gesture: string;
+    /** Normalised device model name. */
+    model: string;
+    /** Timestamp of the gesture. */
+    timestamp: Date | string;
+    /** The original raw data, preserved for advanced use cases. */
+    [key: string]: any;
+}
+/**
+ * Glasses battery update event.
+ */
+export interface BatteryUpdateEvent {
+    /** Battery level 0–100. */
+    level: number;
+    /** Whether the glasses are currently charging. */
+    charging: boolean;
+    /** Estimated minutes remaining (if available). */
+    timeRemaining?: number;
+}
+/**
+ * Dependencies injected by MentraSession into the DeviceManager.
+ */
+export interface DeviceManagerDeps {
+    /** DataStreamRouter — register for stream-type events. */
+    router: {
+        on(key: string, handler: (streamType: string, data: any, message: any) => void): () => void;
+    };
+    /** MessageHandlerRegistry — register for top-level message types. */
+    messageHandlers: {
+        register(type: string, handler: (msg: any) => void): () => void;
+    };
+    /** Subscribe to a data stream (sent to cloud). */
+    addSubscription: (stream: string) => void;
+    /** Unsubscribe from a data stream. */
+    removeSubscription: (stream: string) => void;
+    /** Send an arbitrary message to the cloud. */
+    sendMessage: (message: any) => void;
+    /** Session-scoped logger. */
+    logger: {
+        debug(...args: any[]): void;
+        info(...args: any[]): void;
+        warn(...args: any[]): void;
+        error(...args: any[]): void;
+    };
+    /** Returns the current app's package name. */
+    getPackageName: () => string;
+    /** Returns the active session ID. */
+    getSessionId: () => string;
+    /** PermissionsManager for gating protected streams. */
+    permissions: PermissionsManager;
+}
+/**
+ * Read-only reactive device state container.
+ *
+ * Every property is an {@link Observable} — call `.value` for synchronous
+ * reads or `.onChange(cb)` for reactive subscriptions.
+ */
+export interface DeviceStateShape {
+    readonly connected: Observable<boolean>;
+    readonly modelName: Observable<string | null>;
+    readonly batteryLevel: Observable<number | null>;
+    readonly charging: Observable<boolean | null>;
+    readonly caseBatteryLevel: Observable<number | null>;
+    readonly caseCharging: Observable<boolean | null>;
+    readonly caseOpen: Observable<boolean | null>;
+    readonly caseRemoved: Observable<boolean | null>;
+    readonly wifiConnected: Observable<boolean>;
+    readonly wifiSsid: Observable<string | null>;
+    readonly wifiLocalIp: Observable<string | null>;
+    readonly hotspotEnabled: Observable<boolean | null>;
+    readonly hotspotSsid: Observable<string | null>;
+}
+/**
+ * Manages all device-related state, hardware events, capabilities, and actions.
+ *
+ * Created by MentraSession and exposed as `session.device`.
+ */
+export declare class DeviceManager {
+    /** Reactive device state observables. */
+    readonly state: DeviceStateShape;
+    /** Current device capabilities (set from CONNECTION_ACK). */
+    capabilities: any;
+    private deps;
+    private permissions;
+    /** Internal mutable references to observables (state exposes them read-only). */
+    private readonly _connected;
+    private readonly _modelName;
+    private readonly _batteryLevel;
+    private readonly _charging;
+    private readonly _caseBatteryLevel;
+    private readonly _caseCharging;
+    private readonly _caseOpen;
+    private readonly _caseRemoved;
+    private readonly _wifiConnected;
+    private readonly _wifiSsid;
+    private readonly _wifiLocalIp;
+    private readonly _hotspotEnabled;
+    private readonly _hotspotSsid;
+    /** Capabilities-change listeners. */
+    private capabilitiesListeners;
+    /**
+     * Ref-counted handler bookkeeping per stream key.
+     *
+     * Tracks the number of active handlers for each stream so that
+     * `addSubscription` / `removeSubscription` are called exactly once
+     * when the first handler is added / last handler is removed.
+     */
+    private handlerCounts;
+    /** Cleanup functions returned by router/messageHandlers registrations. */
+    private cleanups;
+    constructor(deps: DeviceManagerDeps);
+    /**
+     * Listen for physical button press events on the glasses.
+     *
+     * @param handler - Called with {@link ButtonPressEvent} for every press
+     * @returns Cleanup function to remove the handler
+     *
+     * @example
+     * ```ts
+     * const stop = device.onButtonPress((e) => {
+     *   if (e.pressType === "long") {
+     *     console.log("Long press on", e.buttonId);
+     *   }
+     * });
+     * ```
+     */
+    onButtonPress(handler: (event: ButtonPressEvent) => void): () => void;
+    /**
+     * Listen for head position (up/down) events from the IMU.
+     *
+     * @param handler - Called with {@link HeadPositionEvent} on position change
+     * @returns Cleanup function to remove the handler
+     */
+    onHeadPosition(handler: (event: HeadPositionEvent) => void): () => void;
+    /**
+     * Listen for touch/gesture events from the glasses touchpad.
+     *
+     * Overloaded:
+     * - `onTouchEvent(handler)` — all touch events
+     * - `onTouchEvent(gesture, handler)` — only events matching the given gesture
+     *
+     * @param gestureOrHandler - A gesture name string, or a handler for all events
+     * @param handler - Handler when the first argument is a gesture name
+     * @returns Cleanup function to remove the handler
+     *
+     * @example
+     * ```ts
+     * // All gestures
+     * device.onTouchEvent((e) => console.log(e.gesture));
+     *
+     * // Specific gesture
+     * device.onTouchEvent("double_tap", (e) => console.log("Double tap!"));
+     * ```
+     */
+    onTouchEvent(handler: (event: TouchEventData) => void): () => void;
+    onTouchEvent(gesture: string, handler: (event: TouchEventData) => void): () => void;
+    /**
+     * Subscribe to multiple touch gestures at once.
+     *
+     * Registers a handler for each gesture and returns a single cleanup
+     * function that removes all of them.
+     *
+     * @param gestures - Array of gesture names (e.g. `["double_tap", "forward_swipe"]`)
+     * @returns Cleanup function that removes all gesture subscriptions
+     *
+     * @example
+     * ```ts
+     * const stop = device.subscribeToGestures(["single_tap", "double_tap", "forward_swipe"]);
+     * // Later:
+     * stop();
+     * ```
+     */
+    subscribeToGestures(gestures: string[]): () => void;
+    /**
+     * Listen for glasses battery update events.
+     *
+     * Also updates the reactive `state.batteryLevel` and `state.charging` observables.
+     *
+     * @param handler - Called with {@link BatteryUpdateEvent} on each update
+     * @returns Cleanup function to remove the handler
+     */
+    onBatteryUpdate(handler: (event: BatteryUpdateEvent) => void): () => void;
+    /**
+     * Listen for VPS (Visual Positioning System) coordinate updates.
+     *
+     * @param handler - Called with raw VPS coordinate data
+     * @returns Cleanup function to remove the handler
+     */
+    onVpsCoordinates(handler: (event: any) => void): () => void;
+    /**
+     * Request the user to set up WiFi on their glasses.
+     *
+     * Sends a `request_wifi_setup` message to the cloud, which prompts
+     * the companion app to display a WiFi configuration flow.
+     *
+     * @param reason - Optional human-readable reason shown to the user
+     *
+     * @example
+     * ```ts
+     * device.requestWifiSetup("This app needs WiFi for real-time sync");
+     * ```
+     */
+    requestWifiSetup(reason?: string): void;
+    /**
+     * Subscribe to device capability changes.
+     *
+     * Called when capabilities are first received (CONNECTION_ACK) and
+     * whenever the device model or capabilities change mid-session.
+     *
+     * @param handler - Called with the new capabilities object
+     * @returns Cleanup function to remove the handler
+     *
+     * @example
+     * ```ts
+     * device.onCapabilitiesChange((caps) => {
+     *   if (caps?.camera?.photo) {
+     *     console.log("Camera supports photos");
+     *   }
+     * });
+     * ```
+     */
+    onCapabilitiesChange(handler: (caps: any) => void): () => void;
+    /**
+     * Handle a `device_state_update` message from the cloud.
+     *
+     * Updates all matching Observable properties. Only fields present in
+     * the message are touched — Observables for absent fields keep their
+     * current value.
+     *
+     * @param message - The raw device_state_update message
+     * @internal
+     */
+    handleDeviceStateUpdate(message: any): void;
+    /**
+     * Handle a `capabilities_update` message from the cloud.
+     *
+     * Extracts the capabilities payload and delegates to {@link setCapabilities}.
+     *
+     * @param message - The raw capabilities_update message
+     * @internal
+     */
+    handleCapabilitiesUpdate(message: any): void;
+    /**
+     * Directly set the device capabilities.
+     *
+     * Called by MentraSession from the CONNECTION_ACK payload, or by
+     * {@link handleCapabilitiesUpdate} for mid-session updates.
+     *
+     * @param caps - The capabilities object (or null)
+     * @internal
+     */
+    setCapabilities(caps: any): void;
+    /**
+     * Remove all tracked handlers and clear listeners.
+     *
+     * Called by MentraSession during disconnect/cleanup.
+     *
+     * @internal
+     */
+    destroy(): void;
+    /**
+     * Register a handler on the DataStreamRouter for a given stream key,
+     * managing subscription lifecycle automatically.
+     *
+     * - Calls `deps.addSubscription` when the first handler for a key is added.
+     * - Calls `deps.removeSubscription` when the last handler for a key is removed.
+     *
+     * @param streamKey - The stream type or prefixed stream key
+     * @param handler - The stream handler function
+     * @returns Cleanup function that unregisters the handler and manages subscription
+     */
+    private addStreamHandler;
+}
+//# sourceMappingURL=DeviceManager.d.ts.map