@mentra/engine 0.1.0-dev.0 → 3.1.0-dev.4

package/src/services/OtaService.ts

@@ -15,11 +15,7 @@ import type {OtaStatus} from "@mentra/bluetooth-sdk/internal"
 import GlobalEventEmitter from "../utils/GlobalEventEmitter"
 import {useGlassesStore} from "../stores/glasses"
 import {handleOtaClockSkewFromGlasses} from "./glassesClockSync"
-import {
-  legacyOtaProgressFromOtaStatusEvent,
-  normalizeOtaStatusEvent,
-  otaStatusFromNormalized,
-} from "./otaLegacyMapping"
+import {legacyOtaProgressFromOtaStatusEvent, normalizeOtaStatusEvent, otaStatusFromNormalized} from "./otaLegacyMapping"
 
 let subs: Array<{remove: () => void}> = []
 
@@ -40,6 +36,16 @@ export function startOtaService(): void {
     }),
   )
 
+  // The glasses process restarted under a live BLE link (sid changed in
+  // glasses_ready/version_info_1). The physical connection never dropped, so this is
+  // the ONLY reconnect-edge signal the OTA coordinator gets after an APK install.
+  subs.push(
+    BluetoothSdk.addListener("glasses_session_changed", (event) => {
+      console.log(`[OTA] glasses_session_changed ${event.previous_sid || "<none>"} -> ${event.sid}`)
+      GlobalEventEmitter.emit("glasses_session_changed", {previousSid: event.previous_sid, sid: event.sid})
+    }),
+  )
+
   // Install progress / lifecycle. Updates both the new (otaStatus) and the legacy
   // (otaProgress) store shapes; auto-fixes clock skew on the relevant failures.
   subs.push(

package/src/services/OtaUpdateCheckService.ts

@@ -1,8 +1,18 @@
 import BluetoothSdk from "@mentra/bluetooth-sdk/internal"
-import type {OtaUpdateInfo} from "@mentra/bluetooth-sdk/internal"
+import type {OtaUpdateInfo} from "@mentra/bluetooth-sdk"
 import {getGlassesSystemTimeMs, isGlassesConnected, useGlassesStore, waitForGlassesState} from "../stores/glasses"
 import {maybeFixGlassesClockFromVersionInfo} from "./glassesClockSync"
-import {getAsgOtaVersionUrl} from "./asgOtaVersionUrl"
+import {hasConfiguredModernOtaManifestPin, resolveOtaManifestUrl} from "./otaManifestUrl"
+
+/**
+ * Phone-side mirror of ASG's `DOWNGRADE_FLOOR_VERSION_CODE`. Set to the versionCode of the first
+ * release shipping the shared media root (the first downgrade-safe build). A non-positive value
+ * means downgrades are disabled, so the phone must NOT offer them — offering a downgrade the
+ * glasses' `DowngradeGate` will refuse leaves the version-change session with no install and the
+ * glasses reporting a bare "complete", which would otherwise present as false success. Keep this
+ * in lockstep with the ASG/recovery constant at release time.
+ */
+export const DOWNGRADE_FLOOR_VERSION_CODE = 0
 
 export interface VersionInfo {
   versionCode: number
@@ -18,11 +28,13 @@ export interface MtkPatch {
   start_firmware: string
   end_firmware: string
   url: string
+  sha256?: string
 }
 
 export interface BesFirmware {
   version: string
   url: string
+  sha256?: string
 }
 
 export interface VersionJson {
@@ -46,9 +58,23 @@ export interface OtaCheckResult {
   updates: string[]
   mtkPatch: MtkPatch | null
   besVersion: string | null
+  /** True when the pending APK step installs an OLDER build than the glasses currently run. */
+  isApkDowngrade: boolean
+  /**
+   * Raw manifest JSON (stringified) this check actually fetched, or null when the
+   * fetch failed. Lets change-watchers baseline on exactly what the check saw,
+   * instead of racing it with a second fetch of the same URL.
+   */
+  manifestBody: string | null
+  /**
+   * Why the check failed, when it did. "network" is retryable (connection/server
+   * trouble); "pin_unavailable" is permanent for this app build (manifest 404/gone,
+   * unparseable, or carrying no valid ASG pin) — the remedy is updating the app.
+   */
+  checkFailureReason?: "network" | "pin_unavailable"
 }
 
-export type OtaCheckSkippedReason = "disconnected" | "missing_build"
+export type OtaCheckSkippedReason = "disconnected" | "missing_build" | "dev_build"
 
 export interface OtaCheckCurrentGlassesResult extends OtaCheckResult {
   updateInfo: OtaUpdateInfo | null
@@ -66,6 +92,8 @@ export interface OtaCheckCurrentGlassesOptions {
   waitForMtkVersionMs?: number
   refreshVersionInfo?: boolean
   fixClockBeforeCheck?: boolean
+  /** Downgrade floor override (defaults to DOWNGRADE_FLOOR_VERSION_CODE); for tests. */
+  floorVersionCode?: number
 }
 
 function emptyCheckResult(skippedReason?: OtaCheckSkippedReason): OtaCheckCurrentGlassesResult {
@@ -76,6 +104,8 @@ function emptyCheckResult(skippedReason?: OtaCheckSkippedReason): OtaCheckCurren
     updates: [],
     mtkPatch: null,
     besVersion: null,
+    isApkDowngrade: false,
+    manifestBody: null,
     updateInfo: null,
     isRequired: true,
     skippedReason,
@@ -86,46 +116,90 @@ function glassesConnectedNow(): boolean {
   return isGlassesConnected(useGlassesStore.getState().connection)
 }
 
-export async function fetchVersionInfo(url: string): Promise<VersionJson | null> {
+type ManifestFetchResult = {json: VersionJson | null; failureReason?: "network" | "pin_unavailable"}
+
+async function fetchVersionInfoDetailed(url: string): Promise<ManifestFetchResult> {
   try {
     const response = await fetch(url)
     if (!response.ok) {
       console.error("Failed to fetch version info:", response.status)
-      return null
+      // 4xx: the manifest does not exist (or is gone) — permanent for this app
+      // build, retrying cannot help. Everything else is transient server/network
+      // trouble and retryable.
+      return {
+        json: null,
+        failureReason: response.status >= 400 && response.status < 500 ? "pin_unavailable" : "network",
+      }
+    }
+    try {
+      return {json: await response.json()}
+    } catch (parseError) {
+      console.error("OTA: manifest is not valid JSON:", parseError)
+      return {json: null, failureReason: "pin_unavailable"}
     }
-    return await response.json()
   } catch (error) {
     console.error("OTA: Error fetching version info:", error)
-    return null
+    return {json: null, failureReason: "network"}
   }
 }
 
+export async function fetchVersionInfo(url: string): Promise<VersionJson | null> {
+  return (await fetchVersionInfoDetailed(url)).json
+}
+
 export function checkVersionUpdateAvailable(
   currentBuildNumber: string | undefined,
   versionJson: VersionJson | null,
+  floorVersionCode: number = DOWNGRADE_FLOOR_VERSION_CODE,
 ): boolean {
+  return getApkUpdateDirection(currentBuildNumber, versionJson, floorVersionCode) !== null
+}
+
+/**
+ * Direction of the pending APK change, or null when the glasses already match the manifest.
+ * Every apps-shaped manifest the phone drives is an exact pin, so both directions are
+ * actionable (mirroring the glasses-side `DowngradeGate`); the ancient top-level manifest
+ * shape stays upgrade-only, and zeroed rescue pins are never actionable.
+ */
+export function getApkUpdateDirection(
+  currentBuildNumber: string | undefined,
+  versionJson: VersionJson | null,
+  floorVersionCode: number = DOWNGRADE_FLOOR_VERSION_CODE,
+): "upgrade" | "downgrade" | null {
   if (!currentBuildNumber || !versionJson) {
-    return false
+    return null
   }
 
   const currentVersion = parseInt(currentBuildNumber, 10)
   if (isNaN(currentVersion)) {
-    return false
+    return null
   }
 
   let serverVersion: number | undefined
+  let exactPin = false
 
-  if (versionJson.apps?.["com.mentra.asg_client"]) {
-    serverVersion = versionJson.apps["com.mentra.asg_client"].versionCode
+  const appEntry = versionJson.apps?.["com.mentra.asg_client"]
+  if (appEntry) {
+    serverVersion = appEntry.versionCode
+    exactPin = true
   } else if (versionJson.versionCode) {
     serverVersion = versionJson.versionCode
   }
 
   if (!serverVersion || isNaN(serverVersion)) {
-    return false
+    return null
   }
 
-  return serverVersion > currentVersion
+  if (serverVersion > currentVersion) {
+    return "upgrade"
+  }
+  // Downgrades require an exact pin AND a target at/above the enabled floor. A non-positive floor
+  // disables downgrades entirely, matching ASG's fail-closed DowngradeGate — so the phone never
+  // offers what the glasses would refuse.
+  if (serverVersion < currentVersion && exactPin && floorVersionCode > 0 && serverVersion >= floorVersionCode) {
+    return "downgrade"
+  }
+  return null
 }
 
 export function getLatestVersionInfo(versionJson: VersionJson | null): VersionInfo | null {
@@ -184,7 +258,7 @@ export function checkBesUpdate(besFirmware: BesFirmware | undefined, currentVers
   return compareVersions(besFirmware.version, currentVersion) > 0
 }
 
-function compareVersions(version1: string, version2: string): number {
+export function compareVersions(version1: string, version2: string): number {
   if (version1.includes(".") && version2.includes(".")) {
     const parts1 = version1.split(".")
     const parts2 = version2.split(".")
@@ -208,14 +282,62 @@ export async function checkForOtaUpdate(
   currentBuildNumber: string,
   currentMtkVersion?: string,
   currentBesVersion?: string,
+  floorVersionCode: number = DOWNGRADE_FLOOR_VERSION_CODE,
 ): Promise<OtaCheckResult> {
   try {
     console.log("OTA: Checking for OTA update - URL: " + otaVersionUrl + ", current build: " + currentBuildNumber)
-    const versionJson = await fetchVersionInfo(otaVersionUrl)
+    const fetched = await fetchVersionInfoDetailed(otaVersionUrl)
+    const versionJson = fetched.json
+    if (!versionJson) {
+      return {
+        hasCheckCompleted: false,
+        updateAvailable: false,
+        latestVersionInfo: null,
+        updates: [],
+        mtkPatch: null,
+        besVersion: null,
+        isApkDowngrade: false,
+        manifestBody: null,
+        checkFailureReason: fetched.failureReason ?? "network",
+      }
+    }
     const latestVersionInfo = getLatestVersionInfo(versionJson)
 
-    const apkUpdateAvailable = checkVersionUpdateAvailable(currentBuildNumber, versionJson)
-    console.log(`OTA: APK update available: ${apkUpdateAvailable} (current: ${currentBuildNumber})`)
+    // A manifest whose ASG pin is missing/zeroed cannot verify anything for modern
+    // glasses (zeroed pins are only legitimate in the frozen legacy rescue manifests
+    // that pre-39 glasses are checked against). Report the check as FAILED rather
+    // than silently completing as "up to date" — an unverifiable state must never
+    // present as a verified one.
+    const currentVersionNumber = parseInt(currentBuildNumber, 10)
+    const pinnedEntry = versionJson?.apps?.["com.mentra.asg_client"]
+    const pinnedVersion = pinnedEntry?.versionCode ?? versionJson?.versionCode
+    if (
+      versionJson &&
+      Number.isFinite(currentVersionNumber) &&
+      currentVersionNumber >= 39 &&
+      !(typeof pinnedVersion === "number" && pinnedVersion > 0)
+    ) {
+      console.error(
+        `OTA: manifest at ${otaVersionUrl} has no valid ASG pin (versionCode=${String(pinnedVersion)}) - treating check as failed`,
+      )
+      return {
+        hasCheckCompleted: false,
+        updateAvailable: false,
+        latestVersionInfo: null,
+        updates: [],
+        mtkPatch: null,
+        besVersion: null,
+        isApkDowngrade: false,
+        manifestBody: null,
+        checkFailureReason: "pin_unavailable",
+      }
+    }
+
+    const apkDirection = getApkUpdateDirection(currentBuildNumber, versionJson, floorVersionCode)
+    const apkUpdateAvailable = apkDirection !== null
+    console.log(
+      `OTA: APK update available: ${apkUpdateAvailable} (current: ${currentBuildNumber}, direction: ${apkDirection ?? "none"})`,
+    )
 
     const mtkPatch = findMatchingMtkPatch(versionJson?.mtk_patches, currentMtkVersion)
     const mtkUpdateAvailable = mtkPatch !== null
@@ -243,6 +365,8 @@ export async function checkForOtaUpdate(
       updates,
       mtkPatch,
       besVersion: versionJson?.bes_firmware?.version || null,
+      isApkDowngrade: apkDirection === "downgrade",
+      manifestBody: versionJson ? JSON.stringify(versionJson) : null,
     }
   } catch (error) {
     console.error("Error checking for OTA update:", error)
@@ -253,6 +377,9 @@ export async function checkForOtaUpdate(
       updates: [],
       mtkPatch: null,
       besVersion: null,
+      isApkDowngrade: false,
+      manifestBody: null,
+      checkFailureReason: "network",
     }
   }
 }
@@ -266,12 +393,18 @@ export async function checkCurrentGlassesForUpdate(
     waitForMtkVersionMs = 2000,
     refreshVersionInfo = true,
     fixClockBeforeCheck = true,
+    floorVersionCode = DOWNGRADE_FLOOR_VERSION_CODE,
   } = options
 
   if (!glassesConnectedNow()) {
     return emptyCheckResult("disconnected")
   }
 
+  if (!hasConfiguredModernOtaManifestPin()) {
+    console.log("OTA: check skipped - this app or Engine package has no embedded OTA manifest pin")
+    return emptyCheckResult("dev_build")
+  }
+
   if (refreshVersionInfo) {
     void BluetoothSdk.requestVersionInfo().catch((error) => {
       console.warn("OTA: Failed to request version_info from glasses:", error)
@@ -284,7 +417,10 @@ export async function checkCurrentGlassesForUpdate(
     buildNumber = useGlassesStore.getState().buildNumber
   }
 
-  if (!buildNumber) {
+  if (!buildNumber || !(parseInt(buildNumber, 10) > 0)) {
+    // Covers absent, non-numeric, and zero build numbers: a glasses version we
+    // cannot parse means nothing is verifiable, so skip rather than ghost an
+    // "up to date" result from a comparison that never really ran.
     return emptyCheckResult("missing_build")
   }
 
@@ -325,8 +461,18 @@ export async function checkCurrentGlassesForUpdate(
     })
   }
 
-  const manifestUrl = getAsgOtaVersionUrl(useGlassesStore.getState().otaVersionUrl, buildNumber)
-  const result = await checkForOtaUpdate(manifestUrl, buildNumber, mtkFirmwareVersion, besFirmwareVersion)
+  const manifestUrl = resolveOtaManifestUrl(useGlassesStore.getState().otaVersionUrl, buildNumber)
+  if (!manifestUrl) {
+    console.log("OTA: check skipped - no OTA manifest pin resolved")
+    return emptyCheckResult("dev_build")
+  }
+  const result = await checkForOtaUpdate(
+    manifestUrl,
+    buildNumber,
+    mtkFirmwareVersion,
+    besFirmwareVersion,
+    floorVersionCode,
+  )
 
   if (!result.hasCheckCompleted) {
     return {
@@ -360,6 +506,7 @@ export async function checkCurrentGlassesForUpdate(
     )
   }
   const updateAvailable = filteredUpdates.length > 0 && !!result.latestVersionInfo
+  const isApkDowngrade = result.isApkDowngrade && filteredUpdates.includes("apk")
   const updateInfo = updateAvailable
     ? {
         available: true,
@@ -367,6 +514,8 @@ export async function checkCurrentGlassesForUpdate(
         versionName: result.latestVersionInfo?.versionName || "",
         updates: filteredUpdates,
         totalSize: 0,
+        ...(filteredUpdates.includes("bes") && result.besVersion ? {besVersion: result.besVersion} : {}),
+        isDowngrade: isApkDowngrade,
       }
     : null
 
@@ -376,8 +525,19 @@ export async function checkCurrentGlassesForUpdate(
     ...result,
     updateAvailable,
     updates: filteredUpdates,
+    isApkDowngrade,
     updateInfo,
-    isRequired: result.latestVersionInfo?.isRequired !== false,
+    // Required-update policy: an EXPLICIT isRequired in the manifest is the
+    // release-engineering escape hatch and wins in both directions. When absent,
+    // upgrades keep the historical forced default, but downgrades are always
+    // skippable — a version change that resets glasses settings must be
+    // declinable unless someone explicitly forced it.
+    isRequired:
+      result.latestVersionInfo?.isRequired === true
+        ? true
+        : result.latestVersionInfo?.isRequired === false
+          ? false
+          : !isApkDowngrade,
     manifestUrl,
     buildNumber,
     mtkFirmwareVersion,

package/src/services/PhoneCalendarHelpers.ts

@@ -0,0 +1,212 @@
+import {MiniappErrorCode, type CalendarEvent} from "@mentra/miniapp"
+
+const DEFAULT_LIMIT = 50
+const MAX_LIMIT = 100
+const MAX_RANGE_MS = 31 * 24 * 60 * 60 * 1000
+
+export interface CalendarListRequest {
+  startsAt?: unknown
+  endsAt?: unknown
+  limit?: unknown
+}
+
+export class PhoneCalendarError extends Error {
+  constructor(
+    public readonly code: MiniappErrorCode,
+    message: string,
+  ) {
+    super(message)
+    this.name = "PhoneCalendarError"
+  }
+}
+
+export interface ValidatedCalendarListRequest {
+  startsAt: Date
+  endsAt: Date
+  limit: number
+}
+
+export interface RawCalendarEvent {
+  id?: string
+  calendarId?: string
+  title?: string | null
+  startDate: string | Date
+  endDate: string | Date
+  timeZone?: string | null
+  allDay?: boolean
+  location?: string | null
+  notes?: string | null
+  url?: string | null
+}
+
+export function validateCalendarListRequest(request: CalendarListRequest): ValidatedCalendarListRequest {
+  const startsAt = parseDate(request.startsAt, "startsAt")
+  const endsAt = parseDate(request.endsAt, "endsAt")
+  if (endsAt.getTime() <= startsAt.getTime()) {
+    throw new PhoneCalendarError(MiniappErrorCode.INVALID_ARGUMENT, "endsAt must be after startsAt")
+  }
+  if (endsAt.getTime() - startsAt.getTime() > MAX_RANGE_MS) {
+    throw new PhoneCalendarError(MiniappErrorCode.INVALID_ARGUMENT, "Calendar query range may not exceed 31 days")
+  }
+
+  const limit = request.limit === undefined ? DEFAULT_LIMIT : request.limit
+  if (typeof limit !== "number" || !Number.isInteger(limit) || limit < 1 || limit > MAX_LIMIT) {
+    throw new PhoneCalendarError(
+      MiniappErrorCode.INVALID_ARGUMENT,
+      `limit must be an integer between 1 and ${MAX_LIMIT}`,
+    )
+  }
+  return {startsAt, endsAt, limit}
+}
+
+function parseDate(value: unknown, field: string): Date {
+  if (typeof value !== "string") {
+    throw new PhoneCalendarError(MiniappErrorCode.INVALID_ARGUMENT, `${field} must be an ISO 8601 string`)
+  }
+  const date = new Date(value)
+  if (Number.isNaN(date.getTime())) {
+    throw new PhoneCalendarError(MiniappErrorCode.INVALID_ARGUMENT, `${field} must be a valid ISO 8601 string`)
+  }
+  return date
+}
+
+export function extractHttpsLinks(...values: Array<string | null | undefined>): string[] {
+  const links = new Set<string>()
+  for (const value of values) {
+    for (const match of value?.match(/https:\/\/[^\s<>"']+/gi) ?? []) {
+      let link = match
+      while (".,;:!?)]}".includes(link[link.length - 1] ?? "")) link = link.slice(0, -1)
+      if (link) links.add(link)
+    }
+  }
+  return [...links]
+}
+
+interface CalendarDateParts {
+  year: number
+  month: number
+  day: number
+  hour: number
+  minute: number
+  second: number
+}
+
+function localDateParts(date: Date): CalendarDateParts {
+  return {
+    year: date.getFullYear(),
+    month: date.getMonth() + 1,
+    day: date.getDate(),
+    hour: date.getHours(),
+    minute: date.getMinutes(),
+    second: date.getSeconds(),
+  }
+}
+
+function datePartsInTimeZone(date: Date, timeZone: string): CalendarDateParts | undefined {
+  try {
+    const parts = new Intl.DateTimeFormat("en-US", {
+      timeZone,
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit",
+      hour: "2-digit",
+      minute: "2-digit",
+      second: "2-digit",
+      hourCycle: "h23",
+    }).formatToParts(date)
+    const value = (type: Intl.DateTimeFormatPartTypes) => Number(parts.find((part) => part.type === type)?.value)
+    return {
+      year: value("year"),
+      month: value("month"),
+      day: value("day"),
+      hour: value("hour"),
+      minute: value("minute"),
+      second: value("second"),
+    }
+  } catch {
+    return undefined
+  }
+}
+
+function timeZoneOffsetMinutes(date: Date, timeZone: string): number | undefined {
+  const parts = datePartsInTimeZone(date, timeZone)
+  if (!parts) return undefined
+  const representedAsUtc = Date.UTC(
+    parts.year,
+    parts.month - 1,
+    parts.day,
+    parts.hour,
+    parts.minute,
+    parts.second,
+    date.getUTCMilliseconds(),
+  )
+  return Math.round((representedAsUtc - date.getTime()) / 60_000)
+}
+
+function pad(value: number, length = 2): string {
+  return String(value).padStart(length, "0")
+}
+
+function formatOffset(offsetMinutes: number): string {
+  if (offsetMinutes === 0) return "Z"
+  const sign = offsetMinutes < 0 ? "-" : "+"
+  const absolute = Math.abs(offsetMinutes)
+  return `${sign}${pad(Math.floor(absolute / 60))}:${pad(absolute % 60)}`
+}
+
+function formatAllDayDate(value: string | Date, timeZone?: string | null): string {
+  const dateOnly = typeof value === "string" ? /^(\d{4})-(\d{2})-(\d{2})$/.exec(value) : null
+  if (dateOnly) {
+    const [, year, month, day] = dateOnly
+    const localMidnight = new Date(Number(year), Number(month) - 1, Number(day))
+    let offsetMinutes = -localMidnight.getTimezoneOffset()
+    if (timeZone) {
+      // Resolve the offset at midnight in the event timezone. Repeating once
+      // accounts for the initial UTC guess landing across a DST boundary.
+      const wallTime = Date.UTC(Number(year), Number(month) - 1, Number(day))
+      let instant = new Date(wallTime)
+      for (let attempt = 0; attempt < 2; attempt += 1) {
+        const offset = timeZoneOffsetMinutes(instant, timeZone)
+        if (offset === undefined) break
+        offsetMinutes = offset
+        instant = new Date(wallTime - offset * 60_000)
+      }
+    }
+    return `${year}-${month}-${day}T00:00:00.000${formatOffset(offsetMinutes)}`
+  }
+
+  const date = new Date(value)
+  const zonedParts = timeZone ? datePartsInTimeZone(date, timeZone) : undefined
+  const parts = zonedParts ?? localDateParts(date)
+  const offsetMinutes =
+    timeZone && zonedParts
+      ? (timeZoneOffsetMinutes(date, timeZone) ?? -date.getTimezoneOffset())
+      : -date.getTimezoneOffset()
+  return `${pad(parts.year, 4)}-${pad(parts.month)}-${pad(parts.day)}T${pad(parts.hour)}:${pad(parts.minute)}:${pad(parts.second)}.${pad(date.getUTCMilliseconds(), 3)}${formatOffset(offsetMinutes)}`
+}
+
+export function normalizeCalendarEvent(event: RawCalendarEvent): CalendarEvent {
+  const startsAt = event.allDay
+    ? formatAllDayDate(event.startDate, event.timeZone)
+    : new Date(event.startDate).toISOString()
+  const endsAt = event.allDay ? formatAllDayDate(event.endDate, event.timeZone) : new Date(event.endDate).toISOString()
+  const calendarId = event.calendarId ?? ""
+  const eventId = event.id ?? ""
+  return {
+    id: `${calendarId}:${eventId}:${startsAt}`,
+    calendarId,
+    title: event.title ?? "",
+    startsAt,
+    endsAt,
+    ...(event.timeZone ? {timezone: event.timeZone} : {}),
+    allDay: !!event.allDay,
+    ...(event.location ? {location: event.location} : {}),
+    ...(event.notes ? {notes: event.notes} : {}),
+    ...(event.url ? {url: event.url} : {}),
+    links: extractHttpsLinks(event.url, event.location, event.notes),
+  }
+}
+
+export function calendarEventOverlapsWindow(event: CalendarEvent, startsAt: Date, endsAt: Date): boolean {
+  return Date.parse(event.endsAt) > startsAt.getTime() && Date.parse(event.startsAt) < endsAt.getTime()
+}

package/src/services/PhoneCalendarService.ts

@@ -0,0 +1,65 @@
+import * as Calendar from "expo-calendar"
+import {Platform} from "react-native"
+import {check, PERMISSIONS, RESULTS} from "react-native-permissions"
+
+import {MiniappErrorCode, type CalendarListResult} from "@mentra/miniapp"
+
+import {
+  calendarEventOverlapsWindow,
+  type CalendarListRequest,
+  normalizeCalendarEvent,
+  PhoneCalendarError,
+  validateCalendarListRequest,
+} from "./PhoneCalendarHelpers"
+
+export {PhoneCalendarError} from "./PhoneCalendarHelpers"
+
+type CalendarPermissionStatus = Awaited<
+  ReturnType<typeof Calendar.getCalendarPermissionsAsync>
+>["status"]
+
+/**
+ * expo-calendar reports anything below EventKit full access as not granted,
+ * so distinguish the states the user can actually fix. "Reopen the miniapp"
+ * is only true while the permission is undetermined — once iOS has resolved
+ * it (denied or write-only/limited), only Settings can change it.
+ */
+async function calendarPermissionMessage(status: CalendarPermissionStatus): Promise<string> {
+  if (status === "undetermined") {
+    return "Calendar permission has not been granted yet. Reopen the miniapp and allow calendar access."
+  }
+  if (Platform.OS === "ios") {
+    const writeOnly = await check(PERMISSIONS.IOS.CALENDARS_WRITE_ONLY).catch(() => null)
+    if (writeOnly === RESULTS.GRANTED || writeOnly === RESULTS.LIMITED) {
+      return 'Calendar access is limited to write-only. Enable "Full Access" for Mentra in Settings › Privacy & Security › Calendars.'
+    }
+    return "Calendar access is denied. Enable it for Mentra in Settings › Privacy & Security › Calendars."
+  }
+  return "Calendar access is denied. Enable the Calendar permission for Mentra in your phone's app settings."
+}
+
+export async function listPhoneCalendarEvents(request: CalendarListRequest): Promise<CalendarListResult> {
+  const {startsAt, endsAt, limit} = validateCalendarListRequest(request)
+  const permission = await Calendar.getCalendarPermissionsAsync()
+  if (permission.status !== "granted") {
+    throw new PhoneCalendarError(MiniappErrorCode.PERMISSION_DENIED, await calendarPermissionMessage(permission.status))
+  }
+
+  const calendars = await Calendar.getCalendarsAsync(Calendar.EntityTypes.EVENT)
+  if (calendars.length === 0) return {events: [], truncated: false}
+
+  const rawEvents = await Calendar.getEventsAsync(
+    calendars.map((calendar) => calendar.id),
+    startsAt,
+    endsAt,
+  )
+  const events = rawEvents
+    .map(normalizeCalendarEvent)
+    .filter((event) => calendarEventOverlapsWindow(event, startsAt, endsAt))
+    .sort((a, b) => Date.parse(a.startsAt) - Date.parse(b.startsAt) || Date.parse(a.endsAt) - Date.parse(b.endsAt))
+
+  return {
+    events: events.slice(0, limit),
+    truncated: events.length > limit,
+  }
+}