@glassly/miniapp 0.1.0-dev.26

package/src/modules/dashboard.ts

@@ -0,0 +1,51 @@
+/**
+ * @fileoverview DashboardAPI. setContent() is a noop in v1 (the cloud
+ * DashboardManager owns widget rendering); showNativeDashboard() is live.
+ */
+
+import {MiniappRequestType} from "../protocol"
+import {MiniappSession} from "../session"
+
+export type DashboardMode = "main" | "expanded" | "always_on"
+
+/** "shown" = forwarded to the glasses; "unsupported" = the host refused (e.g. native nav mode owns the screen). */
+export interface ShowNativeDashboardResult {
+  status: "shown" | "unsupported"
+  reason?: string
+}
+
+export class DashboardAPI {
+  private warned = false
+
+  constructor(private readonly session: MiniappSession) {}
+
+  setContent(mode: DashboardMode, content: string): void {
+    if (!this.warned) {
+      console.warn("[@glassly/miniapp] dashboard.setContent() is deferred in v1.")
+      this.warned = true
+    }
+    // Still forward so the phone can log/ignore consistently.
+    this.session.sendOneShot({
+      type: MiniappRequestType.DASHBOARD_CONTENT_UPDATE,
+      mode,
+      content,
+    })
+  }
+
+  /**
+   * Bring the glasses' native dashboard (the OS-level idle screen) to the
+   * foreground. On the G2 this tears down the current page; the display
+   * returns when the wearer dismisses the dashboard or content is re-rendered.
+   */
+  showNativeDashboard(): Promise<ShowNativeDashboardResult> {
+    return this.session
+      .sendRequest<ShowNativeDashboardResult>({type: MiniappRequestType.SHOW_NATIVE_DASHBOARD})
+      .catch((err) => ({
+        status: "unsupported" as const,
+        reason:
+          typeof err === "object" && err !== null && "message" in err
+            ? String((err as {message: unknown}).message)
+            : String(err),
+      }))
+  }
+}

package/src/modules/display.ts

