@glassly/miniapp 0.3.0-dev.1

package/src/modules/location.ts

@@ -0,0 +1,39 @@
+/**
+ * @fileoverview LocationModule — phone location events.
+ *
+ * Exposes both a continuous `onUpdate` subscription and a one-shot
+ * `getOnce()` poll over `MiniappRequestType.LOCATION_POLL`.
+ *
+ * LOCATION permission must be declared in miniapp.json for either path to
+ * succeed; the phone runtime rejects with PERMISSION_NOT_DECLARED
+ * otherwise.
+ */
+
+import {MiniappRequestType, MiniappStreamType} from "../protocol"
+import {MiniappSession} from "../session"
+import type {LocationData, UnsubscribeFn} from "./events"
+
+export class LocationModule {
+  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 location updates. */
+  onUpdate(handler: (data: LocationData) => void): UnsubscribeFn {
+    return this.session._subscribe(MiniappStreamType.LOCATION_UPDATE, handler as (data: unknown) => void)
+  }
+
+  /**
+   * Request a single location fix. Resolves with the next available
+   * reading from the phone. Useful at app load to seed UI before a
+   * continuous stream of updates begins.
+   */
+  getOnce(): Promise<LocationData> {
+    return this.session.sendRequest<LocationData>({
+      type: MiniappRequestType.LOCATION_POLL,
+    })
+  }
+}

package/src/modules/memory.ts

