@glassly/miniapp 0.3.0-dev.1

package/src/modules/speakers.ts

@@ -0,0 +1,40 @@
+/**
+ * @fileoverview SpeakersModule — resolve enrolled-speaker ids to names.
+ *
+ * On-device voice recognition stamps transcription events with stable opaque
+ * ids (`TranscriptionData.speakerId` = `spk_…`) when a voice matches the
+ * profile the user enrolled in Settings > Voice Recognition (owner-only:
+ * `TranscriptionData.isUser` is the primary signal). Display names are
+ * on-device PII and never ride along with events; a miniapp that wants the
+ * display name must declare the SPEAKERS manifest permission and resolve ids
+ * through this module.
+ *
+ * All calls require the SPEAKERS manifest permission; without it the host
+ * rejects with PERMISSION_NOT_DECLARED. Ids that don't correspond to an
+ * enrolled profile (anonymous diarization labels, deleted profiles) resolve
+ * to null — treat null as "no name available", not an error.
+ */
+
+import {MiniappRequestType} from "../protocol"
+import {MiniappSession} from "../session"
+
+export class SpeakersModule {
+  constructor(private readonly session: MiniappSession) {}
+
+  /** True iff this miniapp's manifest declares the SPEAKERS permission. */
+  get hasPermission(): boolean {
+    return this.session._hasManifestPermission("SPEAKERS")
+  }
+
+  /**
+   * Resolve an enrolled-speaker id to its display name, or null when the id
+   * is not an enrolled profile (anonymous label, deleted profile).
+   */
+  async resolveName(id: string): Promise<string | null> {
+    const result = await this.session.sendRequest<{name: string | null}>({
+      type: MiniappRequestType.SPEAKERS_RESOLVE_NAME,
+      id,
+    })
+    return result?.name ?? null
+  }
+}

package/src/modules/storage.ts

@@ -0,0 +1,109 @@
+/**
+ * @fileoverview SimpleStorage — phone-local key-value store scoped to
+ * (userId, packageName). Mirrors cloud SDK v3's StorageManager surface.
+ *
+ * All operations round-trip to LocalMiniappRuntime, which reads/writes
+ * the phone's storage with a namespaced key format:
+ *   localstorage_{userId}_{packageName}_{key}
+ *
+ * Values are plain strings. Callers serialize structured data with
+ * JSON.stringify themselves (matching cloud's SimpleStorage shape).
+ */
+
+import {MiniappRequestType} from "../protocol"
+import {MiniappSession} from "../session"
+
+export class SimpleStorage {
+  constructor(private readonly session: MiniappSession) {}
+
+  /** Get a value by key. Resolves to null when the key is unset. */
+  async get(key: string): Promise<string | null> {
+    const result = await this.session.sendRequest<{value: string | null}>({
+      type: MiniappRequestType.STORAGE_GET,
+      key,
+    })
+    return result?.value ?? null
+  }
+
+  /** Set a single key/value pair. Overwrites silently. */
+  async set(key: string, value: string): Promise<void> {
+    await this.session.sendRequest<void>({
+      type: MiniappRequestType.STORAGE_SET,
+      key,
+      value,
+    })
+  }
+
+  /** Delete one key. No-op if the key is unset. */
+  async delete(key: string): Promise<void> {
+    await this.session.sendRequest<void>({
+      type: MiniappRequestType.STORAGE_DELETE,
+      key,
+    })
+  }
+
+  /** List every key in this miniapp's namespace. */
+  async keys(): Promise<string[]> {
+    const result = await this.session.sendRequest<{keys: string[]}>({
+      type: MiniappRequestType.STORAGE_LIST,
+    })
+    return result?.keys ?? []
+  }
+
+  /**
+   * @deprecated Renamed to `keys()` for cloud SDK parity. This alias will be
+   * removed in a future release.
+   */
+  async list(): Promise<string[]> {
+    return this.keys()
+  }
+
+  /** Drop every key in this miniapp's namespace. */
+  async clear(): Promise<void> {
+    await this.session.sendRequest<void>({
+      type: MiniappRequestType.STORAGE_CLEAR,
+    })
+  }
+
+  /** True iff `key` is set in this miniapp's namespace. */
+  async has(key: string): Promise<boolean> {
+    const result = await this.session.sendRequest<{has: boolean}>({
+      type: MiniappRequestType.STORAGE_HAS,
+      key,
+    })
+    return !!result?.has
+  }
+
+  /**
+   * Read every key/value pair in this miniapp's namespace. Useful for
+   * hydrating state on bootstrap. Bounded by the underlying namespace
+   * size — keep total stored payload small (typical < 1 MB) to avoid
+   * stalling the JSContext when this resolves.
+   */
+  async getAll(): Promise<Record<string, string>> {
+    const result = await this.session.sendRequest<{values: Record<string, string>}>({
+      type: MiniappRequestType.STORAGE_GET_ALL,
+    })
+    return result?.values ?? {}
+  }
+
+  /** Write many key/value pairs in one round-trip. */
+  async setMultiple(values: Record<string, string>): Promise<void> {
+    await this.session.sendRequest<void>({
+      type: MiniappRequestType.STORAGE_SET_MULTIPLE,
+      values,
+    })
+  }
+
+  /**
+   * Force any pending in-flight writes to disk. No-op today because the
+   * host writes through immediately, but reserved so a future debounced
+   * backend can honor "flush before I quit" calls without breaking the
+   * API.
+   */
+  async flush(): Promise<void> {
+    await this.session.sendRequest<void>({
+      type: MiniappRequestType.STORAGE_FLUSH,
+    })
+  }
+}

