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

package/dist/internal/_SessionManager.d.ts

@@ -0,0 +1,76 @@
+/**
+ * _SessionManager
+ *
+ * Consolidated server-level session orchestrator. Merges the responsibilities
+ * of the previous four separate classes into one:
+ *
+ *   _MentraSessionServerFactory  → createSession()
+ *   _MiniAppSessionRegistry      → session tracking (bySessionId, byUserId maps)
+ *   _MiniAppServerCallbackBridge → callback storage (onSession, onStop, onToolCall)
+ *   _MiniAppServerRuntime        → webhook handling (handleSessionRequest, handleStopRequest)
+ *
+ * This is an internal class — never exported to developers.
+ * MiniAppServer is the only consumer.
+ *
+ * See decisions.md D-007 for rationale on the consolidation.
+ *
+ * @internal
+ */
+import type { Logger } from "pino";
+import type { WebhookResponse, SessionWebhookRequest, StopWebhookRequest, ToolCall } from "../types";
+import type { MentraSessionConfig } from "../session";
+import { MentraSession } from "../session";
+import { _V2SessionShim } from "../session/internal/_V2SessionShim";
+import type { _V2PhotoRequestBridge } from "../session/internal/_V2CameraShim";
+export interface _SessionManagerConfig {
+    packageName: string;
+    apiKey: string;
+    logger: Logger;
+    serverUrl?: string;
+    logLevel?: MentraSessionConfig["logLevel"];
+    verbose?: MentraSessionConfig["verbose"];
+    photoRequestBridge?: _V2PhotoRequestBridge;
+}
+export type _SessionHandler = (session: _V2SessionShim) => void | Promise<void>;
+export type _StopHandler = (session: _V2SessionShim | null, reason: string) => void | Promise<void>;
+export type _ToolCallHandler = (toolCall: ToolCall) => string | undefined | Promise<string | undefined>;
+interface SessionRecord {
+    session: MentraSession;
+    compatSession: _V2SessionShim;
+    userId: string;
+    sessionId: string;
+}
+export declare class _SessionManager {
+    private readonly config;
+    private readonly logger;
+    private readonly bySessionId;
+    private readonly byUserId;
+    private sessionHandler?;
+    private stopHandler?;
+    private toolCallHandler?;
+    private readonly callbackSessionCache;
+    private readonly stopSuppression;
+    constructor(config: _SessionManagerConfig);
+    onSession(handler: _SessionHandler): void;
+    onStop(handler: _StopHandler): void;
+    onToolCall(handler: _ToolCallHandler): void;
+    getBySessionId(sessionId: string): SessionRecord | null;
+    getByUserId(userId: string): SessionRecord | null;
+    get size(): number;
+    handleSessionRequest(request: SessionWebhookRequest): Promise<WebhookResponse>;
+    handleStopRequest(request: StopWebhookRequest): Promise<WebhookResponse>;
+    handleToolCall(toolCall: ToolCall): Promise<{
+        status: "success";
+        reply: string | null;
+    }>;
+    shutdown(): Promise<void>;
+    private createSession;
+    private registrySet;
+    private registryDeleteBySessionId;
+    private deleteIfSameSession;
+    private invokeSessionHandler;
+    private invokeStopHandler;
+    private invokeToolCallHandler;
+}
+export {};
+//# sourceMappingURL=_SessionManager.d.ts.map

package/dist/internal/_SessionManager.d.ts.map

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