@@ -0,0 +1,224 @@
+/**
+ * @fileoverview MemoryModule — the user's shared, phone-local memory timeline.
+ *
+ * One unified per-hour stream of what happened around the user — spoken
+ * transcript lines AND notes (manual, voice, auto) — plus the hourly summary
+ * that heads each session. The store lives on the phone (host-level,
+ * user-scoped), NOT in the per-miniapp storage namespace: every miniapp that
+ * declares the MEMORY manifest permission reads and writes the same timeline,
+ * and the user manages it in Settings > Memory.
+ *
+ * A "session" is one clock hour that has entries, derived from entry
+ * timestamps at read time — there is no stored session id.
+ *
+ * All calls require the MEMORY manifest permission; without it the host
+ * rejects with PERMISSION_NOT_DECLARED. Nothing here leaves the phone.
+ */
+
+import {MiniappRequestType} from "../protocol"
+import {MiniappSession} from "../session"
+
+export type MemoryEntryKind = "line" | "note"
+/** How a note entry originated (only meaningful when kind === "note"). */
+export type MemoryNoteSource = "voice" | "ui" | "auto"
+
+export interface MemoryEntry {
+  id: string
+  kind: MemoryEntryKind
+  text: string
+  /** Epoch ms the entry happened. */
+  at: number
+  speakerId: string | null
+  /** Enrolled-speaker display name resolved by on-device speaker ID, when known. */
+  resolvedSpeakerName?: string | null
+  language: string | null
+  /** Present for note entries. */
+  source?: MemoryNoteSource
+}
+
+export interface MemorySummary {
+  /** Epoch ms of the hour bucket start. */
+  hourStart: number
+  text: string
+  createdAt: number
+}
+
+/** One derived session: a clock hour with its entries and summary. */
+export interface MemorySession {
+  hourStart: number
+  entries: MemoryEntry[]
+  summary: string | null
+  lineCount: number
+  noteCount: number
+}
+
+export interface MemoryQuery {
+  /** Epoch ms lower bound (inclusive). Omit for "from the beginning". */
+  sinceMs?: number
+  /** Epoch ms upper bound (inclusive). Omit for "until now". */
+  untilMs?: number
+  /** Case-insensitive EXACT substring filter (codes, URLs, exact phrases). */
+  contains?: string
+  /**
+   * Fuzzy any-of terms: an entry matches when ANY term matches, and a
+   * multi-word term requires all of its words. Matching tolerates the small
+   * misspellings speech-to-text produces for names ("Korwin" matches
+   * "Corwin"). Host caps at 8 terms. Combined with `contains` as AND.
+   * Ignored by hosts that predate fuzzy search.
+   */
+  terms?: string[]
+  /** Max entries returned (host caps at 200; default 60). Newest kept. */
+  limit?: number
+}
+
+export interface MemorySearchResult {
+  /** Matches in chronological order (newest last). */
+  entries: MemoryEntry[]
+  /**
+   * Entries inside the TIME window before keyword filtering — distinguishes
+   * "keyword matched nothing" from "window empty". Undefined on hosts that
+   * predate fuzzy search.
+   */
+  windowCount?: number
+}
+
+export class MemoryModule {
+  constructor(private readonly session: MiniappSession) {}
+
+  /** True iff this miniapp's manifest declares the MEMORY permission. */
+  get hasPermission(): boolean {
+    return this.session._hasManifestPermission("MEMORY")
+  }
+
+  /** Append a spoken transcript line to the timeline. */
+  async appendLine(input: {
+    text: string
+    speakerId: string | null
+    language: string | null
+    at: number
+  }): Promise<void> {
+    await this.session.sendRequest<void>({
+      type: MiniappRequestType.MEMORY_APPEND_LINE,
+      ...input,
+    })
+  }
+
+  /**
+   * Add a note. `at` targets the hour it belongs to — omit for "now" (the
+   * current session), or pass a timestamp inside a past hour to append to
+   * that session. Notes dedupe on normalized text within the same hour;
+   * resolves null when the note was a duplicate (or empty).
+   */
+  async addNote(text: string, source: MemoryNoteSource = "ui", at?: number): Promise<MemoryEntry | null> {
+    const result = await this.session.sendRequest<{entry: MemoryEntry | null}>({
+      type: MiniappRequestType.MEMORY_ADD_NOTE,
+      text,
+      source,
+      at,
+    })
+    return result?.entry ?? null
+  }
+
+  /** Delete one entry (line or note) by id. Resolves false when unknown. */
+  async removeEntry(id: string): Promise<boolean> {
+    const result = await this.session.sendRequest<{removed: boolean}>({
+      type: MiniappRequestType.MEMORY_REMOVE_ENTRY,
+      id,
+    })
+    return !!result?.removed
+  }
+
+  /** Delete every entry (and summary) in an hour, or a whole day of hours. */
+  async removeScope(scope: "session" | "day", at: number): Promise<void> {
+    await this.session.sendRequest<void>({
+      type: MiniappRequestType.MEMORY_REMOVE_SCOPE,
+      scope,
+      at,
+    })
+  }
+
+  /** All sessions (hours with entries), newest hour first. */
+  async sessions(): Promise<MemorySession[]> {
+    const result = await this.session.sendRequest<{sessions: MemorySession[]}>({
+      type: MiniappRequestType.MEMORY_SESSION_LIST,
+    })
+    return result?.sessions ?? []
+  }
+
+  /**
+   * Query the full timeline by absolute-time window and keyword — the
+   * on-device executor shape for LLM history-search tools. Newest last, so
+   * slicing keeps the most recent matches when the limit bites.
+   */
+  async query(q: MemoryQuery = {}): Promise<MemoryEntry[]> {
+    return (await this.search(q)).entries
+  }
+
+  /**
+   * query() plus search diagnostics ({@link MemorySearchResult.windowCount}).
+   * Same wire request; prefer this from LLM history-search tools so an empty
+   * result can explain WHY it was empty instead of triggering a blind retry.
+   */
+  async search(q: MemoryQuery = {}): Promise<MemorySearchResult> {
+    const result = await this.session.sendRequest<{entries: MemoryEntry[]; windowCount?: number}>({
+      type: MiniappRequestType.MEMORY_QUERY,
+      ...q,
+    })
+    return {
+      entries: result?.entries ?? [],
+      ...(typeof result?.windowCount === "number" ? {windowCount: result.windowCount} : {}),
+    }
+  }
+
+  /** Entries in [sinceMs, untilMs), newest last. Uncapped (unlike query). */
+  async window(sinceMs: number, untilMs?: number): Promise<MemoryEntry[]> {
+    const result = await this.session.sendRequest<{entries: MemoryEntry[]}>({
+      type: MiniappRequestType.MEMORY_WINDOW,
+      sinceMs,
+      untilMs,
+    })
+    return result?.entries ?? []
+  }
+
+  /** Plain-text export of a scope, for the OS share sheet. */
+  async exportText(scope: "session" | "day" | "all", at?: number): Promise<string> {
+    const result = await this.session.sendRequest<{text: string}>({
+      type: MiniappRequestType.MEMORY_EXPORT_TEXT,
+      scope,
+      at,
+    })
+    return result?.text ?? ""
+  }
+
+  /** Upsert the summary heading an hour (keyed by hourStart). */
+  async addSummary(summary: MemorySummary): Promise<void> {
+    await this.session.sendRequest<void>({
+      type: MiniappRequestType.MEMORY_SUMMARY_ADD,
+      ...summary,
+    })
+  }
+
+  /** All hourly summaries, newest hour first. */
+  async summaries(): Promise<MemorySummary[]> {
+    const result = await this.session.sendRequest<{summaries: MemorySummary[]}>({
+      type: MiniappRequestType.MEMORY_SUMMARY_LIST,
+    })
+    return result?.summaries ?? []
+  }
+
+  /** Most recent COMPLETED hour with lines but no summary, or null. */
+  async pendingSummaryHour(nowMs?: number): Promise<number | null> {
+    const result = await this.session.sendRequest<{hourStart: number | null}>({
+      type: MiniappRequestType.MEMORY_PENDING_SUMMARY_HOUR,
+      nowMs,
+    })
+    return result?.hourStart ?? null
+  }
+
+  /** Drop the entire timeline: every entry and every summary. */
+  async clear(): Promise<void> {
+    await this.session.sendRequest<void>({
+      type: MiniappRequestType.MEMORY_CLEAR,
+    })
+  }
+}

