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

package/src/modules/phone.ts

@@ -4,7 +4,7 @@
  * Mirrors cloud SDK v3's PhoneManager structure. Sub-namespaced by concern:
  *
  *   session.phone.notifications.{on, hasPermission, stop}
- *   session.phone.calendar.{on, hasPermission, stop}
+ *   session.phone.calendar.{listEvents, hasPermission}
  *   session.phone.onBattery(...)                          // stays flat
  *
  * Imperative phone-OS calls (share, openUrl, copyToClipboard, download) live
@@ -16,15 +16,9 @@
  * subscribing on iOS is a no-op even though the API is present.
  */
 
-import {MiniappStreamType} from "../protocol"
+import {MiniappRequestType, MiniappStreamType} from "../protocol"
 import {MiniappSession} from "../session"
-import type {
-  BatteryData,
-  CalendarEventData,
-  NotificationDismissedData,
-  PhoneNotificationData,
-  UnsubscribeFn,
-} from "./events"
+import type {BatteryData, NotificationDismissedData, PhoneNotificationData, UnsubscribeFn} from "./events"
 
 class TrackedSubs {
   private readonly unsubs = new Set<UnsubscribeFn>()
@@ -55,9 +49,7 @@ export class PhoneNotificationsModule extends TrackedSubs {
   }
 
   on(handler: (data: PhoneNotificationData) => void): UnsubscribeFn {
-    return this.track(
-      this.session._subscribe(MiniappStreamType.PHONE_NOTIFICATION, handler as (data: unknown) => void),
-    )
+    return this.track(this.session._subscribe(MiniappStreamType.PHONE_NOTIFICATION, handler as (data: unknown) => void))
   }
 
   /**
@@ -71,10 +63,7 @@ export class PhoneNotificationsModule extends TrackedSubs {
    */
   onDismissed(handler: (data: NotificationDismissedData) => void): UnsubscribeFn {
     return this.track(
-      this.session._subscribe(
-        MiniappStreamType.PHONE_NOTIFICATION_DISMISSED,
-        handler as (data: unknown) => void,
-      ),
+      this.session._subscribe(MiniappStreamType.PHONE_NOTIFICATION_DISMISSED, handler as (data: unknown) => void),
     )
   }
 
@@ -84,15 +73,55 @@ export class PhoneNotificationsModule extends TrackedSubs {
   }
 }
 
