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

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

@@ -0,0 +1,189 @@
+/**
+ * TranslationManager — v3 SDK Translation API
+ *
+ * Replaces the old `session.events.ontranslationForLanguage()` method with a
+ * cleaner, composable API that supports multiple simultaneous subscriptions.
+ *
+ * @example
+ * ```ts
+ * const session = await mentra.connect();
+ *
+ * // Subscribe to ALL active translation events
+ * const stopAll = session.translation.on((evt) => {
+ *   console.log(`[${evt.sourceLanguage} → ${evt.targetLanguage}] ${evt.text}`);
+ * });
+ *
+ * // Auto-detect source, translate to Spanish
+ * const stopEs = session.translation.to("es", (evt) => {
+ *   console.log(`Spanish: ${evt.text}`);
+ * });
+ *
+ * // Auto-detect source, translate to multiple targets
+ * const stopMulti = session.translation.to(["es", "ja"], (evt) => {
+ *   console.log(`${evt.targetLanguage}: ${evt.text}`);
+ * });
+ *
+ * // Explicit source → target
+ * const stopEnJa = session.translation.fromTo("en", "ja", (evt) => {
+ *   console.log(`EN→JA: ${evt.text}`);
+ * });
+ *
+ * // Explicit source → multiple targets
+ * const stopEnMulti = session.translation.fromTo("en", ["ja", "es"], (evt) => {
+ *   console.log(`EN→${evt.targetLanguage}: ${evt.text}`);
+ * });
+ *
+ * // Cleanup individual subscriptions
+ * stopEs();
+ *
+ * // Or tear down everything
+ * session.translation.stop();
+ * ```
+ *
+ * @module
+ */
+/**
+ * Normalised translation event delivered to subscriber callbacks.
+ *
+ * This is the *public* shape — it is mapped from the raw cloud
+ * `TranslationData` message inside the manager so consumers never
+ * need to think about wire-level details.
+ */
+export interface TranslationEvent {
+    /** The translated text. */
+    text: string;
+    /** `true` when the cloud considers this segment finalised. */
+    isFinal: boolean;
+    /** ISO 639-1 source language code (e.g. `"en"`, `"ja"`). */
+    sourceLanguage: string;
+    /** ISO 639-1 target language code (e.g. `"es"`, `"ja"`). */
+    targetLanguage: string;
+    /** The original (untranslated) text, when available. */
+    originalText?: string;
+    /** Stable identifier for a contiguous utterance. */
+    utteranceId?: string;
+    /** Translation confidence in the range `[0, 1]`. */
+    confidence?: number;
+    /** Start time of the segment in milliseconds. */
+    startTime: number;
+    /** End time of the segment in milliseconds. */
+    endTime: number;
+}
+/** Callback signature for translation subscribers. */
+export type TranslationHandler = (data: TranslationEvent) => 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 TranslationManagerDeps {
+    /** 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 translation subscriptions and dispatches normalised events to
+ * application-level handlers.
+ *
+ * Every public subscription method (`on`, `to`, `fromTo`) 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 TranslationManager {
+    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 `to("es", …)` calls). We only call
+     * `deps.removeSubscription` when the ref-count drops to zero.
+     */
+    private refCounts;
+    constructor(deps: TranslationManagerDeps);
+    /**
+     * Subscribe to **all** active translation events.
+     *
+     * Registers a prefix handler on the router for `"translation"` so that
+     * events for *any* language pair are delivered to `handler`. No wire
+     * subscription is added for the bare prefix — the individual `to()` and
+     * `fromTo()` calls produce the actual subscriptions. This handler simply
+     * listens to whatever translations are already flowing.
+     *
+     * @param handler - Called for every incoming translation event.
+     * @returns A cleanup function that removes this specific subscription.
+     */
+    on(handler: TranslationHandler): () => void;
+    /**
+     * Auto-detect source language and translate to one or more target
+     * 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 target languages.
+     *
+     * Wire protocol:
+     * - `to("es")` → subscribes `"translation:auto-es"`
+     * - `to(["es", "ja"])` → subscribes `"translation:auto-es"` + `"translation:auto-ja"`
+     *
+     * @param target - ISO 639-1 target language code(s).
+     * @param handler - Called for every matching translation event.
+     * @returns A cleanup function that removes this specific subscription.
+     */
+    to(target: string | string[], handler: TranslationHandler): () => void;
+    /**
+     * Translate from an explicit source language to one or more target
+     * languages.
+     *
+     * Wire protocol:
+     * - `fromTo("en", "ja")` → subscribes `"translation:en-ja"`
+     * - `fromTo("en", ["ja", "es"])` → subscribes `"translation:en-ja"` + `"translation:en-es"`
+     *
+     * @param source - ISO 639-1 source language code.
+     * @param target - ISO 639-1 target language code(s).
+     * @param handler - Called for every matching translation event.
+     * @returns A cleanup function that removes this specific subscription.
+     */
+    fromTo(source: string, target: string | string[], handler: TranslationHandler): () => void;
+    /**
+     * Stop **all** translation subscriptions and remove every handler.
+     *
+     * After calling this, no translation callbacks will fire until new
+     * subscriptions are created via {@link on}, {@link to}, or {@link fromTo}.
+     */
+    stop(): void;
+    /** Returns `true` if there is at least one active subscription. */
+    get active(): boolean;
+    /**
+     * 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=TranslationManager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TranslationManager.d.ts","sourceRoot":"","sources":["../../../src/session/managers/TranslationManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAMH;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,OAAO,EAAE,OAAO,CAAC;IACjB,4DAA4D;IAC5D,cAAc,EAAE,MAAM,CAAC;IACvB,4DAA4D;IAC5D,cAAc,EAAE,MAAM,CAAC;IACvB,wDAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oDAAoD;IACpD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,sDAAsD;AACtD,MAAM,MAAM,kBAAkB,GAAG,CAAC,IAAI,EAAE,gBAAgB,KAAK,IAAI,CAAC;AAIlE;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC,yGAAyG;IACzG,MAAM,EAAE;QACN,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;KAC7F,CAAC;IACF,yEAAyE;IACzE,eAAe,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1C,oCAAoC;IACpC,kBAAkB,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7C,mDAAmD;IACnD,WAAW,EAAE,CAAC,OAAO,EAAE,GAAG,KAAK,IAAI,CAAC;IACpC,yBAAyB;IACzB,MAAM,EAAE;QACN,KAAK,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;QAC5B,IAAI,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;QAC3B,IAAI,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;QAC3B,KAAK,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;KAC7B,CAAC;CACH;AA8ED;;;;;;;GAOG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAyB;IAE9C;;;OAGG;IACH,OAAO,CAAC,aAAa,CAA2B;IAEhD;;;;;;OAMG;IACH,OAAO,CAAC,SAAS,CAA6B;gBAElC,IAAI,EAAE,sBAAsB;IAMxC;;;;;;;;;;;OAWG;IACH,EAAE,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,IAAI;IAwB3C;;;;;;;;;;;;;;;OAeG;IACH,EAAE,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,OAAO,EAAE,kBAAkB,GAAG,MAAM,IAAI;IAgCtE;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,OAAO,EAAE,kBAAkB,GAAG,MAAM,IAAI;IAgC1F;;;;;OAKG;IACH,IAAI,IAAI,IAAI;IAYZ,mEAAmE;IACnE,IAAI,MAAM,IAAI,OAAO,CAEpB;IAID;;;OAGG;IACH,OAAO,CAAC,eAAe;IAgBvB;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;CA6B3B"}

package/dist/session.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @mentra/sdk/session — Server-Free Entrypoint
+ *
+ * This entrypoint exports MentraSession and all managers WITHOUT any
+ * server/Node.js/Hono dependencies. It's designed for:
+ *
+ * 1. Local apps running on the phone (Hermes runtime + NativeBridgeTransport)
+ * 2. Environments where you create MentraSession directly with your own Transport
+ * 3. Keeping bundle size small when you don't need MiniAppServer
+ *
+ * Usage:
+ *   import { MentraSession } from "@mentra/sdk/session"
+ *
+ * If you need the full server (webhooks, Hono, HTTP endpoints):
+ *   import { MiniAppServer, MentraSession } from "@mentra/sdk"
+ *
+ * @module
+ */
+export { MentraSession } from "./session/MentraSession";
+export type { MentraSessionConfig } from "./session/MentraSession";
+export type { Transport, TransportOptions } from "./transport/Transport";
+export { TransportState, isTransportOpen, isTransportClosed } from "./transport/Transport";
+export type { TranscriptionManager, TranscriptionEvent, TranscriptionConfig, } from "./session/managers/TranscriptionManager";
+export type { TranslationManager, TranslationEvent } from "./session/managers/TranslationManager";
+export type { DisplayManager } from "./session/managers/DisplayManager";
+export type { SpeakerManager, PlayOptions, PlayResult, SpeakOptions, StreamOptions, AudioOutputStream, } from "./session/managers/SpeakerManager";
+export type { MicManager, AudioChunk, VadEvent } from "./session/managers/MicManager";
+export type { CameraManager, PhotoOptions, PhotoData } from "./session/managers/CameraManager";
+export type { DeviceManager } from "./session/managers/DeviceManager";
+export type { PhoneManager } from "./session/managers/PhoneManager";
+export type { LocationManager, LocationData } from "./session/managers/LocationManager";
+export type { LedManager } from "./session/managers/LedManager";
+export type { StorageManager } from "./session/managers/StorageManager";
+export type { PermissionsManager, PermissionType } from "./session/managers/PermissionsManager";
+export type { DashboardManager } from "./session/managers/DashboardManager";
+export { TimeUtils } from "./session/managers/TimeUtils";
+export { DataStreamRouter, MessageHandlerRegistry } from "./session/DataStreamRouter";
+export type { StreamHandler, MessageHandler } from "./session/DataStreamRouter";
+export { Observable } from "./utils/Observable";
+export { toErrorMessage, toError, warnOnce } from "./utils/error-utils";
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,YAAY,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AASnE,YAAY,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzE,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAQ3F,YAAY,EACV,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,yCAAyC,CAAC;AACjD,YAAY,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AAClG,YAAY,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AACxE,YAAY,EACV,cAAc,EACd,WAAW,EACX,UAAU,EACV,YAAY,EACZ,aAAa,EACb,iBAAiB,GAClB,MAAM,mCAAmC,CAAC;AAC3C,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AACtF,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAC;AAC/F,YAAY,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AACtE,YAAY,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AACpE,YAAY,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AACxF,YAAY,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAChE,YAAY,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AACxE,YAAY,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,uCAAuC,CAAC;AAChG,YAAY,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAC;AAC5E,OAAO,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAIzD,OAAO,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AACtF,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAIhF,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC"}