package/src/modules/mic.ts

@@ -0,0 +1,103 @@
+/**
+ * @fileoverview MicModule — low-level audio input subscriptions.
+ *
+ * Mirrors cloud SDK v3's MicManager naming. Houses raw audio chunks + VAD;
+ * transcription and translation hoisted to top-level (`session.transcription`
+ * / `session.translation`) in the v3-alignment round so authors don't have to
+ * mentally model "transcription is a microphone thing" — it's just a
+ * top-level domain. This module was called `MicrophoneModule` /
+ * `session.microphone` before that round.
+ *
+ * Audio *output* (TTS, file playback) lives on `session.speaker`.
+ *
+ * MICROPHONE permission must be declared in miniapp.json for any of these
+ * subscriptions to succeed; the phone runtime rejects with
+ * PERMISSION_NOT_DECLARED otherwise.
+ */
+
+import {MiniappRequestType, MiniappStreamType} from "../protocol"
+import {MiniappSession} from "../session"
+import type {AudioChunkData, UnsubscribeFn, VadData} from "./events"
+
+export class MicModule {
+  /** All active unsubscribe functions for stop() to tear down at once. */
+  private readonly unsubs = new Set<UnsubscribeFn>()
+
+  constructor(private readonly session: MiniappSession) {}
+
+  /**
+   * Subscribe to voice activity detection (VAD) events. `data.status` is
+   * `true` while the user is speaking, `false` when silent.
+   */
+  onVoiceActivity(handler: (data: VadData) => void): UnsubscribeFn {
+    return this.track(this.session._subscribe(MiniappStreamType.VAD, handler as (data: unknown) => void))
+  }
+
+  /**
+   * Subscribe to raw audio chunks. Format depends on the phone's mic mode
+   * (PCM or LC3, base64-encoded).
+   */
+  onAudioChunk(handler: (data: AudioChunkData) => void): UnsubscribeFn {
+    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 Glassly 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 Glassly 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
+   * individual unsubscribe functions.
+   */
+  stop(): void {
+    for (const u of this.unsubs) {
+      try {
+        u()
+      } catch {
+        /* ignore */
+      }
+    }
+    this.unsubs.clear()
+  }
+
+  /** True iff `MICROPHONE` is declared in the miniapp's manifest. */
+  get hasPermission(): boolean {
+    return this.session._hasManifestPermission("MICROPHONE")
+  }
+
+  // ------------------------------------------------------------------------
+
+  private track(unsub: UnsubscribeFn): UnsubscribeFn {
+    this.unsubs.add(unsub)
+    return () => {
+      this.unsubs.delete(unsub)
+      unsub()
+    }
+  }
+}

package/src/modules/miniapps.ts

@@ -0,0 +1,103 @@
+/**
+ * @fileoverview MiniappsModule — `session.miniapps`.
+ *
+ * Discover and control the lifecycle of OTHER miniapps: list, start, stop.
+ * SYSTEM-only — every call rejects with NOT_PERMITTED unless the caller is a
+ * system app (Glassly AI is the first consumer). The action *capability* layer
+ * (invoke / handle) lives on `session.actions`, not here — these three are
+ * operations on the app as a whole, not on a declared action.
+ */
+
+import {MiniappRequestType} from "../protocol"
+import {MiniappSession} from "../session"
+
+/** A declared action surfaced by {@link MiniappsModule.list}. */
+export interface MiniappActionInfo {
+  id: string
+  description: string
+  /**
+   * JSON-Schema input descriptor (the MCP-compatible subset). Maps verbatim
+   * 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>
+}
+
+/**
+ * Hardware compatibility for a listed miniapp. Structurally mirrors the host's
+ * `CompatibilityResult` so the runtime can pass it straight through.
+ */
+export interface MiniappCompatibility {
+  isCompatible: boolean
+  missingRequired: Array<{type: string; level?: string}>
+  missingOptional: Array<{type: string; level?: string}>
+  warnings: string[]
+}
+
+/** One installed miniapp, as surfaced to a system caller. */
+export interface MiniappInfo {
+  packageName: string
+  name: string
+  description?: string
+  version: string
+  running: boolean
+  compatibility: MiniappCompatibility
+  /** Declared actions (empty if the miniapp declares none). */
+  actions: MiniappActionInfo[]
+}
+
+export interface ListMiniappsOptions {
+  /** Include incompatible miniapps too (default false — compatible-only). */
+  includeIncompatible?: boolean
+}
+
+export class MiniappsModule {
+  constructor(private readonly session: MiniappSession) {}
+
+  /**
+   * List installed miniapps. Compatible-only by default; pass
+   * `{includeIncompatible: true}` to include the rest (each carries a
+   * `compatibility` result with the missing hardware). SYSTEM-only.
+   */
+  async list(opts?: ListMiniappsOptions): Promise<MiniappInfo[]> {
+    const result = await this.session.sendRequest<MiniappInfo[]>({
+      type: MiniappRequestType.MINIAPPS_LIST,
+      includeIncompatible: opts?.includeIncompatible ?? false,
+    })
+    return result ?? []
+  }
+
+  /**
+   * Start another miniapp in the **background** — spawns its background JS
+   * context without changing the user's phone navigation or foregrounding
+   * anything. The app reports as running and can handle actions / drive the
+   * glasses immediately; its WebView only mounts if the user later opens it.
+   * SYSTEM-only.
+   */
+  async start(packageName: string): Promise<void> {
+    await this.session.sendRequest<void>({
+      type: MiniappRequestType.MINIAPPS_START,
+      packageName,
+    })
+  }
+
+  /** Stop another miniapp. SYSTEM-only. */
+  async stop(packageName: string): Promise<void> {
+    await this.session.sendRequest<void>({
+      type: MiniappRequestType.MINIAPPS_STOP,
+      packageName,
+    })
+  }
+
+  /**
+   * Stop THIS miniapp — the host tears the background context down shortly
+   * after. Not system-gated: an app may always stop itself. Fire-and-forget
+   * (no reply — the caller is going away); flush anything pending first, e.g.
+   * defer this with a short setTimeout from an action handler so the
+   * ACTION_RESULT reaches the caller before teardown.
+   */
+  stopSelf(): void {
+    this.session.sendOneShot({type: MiniappRequestType.MINIAPPS_STOP_SELF})
+  }
+}