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

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

@@ -0,0 +1,252 @@
+/**
+ * 🎤 MicManager — Microphone Input Control
+ *
+ * v3 manager that handles audio input from the user's glasses microphone.
+ * Provides subscriptions for raw PCM audio chunks and voice activity
+ * detection (VAD) events.
+ *
+ * Audio chunks arrive as binary WebSocket frames — MentraSession calls
+ * `handleBinaryAudio()` when it receives a binary frame that isn't
+ * destined for an output stream. VAD events arrive as JSON DATA_STREAM
+ * messages routed through the DataStreamRouter.
+ *
+ * @example
+ * ```ts
+ * const mic = new MicManager(deps);
+ *
+ * // Listen for raw audio
+ * const stopChunks = mic.onChunk((chunk) => {
+ *   console.log(`Got ${chunk.data.byteLength} bytes at ${chunk.sampleRate}Hz`);
+ * });
+ *
+ * // Listen for voice activity
+ * const stopVad = mic.onVoiceActivity((vad) => {
+ *   console.log(vad.isSpeaking ? "Speech started" : "Speech ended");
+ * });
+ *
+ * // Check state
+ * console.log("Speaking:", mic.isSpeaking);
+ * console.log("Active:", mic.isActive);
+ *
+ * // Cleanup
+ * mic.stop();
+ * ```
+ */
+/**
+ * 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;
+}
+/**
+ * A chunk of raw PCM audio data from the glasses microphone.
+ *
+ * Audio is always 16 kHz mono 16-bit signed PCM — the native format
+ * of the glasses microphone hardware.
+ */
+export interface AudioChunk {
+    /** Raw PCM audio data */
+    data: ArrayBuffer;
+    /** Sample rate in Hz (always 16000) */
+    sampleRate: number;
+    /** Number of audio channels (always 1 — mono) */
+    channels: number;
+    /** Timestamp when this chunk was received (ms since epoch) */
+    timestamp: number;
+}
+/**
+ * Voice activity detection event.
+ *
+ * Indicates whether the user is currently speaking. The glasses run
+ * on-device VAD and send status updates as the speech state changes.
+ */
+export interface VadEvent {
+    /** Whether speech is currently detected */
+    isSpeaking: boolean;
+    /** Timestamp when this event was received (ms since epoch) */
+    timestamp: number;
+}
+/**
+ * Manages microphone input from the user's glasses.
+ *
+ * Handles two types of incoming data:
+ *
+ * 1. **Raw PCM audio chunks** — arrive as binary WebSocket frames.
+ *    MentraSession calls `handleBinaryAudio()` for each binary frame
+ *    that isn't part of an output stream. Subscribers receive wrapped
+ *    `AudioChunk` objects with metadata.
+ *
+ * 2. **Voice Activity Detection (VAD)** — arrives as JSON DATA_STREAM
+ *    messages with `streamType: "VAD"`. The glasses send `status: true`
+ *    when speech starts and `status: false` when it stops. The raw
+ *    `status` field may be a boolean or string ("true"/"false") — this
+ *    manager normalizes it to a clean boolean.
+ *
+ * Subscription lifecycle:
+ * - `onChunk()` adds an "audio_chunk" subscription when the first handler
+ *   is registered, and removes it when the last handler unsubscribes.
+ * - `onVoiceActivity()` does the same for the "VAD" subscription.
+ * - `stop()` removes all handlers and unsubscribes from both streams.
+ */
+export declare class MicManager {
+    private readonly deps;
+    /** Registered handlers for audio chunk data */
+    private chunkHandlers;
+    /** Registered handlers for VAD events */
+    private vadHandlers;
+    /** Cleanup function for the VAD router subscription */
+    private vadRouterCleanup;
+    /** Cached latest VAD state — true when speech is detected */
+    private _isSpeaking;
+    /** Cached permission state */
+    private _hasPermission;
+    constructor(deps: ManagerDeps);
+    /**
+     * Whether speech is currently detected.
+     *
+     * This value is cached from the most recent VAD event. It is only
+     * updated while there is at least one `onVoiceActivity` subscriber.
+     *
+     * @example
+     * ```ts
+     * if (mic.isSpeaking) {
+     *   // User is talking — maybe pause TTS
+     * }
+     * ```
+     */
+    get isSpeaking(): boolean;
+    /**
+     * Whether this app has an active `onChunk` subscription.
+     *
+     * Returns true when at least one audio chunk handler is registered,
+     * meaning the microphone stream is subscribed and binary audio data
+     * is being delivered.
+     */
+    get isActive(): boolean;
+    /**
+     * Whether the app has microphone permission.
+     *
+     * Updated when the cloud sends permission state changes. Apps that
+     * require microphone access should declare `MICROPHONE` in their
+     * hardware requirements.
+     */
+    get hasPermission(): boolean;
+    /**
+     * 🎤 Subscribe to raw PCM audio chunks from the microphone.
+     *
+     * Audio is always 16 kHz mono 16-bit signed PCM. The first subscriber
+     * triggers an "audio_chunk" subscription to the cloud; the subscription
+     * is removed when the last handler unsubscribes.
+     *
+     * @param handler - Called with each audio chunk as it arrives
+     * @returns Cleanup function that removes this handler
+     *
+     * @example
+     * ```ts
+     * const stop = mic.onChunk((chunk) => {
+     *   // chunk.data is an ArrayBuffer of PCM16 samples
+     *   const samples = new Int16Array(chunk.data);
+     *   processAudio(samples);
+     * });
+     *
+     * // Later: unsubscribe
+     * stop();
+     * ```
+     */
+    onChunk(handler: (chunk: AudioChunk) => void): () => void;
+    /**
+     * 🗣️ Subscribe to voice activity detection events.
+     *
+     * VAD events indicate when the user starts or stops speaking. The
+     * `status` field from the glasses may be a boolean or a string
+     * ("true"/"false") — this manager normalizes it to a clean boolean.
+     *
+     * The first subscriber triggers a "VAD" subscription to the cloud and
+     * registers a handler on the DataStreamRouter. The subscription is
+     * removed when the last handler unsubscribes.
+     *
+     * @param handler - Called with each VAD event
+     * @returns Cleanup function that removes this handler
+     *
+     * @example
+     * ```ts
+     * const stop = mic.onVoiceActivity((vad) => {
+     *   if (vad.isSpeaking) {
+     *     console.log("User started speaking");
+     *   } else {
+     *     console.log("User stopped speaking");
+     *   }
+     * });
+     *
+     * // Later: unsubscribe
+     * stop();
+     * ```
+     */
+    onVoiceActivity(handler: (vad: VadEvent) => void): () => void;
+    /**
+     * 🛑 Stop all microphone subscriptions.
+     *
+     * Removes all registered chunk and VAD handlers, unsubscribes from
+     * both streams, and resets internal state. After calling `stop()`,
+     * `isActive` will be false and no more callbacks will fire.
+     *
+     * @example
+     * ```ts
+     * mic.onChunk(handleChunk);
+     * mic.onVoiceActivity(handleVad);
+     *
+     * // Later: clean up everything
+     * mic.stop();
+     * ```
+     */
+    stop(): void;
+    /**
+     * Handle an incoming binary audio frame from the WebSocket transport.
+     *
+     * MentraSession calls this method when it receives a binary WebSocket
+     * frame that is identified as microphone audio (not part of an output
+     * stream). The raw bytes are wrapped with metadata and dispatched to
+     * all registered `onChunk` handlers.
+     *
+     * @param data - Raw binary audio data (PCM16, 16 kHz, mono)
+     *
+     * @remarks
+     * This is a public method so MentraSession can call it, but it is not
+     * intended to be called by app developers.
+     *
+     * @internal
+     */
+    handleBinaryAudio(data: ArrayBuffer): void;
+    /**
+     * Process an incoming VAD DATA_STREAM message.
+     *
+     * The glasses send VAD with `status` that can be:
+     * - `true` / `false` (boolean)
+     * - `"true"` / `"false"` (string)
+     *
+     * This method normalizes the value to a clean boolean and caches it
+     * for the `isSpeaking` getter.
+     */
+    private handleVadMessage;
+}
+//# sourceMappingURL=MicManager.d.ts.map

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

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

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