package/src/modules/stream.ts

@@ -0,0 +1,168 @@
+/**
+ * @fileoverview StreamModule -- video streaming from glasses.
+ *
+ * Wires to cloud streaming extensions via the __phone__ subscriber path.
+ *
+ * One entry point: `startStream`. By default it provisions a Glassly-hosted
+ * stream and returns playback URLs (managed). Pass `direct` to publish straight
+ * to your own ingest URL with no relay.
+ */
+
+import {MiniappRequestType} from "../protocol"
+import {MiniappSession} from "../session"
+
+export interface StreamVideoConfig {
+  width?: number
+  height?: number
+  bitrate?: number
+  fps?: number
+}
+
+export interface StreamAudioConfig {
+  bitrate?: number
+  sampleRate?: number
+  echoCancellation?: boolean
+  noiseSuppression?: boolean
+}
+
+export interface StreamResolvedConfig {
+  transport?: "rtmp" | "srt" | "whip"
+  video?: {
+    width: number
+    height: number
+    captureWidth?: number
+    captureHeight?: number
+    bitrate: number
+    fps: number
+  }
+  audio?: {
+    bitrate?: number
+    sampleRate?: number
+    echoCancellation?: boolean
+    noiseSuppression?: boolean
+  }
+}
+
+/**
+ * Restream destination. The full stream key is part of the URL (e.g.
+ * `rtmp://yt.com/live/STREAM-KEY`). `name` is a human label that surfaces
+ * in dashboards but doesn't affect routing.
+ */
+export interface RestreamDestination {
+  url: string
+  name?: string
+}
+
+export interface StartStreamOptions {
+  /**
+   * Publish straight to your own ingest URL (rtmp/rtmps/srt/whip). The glasses
+   * connect to it directly with no Glassly relay, so no playback URLs come back.
+   * Omit this to use the managed relay (the default, best for most apps).
+   */
+  direct?: string
+  /**
+   * Restream destinations the managed relay fans out to (YouTube, Twitch, …).
+   * Bare URL strings or `{url, name?}` objects; mix freely. Managed streams
+   * only — ignored when `direct` is set.
+   */
+  destinations?: Array<string | RestreamDestination>
+  video?: StreamVideoConfig
+  audio?: StreamAudioConfig
+  /** Play glasses-side stream start/stop sounds. Defaults to true. */
+  sound?: boolean
+  /**
+   * Managed ingest protocol, a latency/durability trade. Ignored when `direct`
+   * is set.
+   *   - "srt" (default): ~10-20s latency via LL-HLS, shareable HLS/DASH URLs,
+   *     and automatic recording.
+   *   - "whip": sub-second WebRTC playback (use `webrtcUrl`/WHEP), but no
+   *     HLS/DASH and no recording.
+   *   - "rtmp": RTMPS ingest over TCP 443 → HLS playback. Use when WHIP/SRT
+   *     UDP is blocked (then play `hlsUrl`, not WHEP).
+   */
+  ingest?: "srt" | "whip" | "rtmp"
+  /** Optional Bearer token for direct WHIP Authorization (custom authenticated endpoints). */
+  authToken?: string
+}
+
+export interface StreamResult {
+  streamId: string
+  status: string
+  resolvedConfig?: StreamResolvedConfig
+  /** Managed streams only: the live-input UID for building hosted-player URLs. */
+  liveInputId?: string
+  /** Managed streams only: which playback this stream serves. In "webrtc" mode
+   *  `hlsUrl` never serves content. */
+  mode?: "hls" | "webrtc"
+  /** Managed streams only: HLS playback URL. */
+  hlsUrl?: string
+  /** Managed streams only: DASH playback URL. */
+  dashUrl?: string
+  /** Managed streams only: WHEP playback URL (present in "webrtc" mode). */
+  webrtcUrl?: string
+}
+
+/** Live encoder and device telemetry emitted periodically by supported glasses firmware. */
+export interface StreamLiveStats {
+  /** Current encoded video bitrate in bits per second. */
+  bitrate?: number
+  /** Current encode frame rate. */
+  fps?: number
+  droppedFrames?: number
+  /** Seconds since the stream started. */
+  duration?: number
+  /** Device temperature in °C, if the hardware reports it. */
+  temperatureC?: number
+}
+
+export interface StreamStatus {
+  streamId: string
+  status: string
+  errorDetails?: string
+  /** Negotiated encode config — forwarded once, on the first status ack. */
+  resolvedConfig?: StreamResolvedConfig
+  stats?: StreamLiveStats
+}
+
+export class StreamModule {
+  constructor(private readonly session: MiniappSession) {}
+
+  /**
+   * Start a live video stream from the glasses camera.
+   *
+   * Managed (default) -- Glassly hosts the stream and the result carries
+   * `hlsUrl`/`dashUrl`/`webrtcUrl` for playback. Optionally fan out to your own
+   * `destinations`.
+   *
+   * Direct -- pass `direct` with your own ingest URL; the glasses publish to it
+   * and no playback URLs are returned.
+   */
+  async startStream(options: StartStreamOptions = {}): Promise<StreamResult> {
+    if (options.direct !== undefined) {
+      return this.session.sendRequest<StreamResult>({
+        type: MiniappRequestType.STREAM_START,
+        streamUrl: options.direct,
+        video: options.video,
+        audio: options.audio,
+        sound: options.sound ?? true,
+        ...(options.authToken ? {authToken: options.authToken} : {}),
+      })
+    }
+    return this.session.sendRequest<StreamResult>({
+      type: MiniappRequestType.MANAGED_STREAM_START,
+      restreamDestinations: options.destinations,
+      video: options.video,
+      audio: options.audio,
+      sound: options.sound ?? true,
+      ingest: options.ingest,
+    })
+  }
+
+  /** Stop the active stream, or a specific one by `streamId`. */
+  async stop(streamId?: string): Promise<void> {
+    await this.session.sendRequest<void>({
+      type: MiniappRequestType.STREAM_STOP,
+      streamId,
+    })
+  }
+}