@@ -0,0 +1,214 @@
+/**
+ * @fileoverview DisplayManager — the glasses display, via `render()`.
+ *
+ * render(elements) is replace-the-frame scene rendering: each call describes
+ * everything that should be on screen, the host diffs it against the previous
+ * frame per device, and `render([])` clears. The legacy one-shot `show*`
+ * layout methods were removed once nothing first-party or known-external
+ * called them; hosts still accept the historical `miniapp_display` wire shape
+ * from bundles packed with older SDKs.
+ */
+
+import {MiniappRequestType} from "../protocol"
+import {MiniappSession} from "../session"
+
+export type ViewType = "main" | "dashboard"
+
+export type DisplayBreakMode = "character" | "character-no-hyphen" | "word" | "strict-word"
+
+// ============================================================================
+// render() — the scene API
+// ============================================================================
+
+/** Canvas corner a box's `x`/`y` are measured from (insets grow inward). */
+export type RenderAnchor = "top-left" | "top-right" | "bottom-left" | "bottom-right"
+
+/**
+ * Pixel-space bounding box on the device's drawable canvas (see
+ * `capabilities.display`).
+ *
+ * With an `anchor`, `x`/`y` become insets from that corner, growing inward,
+ * and the host resolves the box against the connected device's real canvas —
+ * e.g. `{x: 0, y: 0, w: 120, h: 120, anchor: "bottom-right"}` sits flush in
+ * the bottom-right corner on every device, whatever its resolution. Corners
+ * only; there is no center/edge anchoring or scaling. Hosts older than the
+ * anchor feature ignore the field and place the box from the top-left.
+ */
+export interface RenderBox {
+  x: number
+  y: number
+  w: number
+  h: number
+  /** Which canvas corner x/y are measured from. Default "top-left". */
+  anchor?: RenderAnchor
+}
+
+export interface RenderTextStyle {
+  /** Border width in px (0/absent = none). */
+  border?: number
+  /** Border corner radius in px. */
+  radius?: number
+  /** What happens to text that doesn't fit the box after wrapping. Default "clip". */
+  overflow?: "clip" | "ellipsis"
+  /** Line-break policy for wrapping (host wraps; the box carries pre-wrapped text). */
+  breakMode?: DisplayBreakMode
+  /**
+   * "mono": fixed-pitch text drawn at `fontSize` px with a fixed line height
+   * of 1.2 × size, and NOT re-wrapped by the host — lines are taken as given.
+   * For grids (terminals, tables). Devices without a phone-side rasterizer
+   * (stock G2 firmware) fall back to their own proportional font.
+   *
+   * "builtin": the glasses draw the text themselves with their built-in 20 px
+   * proportional font (Glassly CFW G2 only — tiny updates instead of bitmap
+   * re-sends). Lines are taken as given (split on \n, never re-wrapped) and
+   * clipped at the display edge, and the render window is pinned to the
+   * middle depth level while such text is on screen. Other devices and stock
+   * firmware fall back to the default proportional face.
+   */
+  font?: "default" | "mono" | "builtin"
+  /** Font size in px for `font: "mono"`. Default 20. */
+  fontSize?: number
+}
+
+export interface RenderRectStyle {
+  border?: number
+  radius?: number
+}
+
+/**
+ * One element of a rendered scene. `id` is optional but recommended for
+ * anything that updates over time: elements with a stable id update in place on
+ * the glasses (no flicker); the host matches unnamed elements by geometry.
+ */
+export type RenderElement =
+  | {type: "text"; id?: string; box: RenderBox; text: string; style?: RenderTextStyle}
+  | {type: "image"; id?: string; box: RenderBox; data: string}
+  | {type: "rect"; id?: string; box: RenderBox; style?: RenderRectStyle}
+
+export interface RenderOptions {
+  view?: ViewType
+  /** Auto-clear after this many ms (same semantics as legacy display options). */
+  durationMs?: number
+}
+
+// ============================================================================
+// Native navigation UI (capability `hasNativeNavigation`, e.g. G2)
+// ============================================================================
+
+/** Turn-by-turn card fields — pre-formatted display strings, rendered verbatim by the device. */
+export interface NativeNavInfo {
+  /** Firmware direction-icon index, 0…35. */
+  directionIcon: number
+  /** Distance to the next maneuver, e.g. "500 m". */
+  distance: string
+  roadName: string
+  /** Remaining trip duration, e.g. "11 min". */
+  spendTime: string
+  /** Distance to the destination, e.g. "0.9 km". */
+  remainDistance: string
+  /** Arrival time, e.g. "18:18". */
+  etaTime: string
+  /** Current speed, e.g. "5 km/h". */
+  speed: string
+}
+
+/**
+ * "sent" = forwarded to the device. "unsupported" = no native nav UI on this
+ * device / no active trip — callers should fall back to render().
+ */
+export interface NativeNavResult {
+  status: "sent" | "unsupported" | "blocked"
+  reason?: string
+}
+
+/**
+ * Outcome of a render request, resolved when the host's display arbitration
+ * settles it. "displayed" = accepted and sent to the device — NOT a
+ * render confirmation. "blocked" = another app owns the display (or the
+ * request failed); `reason` says why.
+ */
+export interface RenderResult {
+  status: "displayed" | "blocked"
+  /** True when the host adjusted the scene (clamped boxes, dropped elements, degraded for the device). */
+  degraded?: boolean
+  /** Ids of elements the host dropped (budget/bounds/device limits) — dropped is never silent. */
+  dropped?: string[]
+  reason?: string
+}
+
+export class DisplayManager {
+  constructor(private readonly session: MiniappSession) {}
+
+  /**
+   * Render a whole scene of positioned elements — replace-the-frame.
+   *
+   * Each call describes everything that should be on screen; the host diffs it
+   * against the previous frame per device (elements with a stable `id` update
+   * in place; elements you stop sending are removed). There is no lifecycle to
+   * manage and no remove calls — `render([])` clears.
+   *
+   * Coordinates are raw pixels on the device's drawable canvas — read
+   * `session.capabilities.display` (populated on the "ready" event) for the
+   * real width/height and element budgets. Out-of-bounds boxes are clamped and
+   * over-budget elements are dropped tail-first; both are reported via the
+   * result, never silently.
+   *
+   * Awaiting is OPT-IN — a plain fire-and-forget call is fine. The returned
+   * promise never rejects.
+   *
+   * @example
+   * const result = await session.display.render([
+   *   {type: "text",  id: "stats", box: {x: 12, y: 9, w: 200, h: 28}, text: "863 m  11 min"},
+   *   {type: "image", id: "map",   box: {x: 335, y: 14, w: 150, h: 150}, data: mapPng},
+   *   {type: "rect",  box: {x: 0, y: 0, w: 500, h: 220}, style: {radius: 4}},
+   * ])
+   * if (result.degraded) console.warn("dropped:", result.dropped)
+   */
+  render(elements: RenderElement[], options: RenderOptions = {}): Promise<RenderResult> {
+    return this.session
+      .sendRequest<RenderResult>({
+        type: MiniappRequestType.RENDER,
+        view: options.view ?? "main",
+        elements,
+        durationMs: options.durationMs,
+      })
+      .catch((err) => ({
+        status: "blocked" as const,
+        reason:
+          typeof err === "object" && err !== null && "message" in err
+            ? String((err as {message: unknown}).message)
+            : String(err),
+      }))
+  }
+
+  /** Update the native nav UI's turn-by-turn card. */
+  sendNativeNavInfo(info: NativeNavInfo): Promise<NativeNavResult> {
+    return this.sendNativeNav({action: "info", info})
+  }
+
+  /**
+   * Push the native nav UI's live mini map (base64 BMP/PNG; the host re-encodes
+   * and scales to the device's slot — 176×176 on G2). Draw north-up with the
+   * cursor centred; the device rotates the bitmap by `rotationDeg`.
+   */
+  sendNativeNavMiniMap(data: string, options: {rotationDeg?: number; border?: boolean} = {}): Promise<NativeNavResult> {
+    return this.sendNativeNav({action: "mini_map", map: {data, ...options}})
+  }
+
+  /** Push the native nav UI's overview (full-route) map — 576×188 on G2. */
+  sendNativeNavOverviewMap(data: string): Promise<NativeNavResult> {
+    return this.sendNativeNav({action: "overview_map", map: {data}})
+  }
+
+  private sendNativeNav(payload: Record<string, unknown>): Promise<NativeNavResult> {
+    return this.session
+      .sendRequest<NativeNavResult>({type: MiniappRequestType.NATIVE_NAV, ...payload})
+      .catch((err) => ({
+        status: "unsupported" as const,
+        reason:
+          typeof err === "object" && err !== null && "message" in err
+            ? String((err as {message: unknown}).message)
+            : String(err),
+      }))
+  }
+}

