@mentra/sdk 2.1.31-beta.6 → 3.0.0-alpha.3

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

@@ -0,0 +1,295 @@
+/**
+ * PhoneManager — Phone-Scoped Event Management
+ *
+ * Consolidates all phone-related data streams into a single manager
+ * with purpose-built sub-managers:
+ *
+ * - **notifications** — Phone notification events and dismissals
+ * - **calendar** — Calendar event stream
+ *
+ * Each sub-manager exposes a `hasPermission` getter that delegates to
+ * the {@link PermissionsManager}, giving callers a convenient way to
+ * check access before subscribing.
+ *
+ * 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 handler is removed.
+ *
+ * @example
+ * ```ts
+ * // Notifications (with permission check)
+ * if (phone.notifications.hasPermission) {
+ *   phone.notifications.on((n) => {
+ *     console.log(`${n.app}: ${n.title}`);
+ *   });
+ * }
+ *
+ * // Calendar events
+ * if (phone.calendar.hasPermission) {
+ *   phone.calendar.on((event) => {
+ *     console.log(event.title, event.start, "→", event.end);
+ *   });
+ * }
+ * ```
+ *
+ * @module
+ */
+import type { PermissionsManager } from "./PermissionsManager";
+/**
+ * Phone notification event delivered from the companion app.
+ */
+export interface PhoneNotificationEvent {
+    /** Unique identifier for this notification. */
+    notificationId: string;
+    /** Source application package/name. */
+    app: string;
+    /** Notification title. */
+    title: string;
+    /** Notification body content. */
+    content: string;
+    /** Notification priority level. */
+    priority: "low" | "normal" | "high";
+}
+/**
+ * Event emitted when a phone notification is dismissed by the user.
+ */
+export interface NotificationDismissedEvent {
+    /** Unique identifier of the dismissed notification. */
+    notificationId: string;
+    /** Source application package/name. */
+    app: string;
+    /** Notification title. */
+    title: string;
+    /** Notification body content. */
+    content: string;
+    /** Platform-specific notification key. */
+    notificationKey: string;
+}
+/**
+ * Normalised calendar event data.
+ *
+ * Raw wire fields are normalised for a cleaner developer experience:
+ * - `dtStart`    → `start`
+ * - `dtEnd`      → `end`
+ * - `timeStamp`  → `timestamp`
+ */
+export interface CalendarEventData {
+    /** Calendar event identifier. */
+    eventId: string;
+    /** Event title/summary. */
+    title: string;
+    /** Normalised start time (ISO string). */
+    start: string;
+    /** Normalised end time (ISO string). */
+    end: string;
+    /** Event timezone. */
+    timezone: string;
+    /** Normalised timestamp of the event update (ISO string). */
+    timestamp: string;
+    /** Any additional fields from the raw payload. */
+    [key: string]: any;
+}
+/**
+ * Dependencies injected by MentraSession into the PhoneManager.
+ */
+export interface PhoneManagerDeps {
+    /** 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;
+}
+/**
+ * Shared ref-counting logic for stream subscriptions.
+ *
+ * Tracks handler counts per stream key and calls `addSubscription` /
+ * `removeSubscription` at the appropriate lifecycle boundaries.
+ * Identical pattern to the `addStreamHandler` private method in DeviceManager,
+ * extracted here so all three PhoneManager sub-concerns can share it.
+ */
+declare class StreamHandlerTracker {
+    private router;
+    private addSubscription;
+    private removeSubscription;
+    /** Ref-counted handler totals keyed by stream string. */
+    private handlerCounts;
+    /** All cleanup functions for bulk teardown. */
+    private cleanups;
+    constructor(router: PhoneManagerDeps["router"], addSubscription: PhoneManagerDeps["addSubscription"], removeSubscription: PhoneManagerDeps["removeSubscription"]);
+    /**
+     * Register a handler on the DataStreamRouter for a given stream key,
+     * managing subscription lifecycle automatically.
+     *
+     * - Calls `addSubscription` when the first handler for a key is added.
+     * - Calls `removeSubscription` when the last handler for a key is removed.
+     *
+     * @param streamKey - The stream type string
+     * @param handler - The stream handler function
+     * @returns Cleanup function that unregisters the handler and manages subscription
+     */
+    add(streamKey: string, handler: (streamType: string, data: any, message: any) => void): () => void;
+    /**
+     * Remove all tracked handlers and unsubscribe from all streams.
+     * Called during session teardown.
+     */
+    destroyAll(): void;
+}
+/**
+ * Sub-manager for phone notification streams.
+ *
+ * Provides handlers for incoming notifications and notification dismissals,
+ * plus a convenience `hasPermission` check.
+ *
+ * @example
+ * ```ts
+ * if (phone.notifications.hasPermission) {
+ *   phone.notifications.on((n) => {
+ *     showOnGlasses(`${n.app}: ${n.title}`);
+ *   });
+ *
+ *   phone.notifications.onDismissed((e) => {
+ *     removeFromGlasses(e.notificationId);
+ *   });
+ * }
+ * ```
+ */
+export declare class NotificationSubManager {
+    private permissions;
+    private tracker;
+    private logger;
+    /** @internal */
+    constructor(permissions: PermissionsManager, tracker: StreamHandlerTracker, logger: PhoneManagerDeps["logger"]);
+    /**
+     * Whether the app has the `notifications` permission.
+     *
+     * Reads from the {@link PermissionsManager} — this is a live check,
+     * not a cached value.
+     */
+    get hasPermission(): boolean;
+    /**
+     * Listen for incoming phone notifications.
+     *
+     * @param handler - Called with {@link PhoneNotificationEvent} for each notification
+     * @returns Cleanup function to remove the handler
+     *
+     * @example
+     * ```ts
+     * const stop = phone.notifications.on((n) => {
+     *   console.log(`[${n.priority}] ${n.app}: ${n.title} — ${n.content}`);
+     * });
+     * ```
+     */
+    on(handler: (notification: PhoneNotificationEvent) => void): () => void;
+    /**
+     * Listen for notification dismissal events.
+     *
+     * Fired when the user dismisses a notification on their phone.
+     *
+     * @param handler - Called with {@link NotificationDismissedEvent} for each dismissal
+     * @returns Cleanup function to remove the handler
+     *
+     * @example
+     * ```ts
+     * phone.notifications.onDismissed((e) => {
+     *   console.log("Dismissed:", e.notificationId, "from", e.app);
+     * });
+     * ```
+     */
+    onDismissed(handler: (event: NotificationDismissedEvent) => void): () => void;
+}
+/**
+ * Sub-manager for calendar event streams.
+ *
+ * Normalises raw calendar data (e.g. `dtStart` → `start`) and provides
+ * a convenience `hasPermission` check.
+ *
+ * @example
+ * ```ts
+ * if (phone.calendar.hasPermission) {
+ *   phone.calendar.on((event) => {
+ *     console.log(`${event.title}: ${event.start} → ${event.end}`);
+ *   });
+ * }
+ * ```
+ */
+export declare class CalendarSubManager {
+    private permissions;
+    private tracker;
+    private logger;
+    /** @internal */
+    constructor(permissions: PermissionsManager, tracker: StreamHandlerTracker, logger: PhoneManagerDeps["logger"]);
+    /**
+     * Whether the app has the `calendar` permission.
+     *
+     * Reads from the {@link PermissionsManager} — this is a live check,
+     * not a cached value.
+     */
+    get hasPermission(): boolean;
+    /**
+     * Listen for calendar events from the phone.
+     *
+     * Raw fields are normalised:
+     * - `dtStart`   → `start`
+     * - `dtEnd`     → `end`
+     * - `timeStamp` → `timestamp`
+     *
+     * @param handler - Called with {@link CalendarEventData} for each event
+     * @returns Cleanup function to remove the handler
+     *
+     * @example
+     * ```ts
+     * const stop = phone.calendar.on((event) => {
+     *   console.log(`${event.title} at ${event.start} (${event.timezone})`);
+     * });
+     * ```
+     */
+    on(handler: (event: CalendarEventData) => void): () => void;
+}
+/**
+ * Manages all phone-related data streams for a MentraSession.
+ *
+ * Exposes sub-managers for notifications and calendar. Created by MentraSession and exposed as
+ * `session.phone`.
+ */
+export declare class PhoneManager {
+    /** Notification stream sub-manager. */
+    readonly notifications: NotificationSubManager;
+    /** Calendar event stream sub-manager. */
+    readonly calendar: CalendarSubManager;
+    private deps;
+    private permissions;
+    private tracker;
+    constructor(deps: PhoneManagerDeps);
+    /**
+     * Remove all registered handlers and unsubscribe from all streams.
+     *
+     * Called by MentraSession during disconnect/teardown.
+     * @internal
+     */
+    destroy(): void;
+}
+export {};
+//# sourceMappingURL=PhoneManager.d.ts.map

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

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

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

@@ -0,0 +1,285 @@
+/**
+ * 🔊 SpeakerManager — Audio Output Control
+ *
+ * v3 manager that wraps the existing AudioManager output functionality.
+ * Handles audio playback, text-to-speech, and real-time audio streaming
+ * to the user's glasses speaker.
+ *
+ * Wire message formats are identical to v2 so the cloud receives the
+ * same AUDIO_PLAY_REQUEST, AUDIO_STOP_REQUEST, AUDIO_STREAM_START,
+ * AUDIO_STREAM_END, and binary frame protocol.
+ *
+ * @example
+ * ```ts
+ * const speaker = new SpeakerManager(deps);
+ *
+ * // Play a URL
+ * const result = await speaker.play({ url: "https://example.com/sound.mp3" });
+ *
+ * // Text-to-speech
+ * await speaker.speak("Hello, world!", { volume: 0.8 });
+ *
+ * // Real-time streaming
+ * const stream = await speaker.createStream({ format: "mp3" });
+ * stream.write(mp3Chunk);
+ * await stream.end();
+ * ```
+ */
+/**
+ * Shared dependency bag injected by MentraSession.
+ * Keeps managers decoupled from the session implementation.
+ */
+export interface ManagerDeps {
+    /** 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;
+    };
+    addSubscription: (stream: string) => void;
+    removeSubscription: (stream: string) => void;
+    sendMessage: (message: any) => void;
+    sendBinary: (data: ArrayBuffer | Uint8Array) => void;
+    logger: {
+        debug(...args: any[]): void;
+        info(...args: any[]): void;
+        warn(...args: any[]): void;
+        error(...args: any[]): void;
+    };
+    getPackageName: () => string;
+    getSessionId: () => string;
+}
+/** Audio track identifier. Multiple tracks can play simultaneously (mixing). */
+export type TrackId = 0 | 1 | 2;
+/**
+ * Options for playing an audio file from a URL.
+ */
+export interface PlayOptions {
+    /** URL of the audio file to play */
+    url: string;
+    /** Volume level 0.0–1.0. Default: 1.0 */
+    volume?: number;
+    /**
+     * Track ID for playback.
+     * - 0: speaker (default audio playback)
+     * - 1: app_audio (app-specific audio)
+     * - 2: tts (text-to-speech audio)
+     * Default: 0
+     */
+    trackId?: TrackId;
+    /** Whether starting playback should stop other audio. Default: false */
+    stopOtherAudio?: boolean;
+}
+/**
+ * Result returned when audio playback completes.
+ */
+export interface PlayResult {
+    /** Duration of the audio in milliseconds (when available) */
+    duration: number;
+}
+/**
+ * Options for text-to-speech playback.
+ */
+export interface SpeakOptions {
+    /** ElevenLabs voice ID (optional — server picks a default) */
+    voiceId?: string;
+    /** ElevenLabs model ID (optional — defaults to eleven_flash_v2_5) */
+    modelId?: string;
+    /** Fine-grained voice settings */
+    voiceSettings?: {
+        stability?: number;
+        similarityBoost?: number;
+        style?: number;
+        speed?: number;
+    };
+    /** Volume level 0.0–1.0. Default: 1.0 */
+    volume?: number;
+    /**
+     * Track ID for playback. Default: 2 (tts)
+     */
+    trackId?: TrackId;
+    /** Whether starting playback should stop other audio. Default: false */
+    stopOtherAudio?: boolean;
+}
+/**
+ * Options for creating a real-time audio output stream.
+ */
+export interface StreamOptions {
+    /**
+     * Format of the audio being written.
+     * - "mp3": MP3 bytes passed through directly (ElevenLabs, OpenAI TTS, etc.)
+     * - "pcm16": Raw 16-bit signed PCM samples (SDK encodes to MP3 before sending)
+     * Default: "mp3"
+     */
+    format?: "mp3" | "pcm16";
+    /** PCM sample rate in Hz (required when format is "pcm16"). Default: 24000 */
+    sampleRate?: number;
+    /** Number of audio channels. Default: 1 (mono) */
+    channels?: 1 | 2;
+    /** MP3 bitrate in kbps for PCM encoding. Default: 128 */
+    bitrate?: number;
+    /** Volume level 0.0–1.0. Default: 1.0 */
+    volume?: number;
+    /**
+     * Track ID for playback. Default: 1 (app_audio)
+     */
+    trackId?: TrackId;
+    /** Whether starting the stream should stop other audio. Default: true */
+    stopOtherAudio?: boolean;
+}
+/** Lifecycle state of an AudioOutputStream */
+export type AudioOutputStreamState = "created" | "streaming" | "ending" | "ended" | "error";
+/**
+ * A real-time audio output stream.
+ *
+ * Audio data is sent as binary WebSocket frames with the protocol:
+ *   [36 bytes: streamId UUID as ASCII] [N bytes: audio data]
+ *
+ * The cloud pipes those bytes into an HTTP chunked response that the
+ * phone's media player consumes like internet radio.
+ */
+export interface AudioOutputStream {
+    /** Unique stream identifier (UUID) */
+    readonly id: string;
+    /** Current lifecycle state */
+    readonly state: AudioOutputStreamState;
+    /** Write audio data to the stream */
+    write(chunk: Uint8Array): void;
+    /** Gracefully end the stream — phone finishes buffered audio */
+    end(): Promise<void>;
+    /** Flush/interrupt — discard buffered audio, silence immediately */
+    flush(): void;
+    /** Register a callback for state changes */
+    onStateChange(handler: (state: AudioOutputStreamState) => void): void;
+}
+/**
+ * Controls audio output on the user's glasses speaker.
+ *
+ * Provides methods for:
+ * - 🎵 Playing audio files from URLs
+ * - ⏹️ Stopping audio playback
+ * - 🗣️ Text-to-speech via ElevenLabs
+ * - 🎙️ Real-time audio streaming
+ *
+ * All messages use the same wire format as v2 AudioManager — the cloud
+ * and phone receive identical AUDIO_PLAY_REQUEST / AUDIO_STOP_REQUEST /
+ * AUDIO_STREAM_* messages.
+ */
+export declare class SpeakerManager {
+    private readonly deps;
+    /**
+     * Map of pending play requests awaiting AUDIO_PLAY_RESPONSE.
+     * Key: requestId, Value: promise resolve/reject pair.
+     */
+    private pendingRequests;
+    /** Currently active output stream (at most one at a time) */
+    private activeStream;
+    /** Cached permission state */
+    private _hasPermission;
+    /** Cleanup function for the AUDIO_PLAY_RESPONSE message handler registration */
+    private responseHandlerCleanup;
+    constructor(deps: ManagerDeps);
+    /**
+     * Whether the app has speaker permission.
+     * Updated when the cloud sends permission state changes.
+     */
+    get hasPermission(): boolean;
+    /**
+     * 🎵 Play an audio file from a URL on the glasses speaker.
+     *
+     * If `stopOtherAudio` is false (default), resolves immediately in
+     * fire-and-forget mode so multiple tracks can play concurrently.
+     * If `stopOtherAudio` is true, waits for the cloud's AUDIO_PLAY_RESPONSE.
+     *
+     * @param opts - Playback options (url is required)
+     * @returns Promise resolving with playback result
+     *
+     * @example
+     * ```ts
+     * const result = await speaker.play({
+     *   url: "https://example.com/sound.mp3",
+     *   volume: 0.8,
+     *   trackId: 0,
+     * });
+     * ```
+     */
+    play(opts: PlayOptions): Promise<PlayResult>;
+    /**
+     * ⏹️ Stop audio playback on the glasses.
+     *
+     * @param trackId - Specific track to stop. If omitted, stops all tracks.
+     *
+     * @example
+     * ```ts
+     * // Stop all audio
+     * await speaker.stop();
+     *
+     * // Stop only the TTS track
+     * await speaker.stop(2);
+     * ```
+     */
+    stop(trackId?: TrackId): Promise<void>;
+    /**
+     * 🗣️ Convert text to speech and play it on the glasses speaker.
+     *
+     * Uses the server-side TTS endpoint which proxies to ElevenLabs.
+     * The generated audio URL is then played via the standard play() path.
+     *
+     * @param text - Text to speak (required)
+     * @param opts - TTS configuration (optional)
+     * @returns Promise resolving with playback result
+     *
+     * @example
+     * ```ts
+     * await speaker.speak("Hello, world!");
+     *
+     * await speaker.speak("Good morning!", {
+     *   voiceId: "custom_voice_id",
+     *   voiceSettings: { stability: 0.5, speed: 1.2 },
+     *   volume: 0.8,
+     * });
+     * ```
+     */
+    speak(text: string, opts?: SpeakOptions): Promise<PlayResult>;
+    /**
+     * 🎙️ Create a real-time audio output stream.
+     *
+     * Opens a streaming relay on the cloud and tells the phone to play it.
+     * Write audio chunks to the returned stream and they play on the glasses
+     * speaker in real-time — like internet radio.
+     *
+     * Only one stream can be active at a time. Call `end()` or `flush()` on
+     * the current stream before creating a new one.
+     *
+     * @param opts - Stream configuration
+     * @returns The AudioOutputStream (already connected and playing)
+     *
+     * @example
+     * ```ts
+     * // MP3 pass-through (most common)
+     * const stream = await speaker.createStream({ format: "mp3" });
+     * elevenLabs.on("chunk", (mp3) => stream.write(mp3));
+     * elevenLabs.on("end", () => stream.end());
+     *
+     * // Interrupt on user speech
+     * mic.onVoiceActivity((vad) => {
+     *   if (vad.isSpeaking) stream.flush();
+     * });
+     * ```
+     */
+    createStream(opts?: StreamOptions): Promise<AudioOutputStream>;
+    /**
+     * Cancel all pending requests and end any active stream.
+     * Called by MentraSession during disconnect/cleanup.
+     * @internal
+     */
+    destroy(): void;
+    /**
+     * Handle AUDIO_PLAY_RESPONSE from the cloud.
+     * Resolves or rejects the corresponding pending play() promise.
+     */
+    private handleAudioPlayResponse;
+}
+//# sourceMappingURL=SpeakerManager.d.ts.map

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

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