package/dist/logging/clean-transport.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Clean Transport for MentraOS SDK
+ *
+ * A lightweight pino-compatible writable stream that formats log output as
+ * single-line colored messages. This is the default console transport.
+ *
+ * Output format:
+ *   MentraOS  ✓ App server running on port 7010
+ *   MentraOS  ⚠ Connection lost, reconnecting (2/3)...
+ *   MentraOS  ✗ Invalid API key
+ *
+ * Color scheme:
+ *   - "MentraOS" prefix: dim gray (always present, visually skippable)
+ *   - ✓ (info): green — success events
+ *   - ⚠ (warn): yellow — warnings, reconnecting, deprecations
+ *   - ✗ (error/fatal): red — failures requiring action
+ *   - · (debug/trace): dim — internal details (only visible at debug level)
+ *   - Message text: default terminal color
+ *
+ * SDK internal log filtering:
+ *   Logs tagged with `_sdk: true` (from managers and internal subsystems) are
+ *   only shown in the terminal at warn level and above. This keeps the developer's
+ *   terminal clean — their own `session.logger.info(...)` calls always show,
+ *   while internal SDK chatter (subscription updates, ping, handler registration)
+ *   is hidden unless the developer sets MENTRA_VERBOSE=true.
+ *
+ *   BetterStack always receives ALL logs regardless of the _sdk tag — the
+ *   filtering only applies to the terminal/clean transport.
+ *
+ * All structured context fields (app, packageName, service, userId, err, etc.)
+ * are intentionally hidden — they're only visible in verbose mode or in BetterStack.
+ * The `msg` field is the only thing shown to the developer.
+ */
+import { Writable } from "stream";
+/**
+ * Creates a writable stream that formats pino JSON log lines as single-line
+ * colored terminal output.
+ *
+ * Pino writes newline-delimited JSON to this stream. Each line is parsed,
+ * and only the `level` and `msg` fields are used for formatting. Everything
+ * else (structured context, error objects, timestamps) is ignored — those
+ * fields still flow to BetterStack via the separate @logtail/pino transport.
+ *
+ * Output is written to `process.stderr` by convention (keeps stdout clean
+ * for program output if someone pipes it).
+ *
+ * @returns A Node.js Writable stream compatible with pino's multistream.
+ */
+export declare function createCleanStream(): Writable;
+//# sourceMappingURL=clean-transport.d.ts.map

package/dist/logging/clean-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clean-transport.d.ts","sourceRoot":"","sources":["../../src/logging/clean-transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AA0BlC;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,IAAI,QAAQ,CA6C5C"}

package/dist/logging/errors.d.ts