package/src/modules/system.ts

@@ -0,0 +1,113 @@
+/**
+ * @fileoverview SystemModule — OS-level utilities (share, open URL, clipboard, download, QR scan).
+ *
+ * These bridge to native phone capabilities via LocalMiniappRuntime.
+ */
+
+import {MiniappRequestType} from "../protocol"
+import {MiniappSession} from "../session"
+
+export interface ShareOptions {
+  text?: string
+  url?: string
+  title?: string
+  /** Base64-encoded file data for file sharing. */
+  base64?: string
+  /** MIME type when sharing base64 data. */
+  mimeType?: string
+  /** Filename when sharing base64 data. */
+  filename?: string
+}
+
+export interface ShareResult {
+  success: boolean
+  cancelled?: boolean
+}
+
+export interface DownloadOptions {
+  /** URL to download from, OR base64 data. */
+  url?: string
+  base64?: string
+  filename?: string
+  mimeType?: string
+}
+
+export interface DownloadResult {
+  success: boolean
+  cancelled?: boolean
+}
+
+export interface ScanQrOptions {
+  /** Header title on the phone scanner overlay. */
+  title?: string
+  /** Hint shown over the camera viewfinder. */
+  hint?: string
+}
+
+export type ScanQrResult = {data: string; cancelled?: false} | {cancelled: true; data?: undefined}
+
+export class SystemModule {
+  constructor(private readonly session: MiniappSession) {}
+
+  /** Open the OS share sheet with the given content. */
+  async share(options: ShareOptions): Promise<ShareResult> {
+    const result = await this.session.sendRequest<ShareResult>({
+      type: MiniappRequestType.SHARE,
+      ...options,
+    })
+    return result ?? {success: false}
+  }
+
+  /** Open a URL in the system browser. Blocks dangerous schemes (javascript:, file:). */
+  openUrl(url: string): void {
+    this.session.sendOneShot({
+      type: MiniappRequestType.OPEN_URL,
+      url,
+    })
+  }
+
+  /** Copy text to the system clipboard. */
+  async copyToClipboard(text: string): Promise<void> {
+    await this.session.sendRequest<void>({
+      type: MiniappRequestType.COPY_CLIPBOARD,
+      text,
+    })
+  }
+
+  /** Download a file. Opens the OS share sheet so user can choose save location. */
+  async download(options: DownloadOptions): Promise<DownloadResult> {
+    const result = await this.session.sendRequest<DownloadResult>({
+      type: MiniappRequestType.DOWNLOAD,
+      ...options,
+    })
+    return result ?? {success: false}
+  }
+
+  /**
+   * Ask the host to stop this miniapp. Use after finishing one-shot work —
+   * e.g. an action handler that woke the app headlessly and has nothing more
+   * to do (return the action's result first; exit tears the context down).
+   * Fire-and-forget: the JS context dies shortly after the host accepts.
+   */
+  exit(): void {
+    this.session.sendOneShot({
+      type: MiniappRequestType.SYSTEM_EXIT,
+    })
+  }
+
+  /**
+   * Open the phone camera QR scanner as a host overlay. Does not unmount the
+   * miniapp (so live sessions survive the scan). Resolves with the raw QR
+   * payload, or `{cancelled: true}` if the user dismisses the scanner.
+   */
+  async scanQr(options: ScanQrOptions = {}): Promise<ScanQrResult> {
+    const result = await this.session.sendRequest<ScanQrResult>(
+      {
+        type: MiniappRequestType.SCAN_QR,
+        ...options,
+      },
+      {timeoutMs: 0},
+    )
+    return result ?? { cancelled: true }
+  }
+}

