@mentra/sdk 2.1.27 → 2.1.28

package/dist/app/session/layouts.js

@@ -1,372 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.LayoutManager = void 0;
-/**
- * 🎨 Layout Manager Module
- *
- * Manages AR display layouts for Apps. This class provides an easy-to-use interface
- * for showing different types of content in the user's AR view.
- *
- * @example
- * ```typescript
- * const layouts = new LayoutManager('org.example.myapp', sendMessage);
- *
- * // Show a simple message
- * layouts.showTextWall('Hello AR World!');
- *
- * // Show a card with title
- * layouts.showReferenceCard('Weather', 'Sunny and 75°F');
- * ```
- */
-const bitmap_utils_1 = require("../../utils/bitmap-utils");
-const types_1 = require("../../types");
-class LayoutManager {
-    /**
-     * 🎯 Creates a new LayoutManager instance
-     *
-     * @param packageName - App package identifier
-     * @param sendMessage - Function to send display requests to MentraOS
-     */
-    constructor(packageName, sendMessage) {
-        this.packageName = packageName;
-        this.sendMessage = sendMessage;
-    }
-    /**
-     * 📦 Creates a display event request with validation
-     *
-     * @param layout - Layout configuration to display
-     * @param view - View type (main or dashboard)
-     * @param durationMs - How long to show the layout (optional)
-     * @returns Formatted display request
-     * @throws Error if layout is invalid
-     */
-    createDisplayEvent(layout, view = types_1.ViewType.MAIN, durationMs) {
-        try {
-            // Validate layout data before sending
-            if (!layout) {
-                throw new Error("Layout cannot be null or undefined");
-            }
-            if (!layout.layoutType) {
-                throw new Error("Layout must have a layoutType property");
-            }
-            // Layout-specific validations
-            switch (layout.layoutType) {
-                case types_1.LayoutType.TEXT_WALL:
-                    if (typeof layout.text !== "string") {
-                        throw new Error("TextWall layout must have a text property");
-                    }
-                    // Ensure text is not too long (prevent performance issues)
-                    if (layout.text.length > 1000) {
-                        console.warn("TextWall text is very long, this may cause performance issues");
-                    }
-                    break;
-                case types_1.LayoutType.DOUBLE_TEXT_WALL:
-                    const doubleText = layout;
-                    if (typeof doubleText.topText !== "string") {
-                        throw new Error("DoubleTextWall layout must have a topText property");
-                    }
-                    if (typeof doubleText.bottomText !== "string") {
-                        throw new Error("DoubleTextWall layout must have a bottomText property");
-                    }
-                    break;
-                case types_1.LayoutType.REFERENCE_CARD:
-                    const refCard = layout;
-                    if (typeof refCard.title !== "string") {
-                        throw new Error("ReferenceCard layout must have a title property");
-                    }
-                    if (typeof refCard.text !== "string") {
-                        throw new Error("ReferenceCard layout must have a text property");
-                    }
-                    break;
-                case types_1.LayoutType.DASHBOARD_CARD:
-                    const dashCard = layout;
-                    if (typeof dashCard.leftText !== "string") {
-                        throw new Error("DashboardCard layout must have a leftText property");
-                    }
-                    if (typeof dashCard.rightText !== "string") {
-                        throw new Error("DashboardCard layout must have a rightText property");
-                    }
-                    break;
-                case types_1.LayoutType.BITMAP_VIEW:
-                    const bitmapView = layout;
-                    if (typeof bitmapView.data !== "string") {
-                        throw new Error("BitmapView layout must have a data property");
-                    }
-                    // Check if data is too large (prevent OOM errors)
-                    if (bitmapView.data.length > 1000000) {
-                        // 1MB limit
-                        throw new Error("Bitmap data is too large (>1MB), please reduce size");
-                    }
-                    break;
-                case types_1.LayoutType.CLEAR_VIEW:
-                    // ClearView has no additional validation needed
-                    break;
-            }
-            // Validate view type
-            if (view !== types_1.ViewType.MAIN && view !== types_1.ViewType.DASHBOARD) {
-                console.warn(`Invalid view type: ${view}, defaulting to MAIN`);
-                view = types_1.ViewType.MAIN;
-            }
-            // Validate duration if provided
-            if (durationMs !== undefined) {
-                if (typeof durationMs !== "number" || durationMs < 0) {
-                    console.warn(`Invalid duration: ${durationMs}, ignoring`);
-                    durationMs = undefined;
-                }
-            }
-            // Create the display request with validated data
-            return {
-                timestamp: new Date(),
-                sessionId: "", // Will be filled by session
-                type: types_1.AppToCloudMessageType.DISPLAY_REQUEST,
-                packageName: this.packageName,
-                view,
-                layout,
-                durationMs,
-            };
-        }
-        catch (error) {
-            console.error("Error creating display event:", error);
-            throw error; // Re-throw to notify caller
-        }
-    }
-    /**
-     * 📝 Shows a single block of text
-     *
-     * Best for:
-     * - Simple messages
-     * - Status updates
-     * - Notifications
-     *
-     * @param text - Text content to display
-     * @param options - Optional parameters (view, duration, priority)
-     *   - priority: If true, this display will not be overridden by other requests (default: false)
-     *
-     * @example
-     * ```typescript
-     * layouts.showTextWall('Connected to server');
-     * layouts.showTextWall('Onboarding!', { priority: true });
-     * ```
-     */
-    showTextWall(text, options) {
-        try {
-            // Validate input before processing
-            if (text === undefined || text === null) {
-                text = ""; // Default to empty string instead of crashing
-                console.warn("showTextWall called with null/undefined text");
-            }
-            // Ensure text is a string
-            if (typeof text !== "string") {
-                text = String(text); // Convert to string
-                console.warn("showTextWall: Non-string input converted to string");
-            }
-            // Create layout with validated text
-            const layout = {
-                layoutType: types_1.LayoutType.TEXT_WALL,
-                text,
-            };
-            // Create and send display event with error handling
-            try {
-                const displayEvent = this.createDisplayEvent(layout, options?.view, options?.durationMs);
-                this.sendMessage(displayEvent);
-            }
-            catch (error) {
-                console.error("Failed to display text wall:", error);
-                // Don't re-throw - prevent app crashes
-            }
-        }
-        catch (error) {
-            console.error("Error in showTextWall:", error);
-            // Don't crash the App - fail gracefully
-        }
-    }
-    /**
-     * ↕️ Shows two sections of text, one above the other
-     *
-     * Best for:
-     * - Before/After content
-     * - Question/Answer displays
-     * - Two-part messages
-     * - Comparisons
-     *
-     * @param topText - Text to show in top section
-     * @param bottomText - Text to show in bottom section
-     * @param options - Optional parameters (view, duration)
-     *
-     * @example
-     * ```typescript
-     * layouts.showDoubleTextWall(
-     *   'Original: Hello',
-     *   'Translated: Bonjour'
-     * );
-     * ```
-     */
-    showDoubleTextWall(topText, bottomText, options) {
-        const layout = {
-            layoutType: types_1.LayoutType.DOUBLE_TEXT_WALL,
-            topText,
-            bottomText,
-        };
-        this.sendMessage(this.createDisplayEvent(layout, options?.view, options?.durationMs));
-    }
-    /**
-     * 📇 Shows a card with a title and content
-     *
-     * Best for:
-     * - Titled content
-     * - Important information
-     * - Structured data
-     * - Notifications with context
-     *
-     * @param title - Card title
-     * @param text - Main content text
-     * @param options - Optional parameters (view, duration)
-     *
-     * @example
-     * ```typescript
-     * layouts.showReferenceCard(
-     *   'Meeting Reminder',
-     *   'Team standup in 5 minutes'
-     * );
-     * ```
-     */
-    showReferenceCard(title, text, options) {
-        const layout = {
-            layoutType: types_1.LayoutType.REFERENCE_CARD,
-            title,
-            text,
-        };
-        this.sendMessage(this.createDisplayEvent(layout, options?.view, options?.durationMs));
-    }
-    /**
-     * 📇 Shows a bitmap
-     *
-     * Uses the proven animation system internally for proper L/R eye synchronization.
-     * This ensures single bitmap displays work consistently with the same
-     * hardware-optimized timing as animations.
-     *
-     * @param data - hex or base64 encoded bitmap data
-     * @param options - Optional parameters (view, duration)
-     *
-     * @example
-     * ```typescript
-     * layouts.showBitmapView(
-     *   yourHexOrBase64EncodedBitmapDataString
-     * );
-     * ```
-     */
-    async showBitmapView(base64Bitmap, options) {
-        const padding = options?.padding ?? { left: 50, top: 35 };
-        const bitmapFrame = await bitmap_utils_1.BitmapUtils.padBase64Bitmap(base64Bitmap, padding);
-        const validation = bitmap_utils_1.BitmapUtils.validateBase64Bitmap(bitmapFrame);
-        if (!validation.isValid) {
-            throw new Error(`❌ Frame validation failed: ${validation.errors.join(", ")}`);
-        }
-        const layout = {
-            layoutType: types_1.LayoutType.BITMAP_VIEW,
-            data: bitmapFrame,
-        };
-        this.sendMessage(this.createDisplayEvent(layout, options?.view));
-    }
-    /**
-     * 📊 Shows a dashboard card with left and right text
-     *
-     * Best for:
-     * - Key-value pairs
-     * - Dashboard displays
-     * - Metrics
-     *
-     * @param leftText - Left side text (typically label/key)
-     * @param rightText - Right side text (typically value)
-     * @param options - Optional parameters (view, duration)
-     *
-     * @example
-     * ```typescript
-     * layouts.showDashboardCard('Weather', '72°F');
-     * ```
-     */
-    showDashboardCard(leftText, rightText, options) {
-        const layout = {
-            layoutType: types_1.LayoutType.DASHBOARD_CARD,
-            leftText,
-            rightText,
-        };
-        this.sendMessage(this.createDisplayEvent(layout, options?.view || types_1.ViewType.DASHBOARD, options?.durationMs));
-    }
-    /**
-     * 🧹 Clears the display
-     *
-     * Best for:
-     * - Clearing previous content
-     * - Resetting display state
-     * - Starting fresh
-     *
-     * @param options - Optional parameters (view)
-     *
-     * @example
-     * ```typescript
-     * layouts.clearView();
-     * layouts.clearView({ view: ViewType.DASHBOARD });
-     * ```
-     */
-    clearView(options) {
-        const layout = {
-            layoutType: types_1.LayoutType.CLEAR_VIEW,
-        };
-        this.sendMessage(this.createDisplayEvent(layout, options?.view));
-    }
-    /**
-     * 🎬 Shows an animated sequence of bitmap images (iOS-controlled timing)
-     *
-     * Sends complete animation package to iOS for device-controlled timing.
-     * This provides superior performance and synchronization by letting
-     * the device control the display timing directly.
-     *
-     * Best for:
-     * - Smooth high-performance animations
-     * - Precise timing control
-     * - Synchronized left/right display
-     * - EvenDemo-quality performance
-     *
-     * @param bitmapDataArray - Array of bitmap data strings (hex or base64 encoded)
-     * @param intervalMs - Time between frames in milliseconds (default: 1650ms)
-     * @param repeat - Whether to loop the animation continuously (default: false)
-     * @param options - Optional parameters (view)
-     *
-     * @example
-     * ```typescript
-     * // Device-controlled animation (recommended)
-     * const frames = ['hexdata1', 'hexdata2', 'hexdata3'];
-     * layouts.showBitmapAnimation(frames, 1650, true);
-     *
-     * // Single-cycle animation
-     * layouts.showBitmapAnimation(loadingFrames, 1650, false);
-     * ```
-     *
-     * @returns Animation controller object with stop() method
-     */
-    showBitmapAnimation(bitmapDataArray, intervalMs = 1650, repeat = false, options) {
-        // Validation
-        if (!Array.isArray(bitmapDataArray) || bitmapDataArray.length === 0) {
-            throw new Error("showBitmapAnimation requires a non-empty array of bitmap data");
-        }
-        // Send complete animation package to iOS for device-controlled timing
-        const layout = {
-            layoutType: types_1.LayoutType.BITMAP_ANIMATION,
-            frames: bitmapDataArray,
-            interval: intervalMs,
-            repeat: repeat,
-        };
-        this.sendMessage(this.createDisplayEvent(layout, options?.view));
-        console.log(`🎬 Sent batched animation to iOS: ${bitmapDataArray.length} frames at ${intervalMs}ms${repeat ? " (repeating)" : ""}`);
-        // Return controller for compatibility
-        return {
-            stop: () => {
-                // Send stop command to iOS
-                this.clearView();
-                console.log("🛑 Animation stop requested");
-            },
-        };
-    }
-}
-exports.LayoutManager = LayoutManager;

