@mentra/miniapp 0.3.0-dev.0 → 3.1.0-dev.10

package/src/index.ts

@@ -36,14 +36,21 @@ export type {MentraOSGlobals, MiniappCapsuleMenuRect, MiniappColorScheme, Miniap
 
 export {MiniappErrorCode, MiniappRequestType, MiniappResponseType, MiniappStreamType} from "./protocol"
 export {CLOUD_STATUS_STREAM} from "./modules/cloud"
+
+// Language registry (issue 021): canonical language types + the validation
+// error the typed transcription/translation surfaces throw.
+export {
+  MiniappValidationError,
+  SUPPORTED_LANGUAGE_HINTS,
+  SUPPORTED_TRANSCRIPTION_LANGUAGES,
+  isTranscriptionLanguage,
+} from "./modules/languages"
+export type {LanguageHint, TranscriptionLanguage} from "./modules/languages"
 export type {CloudClientAudioTransport, CloudClientConnectionStatus, CloudClientStatus} from "./modules/cloud"
 
-// Hardware requirement types — re-exported from @mentra/types so miniapp
-// authors can type their miniapp.json manifest without pulling in the types
-// package directly. Keep explicit exports (enums as value, interfaces as
-// type) per @mentra/types' Bun-compat convention.
-export {HardwareType, HardwareRequirementLevel} from "@mentra/types"
-export type {HardwareRequirement} from "@mentra/types"
+// Canonical miniapp manifest hardware contract.
+export {HardwareType, HardwareRequirementLevel} from "./hardware"
+export type {HardwareRequirement} from "./hardware"
 
 // Transports — exported for advanced uses (forced transport injection, tests)
 export {createTransport} from "./transport/auto"
@@ -71,7 +78,6 @@ export type {
   AudioChunkData,
   BatteryData,
   ButtonPressData,
-  CalendarEventData,
   ConnectionData,
   HeadingData,
   HeadPositionData,
@@ -85,6 +91,7 @@ export type {
   VadData,
   WifiData,
 } from "./modules/events"
+export type {CalendarEvent, CalendarListOptions, CalendarListResult} from "./modules/phone"
 export type {
   PlayAudioOptions,
   SpeakOptions,
@@ -120,7 +127,14 @@ export type {
   StreamStatus,
   StreamVideoConfig,
 } from "./modules/stream"
-export type {ShareOptions, ShareResult, DownloadOptions, DownloadResult} from "./modules/system"
+export type {
+  ShareOptions,
+  ShareResult,
+  DownloadOptions,
+  DownloadResult,
+  ScanQrOptions,
+  ScanQrResult,
+} from "./modules/system"
 export type {MiniappInfo, MiniappActionInfo, MiniappCompatibility, ListMiniappsOptions} from "./modules/miniapps"
 export type {ActionContext, ActionHandler, InvokeOptions} from "./modules/actions"
 
@@ -163,7 +177,7 @@ export type {
 } from "./modules/navigation"
 export type {PermissionsModule, PermissionErrorEvent} from "./modules/permissions"
 export type {PhoneModule, PhoneNotificationsModule, PhoneCalendarModule} from "./modules/phone"
-export type {TranscriptionModule, TranscriptionConfig} from "./modules/transcription"
+export type {TranscriptionModule, TranscriptionConfig, TranscriptionOptions} from "./modules/transcription"
 export type {TranslationModule} from "./modules/translation"
 export type {SpeakerModule} from "./modules/speaker"
 

package/src/modules/camera.ts

@@ -33,6 +33,11 @@ export interface TakePhotoOptions {
   size?: "low" | "medium" | "high" | "max"
   /** Capture at maximum source quality and optimize BLE delivery for readable text. */
   mode?: "photo" | "text"
+  /**
+   * Image delivery path. `auto` tries direct Wi-Fi upload and falls back to
+   * BLE; `direct` disables BLE fallback; `ble` always relays through the phone.
+   */
+  transferMethod?: "auto" | "direct" | "ble"
   compress?: "none" | "low" | "medium" | "high"
   sound?: boolean
   saveToGallery?: boolean
@@ -42,6 +47,38 @@ export interface TakePhotoOptions {
    * manual exposure; ignored otherwise.
    */
   exposureTimeNs?: number
+  /** Sensor ISO for this capture only. Only used when `exposureTimeNs` enables manual exposure. */
+  iso?: number | null
+  /** After AE convergence, divide the metered exposure by this factor (scan mode). */
+  aeExposureDivisor?: number
+  /** Cap ISO after AE metering (scan mode). */
+  isoCap?: number
+  /** Request per-capture noise reduction. Sent on the wire; glasses may log `not_implemented`. */
+  noiseReduction?: boolean
+  /** Request per-capture edge enhancement. Sent on the wire; glasses may log `not_implemented`. */
+  edgeEnhancement?: boolean
+  /**
+   * ZSL buffering. Manual and scan stills force it off because fixed sensor controls take priority.
+   */
+  zsl?: boolean
+  /**
+   * MFNR still capture. Manual and scan stills force it off because fixed sensor controls take priority.
+   */
+  mfnr?: boolean
+  /** ISP digital gain hint. */
+  ispDigitalGain?: number
+  /** ISP analog gain hint. */
+  ispAnalogGain?: string
+  /**
+   * Override the SDK's default 60s request timeout for this capture only.
+   * Leave unset for a normal user-triggered capture (the full 60s ceiling is
+   * appropriate there). Callers that speculatively fire a capture and may
+   * abandon it if the result isn't needed (e.g. a short-lived non-visual
+   * assistant turn racing a capture against a ~1s latency cap) should pass a
+   * short value here so the abandoned `takePhoto()` promise settles quickly
+   * instead of sitting on the default 60s ceiling.
+   */
+  timeoutMs?: number
 }
 
 export interface PhotoTaken {
@@ -54,8 +91,15 @@ export interface PhotoTaken {
 
 export interface WarmUpCameraOptions {
   size?: "low" | "medium" | "high" | "max"
+  /** Match the upcoming capture mode so warm-up and capture share one ASG camera session. */
+  mode?: "photo" | "text"
   exposureTimeNs?: number
+  /** Ready-state hold in milliseconds. Defaults to 15 seconds and is capped at 60 seconds. */
   durationMs?: number
+  /** ZSL preview buffering for the warm-up session. */
+  zsl?: boolean
+  /** MFNR still capture for the warm-up session. */
+  mfnr?: boolean
 }
 
 export interface StartVideoRecordingOptions {
@@ -100,10 +144,11 @@ export class CameraModule {
   }
 
   /**
-   * Apply camera FOV/ROI settings on the glasses.
+   * Apply a session-owned camera FOV/ROI override on the glasses.
    *
    * Resolves after the ASG client reports that the setting was applied to camera
-   * hardware after the restart cooldown. Requires CAMERA permission declared in miniapp.json.
+   * hardware after the restart cooldown. The host restores the prior override or persistent base
+   * when this miniapp closes. Requires CAMERA permission declared in miniapp.json.
    */
   async setFov(request: CameraFovRequest): Promise<CameraFovResult> {
     return this.session.sendRequest<CameraFovResult>({
@@ -122,23 +167,37 @@ export class CameraModule {
    * `session.capabilities.hasCamera` before calling.
    */
   async takePhoto(options: TakePhotoOptions = {}): Promise<PhotoTaken> {
-    return this.session.sendRequest<PhotoTaken>({
-      type: MiniappRequestType.PHOTO,
-      size: options.size ?? "medium",
-      mode: options.mode ?? "photo",
-      compress: options.compress ?? "none",
-      sound: options.sound ?? true,
-      saveToGallery: options.saveToGallery ?? false,
-      exposureTimeNs: options.exposureTimeNs,
-    })
+    return this.session.sendRequest<PhotoTaken>(
+      {
+        type: MiniappRequestType.PHOTO,
+        size: options.size ?? "medium",
+        mode: options.mode ?? "photo",
+        ...(options.transferMethod !== undefined ? {transferMethod: options.transferMethod} : {}),
+        compress: options.compress ?? "none",
+        sound: options.sound ?? true,
+        saveToGallery: options.saveToGallery ?? false,
+        exposureTimeNs: options.exposureTimeNs,
+        iso: options.iso,
+        aeExposureDivisor: options.aeExposureDivisor,
+        isoCap: options.isoCap,
+        noiseReduction: options.noiseReduction,
+        edgeEnhancement: options.edgeEnhancement,
+        zsl: options.zsl,
+        mfnr: options.mfnr,
+        ispDigitalGain: options.ispDigitalGain,
+        ispAnalogGain: options.ispAnalogGain,
+      },
+      options.timeoutMs != null ? {timeoutMs: options.timeoutMs} : undefined,
+    )
   }
 
   /**
    * Pre-warm the glasses camera so the next takePhoto() is near-instant.
-   * The camera stays warm for ~durationMs (default 15s); call warmUp() again to
+   * The camera stays warm for ~durationMs (default 15s, maximum 60s); call warmUp() again to
    * extend it. Warm with the same `size` you'll capture with — a mismatched size
    * forces the camera to reconfigure and loses the speedup. Requires CAMERA
-   * permission in miniapp.json. Resolves once the camera reports ready.
+   * permission in miniapp.json. Resolves once the camera reports ready. The host automatically
+   * releases this miniapp's request-owned lease when the miniapp closes.
    *
    * Warm-ups are serialized: only one runs at a time and none may start while a
    * photo is being captured. If the camera is busy (a capture is in flight, or
@@ -150,8 +209,11 @@ export class CameraModule {
     await this.session.sendRequest<void>({
       type: MiniappRequestType.CAMERA_WARM_UP,
       size: options.size ?? "medium",
+      mode: options.mode ?? "photo",
       exposureTimeNs: options.exposureTimeNs,
       durationMs: options.durationMs ?? 15000,
+      zsl: options.zsl,
+      mfnr: options.mfnr,
     })
   }
 

package/src/modules/events.ts

@@ -9,7 +9,7 @@
  *   - session.imu.onHeadPosition(...)
  *   - session.location.onUpdate(...)
  *   - session.glasses.onBattery(...) / onConnection(...)
- *   - session.phone.onNotification(...) / onCalendarEvent(...) / onBattery(...)
+ *   - session.phone.notifications.on(...) / session.phone.onBattery(...)
  *
  * This module's only public method is `subscribe(rawStreamType, handler)` —
  * a forward-compat escape hatch for new event types not yet wrapped on a
@@ -35,6 +35,9 @@ import {MiniappSession} from "../session"
 
 export type UnsubscribeFn = () => void
 
+/** @internal Host-selected delivery target for a transcription event. */
+export type TranscriptionEventRoute = "default" | "forceLocal" | "all"
+
 // ---------------------------------------------------------------------------
 // Shared event data shapes — re-exported by index.ts so consumers can type
 // their handlers without importing this internal module.
@@ -135,20 +138,6 @@ export interface NotificationDismissedData {
   timestamp: number
 }
 
-export interface CalendarEventData {
-  eventId: string
-  title: string
-  /** ISO 8601 start time. */
-  dtStart: string
-  /** ISO 8601 end time. */
-  dtEnd: string
-  timezone: string
-  allDay: boolean
-  location: string
-  notes: string
-  calendarId: string
-}
-
 export interface VadData {
   /** True while the user is speaking (voice detected), false when silent. */
   status: boolean
@@ -172,8 +161,10 @@ export interface AudioChunkData {
 
 export class EventManager {
   private readonly emitter = new EventEmitter()
-  /** Stream -> ref count. Outbound SUBSCRIBE is sent when refs transition 0↔1. */
+  /** Stream -> ref count. Outbound SUBSCRIBE tracks active streams and routing changes. */
   private readonly refCounts = new Map<string, number>()
+  /** Transcription stream -> refs that require on-device-only processing. */
+  private readonly forceLocalRefCounts = new Map<string, number>()
 
   constructor(private readonly session: MiniappSession) {}
 
@@ -189,26 +180,51 @@ export class EventManager {
    * via a separate envelope `type`; the EventManager only routes them
    * locally.
    */
-  subscribe(stream: string, handler: (data: unknown) => void): UnsubscribeFn {
-    this.emitter.on(stream, handler)
+  subscribe(stream: string, handler: (data: unknown) => void, options: {forceLocal?: boolean} = {}): UnsubscribeFn {
     const isInternal = stream.startsWith("_")
+    const forceLocal = options.forceLocal === true && stream.startsWith(`${MiniappStreamType.TRANSCRIPTION}:`)
+    const listener = (data: unknown, route?: TranscriptionEventRoute) => {
+      if (stream.startsWith(`${MiniappStreamType.TRANSCRIPTION}:`)) {
+        // Hosts that predate routed transcription events omit `route`. Treat
+        // those events as the default/cloud path so a forceLocal listener can
+        // never accidentally receive cloud text.
+        if (forceLocal ? route !== "forceLocal" && route !== "all" : route === "forceLocal") return
+      }
+      handler(data)
+    }
+    this.emitter.on(stream, listener)
     if (!isInternal) {
       const before = this.refCounts.get(stream) ?? 0
       this.refCounts.set(stream, before + 1)
-      if (before === 0) {
+      const forceLocalBefore = this.forceLocalRefCounts.get(stream) ?? 0
+      const defaultBefore = before - forceLocalBefore
+      if (forceLocal) this.forceLocalRefCounts.set(stream, forceLocalBefore + 1)
+      if (before === 0 || (forceLocal && forceLocalBefore === 0) || (!forceLocal && defaultBefore === 0)) {
         this.sendSubscriptionUpdate()
       }
     }
     return () => {
-      this.emitter.off(stream, handler)
+      this.emitter.off(stream, listener)
       if (isInternal) return
       const current = this.refCounts.get(stream) ?? 0
+      const forceLocalCurrent = this.forceLocalRefCounts.get(stream) ?? 0
+      let subscriptionChanged = current <= 1
       if (current <= 1) {
         this.refCounts.delete(stream)
-        this.sendSubscriptionUpdate()
       } else {
         this.refCounts.set(stream, current - 1)
       }
+      if (forceLocal) {
+        if (forceLocalCurrent <= 1) {
+          this.forceLocalRefCounts.delete(stream)
+          subscriptionChanged = true
+        } else {
+          this.forceLocalRefCounts.set(stream, forceLocalCurrent - 1)
+        }
+      } else if (current - forceLocalCurrent <= 1) {
+        subscriptionChanged = true
+      }
+      if (subscriptionChanged) this.sendSubscriptionUpdate()
     }
   }
 
@@ -216,6 +232,7 @@ export class EventManager {
   unsubscribeAll(): void {
     this.emitter.removeAllListeners()
     this.refCounts.clear()
+    this.forceLocalRefCounts.clear()
     this.sendSubscriptionUpdate()
   }
 
@@ -224,8 +241,8 @@ export class EventManager {
   // -------------------------------------------------------------------------
 
   /** @internal */
-  _forwardEvent(stream: string, data: unknown): void {
-    this.emitter.emit(stream, data)
+  _forwardEvent(stream: string, data: unknown, transcriptionRoute?: TranscriptionEventRoute): void {
+    this.emitter.emit(stream, data, transcriptionRoute)
 
     // Wildcard fan-out: handlers register under wildcard patterns
     // ("transcription:auto", "translation:*:<target>", …) but the host
@@ -235,7 +252,7 @@ export class EventManager {
     // LocalMiniappRuntime.forwardEvent matches on the host side —
     // otherwise a wildcard subscriber never fires.
     if (stream.startsWith("transcription:") && stream !== "transcription:auto") {
-      this.emitter.emit("transcription:auto", data)
+      this.emitter.emit("transcription:auto", data, transcriptionRoute)
     } else if (stream.startsWith("translation:")) {
       const parts = stream.split(":")
       const patterns = new Set<string>(["translation:auto"])
@@ -253,9 +270,19 @@ export class EventManager {
   }
 
   private sendSubscriptionUpdate(): void {
-    const subscriptions = Array.from(this.refCounts.keys()).map((stream) =>
-      stream === MiniappStreamType.LOCATION_UPDATE ? {stream: "location_stream", rate: "realtime"} : stream,
-    )
+    const subscriptions = Array.from(this.refCounts.keys()).map((stream) => {
+      if (stream === MiniappStreamType.LOCATION_UPDATE) return {stream: "location_stream", rate: "realtime"}
+
+      const forceLocalRefs = this.forceLocalRefCounts.get(stream) ?? 0
+      if (forceLocalRefs === 0) return stream
+
+      const totalRefs = this.refCounts.get(stream) ?? 0
+      return {
+        stream,
+        forceLocal: true,
+        ...(totalRefs > forceLocalRefs ? {includeCloud: true} : {}),
+      }
+    })
     this.session.sendOneShot({
       type: MiniappRequestType.SUBSCRIBE,
       subscriptions,

package/src/modules/glasses.ts

@@ -41,4 +41,18 @@ export class GlassesModule {
       reason,
     })
   }
+
+  /**
+   * Enable or disable Wi-Fi ADB (wireless debugging) on Mentra Live.
+   * Persisted on the glasses; boot applies the saved preference (default off).
+   *
+   * SYSTEM-only — rejects with `NOT_PERMITTED` unless this miniapp is a system
+   * app. Third-party miniapps must not expose wireless debugging controls.
+   */
+  async setWifiAdbState(enabled: boolean): Promise<void> {
+    await this.session.sendRequest<void>({
+      type: MiniappRequestType.SET_WIFI_ADB_STATE,
+      enabled,
+    })
+  }
 }

package/src/modules/languages.ts

@@ -0,0 +1,72 @@
+/**
+ * @fileoverview Language validation at the SDK boundary (issue 021, WP2).
+ *
+ * The registry itself lives in `@mentra/cloud-protocol/languages` (single
+ * source of truth shared with the cloud). This module re-exports the types so
+ * miniapps import everything from `@mentra/miniapp`, and adds the throwing
+ * validators the typed module surfaces (`transcription.*`, `translation.*`)
+ * call on every language parameter.
+ *
+ * Contract (design doc docs/issues/021-typed-language-subscriptions):
+ *   - Valid by construction: params are typed as literal unions, so TS users
+ *     get autocomplete and compile errors.
+ *   - Loud at runtime: JS users (or `any` casts) get a thrown
+ *     `MiniappValidationError` with a suggestion, never silent fallback.
+ *   - Canonical on the wire: bare codes ("fr") canonicalize to their default
+ *     tag ("fr-FR") before becoming stream keys, so the phone/cloud only ever
+ *     see registry tags.
+ */
+
+import {
+  isTranscriptionLanguage,
+  suggestTranscriptionLanguage,
+  toLanguageHint,
+  toTranscriptionLanguage,
+  SUPPORTED_LANGUAGE_HINTS,
+  SUPPORTED_TRANSCRIPTION_LANGUAGES,
+} from "@mentra/cloud-protocol/languages"
+import type {LanguageHint, TranscriptionLanguage} from "@mentra/cloud-protocol/languages"
+
+export {SUPPORTED_LANGUAGE_HINTS, SUPPORTED_TRANSCRIPTION_LANGUAGES, isTranscriptionLanguage}
+export type {LanguageHint, TranscriptionLanguage}
+
+/**
+ * Thrown synchronously by SDK methods when a parameter fails validation.
+ * Deliberately a hard throw (not a warning, not a silent default): an invalid
+ * language previously produced a subscription that silently transcribed the
+ * wrong language or silently never spoke (OS-1746).
+ */
+export class MiniappValidationError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = "MiniappValidationError"
+  }
+}
+
+/**
+ * Canonicalize a subscription language or throw. Accepts registry tags
+ * ("fr-FR") and bare registry codes ("fr" -> "fr-FR").
+ */
+export function requireTranscriptionLanguage(value: string, param: string): TranscriptionLanguage {
+  const canonical = toTranscriptionLanguage(value)
+  if (canonical) return canonical
+  const suggestion = suggestTranscriptionLanguage(value)
+  throw new MiniappValidationError(
+    `${param}: unknown language ${JSON.stringify(value)}` +
+      (suggestion ? ` — did you mean ${JSON.stringify(suggestion)}?` : "") +
+      ` Supported values are BCP-47 tags from SUPPORTED_TRANSCRIPTION_LANGUAGES (e.g. "en-US", "fr-FR").`,
+  )
+}
+
+/**
+ * Normalize a language hint to the bare code the STT provider accepts, or
+ * throw. Accepts bare codes ("fr") and registry tags ("fr-FR" -> "fr").
+ */
+export function requireLanguageHint(value: string, param: string): LanguageHint {
+  const hint = toLanguageHint(value)
+  if (hint) return hint
+  throw new MiniappValidationError(
+    `${param}: unknown language hint ${JSON.stringify(value)}. ` +
+      `Hints are bare ISO 639-1 codes from SUPPORTED_LANGUAGE_HINTS (e.g. "en", "fr").`,
+  )
+}

package/src/modules/mic.ts

@@ -15,7 +15,7 @@
  * PERMISSION_NOT_DECLARED otherwise.
  */
 
-import {MiniappStreamType} from "../protocol"
+import {MiniappRequestType, MiniappStreamType} from "../protocol"
 import {MiniappSession} from "../session"
 import type {AudioChunkData, UnsubscribeFn, VadData} from "./events"
 
@@ -41,6 +41,35 @@ export class MicModule {
     return this.track(this.session._subscribe(MiniappStreamType.AUDIO_CHUNK, handler as (data: unknown) => void))
   }
 
+  /**
+   * Temporarily override glasses-side voice activity detection (GX8002) for
+   * this miniapp's lifetime. When disabled, mic gating falls back to the
+   * loudness gate only (if it is enabled). The Mentra App's configured value
+   * is restored when this miniapp disconnects.
+   *
+   * Requires `MICROPHONE` in the miniapp manifest.
+   */
+  setVoiceActivityDetectionEnabled(enabled: boolean): Promise<void> {
+    return this.session.sendRequest<void>({
+      type: MiniappRequestType.MIC_SET_VAD_ENABLED,
+      enabled,
+    })
+  }
+
+  /**
+   * Temporarily override the center-mic loudness gate ("Barrier") for this
+   * miniapp's lifetime. It blocks quiet/self-talk audio independent of VAD.
+   * The Mentra App's configured value is restored when this miniapp disconnects.
+   *
+   * Requires `MICROPHONE` in the miniapp manifest.
+   */
+  setLoudnessGateEnabled(enabled: boolean): Promise<void> {
+    return this.session.sendRequest<void>({
+      type: MiniappRequestType.MIC_SET_LOUDNESS_GATE_ENABLED,
+      enabled,
+    })
+  }
+
   /**
    * Tear down every subscription this module owns. Useful when a component
    * is unmounting and wants to free everything at once without tracking

package/src/modules/miniapps.ts

@@ -20,6 +20,8 @@ export interface MiniappActionInfo {
    * to an MCP tool `inputSchema`. Undefined for actions that take no params.
    */
   parameters?: Record<string, unknown>
+  /** JSON-Schema descriptor for the structured value returned by the action. */
+  outputSchema?: Record<string, unknown>
 }
 
 /**

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