package/src/modules/events.ts

@@ -0,0 +1,318 @@
+/**
+ * @fileoverview EventManager — internal subscription registry + escape hatch.
+ *
+ * Most miniapp authors should NOT touch this directly. Use the typed methods
+ * on domain modules instead:
+ *   - session.transcription.on(...)
+ *   - session.mic.onAudioChunk(...) / onVoiceActivity(...)
+ *   - session.input.onButtonPress(...)
+ *   - session.imu.onHeadPosition(...)
+ *   - session.location.onUpdate(...)
+ *   - session.glasses.onBattery(...) / onConnection(...)
+ *   - 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
+ * domain module. Officially undocumented; the typed methods on domain
+ * modules are the canonical surface.
+ *
+ * Internally, EventManager owns:
+ *   1. The ref-count map. Outbound SUBSCRIBE is only sent when a stream's
+ *      ref count transitions 0↔1, so multiple components listening for the
+ *      same stream issue one wire-level subscribe.
+ *   2. Inbound event fan-out via `_forwardEvent(streamType, data)`, called
+ *      by MiniappSession.handleIncoming when an EVENT envelope arrives.
+ *
+ * Domain modules call back into the session via session._subscribe(...) which
+ * in turn delegates to this class — the session is the integration point;
+ * domain modules don't see this class directly.
+ */
+
+import {EventEmitter} from "eventemitter3"
+
+import {MiniappRequestType, MiniappStreamType} from "../protocol"
+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.
+// ---------------------------------------------------------------------------
+
+export interface TranscriptionData {
+  text: string
+  isFinal: boolean
+  language?: string
+  /**
+   * Speaker id when the platform reports one. A stable enrolled-speaker id
+   * (`spk_…`) when on-device voice recognition resolved the voice, else
+   * the provider's anonymous diarization label (e.g. "1"), else absent.
+   * Enrolled display names are never exposed to miniapps — ids only.
+   */
+  speakerId?: string
+  /**
+   * On-device voice recognition against the device owner's enrolled voice
+   * (final segments only). true = the user themself spoke; false =
+   * confidently a different voice; absent = no confident determination
+   * (or voice recognition is off / not enrolled).
+   */
+  isUser?: boolean
+}
+
+export interface TranslationData {
+  text: string
+  isFinal: boolean
+  sourceLanguage: string
+  targetLanguage: string
+  /** Source-language text of the same utterance, when the provider supplies it. */
+  originalText?: string
+  /** Stable id correlating interim + final results of one utterance. */
+  utteranceId?: string
+  /** Speaker id when the provider reports diarization. */
+  speakerId?: string
+}
+
+export interface ButtonPressData {
+  buttonId: string
+  pressType: "short" | "long"
+}
+
+export interface HeadPositionData {
+  position: "up" | "down"
+}
+
+export interface AccelData {
+  /** Accelerometer axes in g (gravity-normalized). */
+  x: number
+  y: number
+  z: number
+  /** Unix ms timestamp of the reading. */
+  timestamp: number
+}
+
+export interface LocationData {
+  lat: number
+  lng: number
+  /** Accuracy in meters, if the platform reported it. */
+  accuracy?: number
+  /** Unix ms timestamp of the fix. */
+  timestamp?: number
+  /** Set when this event is a response to a single-location request. */
+  correlationId?: string
+}
+
+export interface HeadingData {
+  /** Compass heading in degrees, 0 = north, 90 = east. */
+  degrees: number
+}
+
+export interface BatteryData {
+  level: number
+  charging: boolean
+}
+
+export interface ConnectionData {
+  connected: boolean
+  modelName?: string
+}
+
+/** Glasses Wi-Fi state. `connected` is false on glasses without Wi-Fi or when offline. */
+export interface WifiData {
+  connected: boolean
+  ssid?: string
+  localIp?: string
+}
+
+export interface PhoneNotificationData {
+  /** Stable id from the phone's notification listener. */
+  notificationId: string
+  /** Human app name (e.g. "Messages"). */
+  app: string
+  title: string
+  content: string
+  /** Android priority string; empty on iOS. */
+  priority: string
+  timestamp: number
+  /** Reverse-DNS package/bundle id of the originating app. */
+  packageName: string
+}
+
+export interface NotificationDismissedData {
+  /** Same id as the matching post event from `notifications.on(...)`. */
+  notificationId: string
+  /** Android NotificationKey. More stable than notificationId across reposts. */
+  notificationKey?: string
+  /** Reverse-DNS package/bundle id of the originating app. */
+  packageName?: string
+  /** Unix ms timestamp of the dismissal. */
+  timestamp: number
+}
+
+export interface VadData {
+  /** True while the user is speaking (voice detected), false when silent. */
+  status: boolean
+}
+
+export interface TouchData {
+  /**
+   * The gesture: single_tap, double_tap, triple_tap, long_press, swipe_up, or
+   * swipe_down — plus the raw press edges tap_start (finger down) and tap_end
+   * (finger up), which bracket every gesture on hardware that reports them.
+   */
+  kind:
+    | "single_tap"
+    | "double_tap"
+    | "triple_tap"
+    | "long_press"
+    | "swipe_up"
+    | "swipe_down"
+    | "tap_start"
+    | "tap_end"
+    | string
+}
+
+export interface AudioChunkData {
+  /** PCM or LC3, base64-encoded. Format depends on phone's mic mode. */
+  data: string
+  sampleRate?: number
+  format?: string
+}
+
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+
+export class EventManager {
+  private readonly emitter = new EventEmitter()
+  /** 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) {}
+
+  /**
+   * Generic subscribe. `stream` is the raw wire value, including any language
+   * suffix like `"transcription:en-US"`. Forward-compat escape hatch for new
+   * event types not yet wrapped on a domain module. Most authors should use
+   * typed methods on domain modules instead.
+   *
+   * Stream names beginning with `_` (e.g. `_ui` for the session.ui bus) are
+   * INTERNAL — they ride the local _forwardEvent fan-out and never appear in
+   * the outbound SUBSCRIBE list. Native already knows to deliver UI envelopes
+   * via a separate envelope `type`; the EventManager only routes them
+   * locally.
+   */
+  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)
+      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, 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)
+      } 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()
+    }
+  }
+
+  /** Unsubscribe every handler on every stream this EventManager owns. */
+  unsubscribeAll(): void {
+    this.emitter.removeAllListeners()
+    this.refCounts.clear()
+    this.forceLocalRefCounts.clear()
+    this.sendSubscriptionUpdate()
+  }
+
+  // -------------------------------------------------------------------------
+  // Internal — called by MiniappSession when EVENT arrives from phone
+  // -------------------------------------------------------------------------
+
+  /** @internal */
+  _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
+    // delivers events under the CONCRETE stream key
+    // ("transcription:en-US", "translation:en:es"). Re-emit on every
+    // pattern the concrete key satisfies — the same pattern set
+    // 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, transcriptionRoute)
+    } else if (stream.startsWith("translation:")) {
+      const parts = stream.split(":")
+      const patterns = new Set<string>(["translation:auto"])
+      if (parts.length === 3) {
+        const [, source, target] = parts
+        patterns.add("translation:*:*")
+        patterns.add(`translation:*:${target}`)
+        patterns.add(`translation:${source}:*`)
+      }
+      patterns.delete(stream) // exact key already emitted above
+      for (const pattern of patterns) {
+        this.emitter.emit(pattern, data)
+      }
+    }
+  }
+
+  private sendSubscriptionUpdate(): void {
+    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

@@ -0,0 +1,58 @@
+/**
+ * @fileoverview GlassesModule — device-state events for the glasses themselves.
+ *
+ * Reports on the glasses hardware: battery level + charging state, connection
+ * status (connected/disconnected, model name). The phone has its own battery
+ * + connection events on `session.phone`.
+ */
+
+import {MiniappRequestType, MiniappStreamType} from "../protocol"
+import {MiniappSession} from "../session"
+import type {BatteryData, ConnectionData, UnsubscribeFn, WifiData} from "./events"
+
+export class GlassesModule {
+  constructor(private readonly session: MiniappSession) {}
+
+  onBattery(handler: (data: BatteryData) => void): UnsubscribeFn {
+    return this.session._subscribe(MiniappStreamType.GLASSES_BATTERY, handler as (data: unknown) => void)
+  }
+
+  onConnection(handler: (data: ConnectionData) => void): UnsubscribeFn {
+    return this.session._subscribe(MiniappStreamType.GLASSES_CONNECTION, handler as (data: unknown) => void)
+  }
+
+  /**
+   * Subscribe to glasses Wi-Fi state. Fires the current state on subscribe and
+   * on every change. `connected` is false on glasses without Wi-Fi. Streaming
+   * requires Wi-Fi — pair this with {@link requestWifiSetup} to prompt the user.
+   */
+  onWifi(handler: (data: WifiData) => void): UnsubscribeFn {
+    return this.session._subscribe(MiniappStreamType.GLASSES_WIFI, handler as (data: unknown) => void)
+  }
+
+  /**
+   * Ask the host to open the glasses Wi-Fi setup flow on the phone. Mirrors the
+   * cloud SDK's `session.requestWifiSetup(reason)`. `reason` is a user-facing
+   * line shown in the setup prompt (e.g. "Streaming needs your glasses on Wi-Fi").
+   */
+  async requestWifiSetup(reason?: string): Promise<void> {
+    await this.session.sendRequest<void>({
+      type: MiniappRequestType.REQUEST_WIFI_SETUP,
+      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/heading.ts

@@ -0,0 +1,23 @@
+/**
+ * @fileoverview HeadingModule — phone compass heading events.
+ *
+ * Works on both Android and iOS. LOCATION permission must be declared in miniapp.json.
+ */
+
+import {MiniappStreamType} from "../protocol"
+import {MiniappSession} from "../session"
+import type {HeadingData, UnsubscribeFn} from "./events"
+
+export class HeadingModule {
+  constructor(private readonly session: MiniappSession) {}
+
+  /** True iff `LOCATION` is declared in the miniapp's manifest. */
+  get hasPermission(): boolean {
+    return this.session._hasManifestPermission("LOCATION")
+  }
+
+  /** Subscribe to continuous compass heading updates. */
+  onUpdate(handler: (data: HeadingData) => void): UnsubscribeFn {
+    return this.session._subscribe(MiniappStreamType.HEADING_UPDATE, handler as (data: unknown) => void)
+  }
+}