@mentra/sdk 1.1.19

package/dist/tpa/session/modules/streaming.js

@@ -0,0 +1,270 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StreamingModule = void 0;
+/**
+ * 📹 RTMP Streaming Module
+ *
+ * Provides functionality for TPAs to request and manage RTMP streams from smart glasses.
+ * Handles stream lifecycle, status monitoring, and cleanup.
+ */
+const types_1 = require("../../../types");
+const streams_1 = require("../../../types/streams");
+// Stream status information and handler types are imported from '../../../types/rtmp-stream'
+/**
+ * StreamingModule provides functionality for TPAs to request and manage RTMP streams.
+ *
+ * Streams can be requested with configurable parameters for video quality,
+ * audio settings, and stream constraints. Status updates are received through
+ * the standard subscription mechanism.
+ */
+class StreamingModule {
+    /**
+     * Create a new StreamingModule
+     *
+     * @param packageName - The TPA package name
+     * @param sessionId - The current session ID
+     * @param send - Function to send messages to the cloud
+     * @param session - Reference to the parent TpaSession (optional)
+     */
+    constructor(packageName, sessionId, send, session) {
+        this.isStreaming = false;
+        this.packageName = packageName;
+        this.sessionId = sessionId;
+        this.send = send;
+        this.session = session;
+    }
+    /**
+     * Begin an RTMP stream to the specified URL
+     *
+     * @param options - Configuration options for the stream
+     * @returns Promise that resolves when the stream request is sent (not when streaming begins)
+     */
+    async requestStream(options) {
+        console.log(`[RTMP_STREAM_REQUEST] StreamingModule.requestStream called`, {
+            debugKey: 'RTMP_STREAM_REQUEST',
+            packageName: this.packageName,
+            sessionId: this.sessionId,
+            rtmpUrl: options.rtmpUrl,
+            isCurrentlyStreaming: this.isStreaming,
+            currentStreamUrl: this.currentStreamUrl,
+            currentStreamState: this.currentStreamState
+        });
+        if (!options.rtmpUrl) {
+            throw new Error('rtmpUrl is required');
+        }
+        if (this.isStreaming) {
+            console.error(`[RTMP_STREAM_ALREADY_ACTIVE] Already streaming error`, {
+                debugKey: 'RTMP_STREAM_ALREADY_ACTIVE',
+                packageName: this.packageName,
+                sessionId: this.sessionId,
+                currentStreamUrl: this.currentStreamUrl,
+                requestedUrl: options.rtmpUrl,
+                currentStreamState: this.currentStreamState,
+                isStreaming: this.isStreaming
+            });
+            throw new Error('Already streaming. Stop the current stream before starting a new one.');
+        }
+        // Create stream request message
+        const message = {
+            type: types_1.TpaToCloudMessageType.RTMP_STREAM_REQUEST,
+            packageName: this.packageName,
+            sessionId: this.sessionId,
+            rtmpUrl: options.rtmpUrl,
+            video: options.video,
+            audio: options.audio,
+            stream: options.stream,
+            timestamp: new Date()
+        };
+        // Save stream URL for reference
+        this.currentStreamUrl = options.rtmpUrl;
+        // Send the request
+        try {
+            console.log(`[RTMP_STREAM_SENDING] Sending RTMP stream request`, {
+                debugKey: 'RTMP_STREAM_SENDING',
+                packageName: this.packageName,
+                sessionId: this.sessionId,
+                rtmpUrl: options.rtmpUrl,
+                messageType: message.type
+            });
+            this.send(message);
+            this.isStreaming = true;
+            console.log(`[RTMP_STREAM_REQUEST_SENT] RTMP stream request sent successfully`, {
+                debugKey: 'RTMP_STREAM_REQUEST_SENT',
+                packageName: this.packageName,
+                sessionId: this.sessionId,
+                isStreaming: this.isStreaming,
+                currentStreamUrl: this.currentStreamUrl
+            });
+            return Promise.resolve();
+        }
+        catch (error) {
+            console.error(`[RTMP_STREAM_REQUEST_FAIL] Failed to send RTMP stream request`, {
+                debugKey: 'RTMP_STREAM_REQUEST_FAIL',
+                packageName: this.packageName,
+                sessionId: this.sessionId,
+                error,
+                rtmpUrl: options.rtmpUrl
+            });
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return Promise.reject(new Error(`Failed to request RTMP stream: ${errorMessage}`));
+        }
+    }
+    /**
+     * Stop the current RTMP stream
+     *
+     * @returns Promise that resolves when the stop request is sent
+     */
+    async stopStream() {
+        console.log(`[RTMP_STREAM_STOP_REQUEST] StreamingModule.stopStream called`, {
+            debugKey: 'RTMP_STREAM_STOP_REQUEST',
+            packageName: this.packageName,
+            sessionId: this.sessionId,
+            isCurrentlyStreaming: this.isStreaming,
+            currentStreamUrl: this.currentStreamUrl,
+            currentStreamState: this.currentStreamState
+        });
+        if (!this.isStreaming) {
+            console.log(`[RTMP_STREAM_STOP_NOOP] Not streaming - no-op`, {
+                debugKey: 'RTMP_STREAM_STOP_NOOP',
+                packageName: this.packageName,
+                sessionId: this.sessionId
+            });
+            // Not an error - just a no-op if not streaming
+            return Promise.resolve();
+        }
+        // Create stop request message
+        const message = {
+            type: types_1.TpaToCloudMessageType.RTMP_STREAM_STOP,
+            packageName: this.packageName,
+            sessionId: this.sessionId,
+            streamId: this.currentStreamState?.streamId, // Include streamId if available
+            timestamp: new Date()
+        };
+        // Send the request
+        try {
+            this.send(message);
+            return Promise.resolve();
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return Promise.reject(new Error(`Failed to stop RTMP stream: ${errorMessage}`));
+        }
+    }
+    /**
+     * Check if currently streaming
+     *
+     * @returns True if a stream is active or initializing
+     */
+    isCurrentlyStreaming() {
+        return this.isStreaming;
+    }
+    /**
+     * Get the URL of the current stream (if any)
+     *
+     * @returns The RTMP URL of the current stream, or undefined if not streaming
+     */
+    getCurrentStreamUrl() {
+        return this.currentStreamUrl;
+    }
+    /**
+     * Get the current stream status
+     *
+     * @returns The current stream status, or undefined if not available
+     */
+    getStreamStatus() {
+        return this.currentStreamState;
+    }
+    /**
+     * Subscribe to RTMP stream status updates
+     * This uses the standard stream subscription mechanism
+     */
+    subscribeToStatusUpdates() {
+        if (this.session) {
+            this.session.subscribe(streams_1.StreamType.RTMP_STREAM_STATUS);
+        }
+        else {
+            console.error('Cannot subscribe to status updates: session reference not available');
+        }
+    }
+    /**
+     * Unsubscribe from RTMP stream status updates
+     */
+    unsubscribeFromStatusUpdates() {
+        if (this.session) {
+            this.session.unsubscribe(streams_1.StreamType.RTMP_STREAM_STATUS);
+        }
+    }
+    /**
+     * Listen for status updates using the standard event system
+     * @param handler - Function to call when stream status changes
+     * @returns Cleanup function to remove the handler
+     */
+    onStatus(handler) {
+        if (!this.session) {
+            console.error('Cannot listen for status updates: session reference not available');
+            return () => { };
+        }
+        this.subscribeToStatusUpdates();
+        return this.session.on(streams_1.StreamType.RTMP_STREAM_STATUS, handler);
+    }
+    /**
+     * Update internal stream state based on a status message
+     * For internal use by TpaSession
+     * @param message - The status message from the cloud
+     */
+    updateStreamState(message) {
+        console.log(`[RTMP_STREAM_STATE_UPDATE] StreamingModule.updateStreamState called`, {
+            debugKey: 'RTMP_STREAM_STATE_UPDATE',
+            packageName: this.packageName,
+            sessionId: this.sessionId,
+            messageType: message?.type,
+            messageStatus: message?.status,
+            currentIsStreaming: this.isStreaming
+        });
+        // Verify this is a valid stream response
+        if (!(0, types_1.isRtmpStreamStatus)(message)) {
+            console.warn('[RTMP_STREAM_INVALID_STATUS] Received invalid stream status message', {
+                debugKey: 'RTMP_STREAM_INVALID_STATUS',
+                packageName: this.packageName,
+                sessionId: this.sessionId,
+                message
+            });
+            return;
+        }
+        // Convert to StreamStatus format
+        const status = {
+            type: message.type,
+            streamId: message.streamId,
+            status: message.status,
+            errorDetails: message.errorDetails,
+            appId: message.appId,
+            stats: message.stats,
+            timestamp: message.timestamp || new Date()
+        };
+        console.log(`[RTMP_STREAM_STATUS_PROCESSED] Stream status processed`, {
+            debugKey: 'RTMP_STREAM_STATUS_PROCESSED',
+            packageName: this.packageName,
+            sessionId: this.sessionId,
+            streamId: status.streamId,
+            oldStatus: this.currentStreamState?.status,
+            newStatus: status.status,
+            wasStreaming: this.isStreaming
+        });
+        // Updated logic to check for timeout to handle resetting state.
+        // Update local state based on status
+        if (status.status === 'stopped' || status.status === 'error' || status.status === 'timeout') {
+            console.log(`[RTMP_STREAM_STATE_STOPPED] Stream stopped - updating local state`, {
+                debugKey: 'RTMP_STREAM_STATE_STOPPED',
+                packageName: this.packageName,
+                sessionId: this.sessionId,
+                status: status.status,
+                wasStreaming: this.isStreaming
+            });
+            this.isStreaming = false;
+            this.currentStreamUrl = undefined;
+        }
+        // Save the latest status
+        this.currentStreamState = status;
+    }
+}
+exports.StreamingModule = StreamingModule;

