@mentra/miniapp 0.3.0-beta.0 → 0.3.0-beta.1

package/src/modules/transcription.ts

@@ -21,11 +21,18 @@
 import {MiniappRequestType, MiniappStreamType} from "../protocol"
 import {MiniappSession} from "../session"
 import type {TranscriptionData, UnsubscribeFn} from "./events"
+import {requireLanguageHint, requireTranscriptionLanguage} from "./languages"
+import type {LanguageHint, TranscriptionLanguage} from "./languages"
 
 /** Configuration for cloud-side transcription behavior. */
 export interface TranscriptionConfig {
-  /** ISO 639-1 language hints to improve detection accuracy (e.g. ["en", "ja"]). */
-  languageHints?: string[]
+  /**
+   * Language hints to improve auto-detection accuracy. Bare ISO 639-1 codes
+   * from the registry (e.g. ["en", "ja"]); registry BCP-47 tags are accepted
+   * and normalized ("en-US" -> "en"). Anything else throws
+   * `MiniappValidationError`.
+   */
+  languageHints?: LanguageHint[]
   /** Custom vocabulary / boosted terms (e.g. ["MentraOS", "HIPAA"]). */
   vocabulary?: string[]
   /** Enable speaker diarisation. Defaults vary by provider. */
@@ -65,15 +72,24 @@ export class TranscriptionModule {
    * Subscribe to transcription for one or more specific languages. Each call
    * is independent; multiple can be active simultaneously.
    *
-   * @param language - BCP-47 tag(s), e.g. `"en-US"` or `["en-US", "es-ES"]`.
+   * Languages are validated against the platform registry
+   * (`SUPPORTED_TRANSCRIPTION_LANGUAGES`): registry BCP-47 tags pass through,
+   * bare registry codes canonicalize ("fr" -> "fr-FR"), anything else throws
+   * `MiniappValidationError` immediately — an invalid language must never
+   * become a subscription that silently transcribes the wrong thing
+   * (OS-1746 / issue 021).
+   *
+   * @param language - Registry tag(s), e.g. `"en-US"` or `["en-US", "es-ES"]`.
    * @param handler  - Called for every event in any of the listed languages.
    */
   forLanguage(
-    language: string | string[],
+    language: TranscriptionLanguage | TranscriptionLanguage[],
     handler: (data: TranscriptionData) => void,
     options: TranscriptionOptions = {},
   ): UnsubscribeFn {
-    const langs = Array.isArray(language) ? language : [language]
+    const langs = (Array.isArray(language) ? language : [language]).map((lang) =>
+      requireTranscriptionLanguage(lang, "transcription.forLanguage(language)"),
+    )
     if (langs.length === 0) return () => {}
 
     const unsubs: UnsubscribeFn[] = []
@@ -100,15 +116,29 @@ export class TranscriptionModule {
 
   /**
    * Apply transcription configuration (language hints, custom vocabulary,
-   * diarisation toggle). Sent to the cloud immediately. Cached locally so we
-   * could re-send on reconnect (future).
+   * diarisation toggle). Hints are validated against the registry and
+   * normalized to bare codes ("en-US" -> "en"); unknown values throw
+   * `MiniappValidationError` synchronously.
+   *
+   * Sent to the phone runtime as a REQUEST (not a one-shot) so the returned
+   * promise rejects if the runtime cannot apply it — a config that the
+   * platform ignores must be loud, not silent (issue 021 S3). Cached locally
+   * so the runtime can re-apply on reconnect.
    */
-  configure(config: TranscriptionConfig): void {
-    this.currentConfig = {...config}
-    this.session.sendOneShot({
-      type: MiniappRequestType.TRANSCRIPTION_CONFIG,
-      config: {...config},
-    })
+  configure(config: TranscriptionConfig): Promise<void> {
+    const normalized: TranscriptionConfig = {
+      ...config,
+      languageHints: config.languageHints?.map((hint) =>
+        requireLanguageHint(hint, "transcription.configure(languageHints)"),
+      ),
+    }
+    this.currentConfig = {...normalized}
+    return this.session
+      .sendRequest<void>({
+        type: MiniappRequestType.TRANSCRIPTION_CONFIG,
+        config: {...normalized},
+      })
+      .then(() => undefined)
   }
 
   /** Tear down every transcription subscription this module owns. */

package/src/modules/translation.ts

@@ -20,9 +20,17 @@
 import {MiniappStreamType} from "../protocol"
 import {MiniappSession} from "../session"
 import type {TranslationData, UnsubscribeFn} from "./events"
+import {requireTranscriptionLanguage} from "./languages"
+import type {TranscriptionLanguage} from "./languages"
 
 export type TranslationHandler = (data: TranslationData) => void
 
+/**
+ * Translation source: a registry language, or "auto" to let the cloud detect
+ * the spoken language.
+ */
+export type TranslationSource = TranscriptionLanguage | "auto"
+
 export class TranslationModule {
   private readonly unsubs = new Set<UnsubscribeFn>()
 
@@ -51,8 +59,10 @@ export class TranslationModule {
    * regardless of source. Useful for "I'm a Spanish speaker, translate
    * whatever I hear to Spanish."
    */
-  to(target: string | string[], handler: TranslationHandler): UnsubscribeFn {
-    const targets = Array.isArray(target) ? target : [target]
+  to(target: TranscriptionLanguage | TranscriptionLanguage[], handler: TranslationHandler): UnsubscribeFn {
+    const targets = (Array.isArray(target) ? target : [target]).map((t) =>
+      requireTranscriptionLanguage(t, "translation.to(target)"),
+    )
     if (targets.length === 0) return () => {}
     const unsubs: UnsubscribeFn[] = []
     for (const t of targets) {
@@ -81,17 +91,21 @@ export class TranslationModule {
    * from the same source.
    */
   fromTo(
-    source: string,
-    target: string | string[],
+    source: TranslationSource,
+    target: TranscriptionLanguage | TranscriptionLanguage[],
     handler: TranslationHandler,
   ): UnsubscribeFn {
-    const targets = Array.isArray(target) ? target : [target]
+    const validSource =
+      source === "auto" ? "auto" : requireTranscriptionLanguage(source, "translation.fromTo(source)")
+    const targets = (Array.isArray(target) ? target : [target]).map((t) =>
+      requireTranscriptionLanguage(t, "translation.fromTo(target)"),
+    )
     if (targets.length === 0) return () => {}
     const unsubs: UnsubscribeFn[] = []
     for (const t of targets) {
       unsubs.push(
         this.session._subscribe(
-          `${MiniappStreamType.TRANSLATION}:${source}:${t}`,
+          `${MiniappStreamType.TRANSLATION}:${validSource}:${t}`,
           handler as (data: unknown) => void,
         ),
       )
@@ -113,8 +127,8 @@ export class TranslationModule {
    * SDK v3 parity. This alias will be removed in a future release.
    */
   forLanguagePair(
-    fromLang: string,
-    toLang: string,
+    fromLang: TranslationSource,
+    toLang: TranscriptionLanguage,
     handler: TranslationHandler,
   ): UnsubscribeFn {
     return this.fromTo(fromLang, toLang, handler)

package/src/session.ts

@@ -194,7 +194,11 @@ type SessionEmitterEvents = {
   auth: (auth: MiniappAuthState) => void
 }
 
-export class MiniappSession {
+// The default preserves the pre-channel-registry behavior for code that creates
+// or accepts a bare MiniappSession. `registerMiniapp<Channels>` supplies the
+// concrete mapping for scaffolded miniapps.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export class MiniappSession<TChannels extends object = any> {
   public readonly auth: AuthModule
   public readonly display: DisplayManager
   /**
@@ -238,7 +242,7 @@ export class MiniappSession {
    * with inverted buffering policy (background drops when no WebView is
    * bound; the WebView buffers until ready).
    */
-  public readonly ui: UIModule
+  public readonly ui: UIModule<TChannels>
   /**
    * Inter-miniapp lifecycle + discovery (list / start / stop). SYSTEM-only —
    * calls reject with NOT_PERMITTED unless this miniapp is a system app.
@@ -324,7 +328,7 @@ export class MiniappSession {
     this.system = new SystemModule(this)
     this.transcription = new TranscriptionModule(this)
     this.translation = new TranslationModule(this)
-    this.ui = new UIModuleImpl(this)
+    this.ui = new UIModuleImpl<TChannels>(this)
     this.miniapps = new MiniappsModule(this)
     this.actions = new ActionsModule(this)
   }

package/src/sub-path-types.test-d.ts

@@ -23,12 +23,23 @@
  */
 
 // ----- @mentra/miniapp/background ---------------------------------------
-import type {MiniappSession} from "./background/index"
+import {registerMiniapp} from "./background/index"
+import type {MiniappSession, UIModule} from "./background/index"
 
 // ✅ MiniappSession is reachable from the background entry.
 const _bg: MiniappSession | undefined = undefined
 void _bg
 
+// ✅ registerMiniapp<Channels> carries the shared channel registry into
+//    session.ui on the background side.
+interface _TestChannels {
+  ping: {at: number}
+}
+type _RegisteredHandler = Parameters<typeof registerMiniapp<_TestChannels>>[0]
+type _RegisteredSession = Parameters<_RegisteredHandler>[0]
+type _Assert<T extends true> = T
+export type _TypedBackground = _Assert<_RegisteredSession["ui"] extends UIModule<_TestChannels> ? true : false>
+
 // ----- @mentra/miniapp/ui -----------------------------------------------
 import type {MentraUiGlobal, MentraTyped} from "./ui/index"