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

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

@@ -0,0 +1,289 @@
+/**
+ * StorageManager — v3 SDK Key-Value Storage API
+ *
+ * Wraps the existing SimpleStorage patterns from v2 with a cleaner,
+ * composable API. Provides localStorage-like semantics with cloud
+ * synchronisation via HTTP REST endpoints.
+ *
+ * **Mental Model:** Local cache (RAM) is the source of truth for reads.
+ * Writes are applied to RAM immediately and batched/debounced to the
+ * server for persistence. On disconnect, pending writes are flushed.
+ *
+ * Data is isolated by userId and packageName on the server side.
+ * The REST endpoints live on the SDK's own HTTP server (same origin
+ * as the WebSocket connection, minus the `/app-ws` path).
+ *
+ * REST API:
+ * - `GET    /api/sdk/simple-storage/:userId`            → fetch all data
+ * - `PUT    /api/sdk/simple-storage/:userId`             → batch upsert `{ data: { key: value } }`
+ * - `DELETE /api/sdk/simple-storage/:userId/:key`        → delete single key
+ * - `DELETE /api/sdk/simple-storage/:userId`             → clear all data
+ *
+ * @module
+ */
+/**
+ * Dependencies injected by MentraSession.
+ *
+ * Structural type — no concrete imports so the manager stays unit-testable
+ * with plain stubs.
+ */
+export interface StorageManagerDeps {
+    /** DataStreamRouter — not used by StorageManager but part of the shared shape. */
+    router: {
+        on(key: string, handler: (streamType: string, data: any, message: any) => void): () => void;
+    };
+    /** MessageHandlerRegistry — not used by StorageManager but part of the shared shape. */
+    messageHandlers: {
+        register(type: string, handler: (msg: any) => void): () => void;
+    };
+    /** Add a subscription string (not used by StorageManager). */
+    addSubscription: (stream: string) => void;
+    /** Remove a subscription string (not used by StorageManager). */
+    removeSubscription: (stream: string) => void;
+    /** Send an arbitrary JSON message over the WebSocket. */
+    sendMessage: (message: any) => void;
+    /** Structured logger. */
+    logger: {
+        debug(...args: any[]): void;
+        info(...args: any[]): void;
+        warn(...args: any[]): void;
+        error(...args: any[]): void;
+    };
+    /** Package name — used for auth headers. */
+    getPackageName: () => string;
+    /** Current session ID. */
+    getSessionId: () => string;
+    /** Server URL for HTTP API calls (WebSocket URL or HTTP base). */
+    getServerUrl?: () => string | null;
+}
+/**
+ * Configuration options for StorageManager.
+ */
+export interface StorageManagerConfig {
+    /** User ID for storage isolation. */
+    userId: string;
+    /** API key for authentication. */
+    apiKey?: string;
+}
+/**
+ * Key-value storage with local caching and debounced cloud sync.
+ *
+ * Provides a familiar `get`/`set`/`delete`/`clear` interface backed by
+ * an in-memory cache with automatic persistence to the MentraOS cloud.
+ * Writes are batched and debounced to minimise network traffic.
+ *
+ * @example
+ * ```ts
+ * const session = await mentra.connect();
+ *
+ * // Set a value
+ * await session.storage.set("username", "alice");
+ *
+ * // Get a value
+ * const name = await session.storage.get("username");
+ * console.log(name); // "alice"
+ *
+ * // Check existence
+ * const exists = await session.storage.has("username");
+ *
+ * // Delete a key
+ * await session.storage.delete("username");
+ *
+ * // Flush pending writes immediately
+ * await session.storage.flush();
+ * ```
+ */
+export declare class StorageManager {
+    private readonly deps;
+    private readonly userId;
+    private readonly apiKey;
+    /** Local cache — `null` means "not yet loaded from server". */
+    private cache;
+    /** Base URL for HTTP API calls. */
+    private readonly baseUrl;
+    /** Pending writes waiting to be flushed. */
+    private pendingWrites;
+    /** Timer for the idle debounce window. */
+    private debounceTimer;
+    /** Timer for the maximum wait window. */
+    private maxWaitTimer;
+    /** Timestamp of the first write in the current batch. */
+    private firstWriteTime;
+    constructor(deps: StorageManagerDeps, config: StorageManagerConfig);
+    /**
+     * Get a value by key.
+     *
+     * Reads from the local cache. If the cache has not been populated yet,
+     * it is fetched from the server first.
+     *
+     * @param key - The storage key to retrieve.
+     * @returns The stored value, or `undefined` if the key does not exist.
+     *
+     * @example
+     * ```ts
+     * const value = await session.storage.get("theme");
+     * ```
+     */
+    get(key: string): Promise<any>;
+    /**
+     * Set a value for a key.
+     *
+     * The local cache is updated immediately. The write is batched and
+     * debounced — it will be persisted to the server after 3 seconds of
+     * idle time or 10 seconds maximum, whichever comes first.
+     *
+     * @param key - The storage key.
+     * @param value - The value to store. Will be serialised as JSON on the server.
+     * @throws If the serialised value exceeds the 100 KB size limit.
+     *
+     * @example
+     * ```ts
+     * await session.storage.set("score", "42");
+     * ```
+     */
+    set(key: string, value: any): Promise<void>;
+    /**
+     * Delete a single key.
+     *
+     * Removes the key from the local cache immediately and sends a DELETE
+     * request to the server. Unlike `set()`, deletes are flushed immediately
+     * for consistency.
+     *
+     * @param key - The storage key to remove.
+     *
+     * @example
+     * ```ts
+     * await session.storage.delete("old-key");
+     * ```
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Clear all stored data.
+     *
+     * Empties the local cache and sends a DELETE request to remove all
+     * data from the server.
+     *
+     * @example
+     * ```ts
+     * await session.storage.clear();
+     * ```
+     */
+    clear(): Promise<void>;
+    /**
+     * Get all storage keys.
+     *
+     * @returns An array of all keys currently in storage.
+     *
+     * @example
+     * ```ts
+     * const allKeys = await session.storage.keys();
+     * console.log("Stored keys:", allKeys);
+     * ```
+     */
+    keys(): Promise<string[]>;
+    /**
+     * Check whether a key exists in storage.
+     *
+     * @param key - The storage key to check.
+     * @returns `true` if the key exists.
+     *
+     * @example
+     * ```ts
+     * if (await session.storage.has("user-prefs")) {
+     *   // load prefs
+     * }
+     * ```
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Get a shallow copy of all stored key-value pairs.
+     *
+     * @returns A record of all stored data.
+     *
+     * @example
+     * ```ts
+     * const allData = await session.storage.getAll();
+     * console.log(allData);
+     * ```
+     */
+    getAll(): Promise<Record<string, any>>;
+    /**
+     * Set multiple key-value pairs at once.
+     *
+     * All values are validated for size before any are applied. The local
+     * cache is updated immediately and writes are batched for persistence.
+     *
+     * @param data - A record of key-value pairs to set.
+     * @throws If any value exceeds the 100 KB size limit.
+     *
+     * @example
+     * ```ts
+     * await session.storage.setMultiple({
+     *   theme: "dark",
+     *   language: "en",
+     *   fontSize: "14",
+     * });
+     * ```
+     */
+    setMultiple(data: Record<string, any>): Promise<void>;
+    /**
+     * Flush all pending writes to the server immediately.
+     *
+     * This is called automatically by the debounce/max-wait timers, but can
+     * also be called explicitly (e.g., before disconnect). If there are no
+     * pending writes, this is a no-op.
+     *
+     * @throws If the server returns an error (413 for size limit, 429 for rate limit).
+     *
+     * @example
+     * ```ts
+     * await session.storage.flush();
+     * ```
+     */
+    flush(): Promise<void>;
+    /**
+     * Flush pending writes and clean up all resources.
+     *
+     * Called by MentraSession during disconnect/cleanup.
+     * @internal
+     */
+    destroy(): Promise<void>;
+    /**
+     * Ensure the local cache is populated from the server.
+     * Only fetches once — subsequent calls are no-ops.
+     */
+    private ensureCacheLoaded;
+    /**
+     * Fetch all stored data from the server and populate the local cache.
+     */
+    private fetchFromServer;
+    /**
+     * Schedule a debounced flush of pending writes.
+     *
+     * Uses a two-timer strategy:
+     * 1. **Idle timer** — fires after {@link DEBOUNCE_MS} of inactivity (reset on each write).
+     * 2. **Max wait timer** — fires after {@link MAX_WAIT_MS} from the first write in the batch,
+     *    ensuring writes are never delayed indefinitely during continuous activity.
+     */
+    private scheduleFlush;
+    /**
+     * Clear all flush timers and reset batch tracking state.
+     */
+    private clearTimers;
+    /**
+     * Resolve the base URL for HTTP API calls.
+     *
+     * Converts the WebSocket URL (e.g., `wss://host/app-ws`) to an HTTP URL
+     * (e.g., `https://host`). Falls back to `http://localhost:8002` if no
+     * server URL is available.
+     */
+    private resolveBaseUrl;
+    /**
+     * Generate auth headers for API requests.
+     *
+     * Uses the `packageName:apiKey` format expected by the SDK server's
+     * auth middleware.
+     */
+    private getAuthHeaders;
+}
+//# sourceMappingURL=StorageManager.d.ts.map

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

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

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