package/dist/tpa/session/settings.d.ts

@@ -0,0 +1,202 @@
+import { AppSetting, AppSettings } from '../../types';
+/**
+ * Change information for a single setting
+ */
+export interface SettingChange {
+    oldValue: any;
+    newValue: any;
+}
+/**
+ * Map of setting keys to their change information
+ */
+export type SettingsChangeMap = Record<string, SettingChange>;
+/**
+ * Callback for when any setting changes
+ */
+export type SettingsChangeHandler = (changes: SettingsChangeMap) => void;
+/**
+ * Callback for when a specific setting changes
+ */
+export type SettingValueChangeHandler<T = any> = (newValue: T, oldValue: T) => void;
+/**
+ * 🔧 Settings Manager
+ *
+ * Provides a type-safe interface for accessing and reacting to TPA settings.
+ * Automatically synchronizes with AugmentOS Cloud.
+ */
+export declare class SettingsManager {
+    private settings;
+    private emitter;
+    private apiClient?;
+    private augmentosSettings;
+    private augmentosEmitter;
+    private subscribeFn?;
+    /**
+     * Create a new settings manager
+     *
+     * @param initialSettings Initial settings values (if available)
+     * @param packageName Package name for the TPA
+     * @param wsUrl WebSocket URL (for deriving HTTP API URL)
+     * @param userId User ID (for authenticated requests)
+     * @param subscribeFn Optional function to call to subscribe to streams
+     */
+    constructor(initialSettings?: AppSettings, packageName?: string, wsUrl?: string, userId?: string, subscribeFn?: (streams: string[]) => Promise<void>);
+    /**
+     * Configure the API client
+     *
+     * @param packageName Package name for the TPA
+     * @param wsUrl WebSocket URL
+     * @param userId User ID
+     */
+    configureApiClient(packageName: string, wsUrl: string, userId: string): void;
+    /**
+     * Update the current settings
+     * This is called internally when settings are loaded or changed
+     *
+     * @param newSettings New settings values
+     * @returns Map of changed settings
+     */
+    updateSettings(newSettings: AppSettings): SettingsChangeMap;
+    /**
+     * Check if two setting values are equal
+     *
+     * @param a First value
+     * @param b Second value
+     * @returns True if the values are equal
+     */
+    private areEqual;
+    /**
+     * Emit change events for updated settings
+     *
+     * @param changes Map of changed settings
+     */
+    private emitChanges;
+    /**
+     * 🔄 Listen for changes to any setting
+     *
+     * @param handler Function to call when settings change
+     * @returns Function to remove the listener
+     *
+     * @example
+     * ```typescript
+     * settings.onChange((changes) => {
+     *   console.log('Settings changed:', changes);
+     * });
+     * ```
+     */
+    onChange(handler: SettingsChangeHandler): () => void;
+    /**
+     * 🔄 Listen for changes to a specific setting
+     *
+     * @param key Setting key to monitor
+     * @param handler Function to call when the setting changes
+     * @returns Function to remove the listener
+     *
+     * @example
+     * ```typescript
+     * settings.onValueChange('transcribe_language', (newValue, oldValue) => {
+     *   console.log(`Language changed from ${oldValue} to ${newValue}`);
+     * });
+     * ```
+     */
+    onValueChange<T = any>(key: string, handler: SettingValueChangeHandler<T>): () => void;
+    /**
+     * 🔍 Check if a setting exists
+     *
+     * @param key Setting key to check
+     * @returns True if the setting exists
+     */
+    has(key: string): boolean;
+    /**
+     * 🔍 Get all settings
+     *
+     * @returns Copy of all settings
+     */
+    getAll(): AppSettings;
+    /**
+     * 🔍 Get a setting value with type safety
+     *
+     * @param key Setting key to get
+     * @param defaultValue Default value if setting doesn't exist or is undefined
+     * @returns Setting value or default value
+     *
+     * @example
+     * ```typescript
+     * const lineWidth = settings.get<number>('line_width', 30);
+     * const language = settings.get<string>('transcribe_language', 'English');
+     * ```
+     */
+    get<T = any>(key: string, defaultValue?: T): T;
+    /**
+     * 🎛️ Get an AugmentOS system setting value with optional default
+     *
+     * @param key AugmentOS setting key (e.g., 'metricSystemEnabled', 'brightness')
+     * @param defaultValue Default value to return if the setting is not found
+     * @returns The setting value or the default value
+     *
+     * @example
+     * ```typescript
+     * const isMetric = settings.getAugmentOS<boolean>('metricSystemEnabled', false);
+     * const brightness = settings.getAugmentOS<number>('brightness', 50);
+     * ```
+     */
+    getAugmentOS<T = any>(key: string, defaultValue?: T): T;
+    /**
+     * 🔍 Find a setting by key
+     *
+     * @param key Setting key to find
+     * @returns Setting object or undefined
+     */
+    getSetting(key: string): AppSetting | undefined;
+    /**
+     * 🔄 Fetch settings from the cloud
+     * This is generally not needed since settings are automatically kept in sync,
+     * but can be used to force a refresh if needed.
+     *
+     * @returns Promise that resolves to the updated settings
+     * @throws Error if the API client is not configured or the request fails
+     */
+    fetch(): Promise<AppSettings>;
+    /**
+     * 🎛️ Listen for changes to a specific AugmentOS setting (e.g., metricSystemEnabled)
+     *
+     * @param key The augmentosSettings key to listen for (e.g., 'metricSystemEnabled')
+     * @param handler Function to call when the value changes
+     * @returns Function to remove the listener
+     *
+     * @example
+     * ```typescript
+     * settings.onAugmentOSChange('metricSystemEnabled', (isMetric, wasMetric) => {
+     *   console.log(`Units changed: ${wasMetric ? 'metric' : 'imperial'} → ${isMetric ? 'metric' : 'imperial'}`);
+     * });
+     * ```
+     */
+    onAugmentOSChange<T = any>(key: string, handler: SettingValueChangeHandler<T>): () => void;
+    /**
+     * Listen for changes to a specific AugmentOS setting (e.g., metricSystemEnabled)
+     * This is a convenience wrapper for onValueChange for well-known augmentosSettings keys.
+     * @param key The augmentosSettings key to listen for (e.g., 'metricSystemEnabled')
+     * @param handler Function to call when the value changes
+     * @returns Function to remove the listener
+     * @deprecated Use onAugmentOSChange instead
+     */
+    onAugmentosSettingsChange<T = any>(key: string, handler: SettingValueChangeHandler<T>): () => void;
+    /**
+     * Update the current AugmentOS settings
+     * Compares new and old values, emits per-key events, and updates stored values.
+     * @param newSettings The new AugmentOS settings object
+     */
+    updateAugmentosSettings(newSettings: Record<string, any>): void;
+    /**
+     * Subscribe to changes for a specific AugmentOS setting (e.g., 'metricSystemEnabled')
+     * @param key The AugmentOS setting key to listen for
+     * @param handler Function to call when the value changes (newValue, oldValue)
+     * @returns Function to remove the listener
+     */
+    onAugmentosSettingChange<T = any>(key: string, handler: (newValue: T, oldValue: T) => void): () => void;
+    /**
+     * Get the current value of an AugmentOS setting
+     */
+    getAugmentosSetting<T = any>(key: string, defaultValue?: T): T;
+}
+//# sourceMappingURL=settings.d.ts.map