@@ -0,0 +1,182 @@
+/**
+ * PermissionsManager — App Permission State
+ *
+ * Tracks which permissions the current app has been granted based on
+ * the app's manifest/registration on the developer console. Permissions
+ * are populated when the session connects (from CONNECTION_ACK settings)
+ * and can be queried synchronously by other managers.
+ *
+ * This manager is read-only from the app's perspective — permissions are
+ * controlled by the platform, not the app.
+ *
+ * @example
+ * ```ts
+ * // Check a single permission
+ * if (permissions.has("camera")) {
+ *   // Safe to use camera APIs
+ * }
+ *
+ * // Get all permissions
+ * const all = permissions.getAll();
+ * console.log("Notifications allowed:", all.notifications);
+ *
+ * // React to permission changes
+ * const cleanup = permissions.onUpdate((perms) => {
+ *   console.log("Permissions updated:", perms);
+ * });
+ * ```
+ *
+ * @module
+ */
+/**
+ * Permission types supported by the MentraOS platform.
+ *
+ * These correspond to capabilities and data streams that require
+ * explicit opt-in via the developer console app manifest.
+ */
+export type PermissionType = "location" | "microphone" | "camera" | "notifications" | "calendar";
+/**
+ * Complete permission record mapping every permission type to its grant status.
+ */
+export type PermissionRecord = Record<PermissionType, boolean>;
+/**
+ * Dependencies injected by MentraSession.
+ */
+export interface PermissionsManagerDeps {
+    /** Logger instance scoped to the session. */
+    logger: {
+        debug(...args: any[]): void;
+        info(...args: any[]): void;
+        warn(...args: any[]): void;
+        error(...args: any[]): void;
+    };
+    /** MessageHandlerRegistry — register for top-level message types. */
+    messageHandlers: {
+        register(type: string, handler: (msg: any) => void): () => void;
+    };
+}
+/**
+ * Manages the permission state for the current app session.
+ *
+ * Permissions are populated from the CONNECTION_ACK payload when the
+ * session is established. Other managers (DeviceManager, PhoneManager)
+ * query this manager to gate access to protected streams.
+ *
+ * The manager emits updates whenever the permission set changes, allowing
+ * UI or logic to react to permission grants/revocations in real time.
+ */
+export declare class PermissionsManager {
+    /** Current permission state. */
+    private permissions;
+    /** Registered update listeners. */
+    private listeners;
+    /** Logger instance. */
+    private logger;
+    /** Message handler registry for cloud message subscriptions. */
+    private messageHandlers;
+    constructor(deps: PermissionsManagerDeps);
+    /**
+     * Check whether the app has been granted a specific permission.
+     *
+     * @param permission - The permission type to check
+     * @returns `true` if the permission is granted, `false` otherwise
+     *
+     * @example
+     * ```ts
+     * if (permissions.has("microphone")) {
+     *   session.events.onTranscription(handler);
+     * }
+     * ```
+     */
+    has(permission: PermissionType): boolean;
+    /**
+     * Get a snapshot of all permissions as a record.
+     *
+     * The returned object is a copy — mutations do not affect internal state.
+     *
+     * @returns A record mapping every {@link PermissionType} to its grant status
+     *
+     * @example
+     * ```ts
+     * const perms = permissions.getAll();
+     * console.log("Camera:", perms.camera);
+     * console.log("Location:", perms.location);
+     * ```
+     */
+    getAll(): PermissionRecord;
+    /**
+     * Subscribe to permission updates.
+     *
+     * The handler is called whenever the permission set changes (e.g., on
+     * CONNECTION_ACK or a mid-session settings update). It receives a
+     * snapshot copy of the full permission record.
+     *
+     * @param handler - Callback invoked with the updated permission record
+     * @returns Cleanup function that removes the listener
+     *
+     * @example
+     * ```ts
+     * const cleanup = permissions.onUpdate((perms) => {
+     *   if (!perms.camera) {
+     *     console.warn("Camera permission revoked");
+     *   }
+     * });
+     *
+     * // Later: stop listening
+     * cleanup();
+     * ```
+     */
+    onUpdate(handler: (permissions: PermissionRecord) => void): () => void;
+    /**
+     * Listen for permission error events from the cloud.
+     * Fires when a bulk subscription is rejected due to missing permissions.
+     *
+     * @param handler - Callback invoked with the error details
+     * @returns Cleanup function that removes the listener
+     *
+     * @example
+     * ```ts
+     * const cleanup = permissions.onPermissionError((err) => {
+     *   console.error("Permission error:", err.message, err.deniedPermissions);
+     * });
+     * ```
+     */
+    onPermissionError(handler: (error: {
+        message: string;
+        deniedPermissions?: string[];
+    }) => void): () => void;
+    /**
+     * Listen for permission denied events from the cloud.
+     * Fires when an individual stream subscription is rejected.
+     *
+     * @param handler - Callback invoked with the denial details
+     * @returns Cleanup function that removes the listener
+     *
+     * @example
+     * ```ts
+     * const cleanup = permissions.onPermissionDenied((err) => {
+     *   console.warn("Denied:", err.permission, err.streamType);
+     * });
+     * ```
+     */
+    onPermissionDenied(handler: (error: {
+        message: string;
+        permission?: string;
+        streamType?: string;
+    }) => void): () => void;
+    /**
+     * Update permissions from connection settings or a settings update payload.
+     *
+     * Called internally by MentraSession when:
+     * - A CONNECTION_ACK is received with initial settings/permissions
+     * - A mid-session settings update includes permission changes
+     *
+     * Accepts flexible input — extracts permissions from nested structures
+     * commonly found in CONNECTION_ACK and settings_update payloads.
+     *
+     * @param settings - The raw settings object from the cloud message
+     * @internal
+     */
+    updateFromSettings(settings: any): void;
+}
+//# sourceMappingURL=PermissionsManager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PermissionsManager.d.ts","sourceRoot":"","sources":["../../../src/session/managers/PermissionsManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAIH;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,YAAY,GAAG,QAAQ,GAAG,eAAe,GAAG,UAAU,CAAC;AAEjG;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;AAE/D;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,6CAA6C;IAC7C,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,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;CACH;AA4BD;;;;;;;;;GASG;AACH,qBAAa,kBAAkB;IAC7B,gCAAgC;IAChC,OAAO,CAAC,WAAW,CAAmB;IAEtC,mCAAmC;IACnC,OAAO,CAAC,SAAS,CAA2D;IAE5E,uBAAuB;IACvB,OAAO,CAAC,MAAM,CAAmC;IAEjD,gEAAgE;IAChE,OAAO,CAAC,eAAe,CAA4C;gBAEvD,IAAI,EAAE,sBAAsB;IAQxC;;;;;;;;;;;;OAYG;IACH,GAAG,CAAC,UAAU,EAAE,cAAc,GAAG,OAAO;IAIxC;;;;;;;;;;;;;OAaG;IACH,MAAM,IAAI,gBAAgB;IAI1B;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,WAAW,EAAE,gBAAgB,KAAK,IAAI,GAAG,MAAM,IAAI;IAOtE;;;;;;;;;;;;;OAaG;IACH,iBAAiB,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,KAAK,IAAI,GAAG,MAAM,IAAI;IAW1G;;;;;;;;;;;;;OAaG;IACH,kBAAkB,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,GAAG,MAAM,IAAI;IAavH;;;;;;;;;;;;OAYG;IACH,kBAAkB,CAAC,QAAQ,EAAE,GAAG,GAAG,IAAI;CAqDxC"}