-export class PhoneCalendarModule extends TrackedSubs {
-  constructor(private readonly session: MiniappSession) {
-    super()
-  }
+export interface CalendarListOptions {
+  /** Inclusive start of the query window. */
+  startsAt: string | Date
+  /** Exclusive end of the query window. Must be after startsAt. */
+  endsAt: string | Date
+  /** Maximum events to return. Defaults to 50 and may not exceed 100. */
+  limit?: number
+}
 
-  on(handler: (data: CalendarEventData) => void): UnsubscribeFn {
-    return this.track(
-      this.session._subscribe(MiniappStreamType.CALENDAR_EVENT, handler as (data: unknown) => void),
-    )
+export interface CalendarEvent {
+  /** Stable occurrence id, unique across calendars and recurring instances. */
+  id: string
+  calendarId: string
+  title: string
+  /** ISO 8601 start time. All-day events preserve their calendar timezone offset. */
+  startsAt: string
+  /** ISO 8601 end time. All-day events preserve their calendar timezone offset. */
+  endsAt: string
+  timezone?: string
+  allDay: boolean
+  location?: string
+  notes?: string
+  url?: string
+  /** Deduplicated HTTPS links found in the event URL, location, and notes. */
+  links: string[]
+}
+
+export interface CalendarListResult {
+  events: CalendarEvent[]
+  /** True when more matching events existed than the requested limit. */
+  truncated: boolean
+}
+
+export class PhoneCalendarModule {
+  constructor(private readonly session: MiniappSession) {}
+
+  /**
+   * Read calendar events in a bounded window. CALENDAR must be declared in
+   * miniapp.json and granted before the miniapp opens.
+   */
+  listEvents(options: CalendarListOptions): Promise<CalendarListResult> {
+    const startsAt = normalizeCalendarDate(options?.startsAt, "startsAt")
+    const endsAt = normalizeCalendarDate(options?.endsAt, "endsAt")
+    return this.session.sendRequest<CalendarListResult>({
+      type: MiniappRequestType.CALENDAR_LIST_EVENTS,
+      startsAt,
+      endsAt,
+      ...(options.limit === undefined ? {} : {limit: options.limit}),
+    })
   }
 
   /** True iff `CALENDAR` is declared in the miniapp's manifest. */
@@ -101,6 +130,12 @@ export class PhoneCalendarModule extends TrackedSubs {
   }
 }
 
+function normalizeCalendarDate(value: string | Date | undefined, field: string): string {
+  const date = value instanceof Date ? value : new Date(value ?? "")
+  if (Number.isNaN(date.getTime())) throw new TypeError(`${field} must be a valid Date or ISO 8601 string`)
+  return date.toISOString()
+}
+
 export class PhoneModule {
   public readonly notifications: PhoneNotificationsModule
   public readonly calendar: PhoneCalendarModule

package/src/modules/speaker.ts

@@ -50,6 +50,12 @@ export interface SpeakOptions {
   voice_settings?: Record<string, unknown>
   volume?: number
   stopOtherAudio?: boolean
+  /**
+   * Force this call to use on-device offline TTS, skipping cloud TTS
+   * entirely — even when cloud is connected. Rejects with `TTS_LOCAL_UNAVAILABLE`
+   * if the offline model isn't ready instead of falling back to cloud.
+   */
+  forceLocal?: boolean
 }
 
 export interface SpeakResult {
@@ -244,7 +250,15 @@ export class SpeakerModule {
    * Rejects with a MiniappRequestError containing a `code` field on cloud-side
    * TTS failures: `TTS_TEXT_TOO_LONG`, `TTS_INVALID_VOICE`, `TTS_UPSTREAM_ERROR`.
    */
-  async speak(text: string, options: SpeakOptions = {}): Promise<SpeakResult> {
+  async speak(text: string, options?: SpeakOptions): Promise<SpeakResult>
+  async speak(sentences: string[], options?: SpeakOptions): Promise<SpeakResult>
+  async speak(text: string | string[], options: SpeakOptions = {}): Promise<SpeakResult> {
+    const normalized = Array.isArray(text)
+      ? text.map((sentence) => sentence.trim()).filter(Boolean)
+      : text.trim()
+    if ((Array.isArray(normalized) && normalized.length === 0) || normalized === "") {
+      throw {code: MiniappErrorCode.INTERNAL, message: "speak requires at least one non-empty sentence"}
+    }
     try {
       // Like play(): resolves only when TTS playback completes, so opt out of the
       // default request timeout (long text can outlast it). Settled by the host
@@ -252,11 +266,12 @@ export class SpeakerModule {
       const result = await this.session.sendRequest<SpeakResult | null>(
         {
           type: MiniappRequestType.SPEAK,
-          text,
+          text: normalized,
           voice_id: options.voice_id,
           voice_settings: options.voice_settings,
           volume: options.volume,
           stopOtherAudio: options.stopOtherAudio ?? false,
+          forceLocal: options.forceLocal ?? false,
         },
         {timeoutMs: 0},
       )

package/src/modules/transcription.ts

@@ -32,6 +32,15 @@ export interface TranscriptionConfig {
   diarization?: boolean
 }
 
+export interface TranscriptionOptions {
+  /**
+   * Use only on-device STT for this listener; never deliver cloud transcripts.
+   * Other listeners on the same stream keep their own routing choice. Requires
+   * a downloaded local STT model.
+   */
+  forceLocal?: boolean
+}
+
 export class TranscriptionModule {
   private readonly unsubs = new Set<UnsubscribeFn>()
   private currentConfig: TranscriptionConfig | null = null
@@ -46,9 +55,9 @@ export class TranscriptionModule {
    * (handlers on `transcription:auto` receive any `transcription:<lang>`
    * event) preserves existing semantics.
    */
-  on(handler: (data: TranscriptionData) => void): UnsubscribeFn {
+  on(handler: (data: TranscriptionData) => void, options: TranscriptionOptions = {}): UnsubscribeFn {
     return this.track(
-      this.session._subscribe(`${MiniappStreamType.TRANSCRIPTION}:auto`, handler as (data: unknown) => void),
+      this.session._subscribe(`${MiniappStreamType.TRANSCRIPTION}:auto`, handler as (data: unknown) => void, options),
     )
   }
 
@@ -59,14 +68,22 @@ export class TranscriptionModule {
    * @param language - BCP-47 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[], handler: (data: TranscriptionData) => void): UnsubscribeFn {
+  forLanguage(
+    language: string | string[],
+    handler: (data: TranscriptionData) => void,
+    options: TranscriptionOptions = {},
+  ): UnsubscribeFn {
     const langs = Array.isArray(language) ? language : [language]
     if (langs.length === 0) return () => {}
 
     const unsubs: UnsubscribeFn[] = []
     for (const lang of langs) {
       unsubs.push(
-        this.session._subscribe(`${MiniappStreamType.TRANSCRIPTION}:${lang}`, handler as (data: unknown) => void),
+        this.session._subscribe(
+          `${MiniappStreamType.TRANSCRIPTION}:${lang}`,
+          handler as (data: unknown) => void,
+          options,
+        ),
       )
     }
     const combined: UnsubscribeFn = () => {

package/src/protocol.ts

@@ -60,6 +60,9 @@ export enum MiniappRequestType {
   /** One-shot location poll. */
   LOCATION_POLL = "miniapp_location_poll",
 
+  /** Read a bounded snapshot of phone calendar events. */
+  CALENDAR_LIST_EVENTS = "miniapp_calendar_list_events",
+
   /** Start a turn-by-turn navigation trip. Android only. */
   NAVIGATION_START = "miniapp_navigation_start",
   /** Stop the active navigation trip (if any). */
@@ -300,8 +303,6 @@ export enum MiniappStreamType {
    * fire. See agents/miniapp-speaker-state-and-notif-dismissed-plan.md.
    */
   PHONE_NOTIFICATION_DISMISSED = "phone_notification_dismissed",
-  CALENDAR_EVENT = "calendar_event",
-
   // Photos, streaming
   PHOTO_TAKEN = "photo_taken",
   STREAM_STATUS = "stream_status",
@@ -318,6 +319,9 @@ export enum MiniappErrorCode {
   /** The miniapp subscribed to a stream whose required permission wasn't in its manifest. */
   PERMISSION_NOT_DECLARED = "PERMISSION_NOT_DECLARED",
 
+  /** The required phone OS permission is not currently granted. */
+  PERMISSION_DENIED = "PERMISSION_DENIED",
+
   /** Request routed to a method that isn't supported yet. */
   NOT_IMPLEMENTED = "NOT_IMPLEMENTED",
 
@@ -332,6 +336,9 @@ export enum MiniappErrorCode {
   TTS_INVALID_VOICE = "TTS_INVALID_VOICE",
   TTS_UPSTREAM_ERROR = "TTS_UPSTREAM_ERROR",
 
+  /** `speak({forceLocal: true})` but the on-device offline TTS model isn't downloaded/ready. */
+  TTS_LOCAL_UNAVAILABLE = "TTS_LOCAL_UNAVAILABLE",
+
   /** Not connected / pre-ACK and transport closed. */
   NOT_CONNECTED = "NOT_CONNECTED",
 

package/src/session.ts

@@ -24,7 +24,7 @@ import {AuthModule} from "./modules/auth"
 import {CloudModule} from "./modules/cloud"
 import {DashboardAPI} from "./modules/dashboard"
 import {DisplayManager} from "./modules/display"
-import {EventManager, type UnsubscribeFn} from "./modules/events"
+import {EventManager, type TranscriptionEventRoute, type UnsubscribeFn} from "./modules/events"
 import {GlassesModule} from "./modules/glasses"
 import {HeadingModule} from "./modules/heading"
 import {ImuModule} from "./modules/imu"
@@ -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)
   }
@@ -392,8 +396,12 @@ export class MiniappSession {
    * session.transcription.on(...)
    * etc. instead."
    */
-  _subscribe(streamType: string, handler: (data: unknown) => void): UnsubscribeFn {
-    return this.events.subscribe(streamType, handler)
+  _subscribe(
+    streamType: string,
+    handler: (data: unknown) => void,
+    options: {forceLocal?: boolean} = {},
+  ): UnsubscribeFn {
+    return this.events.subscribe(streamType, handler, options)
   }
 
   // -------------------------------------------------------------------------
@@ -677,7 +685,11 @@ export class MiniappSession {
       case MiniappResponseType.EVENT: {
         const streamType = payload.streamType as string | undefined
         if (!streamType) return
-        this.events._forwardEvent(streamType, payload.data)
+        this.events._forwardEvent(
+          streamType,
+          payload.data,
+          payload.transcriptionRoute as TranscriptionEventRoute | undefined,
+        )
         return
       }
 

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"
 

package/src/transport/mock.ts

@@ -226,6 +226,9 @@ function syntheticDataFor(requestId: string, requestType: string, requestPayload
       // Atlantic, which makes maps/navigation unusable in the WebView.
       return {lat: 37.7956, lng: -122.3933, accuracy: 0, timestamp: Date.now()}
 
+    case MiniappRequestType.CALENDAR_LIST_EVENTS:
+      return {events: [], truncated: false}
+
     case MiniappRequestType.STORAGE_GET:
       return {value: null}