package/dist/tpa/session/settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../../../src/tpa/session/settings.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAMtD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,GAAG,CAAC;IACd,QAAQ,EAAE,GAAG,CAAC;CACf;AAED;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAE9D;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,CAAC;AAEzE;;GAEG;AACH,MAAM,MAAM,yBAAyB,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,KAAK,IAAI,CAAC;AAUpF;;;;;GAKG;AACH,qBAAa,eAAe;IAE1B,OAAO,CAAC,QAAQ,CAAmB;IAGnC,OAAO,CAAC,OAAO,CAAsB;IAGrC,OAAO,CAAC,SAAS,CAAC,CAAY;IAG9B,OAAO,CAAC,iBAAiB,CAA2B;IACpD,OAAO,CAAC,gBAAgB,CAAsB;IAC9C,OAAO,CAAC,WAAW,CAAC,CAAuC;IAE3D;;;;;;;;OAQG;gBAED,eAAe,GAAE,WAAgB,EACjC,WAAW,CAAC,EAAE,MAAM,EACpB,KAAK,CAAC,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,MAAM,EACf,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC;IAWpD;;;;;;OAMG;IACH,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAS5E;;;;;;OAMG;IACH,cAAc,CAAC,WAAW,EAAE,WAAW,GAAG,iBAAiB;IA2C3D;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ;IAMhB;;;;OAIG;IACH,OAAO,CAAC,WAAW;IAUnB;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,OAAO,EAAE,qBAAqB,GAAG,MAAM,IAAI;IAKpD;;;;;;;;;;;;;OAaG;IACH,aAAa,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,yBAAyB,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;IAMtF;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIzB;;;;OAIG;IACH,MAAM,IAAI,WAAW;IAIrB;;;;;;;;;;;;OAYG;IACH,GAAG,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,CAAC,GAAG,CAAC;IAU9C;;;;;;;;;;;;OAYG;IACH,YAAY,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,CAAC,GAAG,CAAC;IAUvD;;;;;OAKG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAI/C;;;;;;;OAOG;IACG,KAAK,IAAI,OAAO,CAAC,WAAW,CAAC;IAenC;;;;;;;;;;;;;OAaG;IACH,iBAAiB,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,yBAAyB,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;IAI1F;;;;;;;OAOG;IACH,yBAAyB,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,yBAAyB,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;IAIlG;;;;OAIG;IACH,uBAAuB,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI;IAsB/D;;;;;OAKG;IACH,wBAAwB,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI;IA4BvG;;OAEG;IACH,mBAAmB,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,CAAC,GAAG,CAAC;CAO/D"}