@@ -0,0 +1,175 @@
+/**
+ * ⏰ TimeUtils — Stateless Timezone Utilities
+ *
+ * Pure utility class for timezone-aware date operations. Uses the built-in
+ * `Intl.DateTimeFormat` API for formatting — no external dependencies.
+ *
+ * This class has **no transport layer**, no subscriptions, and no wire
+ * messages. It is a convenience wrapper for apps that need to display
+ * or reason about times in the user's local timezone (which may differ
+ * from the server's timezone).
+ *
+ * @example
+ * ```ts
+ * const time = new TimeUtils("America/New_York");
+ *
+ * // Current time in the user's timezone
+ * const now = time.now();
+ *
+ * // Format a date for display
+ * const formatted = time.format(now, { hour: "numeric", minute: "2-digit" });
+ * // => "3:45 PM"
+ *
+ * // Convert a UTC date to the user's local timezone
+ * const local = time.toLocal(new Date("2024-01-15T20:00:00Z"));
+ *
+ * // Change timezone at runtime (e.g., user travelled)
+ * time.setTimezone("Europe/London");
+ * ```
+ *
+ * @module
+ */
+/**
+ * Timezone-aware date utility class.
+ *
+ * Wraps the `Intl.DateTimeFormat` API to provide convenient methods for
+ * creating, converting, and formatting dates in a specific timezone.
+ *
+ * The timezone can be changed at runtime via {@link setTimezone}, making
+ * this class suitable for long-lived sessions where the user may travel
+ * across timezone boundaries.
+ */
+export declare class TimeUtils {
+    /**
+     * The current IANA timezone identifier (e.g., `"America/New_York"`,
+     * `"Europe/London"`, `"Asia/Tokyo"`).
+     */
+    private _zone;
+    /**
+     * Create a new TimeUtils instance.
+     *
+     * @param timezone - IANA timezone identifier. Must be a valid timezone
+     *   string recognised by `Intl.DateTimeFormat` (e.g., `"America/New_York"`,
+     *   `"UTC"`, `"Asia/Tokyo"`).
+     *
+     * @throws {RangeError} If the provided timezone string is not a valid
+     *   IANA timezone identifier.
+     *
+     * @example
+     * ```ts
+     * const time = new TimeUtils("America/Los_Angeles");
+     * ```
+     */
+    constructor(timezone: string);
+    /**
+     * The current IANA timezone identifier.
+     *
+     * @example
+     * ```ts
+     * console.log(time.zone); // "America/New_York"
+     * ```
+     */
+    get zone(): string;
+    /**
+     * Get the current date/time.
+     *
+     * Returns a standard `Date` object representing the current instant.
+     * The `Date` itself is always UTC internally — use {@link format} or
+     * {@link toLocal} to interpret it in the configured timezone.
+     *
+     * @returns A `Date` representing the current moment.
+     *
+     * @example
+     * ```ts
+     * const now = time.now();
+     * console.log(time.format(now)); // formatted in the configured timezone
+     * ```
+     */
+    now(): Date;
+    /**
+     * Convert a `Date` to a new `Date` whose UTC fields represent the
+     * wall-clock time in the configured timezone.
+     *
+     * This is useful when you need to extract hours/minutes/seconds that
+     * correspond to the local timezone without using `Intl` formatting.
+     *
+     * **Note:** The returned `Date` is a synthetic object — its
+     * `getUTCHours()` etc. return the *local* values, but calling
+     * `toISOString()` on it will produce a misleading string. Prefer
+     * {@link format} for display purposes.
+     *
+     * @param date - The date to convert. Defaults to `new Date()` (now).
+     * @returns A new `Date` whose UTC methods return local-timezone values.
+     *
+     * @example
+     * ```ts
+     * const utcDate = new Date("2024-01-15T20:00:00Z");
+     * const local = time.toLocal(utcDate);
+     * console.log(local.getUTCHours()); // 15 if timezone is "America/New_York" (EST = UTC-5)
+     * ```
+     */
+    toLocal(date?: Date): Date;
+    /**
+     * Format a `Date` for display in the configured timezone.
+     *
+     * Delegates to `Intl.DateTimeFormat` with the configured timezone
+     * injected automatically. Any valid `Intl.DateTimeFormatOptions` can
+     * be passed through.
+     *
+     * If no options are provided, a sensible default is used:
+     * `"1/15/2024, 3:45:00 PM"` (locale-dependent).
+     *
+     * @param date - The date to format.
+     * @param opts - Optional `Intl.DateTimeFormatOptions` to control output.
+     * @returns The formatted date string.
+     *
+     * @example
+     * ```ts
+     * // Default format
+     * time.format(new Date());
+     * // => "1/15/2024, 3:45:00 PM"
+     *
+     * // Custom format — time only
+     * time.format(new Date(), { hour: "numeric", minute: "2-digit" });
+     * // => "3:45 PM"
+     *
+     * // Custom format — full date
+     * time.format(new Date(), {
+     *   weekday: "long",
+     *   year: "numeric",
+     *   month: "long",
+     *   day: "numeric",
+     * });
+     * // => "Monday, January 15, 2024"
+     *
+     * // With a specific locale
+     * time.format(new Date(), { hour: "numeric", minute: "2-digit" });
+     * ```
+     */
+    format(date: Date, opts?: Intl.DateTimeFormatOptions): string;
+    /**
+     * Change the timezone at runtime.
+     *
+     * Validates the new timezone before applying it. If the timezone is
+     * invalid, a `RangeError` is thrown and the previous timezone is retained.
+     *
+     * @param tz - New IANA timezone identifier.
+     * @throws {RangeError} If the timezone string is not valid.
+     *
+     * @example
+     * ```ts
+     * time.setTimezone("Europe/London");
+     * console.log(time.zone); // "Europe/London"
+     * ```
+     */
+    setTimezone(tz: string): void;
+    /**
+     * Validate that a timezone string is recognised by the runtime's
+     * `Intl.DateTimeFormat` implementation.
+     *
+     * @param tz - The timezone string to validate.
+     * @throws {RangeError} If the timezone is not valid.
+     */
+    private static validateTimezone;
+}
+//# sourceMappingURL=TimeUtils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TimeUtils.d.ts","sourceRoot":"","sources":["../../../src/session/managers/TimeUtils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAIH;;;;;;;;;GASG;AACH,qBAAa,SAAS;IACpB;;;OAGG;IACH,OAAO,CAAC,KAAK,CAAS;IAEtB;;;;;;;;;;;;;;OAcG;gBACS,QAAQ,EAAE,MAAM;IAS5B;;;;;;;OAOG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAID;;;;;;;;;;;;;;OAcG;IACH,GAAG,IAAI,IAAI;IAIX;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,OAAO,CAAC,IAAI,GAAE,IAAiB,GAAG,IAAI;IAiCtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;IACH,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,qBAAqB,GAAG,MAAM;IAS7D;;;;;;;;;;;;;;OAcG;IACH,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAO7B;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,CAAC,gBAAgB;CAYhC"}

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

