@mentra/miniapp 0.3.0-beta.0

package/src/modules/permissions.ts

@@ -0,0 +1,84 @@
+/**
+ * @fileoverview PermissionsModule — manifest-declared permission introspection.
+ *
+ * Mirrors cloud SDK v3's PermissionsManager surface and semantics:
+ *   permissions.has(type)         — synchronous boolean
+ *   permissions.getAll()          — full PermissionRecord
+ *   permissions.onUpdate(handler) — fires on cache change
+ *   permissions.onPermissionError(handler) — typed handler for the existing
+ *                                            PERMISSION_NOT_DECLARED error
+ *
+ * What "permission" means here. Same as v3: this module tracks
+ * **manifest-declared** permissions. `permissions.has("microphone") === true`
+ * means the miniapp's manifest.json declared MICROPHONE — it does NOT mean
+ * the user actually granted the OS permission. To detect OS-grant state,
+ * observe whether your subscriptions actually deliver events.
+ *
+ * OS-level grant state and `request(...)` are deferred to a future round.
+ * Their additions will land additively on this same module — `isGranted(...)`
+ * / `request(...)` alongside the existing `has(...)` / `getAll(...)` —
+ * without renaming today's surface.
+ */
+
+import {MiniappErrorCode} from "../protocol"
+import type {MiniappRequestError} from "../session"
+import {MiniappSession} from "../session"
+import type {PermissionRecord, PermissionType} from "../session"
+import type {UnsubscribeFn} from "./events"
+
+export interface PermissionErrorEvent {
+  /** The error code. Always PERMISSION_NOT_DECLARED today; reserved for future codes. */
+  code: string
+  message: string
+  /** The manifest permission name (UPPER_CASE) that was missing. */
+  permission?: string
+  /** The subscription / operation that triggered the rejection. */
+  subscription?: string
+  operation?: string
+}
+
+export class PermissionsModule {
+  /** Local handlers for onUpdate. Session emitter handles the fan-out. */
+  constructor(private readonly session: MiniappSession) {}
+
+  /** True iff the named permission is declared in the miniapp's manifest. */
+  has(type: PermissionType): boolean {
+    return this.session._getPermissions()[type] === true
+  }
+
+  /** Full record of declared permissions. Fresh shallow copy. */
+  getAll(): PermissionRecord {
+    return this.session._getPermissions()
+  }
+
+  /**
+   * Subscribe to declared-permission updates. Fires when the cached record
+   * changes — usually on CONNECT_ACK, or when the phone pushes a
+   * PERMISSIONS_UPDATE (e.g. dev miniapp re-scanned with updated manifest).
+   *
+   * Does NOT fire immediately with the current value — call getAll()
+   * separately if you want the seed.
+   */
+  onUpdate(handler: (perms: PermissionRecord) => void): UnsubscribeFn {
+    return this.session.on("permissions", handler)
+  }
+
+  /**
+   * Subscribe to typed PERMISSION_NOT_DECLARED errors. Sugar over the
+   * existing session "error" event, filtered to the permission-error code.
+   */
+  onPermissionError(handler: (err: PermissionErrorEvent) => void): UnsubscribeFn {
+    return this.session.on("error", (e) => {
+      const maybe = e as Error & Partial<MiniappRequestError> & Record<string, unknown>
+      if (maybe?.code === MiniappErrorCode.PERMISSION_NOT_DECLARED) {
+        handler({
+          code: String(maybe.code),
+          message: String(maybe.message ?? ""),
+          permission: maybe.permission as string | undefined,
+          subscription: maybe.subscription as string | undefined,
+          operation: maybe.operation as string | undefined,
+        })
+      }
+    })
+  }
+}

package/src/modules/phone.ts

@@ -0,0 +1,155 @@
+/**
+ * @fileoverview PhoneModule — phone device-state events.
+ *
+ * Mirrors cloud SDK v3's PhoneManager structure. Sub-namespaced by concern:
+ *
+ *   session.phone.notifications.{on, hasPermission, stop}
+ *   session.phone.calendar.{listEvents, hasPermission}
+ *   session.phone.onBattery(...)                          // stays flat
+ *
+ * Imperative phone-OS calls (share, openUrl, copyToClipboard, download) live
+ * on `session.system` — different shape (one-shot calls vs. event subs) so
+ * we don't conflate them.
+ *
+ * `phone.notifications.onDismissed` is Android-only. iOS doesn't expose
+ * notification-dismiss callbacks to apps (Apple privacy restriction);
+ * subscribing on iOS is a no-op even though the API is present.
+ */
+
+import {MiniappRequestType, MiniappStreamType} from "../protocol"
+import {MiniappSession} from "../session"
+import type {BatteryData, NotificationDismissedData, PhoneNotificationData, UnsubscribeFn} from "./events"
+
+class TrackedSubs {
+  private readonly unsubs = new Set<UnsubscribeFn>()
+
+  protected track(unsub: UnsubscribeFn): UnsubscribeFn {
+    this.unsubs.add(unsub)
+    return () => {
+      this.unsubs.delete(unsub)
+      unsub()
+    }
+  }
+
+  stop(): void {
+    for (const u of this.unsubs) {
+      try {
+        u()
+      } catch {
+        /* ignore */
+      }
+    }
+    this.unsubs.clear()
+  }
+}
+
+export class PhoneNotificationsModule extends TrackedSubs {
+  constructor(private readonly session: MiniappSession) {
+    super()
+  }
+
+  on(handler: (data: PhoneNotificationData) => void): UnsubscribeFn {
+    return this.track(this.session._subscribe(MiniappStreamType.PHONE_NOTIFICATION, handler as (data: unknown) => void))
+  }
+
+  /**
+   * Subscribe to dismiss events for phone notifications. Fires when the user
+   * dismisses (swipes away or clears) a notification.
+   *
+   * **Android only.** iOS does not expose dismiss callbacks to apps (Apple
+   * privacy restriction); subscribing on iOS succeeds but no events ever
+   * fire. The matching `notifications.on()` post-event still works on both
+   * platforms.
+   */
+  onDismissed(handler: (data: NotificationDismissedData) => void): UnsubscribeFn {
+    return this.track(
+      this.session._subscribe(MiniappStreamType.PHONE_NOTIFICATION_DISMISSED, handler as (data: unknown) => void),
+    )
+  }
+
+  /** True iff `READ_NOTIFICATIONS` is declared in the miniapp's manifest. */
+  get hasPermission(): boolean {
+    return this.session._hasManifestPermission("READ_NOTIFICATIONS")
+  }
+}
+
+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
+}
+
+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. */
+  get hasPermission(): boolean {
+    return this.session._hasManifestPermission("CALENDAR")
+  }
+}
+
+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
+
+  constructor(private readonly session: MiniappSession) {
+    this.notifications = new PhoneNotificationsModule(session)
+    this.calendar = new PhoneCalendarModule(session)
+  }
+
+  /**
+   * Phone battery events. Stays flat (not sub-namespaced) — single event,
+   * no extra surface.
+   */
+  onBattery(handler: (data: BatteryData) => void): UnsubscribeFn {
+    return this.session._subscribe(MiniappStreamType.PHONE_BATTERY, handler as (data: unknown) => void)
+  }
+}