@@ -0,0 +1,90 @@
+/**
+ * MentraOS SDK Error Classes
+ *
+ * Structured error hierarchy for programmatic error handling.
+ * All classes extend Error so `instanceof Error` checks still work (backward compatible).
+ *
+ * Usage:
+ * ```typescript
+ * import { MentraAuthError, MentraConnectionError } from '@mentra/sdk';
+ *
+ * session.events.onError((error) => {
+ *   if (error instanceof MentraAuthError) {
+ *     console.log('Bad API key, check your config');
+ *   } else if (error instanceof MentraConnectionError) {
+ *     console.log('Connection issue, will retry');
+ *   }
+ * });
+ * ```
+ */
+/**
+ * Base error class for all MentraOS SDK errors.
+ *
+ * Every SDK error has a `.code` string for programmatic matching
+ * without relying on `.message` string parsing.
+ */
+export declare class MentraError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+/**
+ * Authentication or authorization failure.
+ *
+ * Thrown/emitted when:
+ * - API key is invalid or expired
+ * - Token verification fails
+ * - Cloud rejects credentials
+ */
+export declare class MentraAuthError extends MentraError {
+    constructor(message: string);
+}
+/**
+ * Connection-level failure.
+ *
+ * Thrown/emitted when:
+ * - WebSocket connection is refused (ECONNREFUSED)
+ * - Connection is lost unexpectedly
+ * - All reconnection attempts are exhausted
+ * - Server is unreachable
+ */
+export declare class MentraConnectionError extends MentraError {
+    constructor(message: string, code?: string);
+}
+/**
+ * Operation timed out.
+ *
+ * Thrown/emitted when:
+ * - WebSocket connection handshake exceeds timeout
+ * - Photo request times out
+ * - Audio play request times out
+ */
+export declare class MentraTimeoutError extends MentraError {
+    constructor(message: string);
+}
+/**
+ * Configuration or input validation failure.
+ *
+ * Thrown synchronously when:
+ * - WebSocket URL is missing or malformed
+ * - Layout is missing required properties
+ * - Invalid language code is provided
+ * - Required config fields are absent
+ */
+export declare class MentraValidationError extends MentraError {
+    constructor(message: string);
+}
+/**
+ * Permission denied by MentraOS Cloud.
+ *
+ * Emitted when:
+ * - App subscribes to a stream it lacks permission for
+ * - Cloud rejects a subscription request
+ *
+ * Includes the stream name and required permission for programmatic handling.
+ */
+export declare class MentraPermissionError extends MentraError {
+    readonly stream: string;
+    readonly requiredPermission: string;
+    constructor(message: string, stream: string, requiredPermission: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/logging/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/logging/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;GAKG;AACH,qBAAa,WAAY,SAAQ,KAAK;aAGlB,IAAI,EAAE,MAAM;gBAD5B,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,MAAM;CAS/B;AAED;;;;;;;GAOG;AACH,qBAAa,eAAgB,SAAQ,WAAW;gBAClC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;GAQG;AACH,qBAAa,qBAAsB,SAAQ,WAAW;gBACxC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,MAA2B;CAI/D;AAED;;;;;;;GAOG;AACH,qBAAa,kBAAmB,SAAQ,WAAW;gBACrC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;GAQG;AACH,qBAAa,qBAAsB,SAAQ,WAAW;gBACxC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;GAQG;AACH,qBAAa,qBAAsB,SAAQ,WAAW;aAGlC,MAAM,EAAE,MAAM;aACd,kBAAkB,EAAE,MAAM;gBAF1C,OAAO,EAAE,MAAM,EACC,MAAM,EAAE,MAAM,EACd,kBAAkB,EAAE,MAAM;CAK7C"}

package/dist/logging/logger.d.ts

@@ -1,4 +1,75 @@
+/**
+ * MentraOS SDK Logger
+ *
+ * Factory-based logger that supports two modes:
+ *
+ * **Clean mode** (default): Single-line colored output via the clean transport.
+ *   MentraOS  ✓ App server running on port 7010
+ *   MentraOS  ✗ Invalid API key
+ *
+ * **Verbose mode**: Full pino-pretty structured output (today's behavior).
+ *   Activated via `verbose: true` in config or `MENTRA_VERBOSE=true` env var.
+ *
+ * The BetterStack transport always runs at debug level when BETTERSTACK_SOURCE_TOKEN
+ * is set, regardless of the console transport level. This is intentional — it's
+ * an undocumented internal feature for Mentra's own apps.
+ *
+ * Resolution order for log level:
+ *   1. MENTRA_VERBOSE=true → verbose mode, debug level
+ *   2. MENTRA_LOG_LEVEL env var → sets level (debug implies verbose)
+ *   3. config.verbose: true → verbose mode, debug level
+ *   4. config.logLevel → sets level
+ *   5. Default → info level, clean mode
+ */
 import pino from "pino";
-export declare const logger: pino.Logger<never, boolean>;
+import type { Logger } from "pino";
+export type MentraLogLevel = "none" | "error" | "warn" | "info" | "debug";
+export interface LoggerConfig {
+    /**
+     * SDK console log level. Default: 'info'.
+     * - 'none':  Suppress all SDK console output
+     * - 'error': Only errors
+     * - 'warn':  Errors + warnings
+     * - 'info':  Errors + warnings + lifecycle events (default)
+     * - 'debug': Everything (verbose structured output)
+     *
+     * Can be overridden with MENTRA_LOG_LEVEL env var.
+     */
+    logLevel?: MentraLogLevel;
+    /**
+     * Enable verbose internal logging (full pino-pretty structured output).
+     * Useful when debugging SDK issues — Mentra support may ask you to enable this.
+     * Can also be enabled with MENTRA_VERBOSE=true env var.
+     * Default: false
+     */
+    verbose?: boolean;
+}
+/**
+ * Create a configured pino Logger instance.
+ *
+ * This is the primary entry point. Each AppServer creates one root logger
+ * via this function and then derives child loggers for sessions and modules.
+ *
+ * @param config - Optional logging configuration. If omitted, defaults to
+ *                 warn-level clean output (env vars can still override).
+ * @returns A pino Logger instance with the appropriate transports.
+ *
+ * @example
+ * ```typescript
+ * // Default: clean output at warn level
+ * const logger = createLogger();
+ *
+ * // Verbose for debugging
+ * const logger = createLogger({ verbose: true });
+ *
+ * // Quiet — errors only
+ * const logger = createLogger({ logLevel: 'error' });
+ *
+ * // Silent — suppress all console output (BetterStack still receives logs)
+ * const logger = createLogger({ logLevel: 'none' });
+ * ```
+ */
+export declare function createLogger(config?: LoggerConfig): Logger;
+export declare const logger: pino.Logger;
 export default logger;
 //# sourceMappingURL=logger.d.ts.map

package/dist/logging/logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/logging/logger.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,MAAM,CAAA;AA+EvB,eAAO,MAAM,MAAM,6BAAuC,CAAA;AAS1D,eAAe,MAAM,CAAA"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/logging/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,KAAK,EAAE,MAAM,EAAS,MAAM,MAAM,CAAC;AAM1C,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE1E,MAAM,WAAW,YAAY;IAC3B;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAC;IAE1B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAgHD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,YAAY,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,MAAM,CA6D1D;AAWD,eAAO,MAAM,MAAM,aAGjB,CAAC;AAEH,eAAe,MAAM,CAAC"}

package/dist/logging/telemetry-transport.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Telemetry Transport for MentraOS SDK
+ *
+ * A pino-compatible Writable stream that intercepts log entries and pushes
+ * them into a session-scoped ring buffer for incident debugging.
+ *
+ * This transport is added to the session logger (not the server logger), so
+ * the buffer is automatically scoped to one user's session. Every log line
+ * written via session.logger — including all module child loggers (camera,
+ * audio, led, etc.) — is captured here with zero effort from app developers.
+ *
+ * Design notes:
+ * - Only captures info+ entries. Debug is too noisy for incident bundles;
+ *   BetterStack captures debug separately.
+ * - Ring buffer: oldest entries are dropped when full. This is intentional —
+ *   the most recent logs before a bug report are the most useful.
+ * - The buffer is an external array passed in by reference, so AppSession
+ *   owns the lifetime and can clear it on disconnect simply by reassigning.
+ * - This transport does NOT forward to BetterStack or console — those run
+ *   via the parent appServer.logger streams independently.
+ */
+import { Writable } from "stream";
+import type { TelemetryLogEntry } from "../types/messages/app-to-cloud";
+/**
+ * Creates a pino-compatible Writable stream that pushes log entries into
+ * a caller-owned ring buffer.
+ *
+ * @param buffer     - The array to push entries into. Owned by the caller
+ *                     (AppSession). Passed by reference so the caller can
+ *                     clear it by splicing or reassigning.
+ * @param bufferSize - Maximum number of entries to keep. When the buffer
+ *                     exceeds this, the oldest entries are dropped.
+ *                     Default: 500.
+ * @returns A Node.js Writable stream compatible with pino's multistream.
+ *
+ * @example
+ * ```typescript
+ * const telemetryBuffer: TelemetryLogEntry[] = []
+ * const stream = createTelemetryStream(telemetryBuffer, 500)
+ *
+ * const logger = pino(
+ *   { level: "debug" },
+ *   pino.multistream([
+ *     { stream: parentStream, level: "warn" },
+ *     { stream: stream,       level: "info" },
+ *   ])
+ * )
+ * ```
+ */
+export declare function createTelemetryStream(buffer: TelemetryLogEntry[], bufferSize?: number): Writable;
+//# sourceMappingURL=telemetry-transport.d.ts.map

package/dist/logging/telemetry-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-transport.d.ts","sourceRoot":"","sources":["../../src/logging/telemetry-transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAClC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAiBxE;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,iBAAiB,EAAE,EAAE,UAAU,SAAM,GAAG,QAAQ,CAwD7F"}

package/dist/session/DataStreamRouter.d.ts

@@ -0,0 +1,219 @@
+/**
+ * DataStreamRouter — Typed Message Dispatch
+ *
+ * Replaces the 413-line if/else chain in the old AppSession.handleMessage()
+ * with a clean registry pattern. Each manager registers handlers for the
+ * message types it cares about. The router dispatches incoming messages
+ * to all matching handlers.
+ *
+ * Two levels of dispatch:
+ *
+ * 1. **MessageHandlerRegistry** — routes by top-level `message.type`
+ *    (e.g., "tpa_connection_ack", "settings_update", "data_stream",
+ *    "device_state_update", "capabilities_update", etc.)
+ *
+ * 2. **DataStreamRouter** — routes DATA_STREAM messages by `streamType`
+ *    (e.g., "transcription:en", "translation:en-ja", "button_press",
+ *    "phone_notification", etc.)
+ *
+ * MentraSession wires them together:
+ *   - Creates MessageHandlerRegistry
+ *   - Creates DataStreamRouter
+ *   - Registers DataStreamRouter.handle as the handler for "data_stream"
+ *   - Each manager registers its handlers on one or both registries
+ *
+ * @example
+ * ```ts
+ * const messages = new MessageHandlerRegistry();
+ * const streams = new DataStreamRouter();
+ *
+ * // MentraSession registers the bridge
+ * messages.register("data_stream", (msg) => streams.handle(msg));
+ *
+ * // TranscriptionManager registers for transcription streams
+ * streams.on("transcription", (streamType, data) => { ... });
+ *
+ * // DeviceManager registers for direct messages
+ * messages.register("device_state_update", (msg) => { ... });
+ * messages.register("capabilities_update", (msg) => { ... });
+ *
+ * // Dispatch an incoming message — ~5 lines instead of 413
+ * const msg = JSON.parse(raw);
+ * if (msg?.type) messages.dispatch(msg);
+ * ```
+ */
+/**
+ * Handler for a top-level message type.
+ * Receives the full parsed message object.
+ */
+export type MessageHandler = (message: any) => void;
+/**
+ * Routes incoming messages by their `type` field to registered handlers.
+ * Multiple handlers can be registered for the same message type — all fire.
+ *
+ * This replaces the massive if/else chain with O(1) lookup + iteration.
+ */
+export declare class MessageHandlerRegistry {
+    /**
+     * Map from message type string → array of handlers.
+     * Using an array per type supports multiple managers registering
+     * for the same message type (e.g., multiple subsystems interested
+     * in CONNECTION_ACK).
+     */
+    private handlers;
+    /**
+     * Register a handler for a specific message type.
+     * Multiple handlers per type are supported — all will fire.
+     * Returns a cleanup function that removes this specific handler.
+     *
+     * @param type - The message `type` field value to match
+     * @param handler - Function called with the full message object
+     * @returns Cleanup function to unregister this handler
+     */
+    register(type: string, handler: MessageHandler): () => void;
+    /**
+     * Dispatch a message to all handlers registered for its `type`.
+     * Returns true if at least one handler was called, false otherwise.
+     *
+     * Handlers are called synchronously in registration order.
+     * Errors in one handler do not prevent other handlers from running.
+     */
+    dispatch(message: {
+        type: string;
+        [key: string]: any;
+    }): boolean;
+    /**
+     * Check whether any handlers are registered for a message type.
+     */
+    has(type: string): boolean;
+    /**
+     * Remove all handlers for all message types.
+     * Called during session cleanup/disconnect.
+     */
+    clear(): void;
+}
+/**
+ * Handler for a DATA_STREAM sub-message.
+ *
+ * @param streamType - The full stream type string (e.g., "transcription:en", "button_press")
+ * @param data - The payload data from the DATA_STREAM message (already unwrapped)
+ * @param message - The full raw DATA_STREAM message (for handlers that need metadata)
+ */
+export type StreamHandler = (streamType: string, data: any, message: any) => void;
+/**
+ * Routes DATA_STREAM messages to handlers based on `streamType`.
+ *
+ * Supports two matching strategies:
+ *
+ * 1. **Exact match** — `streamType === registeredKey`
+ *    e.g., registered "button_press" matches incoming "button_press"
+ *
+ * 2. **Prefix match** — `streamType.startsWith(registeredPrefix)`
+ *    e.g., registered "transcription" matches "transcription:en", "transcription:auto"
+ *    e.g., registered "translation" matches "translation:en-ja", "translation:auto-es"
+ *    e.g., registered "touch_event" matches "touch_event:triple_tap"
+ *
+ * ALL matching handlers fire (not just the first match).
+ * This is critical for supporting multiple simultaneous forLanguage() calls:
+ *
+ * ```ts
+ * // Both handlers fire for "transcription:en" messages
+ * router.on("transcription:en", handlerA);
+ * router.on("transcription:en", handlerB);
+ *
+ * // Prefix handler also fires for "transcription:en" messages
+ * router.on("transcription", handlerC);  // matches all transcription:*
+ * ```
+ *
+ * Matching order: exact matches first, then prefix matches (longest prefix first).
+ * Within the same key, handlers fire in registration order.
+ */
+export declare class DataStreamRouter {
+    /**
+     * Map from stream key (exact or prefix) → array of handlers.
+     */
+    private handlers;
+    /**
+     * Cached sorted prefix keys for efficient matching.
+     * Invalidated when handlers are added or removed.
+     * Sorted by length descending so longest prefix matches first.
+     */
+    private prefixKeysCache;
+    /**
+     * Register a handler for a stream type or prefix.
+     *
+     * @param key - Stream type to match. Can be:
+     *   - Exact: "button_press", "transcription:en", "phone_notification"
+     *   - Prefix: "transcription" (matches "transcription:en", "transcription:auto", etc.)
+     * @param handler - Called with (streamType, data, fullMessage) for each match
+     * @returns Cleanup function to unregister this handler
+     *
+     * @example
+     * ```ts
+     * // Exact match — only "button_press"
+     * const stop = router.on("button_press", (st, data) => { ... });
+     *
+     * // Prefix match — all transcription streams
+     * const stop = router.on("transcription", (st, data) => { ... });
+     *
+     * // Specific language
+     * const stop = router.on("transcription:en", (st, data) => { ... });
+     *
+     * // Later: unsubscribe
+     * stop();
+     * ```
+     */
+    on(key: string, handler: StreamHandler): () => void;
+    /**
+     * Dispatch a DATA_STREAM message to all matching handlers.
+     *
+     * Expects a message shaped like:
+     * ```json
+     * {
+     *   "type": "data_stream",
+     *   "streamType": "transcription:en",
+     *   "data": { "text": "hello", "isFinal": true, ... }
+     * }
+     * ```
+     *
+     * Returns true if at least one handler was called.
+     */
+    handle(message: any): boolean;
+    /**
+     * Check whether any handlers are registered for a stream key.
+     */
+    has(key: string): boolean;
+    /**
+     * Get all registered stream keys (both exact and prefix).
+     * Useful for deriving the current subscription set.
+     */
+    getRegisteredKeys(): string[];
+    /**
+     * Remove all handlers.
+     * Called during session cleanup/disconnect.
+     */
+    clear(): void;
+    /**
+     * Get sorted prefix keys for matching, with longest first.
+     * Uses a cache that's invalidated when handlers change.
+     */
+    private getPrefixKeys;
+}
+/**
+ * Derive the set of subscription strings from the DataStreamRouter's
+ * registered handler keys. This is used by MentraSession to compute
+ * the SUBSCRIPTION_UPDATE message payload.
+ *
+ * The logic:
+ * - Each registered key on the DataStreamRouter represents a desired subscription.
+ * - Keys like "transcription" (prefix) map to "transcription:auto" subscription.
+ * - Keys like "transcription:en" (exact) map to "transcription:en" subscription.
+ * - Non-subscribable keys (e.g., internal-only) are filtered out.
+ *
+ * @param router - The DataStreamRouter to derive subscriptions from
+ * @param additionalSubscriptions - Extra subscriptions from other sources
+ *   (e.g., DeviceManager state subscriptions that don't go through the router)
+ * @returns Deduplicated array of subscription strings
+ */
+export declare function deriveSubscriptions(router: DataStreamRouter, additionalSubscriptions?: Set<string>): string[];
+//# sourceMappingURL=DataStreamRouter.d.ts.map

package/dist/session/DataStreamRouter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DataStreamRouter.d.ts","sourceRoot":"","sources":["../../src/session/DataStreamRouter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAIH;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,EAAE,GAAG,KAAK,IAAI,CAAC;AAEpD;;;;;GAKG;AACH,qBAAa,sBAAsB;IACjC;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAuC;IAEvD;;;;;;;;OAQG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,MAAM,IAAI;IAuB3D;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;KAAE,GAAG,OAAO;IAoBhE;;OAEG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAK1B;;;OAGG;IACH,KAAK,IAAI,IAAI;CAGd;AAID;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,KAAK,IAAI,CAAC;AAElF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,gBAAgB;IAC3B;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAsC;IAEtD;;;;OAIG;IACH,OAAO,CAAC,eAAe,CAAyB;IAEhD;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,MAAM,IAAI;IAyBnD;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,OAAO,EAAE,GAAG,GAAG,OAAO;IAyD7B;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAKzB;;;OAGG;IACH,iBAAiB,IAAI,MAAM,EAAE;IAO7B;;;OAGG;IACH,KAAK,IAAI,IAAI;IAOb;;;OAGG;IACH,OAAO,CAAC,aAAa;CAMtB;AAID;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,gBAAgB,EAAE,uBAAuB,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,CA8B7G"}