package/src/modules/transcription.ts

@@ -0,0 +1,180 @@
+/**
+ * @fileoverview TranscriptionModule — top-level transcription API.
+ *
+ * Mirrors cloud SDK v3's TranscriptionManager:
+ *
+ *   session.transcription.on(handler)                                // auto-detect
+ *   session.transcription.forLanguage("en-US", handler)              // single language
+ *   session.transcription.forLanguage(["en-US", "es-ES"], handler)   // multi-language
+ *   session.transcription.configure({languageHints, vocabulary, diarization})
+ *   session.transcription.stop()                                     // tear down all
+ *
+ * Hoisted to top-level (vs. nested under `session.mic`) because transcription
+ * is a domain in its own right, not a microphone-input event. The `mic`
+ * module still exposes lower-level audio chunks + VAD; this module is for
+ * "give me text from speech."
+ *
+ * MICROPHONE permission must be declared in miniapp.json. The phone runtime
+ * rejects with PERMISSION_NOT_DECLARED otherwise.
+ */
+
+import {MiniappRequestType, MiniappStreamType} from "../protocol"
+import {MiniappSession} from "../session"
+import type {TranscriptionData, UnsubscribeFn} from "./events"
+import {requireLanguageHint, requireTranscriptionLanguage} from "./languages"
+import type {LanguageHint, TranscriptionLanguage} from "./languages"
+
+/** Configuration for cloud-side transcription behavior. */
+export interface TranscriptionConfig {
+  /**
+   * Language hints to improve auto-detection accuracy. Bare ISO 639-1 codes
+   * from the registry (e.g. ["en", "ja"]); registry BCP-47 tags are accepted
+   * and normalized ("en-US" -> "en"). Anything else throws
+   * `MiniappValidationError`.
+   */
+  languageHints?: LanguageHint[]
+  /** Custom vocabulary / boosted terms (e.g. ["Glassly", "HIPAA"]). */
+  vocabulary?: string[]
+  /**
+   * Enable speaker diarisation. Currently always on for cloud transcription
+   * (the platform's provider runs diarization unconditionally and events
+   * carry `speakerId` when detected); the flag is accepted for
+   * forward-compatibility with providers where it is optional.
+   */
+  diarization?: boolean
+}
+
+export interface TranscriptionOptions {
+  /**
+   * Use only on-device STT for this listener; never deliver cloud transcripts.
+   * Other listeners on the same stream keep their own routing choice. Requires
+   * a downloaded local STT model.
+   */
+  forceLocal?: boolean
+}
+
+export class TranscriptionModule {
+  private readonly unsubs = new Set<UnsubscribeFn>()
+  private currentConfig: TranscriptionConfig | null = null
+
+  constructor(private readonly session: MiniappSession) {}
+
+  /**
+   * Subscribe to all transcription events (auto-detect language). The
+   * detected language is in `data.language`.
+   *
+   * Wire-level: subscribes to `transcription:auto`. Today's wildcard fan-out
+   * (handlers on `transcription:auto` receive any `transcription:<lang>`
+   * event) preserves existing semantics.
+   */
+  on(handler: (data: TranscriptionData) => void, options: TranscriptionOptions = {}): UnsubscribeFn {
+    return this.track(
+      this.session._subscribe(`${MiniappStreamType.TRANSCRIPTION}:auto`, handler as (data: unknown) => void, options),
+    )
+  }
+
+  /**
+   * Subscribe to transcription for one or more specific languages. Each call
+   * is independent; multiple can be active simultaneously.
+   *
+   * Languages are validated against the platform registry
+   * (`SUPPORTED_TRANSCRIPTION_LANGUAGES`): registry BCP-47 tags pass through,
+   * bare registry codes canonicalize ("fr" -> "fr-FR"), anything else throws
+   * `MiniappValidationError` immediately — an invalid language must never
+   * become a subscription that silently transcribes the wrong thing
+   * (OS-1746 / issue 021).
+   *
+   * @param language - Registry tag(s), e.g. `"en-US"` or `["en-US", "es-ES"]`.
+   * @param handler  - Called for every event in any of the listed languages.
+   */
+  forLanguage(
+    language: TranscriptionLanguage | TranscriptionLanguage[],
+    handler: (data: TranscriptionData) => void,
+    options: TranscriptionOptions = {},
+  ): UnsubscribeFn {
+    const langs = (Array.isArray(language) ? language : [language]).map((lang) =>
+      requireTranscriptionLanguage(lang, "transcription.forLanguage(language)"),
+    )
+    if (langs.length === 0) return () => {}
+
+    const unsubs: UnsubscribeFn[] = []
+    for (const lang of langs) {
+      unsubs.push(
+        this.session._subscribe(
+          `${MiniappStreamType.TRANSCRIPTION}:${lang}`,
+          handler as (data: unknown) => void,
+          options,
+        ),
+      )
+    }
+    const combined: UnsubscribeFn = () => {
+      for (const u of unsubs) {
+        try {
+          u()
+        } catch {
+          /* ignore */
+        }
+      }
+    }
+    return this.track(combined)
+  }
+
+  /**
+   * Apply transcription configuration (language hints, custom vocabulary,
+   * diarisation toggle). Hints are validated against the registry and
+   * normalized to bare codes ("en-US" -> "en"); unknown values throw
+   * `MiniappValidationError` synchronously.
+   *
+   * Sent to the phone runtime as a REQUEST (not a one-shot) so the returned
+   * promise rejects if the runtime cannot apply it — a config that the
+   * platform ignores must be loud, not silent (issue 021 S3). Cached locally
+   * so the runtime can re-apply on reconnect.
+   */
+  configure(config: TranscriptionConfig): Promise<void> {
+    const normalized: TranscriptionConfig = {
+      ...config,
+      languageHints: config.languageHints?.map((hint) =>
+        requireLanguageHint(hint, "transcription.configure(languageHints)"),
+      ),
+    }
+    this.currentConfig = {...normalized}
+    return this.session
+      .sendRequest<void>({
+        type: MiniappRequestType.TRANSCRIPTION_CONFIG,
+        config: {...normalized},
+      })
+      .then(() => undefined)
+  }
+
+  /** Tear down every transcription subscription this module owns. */
+  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")
+  }
+
+  /** @internal — current config, read by tests / future reconnect logic. */
+  _getConfig(): TranscriptionConfig | null {
+    return this.currentConfig ? {...this.currentConfig} : null
+  }
+
+  // ------------------------------------------------------------------------
+
+  private track(unsub: UnsubscribeFn): UnsubscribeFn {
+    this.unsubs.add(unsub)
+    return () => {
+      this.unsubs.delete(unsub)
+      unsub()
+    }
+  }
+}