package/dist/app/session/modules/audio.js

@@ -1,321 +0,0 @@
-"use strict";
-/**
- * 🔊 Audio Module
- *
- * Audio functionality for App Sessions.
- * Handles audio playback on connected glasses.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.AudioManager = void 0;
-const types_1 = require("../../../types");
-/**
- * 🔊 Audio Module Implementation
- *
- * Audio management for App Sessions.
- * Provides methods for:
- * - 🎵 Playing audio on glasses
- * - ⏹️ Stopping audio playback
- * - 🔍 Monitoring audio request status
- * - 🧹 Cleanup and cancellation
- *
- * @example
- * ```typescript
- * // Play audio
- * const result = await session.audio.playAudio({
- *   audioUrl: 'https://example.com/sound.mp3',
- *   volume: 0.8
- * });
- *
- * // Stop all audio
- * session.audio.stopAudio();
- * ```
- */
-class AudioManager {
-    /**
-     * Create a new AudioManager
-     *
-     * @param packageName - The App package name
-     * @param sessionId - The current session ID
-     * @param send - Function to send messages to the cloud
-     * @param session - Reference to the parent AppSession (optional)
-     * @param logger - Logger instance for debugging
-     */
-    constructor(packageName, sessionId, send, session, logger) {
-        /** Map to store pending audio play request promises */
-        this.pendingAudioRequests = new Map();
-        this.packageName = packageName;
-        this.sessionId = sessionId;
-        this.send = send;
-        this.session = session;
-        this.logger = logger || console;
-    }
-    // =====================================
-    // 🎵 Audio Playback Functionality
-    // =====================================
-    /**
-     * 🔊 Play audio on the connected glasses
-     * @param options - Audio playback configuration
-     * @returns Promise that resolves with playback result
-     *
-     * @example
-     * ```typescript
-     * // Play audio from URL
-     * const result = await session.audio.playAudio({
-     *   audioUrl: 'https://example.com/sound.mp3',
-     *   volume: 0.8
-     * });
-     * ```
-     */
-    async playAudio(options) {
-        return new Promise((resolve, reject) => {
-            try {
-                // Validate input
-                if (!options.audioUrl) {
-                    reject("audioUrl must be provided");
-                    return;
-                }
-                // Generate unique request ID
-                const requestId = `audio_req_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
-                // Store promise resolvers for when we get the response
-                this.pendingAudioRequests.set(requestId, { resolve, reject });
-                // Create audio play request message
-                const message = {
-                    type: types_1.AppToCloudMessageType.AUDIO_PLAY_REQUEST,
-                    packageName: this.packageName,
-                    sessionId: this.sessionId,
-                    requestId,
-                    timestamp: new Date(),
-                    audioUrl: options.audioUrl,
-                    volume: options.volume ?? 1.0,
-                    stopOtherAudio: options.stopOtherAudio ?? true,
-                };
-                // Send request to cloud
-                this.send(message);
-                // Set timeout to avoid hanging promises
-                const timeoutMs = 60000; // 60 seconds
-                if (this.session && this.session.resources) {
-                    // Use session's resource tracker for automatic cleeanup
-                    this.session.resources.setTimeout(() => {
-                        if (this.pendingAudioRequests.has(requestId)) {
-                            this.pendingAudioRequests
-                                .get(requestId)
-                                .reject("Audio play request timed out");
-                            this.pendingAudioRequests.delete(requestId);
-                            this.logger.warn({ requestId }, `🔊 Audio play request timed out`);
-                        }
-                    }, timeoutMs);
-                }
-                else {
-                    // Fallback to regular setTimeout if session not available
-                    setTimeout(() => {
-                        if (this.pendingAudioRequests.has(requestId)) {
-                            this.pendingAudioRequests
-                                .get(requestId)
-                                .reject("Audio play request timed out");
-                            this.pendingAudioRequests.delete(requestId);
-                            this.logger.warn({ requestId }, `🔊 Audio play request timed out`);
-                        }
-                    }, timeoutMs);
-                }
-            }
-            catch (error) {
-                const errorMessage = error instanceof Error ? error.message : String(error);
-                reject(`Failed to play audio: ${errorMessage}`);
-            }
-        });
-    }
-    /**
-     * 🔇 Stop audio playback on the connected glasses
-     *
-     * @example
-     * ```typescript
-     * // Stop all currently playing audio
-     * session.audio.stopAudio();
-     * ```
-     */
-    stopAudio() {
-        try {
-            // Create audio stop request message
-            const message = {
-                type: types_1.AppToCloudMessageType.AUDIO_STOP_REQUEST,
-                packageName: this.packageName,
-                sessionId: this.sessionId,
-                timestamp: new Date(),
-            };
-            // Send request to cloud (one-way, no response expected)
-            this.send(message);
-            this.logger.info(`🔇 Audio stop request sent`);
-        }
-        catch (error) {
-            const errorMessage = error instanceof Error ? error.message : String(error);
-            this.logger.error(`Failed to stop audio: ${errorMessage}`);
-        }
-    }
-    /**
-     * 🗣️ Convert text to speech and play it on the connected glasses
-     * @param text - Text to convert to speech (required)
-     * @param options - Text-to-speech configuration (optional)
-     * @returns Promise that resolves with playback result
-     *
-     * @example
-     * ```typescript
-     * // Basic text-to-speech
-     * const result = await session.audio.speak('Hello, world!');
-     *
-     * // With custom voice settings
-     * const result = await session.audio.speak('Hello, world!', {
-     *   voice_id: 'your_voice_id',
-     *   voice_settings: {
-     *     stability: 0.5,
-     *     speed: 1.2
-     *   },
-     *   volume: 0.8
-     * });
-     * ```
-     */
-    async speak(text, options = {}) {
-        // Validate input
-        if (!text) {
-            throw new Error("text must be provided");
-        }
-        // Get the HTTPS server URL from the session
-        const baseUrl = this.session?.getHttpsServerUrl?.();
-        if (!baseUrl) {
-            throw new Error("Cannot determine server URL for TTS endpoint");
-        }
-        // Build query parameters for the TTS endpoint
-        const queryParams = new URLSearchParams();
-        queryParams.append("text", text);
-        if (options.voice_id) {
-            queryParams.append("voice_id", options.voice_id);
-        }
-        if (options.model_id) {
-            queryParams.append("model_id", options.model_id);
-        }
-        if (options.voice_settings) {
-            queryParams.append("voice_settings", JSON.stringify(options.voice_settings));
-        }
-        // Construct the TTS URL
-        const ttsUrl = `${baseUrl}/api/tts?${queryParams.toString()}`;
-        this.logger.info({ text, ttsUrl }, `🗣️ Generating speech from text`);
-        // Use the existing playAudio method to play the TTS audio
-        return this.playAudio({
-            audioUrl: ttsUrl,
-            volume: options.volume,
-        });
-    }
-    // =====================================
-    // 📥 Response Handling
-    // =====================================
-    /**
-     * 📥 Handle audio play response from cloud
-     *
-     * This method is called internally when an audio play response is received.
-     * It resolves the corresponding pending promise with the response data.
-     *
-     * @param response - The audio play response received
-     * @internal This method is used internally by AppSession
-     */
-    handleAudioPlayResponse(response) {
-        const pendingRequest = this.pendingAudioRequests.get(response.requestId);
-        if (pendingRequest) {
-            // Resolve the promise with the response data
-            pendingRequest.resolve({
-                success: response.success,
-                error: response.error,
-                duration: response.duration,
-            });
-            // Clean up
-            this.pendingAudioRequests.delete(response.requestId);
-            this.logger.info({
-                requestId: response.requestId,
-                success: response.success,
-                duration: response.duration,
-            }, `🔊 Audio play response received`);
-        }
-        else {
-            this.logger.warn({ requestId: response.requestId }, `🔊 Received audio play response for unknown request ID`);
-        }
-    }
-    // =====================================
-    // 🔍 Status and Management
-    // =====================================
-    /**
-     * 🔍 Check if there are pending audio requests
-     * @param requestId - Optional specific request ID to check
-     * @returns True if there are pending requests (or specific request exists)
-     */
-    hasPendingRequest(requestId) {
-        if (requestId) {
-            return this.pendingAudioRequests.has(requestId);
-        }
-        return this.pendingAudioRequests.size > 0;
-    }
-    /**
-     * 📊 Get the number of pending audio requests
-     * @returns Number of pending requests
-     */
-    getPendingRequestCount() {
-        return this.pendingAudioRequests.size;
-    }
-    /**
-     * 📋 Get all pending request IDs
-     * @returns Array of pending request IDs
-     */
-    getPendingRequestIds() {
-        return Array.from(this.pendingAudioRequests.keys());
-    }
-    /**
-     * ❌ Cancel a specific audio request
-     * @param requestId - The request ID to cancel
-     * @returns True if the request was found and cancelled
-     */
-    cancelAudioRequest(requestId) {
-        const pendingRequest = this.pendingAudioRequests.get(requestId);
-        if (pendingRequest) {
-            pendingRequest.reject("Audio request cancelled");
-            this.pendingAudioRequests.delete(requestId);
-            this.logger.info({ requestId }, `🔊 Audio request cancelled`);
-            return true;
-        }
-        return false;
-    }
-    /**
-     * 🧹 Cancel all pending audio requests
-     * @returns Number of requests that were cancelled
-     */
-    cancelAllAudioRequests() {
-        const count = this.pendingAudioRequests.size;
-        this.pendingAudioRequests.forEach((request, requestId) => {
-            request.reject("Audio request cancelled due to cleanup");
-            this.logger.debug({ requestId }, `🔊 Audio request cancelled during cleanup`);
-        });
-        this.pendingAudioRequests.clear();
-        if (count > 0) {
-            this.logger.info({ cancelledCount: count }, `🧹 Cancelled all pending audio requests`);
-        }
-        return count;
-    }
-    // =====================================
-    // 🔧 Internal Management
-    // =====================================
-    /**
-     * 🔄 Update the session ID when reconnecting
-     * @param newSessionId - The new session ID
-     * @internal Used by AppSession during reconnection
-     */
-    updateSessionId(newSessionId) {
-        this.sessionId = newSessionId;
-        this.logger.debug({ newSessionId }, `🔄 Audio module session ID updated`);
-    }
-    /**
-     * 🧹 Cancel all pending requests (cleanup)
-     * @returns Object with count of cancelled requests
-     * @internal Used by AppSession during cleanup
-     */
-    cancelAllRequests() {
-        const audioRequests = this.cancelAllAudioRequests();
-        return { audioRequests };
-    }
-}
-exports.AudioManager = AudioManager;