@@ -0,0 +1,195 @@
+/**
+ * TranscriptionManager — v3 SDK Transcription API
+ *
+ * Replaces the old `session.events.onTranscription*()` methods with a cleaner,
+ * composable API that supports multiple simultaneous subscriptions.
+ *
+ * @example
+ * ```ts
+ * const session = await mentra.connect();
+ *
+ * // Subscribe to all transcription (auto-detect language)
+ * const stopAll = session.transcription.on((evt) => {
+ *   console.log(`[${evt.language}] ${evt.text}`);
+ * });
+ *
+ * // Also subscribe to a specific language — independent of the above
+ * const stopEn = session.transcription.forLanguage("en", (evt) => {
+ *   console.log(`English: ${evt.text}`);
+ * });
+ *
+ * // Multiple languages in one call
+ * const stopMulti = session.transcription.forLanguage(["ja", "es"], (evt) => {
+ *   console.log(`${evt.language}: ${evt.text}`);
+ * });
+ *
+ * // Configure hints / vocabulary / diarization
+ * session.transcription.configure({
+ *   languageHints: ["en", "ja"],
+ *   vocabulary: ["MentraOS", "HIPAA"],
+ *   diarization: true,
+ * });
+ *
+ * // Cleanup individual subscriptions
+ * stopEn();
+ *
+ * // Or tear down everything
+ * session.transcription.stop();
+ * ```
+ *
+ * @module
+ */
+/**
+ * Configuration options that influence transcription behaviour on the cloud.
+ *
+ * Passed to {@link TranscriptionManager.configure}. Applies globally to all
+ * active subscriptions managed by this instance.
+ */
+export interface TranscriptionConfig {
+    /** ISO 639-1 language hints to improve detection accuracy (e.g. `["en", "ja", "es"]`). */
+    languageHints?: string[];
+    /** Custom vocabulary / boosted terms (e.g. `["MentraOS", "HIPAA"]`). */
+    vocabulary?: string[];
+    /** Enable speaker diarisation. Defaults to `true`. */
+    diarization?: boolean;
+}
+/**
+ * Normalised transcription event delivered to subscriber callbacks.
+ *
+ * This is the *public* shape — it is mapped from the raw cloud
+ * `TranscriptionData` message inside the manager so consumers never
+ * need to think about wire-level details.
+ */
+export interface TranscriptionEvent {
+    /** The transcribed text. */
+    text: string;
+    /** `true` when the cloud considers this utterance segment finalised. */
+    isFinal: boolean;
+    /** ISO 639-1 detected language code (e.g. `"en"`, `"ja"`). */
+    language: string;
+    /** Speaker identifier when diarisation is enabled. */
+    speakerId?: string;
+    /** Stable identifier for a contiguous utterance. Interim and final events for the same utterance share this ID. */
+    utteranceId?: string;
+    /** Recognition confidence in the range `[0, 1]`. */
+    confidence?: number;
+    /** Start time of the utterance segment in milliseconds. */
+    startTime: number;
+    /** End time of the utterance segment in milliseconds. */
+    endTime: number;
+    /** Audio duration in milliseconds. */
+    duration?: number;
+    /** Provider-specific metadata (token-level details, etc.). */
+    metadata?: any;
+}
+/** Callback signature for transcription subscribers. */
+export type TranscriptionHandler = (data: TranscriptionEvent) => void;
+/**
+ * Dependencies injected by MentraSession.
+ *
+ * This is intentionally a *structural* type — we don't import the concrete
+ * `DataStreamRouter` class so that the manager remains unit-testable with
+ * plain stubs.
+ */
+export interface TranscriptionManagerDeps {
+    /** Register for DATA_STREAM messages by streamType key (exact or prefix). Returns a cleanup function. */
+    router: {
+        on(key: string, handler: (streamType: string, data: any, message: any) => void): () => void;
+    };
+    /** Add a subscription string (triggers SUBSCRIPTION_UPDATE to cloud). */
+    addSubscription: (stream: string) => void;
+    /** Remove a subscription string. */
+    removeSubscription: (stream: string) => void;
+    /** Send an arbitrary JSON message to the cloud. */
+    sendMessage: (message: any) => void;
+    /** Structured logger. */
+    logger: {
+        debug(...args: any[]): void;
+        info(...args: any[]): void;
+        warn(...args: any[]): void;
+        error(...args: any[]): void;
+    };
+}
+/**
+ * Manages transcription subscriptions and dispatches normalised events to
+ * application-level handlers.
+ *
+ * Every public subscription method (`on`, `forLanguage`) is **independent** —
+ * multiple can be active simultaneously and each returns its own cleanup
+ * function. Calling {@link stop} tears down *all* active subscriptions.
+ */
+export declare class TranscriptionManager {
+    private readonly deps;
+    /**
+     * All currently-active registrations. We track them so that {@link stop}
+     * can clean everything up in one shot.
+     */
+    private registrations;
+    /**
+     * Reference count per subscription stream string.
+     *
+     * Multiple independent registrations may share the same underlying stream
+     * key (e.g. two `forLanguage("en", …)` calls). We only call
+     * `deps.removeSubscription` when the ref-count drops to zero.
+     */
+    private refCounts;
+    /** Latest config applied via {@link configure}. */
+    private currentConfig;
+    constructor(deps: TranscriptionManagerDeps);
+    /**
+     * Subscribe to **all** transcription events (auto-detect, all languages).
+     *
+     * Registers a prefix handler on the router for `"transcription"` so that
+     * events for *any* language are delivered to `handler`. The cloud
+     * subscription is `"transcription:auto"`.
+     *
+     * @param handler - Called for every incoming transcription event.
+     * @returns A cleanup function that removes this specific subscription.
+     */
+    on(handler: TranscriptionHandler): () => void;
+    /**
+     * Subscribe to transcription for one or more specific languages.
+     *
+     * Each call is **independent** — multiple can be active simultaneously.
+     * When an array is provided the handler fires for events in *any* of the
+     * listed languages.
+     *
+     * @param lang - ISO 639-1 language code(s) (e.g. `"en"` or `["en", "ja"]`).
+     * @param handler - Called for every matching transcription event.
+     * @returns A cleanup function that removes this specific subscription.
+     */
+    forLanguage(lang: string | string[], handler: TranscriptionHandler): () => void;
+    /**
+     * Apply transcription configuration (language hints, custom vocabulary,
+     * diarisation toggle).
+     *
+     * The configuration is sent to the cloud immediately and cached so that
+     * it can be re-sent if the session reconnects.
+     *
+     * @param config - Configuration to apply.
+     */
+    configure(config: TranscriptionConfig): void;
+    /**
+     * Stop **all** transcription subscriptions and remove every handler.
+     *
+     * After calling this, no transcription callbacks will fire until new
+     * subscriptions are created via {@link on} or {@link forLanguage}.
+     */
+    stop(): void;
+    /** Returns `true` if there is at least one active subscription. */
+    get active(): boolean;
+    /** Returns the current configuration, or `null` if none has been set. */
+    get config(): TranscriptionConfig | null;
+    /**
+     * Track a new registration: increment ref-counts and call
+     * `addSubscription` for any stream that is newly referenced.
+     */
+    private addRegistration;
+    /**
+     * Tear down a registration: unregister router handlers, decrement
+     * ref-counts, and call `removeSubscription` when a stream drops to zero
+     * references.
+     */
+    private removeRegistration;
+}
+//# sourceMappingURL=TranscriptionManager.d.ts.map

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

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