@mentra/miniapp 0.3.0-dev.0

package/src/modules/actions.ts

@@ -0,0 +1,156 @@
+/**
+ * @fileoverview ActionsModule — `session.actions`.
+ *
+ * The MCP-shaped capability layer, both directions:
+ *   - `invoke(pkg, actionId, params)` — call another miniapp's declared action.
+ *     SYSTEM-only; headless-wakes the target if it's stopped.
+ *   - `handle(actionId, fn)` — expose one of your own actions. Open to all
+ *     miniapps. Mirrors `session.ui.handle` (one handler per id, throws on
+ *     double-register, errors propagate to the caller).
+ *
+ * `invoke` ↔ `handle` are the two ends of one wire (keyed by `actionId`), which
+ * is why they share this namespace rather than being split across
+ * `session.miniapps`.
+ */
+
+import {MiniappErrorCode, MiniappRequestType} from "../protocol"
+import {MiniappSession} from "../session"
+
+/** Context handed to an action handler. `callerPackageName` is host-stamped. */
+export interface ActionContext {
+  /** The package that invoked this action (trustworthy — set by the host). */
+  callerPackageName: string
+}
+
+export type ActionHandler = (params: Record<string, unknown>, ctx: ActionContext) => unknown | Promise<unknown>
+
+export interface InvokeOptions {
+  /** Overall timeout in ms (default 30s, max 120s — host-enforced). */
+  timeoutMs?: number
+}
+
+interface BufferedCall {
+  callId: string
+  params: Record<string, unknown>
+  ctx: ActionContext
+  timer: ReturnType<typeof setTimeout>
+}
+
+/**
+ * How long the SDK holds an inbound ACTION_CALL waiting for its handler to
+ * register (a just-woken miniapp registers handlers a beat after CONNECT).
+ * If no handler appears in this window the call is failed with
+ * NO_ACTION_HANDLER. Mirrors the UI bus's pre-handler buffering.
+ */
+const HANDLER_WAIT_MS = 5_000
+
+export class ActionsModule {
+  private readonly handlers = new Map<string, ActionHandler>()
+  /** Inbound calls buffered until their handler registers, keyed by actionId. */
+  private readonly buffered = new Map<string, BufferedCall[]>()
+
+  constructor(private readonly session: MiniappSession) {}
+
+  /**
+   * Invoke a declared action on another miniapp. Resolves with the handler's
+   * return value, rejects with a MiniappRequestError (NOT_PERMITTED,
+   * APP_NOT_FOUND, ACTION_NOT_FOUND, WAKE_FAILED, NO_ACTION_HANDLER,
+   * ACTION_TIMEOUT, PAYLOAD_TOO_LARGE, or the handler's own error). SYSTEM-only.
+   */
+  invoke<TResult = unknown>(
+    packageName: string,
+    actionId: string,
+    params?: Record<string, unknown>,
+    opts?: InvokeOptions,
+  ): Promise<TResult> {
+    return this.session.sendRequest<TResult>({
+      type: MiniappRequestType.ACTION_INVOKE,
+      targetPackageName: packageName,
+      actionId,
+      params: params ?? {},
+      ...(opts?.timeoutMs != null ? {timeoutMs: opts.timeoutMs} : {}),
+    })
+  }
+
+  /**
+   * Register a handler for one of this miniapp's declared actions. One handler
+   * per actionId — throws synchronously on double-register. The returned
+   * function unregisters. Declare the action in `miniapp.json` for it to be
+   * invokable; an undeclared id still registers but the host never routes to it.
+   */
+  handle(actionId: string, handler: ActionHandler): () => void {
+    if (this.handlers.has(actionId)) {
+      throw new Error(`session.actions.handle: a handler is already registered for "${actionId}"`)
+    }
+    this.handlers.set(actionId, handler)
+
+    // Flush any calls that arrived before this handler registered.
+    const waiting = this.buffered.get(actionId)
+    if (waiting) {
+      this.buffered.delete(actionId)
+      for (const call of waiting) {
+        clearTimeout(call.timer)
+        void this.dispatch(call.callId, actionId, call.params, call.ctx)
+      }
+    }
+
+    return () => {
+      if (this.handlers.get(actionId) === handler) this.handlers.delete(actionId)
+    }
+  }
+
+  /**
+   * @internal — called by MiniappSession.handleIncoming on an ACTION_CALL.
+   * Routes to the registered handler, or buffers briefly for one to appear.
+   */
+  _deliver(callId: string, actionId: string, params: Record<string, unknown>, ctx: ActionContext): void {
+    if (this.handlers.has(actionId)) {
+      void this.dispatch(callId, actionId, params, ctx)
+      return
+    }
+    // No handler yet — buffer, and fail with NO_ACTION_HANDLER if none registers.
+    const timer = setTimeout(() => {
+      const arr = this.buffered.get(actionId)
+      if (arr) {
+        const idx = arr.findIndex((c) => c.callId === callId)
+        if (idx >= 0) arr.splice(idx, 1)
+        if (arr.length === 0) this.buffered.delete(actionId)
+      }
+      this.sendResult(callId, false, undefined, {
+        code: MiniappErrorCode.NO_ACTION_HANDLER,
+        message: `No handler registered for action "${actionId}"`,
+      })
+    }, HANDLER_WAIT_MS)
+    const arr = this.buffered.get(actionId) ?? []
+    arr.push({callId, params, ctx, timer})
+    this.buffered.set(actionId, arr)
+  }
+
+  private async dispatch(
+    callId: string,
+    actionId: string,
+    params: Record<string, unknown>,
+    ctx: ActionContext,
+  ): Promise<void> {
+    const handler = this.handlers.get(actionId)
+    if (!handler) return
+    try {
+      const result = await handler(params, ctx)
+      this.sendResult(callId, true, result ?? null)
+    } catch (e) {
+      this.sendResult(callId, false, undefined, {
+        code: MiniappErrorCode.INTERNAL,
+        message: (e as Error)?.message ?? "action handler threw",
+      })
+    }
+  }
+
+  private sendResult(callId: string, ok: boolean, result?: unknown, error?: {code: string; message: string}): void {
+    this.session.sendOneShot({
+      type: MiniappRequestType.ACTION_RESULT,
+      callId,
+      ok,
+      ...(ok ? {result} : {error}),
+    })
+  }
+}

package/src/modules/auth.ts

@@ -0,0 +1,68 @@
+import type {MiniappSession, MiniappAuthState} from "../session"
+
+export interface AuthFetchOptions extends RequestInit {
+  /**
+   * Minimum remaining token lifetime before using the current token. Defaults to
+   * 30 seconds. If the token is absent or too close to expiry, the call waits
+   * for the host's next auth update.
+   */
+  minTtlMs?: number
+}
+
+const DEFAULT_MIN_TTL_MS = 30_000
+
+export class AuthModule {
+  constructor(private readonly session: MiniappSession) {}
+
+  get current(): MiniappAuthState | null {
+    return this.session._getAuth()
+  }
+
+  get mentraUserId(): string | null {
+    return this.current?.mentraUserId ?? null
+  }
+
+  get oemId(): string | null {
+    return this.current?.oemId ?? null
+  }
+
+  async getToken(options: {minTtlMs?: number} = {}): Promise<string> {
+    const auth = await this.session._waitForAuth(options.minTtlMs ?? DEFAULT_MIN_TTL_MS)
+    return auth.token
+  }
+
+  async getAuthHeader(options: {minTtlMs?: number} = {}): Promise<string> {
+    return `Bearer ${await this.getToken(options)}`
+  }
+
+  async fetch(input: RequestInfo | URL, init: AuthFetchOptions = {}): Promise<Response> {
+    const {minTtlMs, ...requestInit} = init
+    const token = await this.getToken({minTtlMs})
+    const headers = mergeHeaders(requestInit.headers, {Authorization: `Bearer ${token}`})
+    return fetch(input, {...requestInit, headers})
+  }
+
+  onUpdate(handler: (auth: MiniappAuthState) => void): () => void {
+    return this.session.on("auth", handler)
+  }
+}
+
+function mergeHeaders(base: HeadersInit | undefined, next: Record<string, string>): Record<string, string> {
+  const headers: Record<string, string> = {}
+
+  if (Array.isArray(base)) {
+    for (const [key, value] of base) {
+      headers[key] = value
+    }
+  } else if (typeof Headers !== "undefined" && base instanceof Headers) {
+    base.forEach((value, key) => {
+      headers[key] = value
+    })
+  } else if (base && typeof base === "object") {
+    for (const [key, value] of Object.entries(base)) {
+      if (typeof value === "string") headers[key] = value
+    }
+  }
+
+  return {...headers, ...next}
+}

package/src/modules/base64.ts

@@ -0,0 +1,87 @@
+/**
+ * @fileoverview Dependency-free base64 codec for the miniapp background runtime.
+ *
+ * The background bundle runs in a per-miniapp JS engine (JavaScriptCore on iOS,
+ * QuickJS on Android) where `Buffer`, `btoa`/`atob`, and Node APIs are NOT
+ * guaranteed to exist. `session.blob` round-trips binary as base64 strings over
+ * the JSON bridge, so it needs an encoder/decoder that works with nothing but
+ * the language. This is that — standard RFC 4648 base64, no padding tricks.
+ */
+
+const ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"
+
+/** Reverse lookup table: char code → 6-bit value (or -1). Built once. */
+const LOOKUP: Int16Array = (() => {
+  const t = new Int16Array(256).fill(-1)
+  for (let i = 0; i < ALPHABET.length; i++) t[ALPHABET.charCodeAt(i)] = i
+  t["=".charCodeAt(0)] = 0
+  return t
+})()
+
+/** Coerce a Uint8Array / ArrayBuffer / ArrayBufferView into a Uint8Array view (no copy when possible). */
+export function toUint8Array(input: Uint8Array | ArrayBuffer | ArrayBufferView): Uint8Array {
+  if (input instanceof Uint8Array) return input
+  if (input instanceof ArrayBuffer) return new Uint8Array(input)
+  return new Uint8Array(input.buffer, input.byteOffset, input.byteLength)
+}
+
+/** Encode bytes to a base64 string. */
+export function bytesToBase64(input: Uint8Array | ArrayBuffer): string {
+  const bytes = input instanceof Uint8Array ? input : new Uint8Array(input)
+  const len = bytes.length
+  let out = ""
+  let i = 0
+  for (; i + 2 < len; i += 3) {
+    const n = (bytes[i] << 16) | (bytes[i + 1] << 8) | bytes[i + 2]
+    out += ALPHABET[(n >> 18) & 63] + ALPHABET[(n >> 12) & 63] + ALPHABET[(n >> 6) & 63] + ALPHABET[n & 63]
+  }
+  const rem = len - i
+  if (rem === 1) {
+    const n = bytes[i] << 16
+    out += ALPHABET[(n >> 18) & 63] + ALPHABET[(n >> 12) & 63] + "=="
+  } else if (rem === 2) {
+    const n = (bytes[i] << 16) | (bytes[i + 1] << 8)
+    out += ALPHABET[(n >> 18) & 63] + ALPHABET[(n >> 12) & 63] + ALPHABET[(n >> 6) & 63] + "="
+  }
+  return out
+}
+
+/** Decode a base64 string to bytes. Ignores whitespace; tolerant of missing padding. */
+export function base64ToBytes(b64: string): Uint8Array {
+  // Count valid (non-whitespace) chars and trailing '=' to size the output exactly.
+  let validChars = 0
+  let pad = 0
+  for (let i = 0; i < b64.length; i++) {
+    const c = b64.charCodeAt(i)
+    if (c === 0x3d) {
+      pad++
+      validChars++
+    } else if (LOOKUP[c] !== -1) {
+      validChars++
+    }
+  }
+  const fullGroups = Math.floor(validChars / 4)
+  const remChars = validChars - fullGroups * 4
+  let outLen = fullGroups * 3 - (pad > 0 && remChars === 0 ? pad : 0)
+  if (remChars === 2) outLen += 1
+  else if (remChars === 3) outLen += 2
+  if (outLen < 0) outLen = 0
+
+  const out = new Uint8Array(outLen)
+  let acc = 0
+  let bits = 0
+  let o = 0
+  for (let i = 0; i < b64.length && o < outLen; i++) {
+    const c = b64.charCodeAt(i)
+    if (c === 0x3d) break // '=' — end of data
+    const v = LOOKUP[c]
+    if (v === -1) continue // skip whitespace / stray chars
+    acc = (acc << 6) | v
+    bits += 6
+    if (bits >= 8) {
+      bits -= 8
+      out[o++] = (acc >> bits) & 0xff
+    }
+  }
+  return out
+}

package/src/modules/blob.ts

@@ -0,0 +1,341 @@
+/**
+ * @fileoverview BlobModule — phone-local persistent BINARY storage, keyed and
+ * scoped to (userId, packageName). The binary sibling of `session.storage`:
+ * where storage holds small strings, blob holds arbitrary bytes (PDFs, EPUBs,
+ * audio, video, model files, caches) as files on the phone.
+ *
+ * It deliberately mirrors `session.storage`'s shape — `set` / `get` / `delete` /
+ * `keys` / `has` / `clear` — so it's instantly familiar, plus the things files
+ * (and not strings) need:
+ *   - `setFromUrl(key, url)` — the host downloads a URL straight to disk
+ *     (like the web Cache API's `cache.add`, iOS `URLSession` download task, or
+ *     Android `DownloadManager`). Bytes never cross the bridge.
+ *   - `importFile()` — opens the OS file picker and stores the chosen file.
+ *     Bytes never cross the bridge.
+ *   - `share(key)` — hands the file to the OS share sheet.
+ *   - `createWriteStream` / `createReadStream` — for streaming huge payloads
+ *     (named like Node's `fs.createWriteStream`).
+ *
+ * BACKGROUND-ONLY. Binary doesn't belong in the WebView. A blob's `uri` is a
+ * `file://` path in the app's private storage — fine for `session.speaker.play`,
+ * `blob.share`, or another host capability, but a WebView generally can't load
+ * it directly (route rendering through a host viewer for now).
+ *
+ * Transfer model: the bridge moves JSON strings through a per-miniapp JS engine
+ * (JSC/QuickJS) with a watchdog, so in-JS writes/reads are CHUNKED (≤ ~1 MB raw
+ * per call). Prefer `setFromUrl` / `importFile` when you can — they keep the
+ * bytes entirely host-side.
+ */
+
+import {MiniappRequestType} from "../protocol"
+import {MiniappSession} from "../session"
+import {base64ToBytes, bytesToBase64, toUint8Array} from "./base64"
+
+/** Metadata for one stored blob. `uri` is a `file://` path. */
+export interface BlobMeta {
+  /** The key it's stored under (caller-chosen). */
+  key: string
+  /** Optional display/file name (e.g. the original filename for an import). */
+  name?: string
+  /** MIME type, e.g. "application/pdf". */
+  mimeType: string
+  /** Size on disk in bytes. */
+  bytes: number
+  /** Epoch ms first written. */
+  createdAt: number
+  /** Epoch ms last written. */
+  updatedAt: number
+  /** Content md5 (lowercase hex), computed host-side (skipped for very large blobs). */
+  md5?: string
+  /** `file://` URI. Feed to `session.speaker.play`, `blob.share`, etc. */
+  uri: string
+  /** App-defined metadata persisted with the blob. */
+  meta?: Record<string, string | number | boolean>
+}
+
+export interface BlobSetOptions {
+  /** Default "application/octet-stream". */
+  mimeType?: string
+  name?: string
+  meta?: Record<string, string | number | boolean>
+}
+
+export interface BlobSetFromUrlOptions extends BlobSetOptions {
+  /** Request headers (e.g. an Authorization token) for the download. */
+  headers?: Record<string, string>
+}
+
+export interface BlobImportOptions {
+  /** Key to store under. Default: a generated key. */
+  key?: string
+  /** Restrict the picker to a MIME type, e.g. "application/pdf". */
+  mimeType?: string
+  meta?: Record<string, string | number | boolean>
+}
+
+/** Raw bytes per chunked write. ~1 MB raw → ~1.34 MB base64, under the watchdog. */
+export const BLOB_WRITE_CHUNK_BYTES = 1024 * 1024
+const BLOB_WRITE_CHUNK_B64 = Math.floor(BLOB_WRITE_CHUNK_BYTES / 3) * 4
+/** Max bytes `bytes()` will buffer before throwing — read large blobs as a stream. */
+export const BLOB_READ_ALL_MAX_BYTES = 32 * 1024 * 1024
+
+/**
+ * Streaming writer (`fs.createWriteStream`-like). Call `write`/`writeBase64` as
+ * many times as you like (each is auto-split into bridge-safe chunks), then
+ * `close()` to publish, or `abort()` to discard the partial blob.
+ */
+export class BlobWriter {
+  private settled = false
+
+  constructor(
+    private readonly session: MiniappSession,
+    readonly key: string,
+  ) {}
+
+  /** Append raw bytes. Auto-chunked. */
+  async write(chunk: Uint8Array | ArrayBuffer): Promise<void> {
+    this.assertOpen()
+    const bytes = toUint8Array(chunk)
+    for (let off = 0; off < bytes.length; off += BLOB_WRITE_CHUNK_BYTES) {
+      await this.send(bytesToBase64(bytes.subarray(off, off + BLOB_WRITE_CHUNK_BYTES)))
+    }
+  }
+
+  /** Append already-base64-encoded bytes (e.g. straight from `mic.onAudioChunk`). */
+  async writeBase64(b64: string): Promise<void> {
+    this.assertOpen()
+    // Slice on 4-char boundaries so each chunk is whole base64 groups.
+    for (let off = 0; off < b64.length; off += BLOB_WRITE_CHUNK_B64) {
+      await this.send(b64.slice(off, off + BLOB_WRITE_CHUNK_B64))
+    }
+  }
+
+  /**
+   * Overwrite bytes at a fixed offset within the not-yet-closed blob (a seek
+   * write). Must stay within already-written bytes; does not grow the blob.
+   * Advanced — used e.g. to patch a container header on finalize.
+   */
+  async writeAt(offset: number, chunk: Uint8Array | ArrayBuffer): Promise<void> {
+    this.assertOpen()
+    await this.session.sendRequest<{bytesWritten: number}>({
+      type: MiniappRequestType.BLOB_WRITE,
+      key: this.key,
+      offset,
+      base64: bytesToBase64(toUint8Array(chunk)),
+    })
+  }
+
+  /** Finalize and return the blob's metadata. Optional `meta` merges into the record. */
+  async close(meta?: Record<string, string | number | boolean>): Promise<BlobMeta> {
+    this.assertOpen()
+    this.settled = true
+    return this.session.sendRequest<BlobMeta>({type: MiniappRequestType.BLOB_COMMIT, key: this.key, meta})
+  }
+
+  /** Discard the partial blob. Idempotent. */
+  async abort(): Promise<void> {
+    if (this.settled) return
+    this.settled = true
+    await this.session.sendRequest<void>({type: MiniappRequestType.BLOB_ABORT, key: this.key})
+  }
+
+  private assertOpen(): void {
+    if (this.settled) throw new Error("BlobWriter is already closed/aborted")
+  }
+
+  private send(base64: string): Promise<{bytesWritten: number}> {
+    return this.session.sendRequest<{bytesWritten: number}>({
+      type: MiniappRequestType.BLOB_WRITE,
+      key: this.key,
+      base64,
+    })
+  }
+}
+
+/** Streaming reader (`fs.createReadStream`-like). */
+export class BlobReader {
+  private closed = false
+
+  constructor(
+    private readonly session: MiniappSession,
+    readonly handle: string,
+    readonly meta: BlobMeta,
+  ) {}
+
+  /** Read up to `maxBytes` (default one chunk). `done` is true at end of file. */
+  async read(maxBytes = BLOB_WRITE_CHUNK_BYTES): Promise<{bytes: Uint8Array; done: boolean}> {
+    if (this.closed) throw new Error("BlobReader is closed")
+    const res = await this.session.sendRequest<{base64: string; done: boolean}>({
+      type: MiniappRequestType.BLOB_READ,
+      handle: this.handle,
+      maxBytes,
+    })
+    return {bytes: base64ToBytes(res?.base64 ?? ""), done: !!res?.done}
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) return
+    this.closed = true
+    await this.session.sendRequest<void>({type: MiniappRequestType.BLOB_CLOSE_READ, handle: this.handle})
+  }
+}
+
+export class BlobModule {
+  constructor(private readonly session: MiniappSession) {}
+
+  // ── write ────────────────────────────────────────────────────────────────
+
+  /** Store bytes under `key`. `data` may be a Uint8Array/ArrayBuffer or a base64 string. */
+  async set(key: string, data: Uint8Array | ArrayBuffer | string, opts: BlobSetOptions = {}): Promise<BlobMeta> {
+    const writer = await this.createWriteStream(key, opts)
+    try {
+      if (typeof data === "string") await writer.writeBase64(data)
+      else await writer.write(data)
+      return await writer.close()
+    } catch (err) {
+      await writer.abort().catch(() => {})
+      throw err
+    }
+  }
+
+  /**
+   * Download `url` straight into a blob under `key`, host-side. The bytes never
+   * cross the bridge (like the web Cache API's `cache.add`). `opts.headers` lets
+   * you pass auth. Resolves to the stored blob's metadata.
+   */
+  setFromUrl(key: string, url: string, opts: BlobSetFromUrlOptions = {}): Promise<BlobMeta> {
+    return this.session.sendRequest<BlobMeta>({
+      type: MiniappRequestType.BLOB_SET_FROM_URL,
+      key,
+      url,
+      mimeType: opts.mimeType,
+      name: opts.name,
+      headers: opts.headers,
+      meta: opts.meta,
+    })
+  }
+
+  /**
+   * Open the OS file picker and store the chosen file as a blob, host-side.
+   * Resolves to the blob's metadata, or `null` if the user cancelled.
+   */
+  importFile(opts: BlobImportOptions = {}): Promise<BlobMeta | null> {
+    return this.session.sendRequest<BlobMeta | null>({
+      type: MiniappRequestType.BLOB_IMPORT,
+      key: opts.key,
+      mimeType: opts.mimeType,
+      meta: opts.meta,
+    })
+  }
+
+  /** Open a streaming writer for `key` (for large/streamed payloads). */
+  async createWriteStream(key: string, opts: BlobSetOptions = {}): Promise<BlobWriter> {
+    const res = await this.session.sendRequest<{key: string}>({
+      type: MiniappRequestType.BLOB_CREATE,
+      key,
+      mimeType: opts.mimeType,
+      name: opts.name,
+      meta: opts.meta,
+    })
+    return new BlobWriter(this.session, res.key)
+  }
+
+  // ── read ─────────────────────────────────────────────────────────────────
+
+  /** Metadata (incl. the `file://` uri) for `key`, or null if absent. */
+  get(key: string): Promise<BlobMeta | null> {
+    return this.session.sendRequest<BlobMeta | null>({type: MiniappRequestType.BLOB_GET, key})
+  }
+
+  /** Alias of `get` — the file-stat verb. */
+  stat(key: string): Promise<BlobMeta | null> {
+    return this.get(key)
+  }
+
+  /** True iff a blob is stored under `key`. */
+  async has(key: string): Promise<boolean> {
+    return (await this.get(key)) !== null
+  }
+
+  /** Every key this miniapp has stored, newest first. */
+  async keys(): Promise<string[]> {
+    return (await this.list()).map((m) => m.key)
+  }
+
+  /** Every blob this miniapp owns, newest first. */
+  async list(): Promise<BlobMeta[]> {
+    const res = await this.session.sendRequest<{blobs: BlobMeta[]}>({type: MiniappRequestType.BLOB_LIST})
+    return res?.blobs ?? []
+  }
+
+  /** Open a streaming reader. Prefer `get(key).uri` when you just need to play/share it. */
+  async createReadStream(key: string): Promise<BlobReader> {
+    const res = await this.session.sendRequest<{handle: string; meta: BlobMeta}>({
+      type: MiniappRequestType.BLOB_OPEN_READ,
+      key,
+    })
+    return new BlobReader(this.session, res.handle, res.meta)
+  }
+
+  /** Read a whole blob into memory as bytes, or null if absent. Throws past the cap — stream big ones. */
+  async bytes(key: string): Promise<Uint8Array | null> {
+    let reader: BlobReader
+    try {
+      reader = await this.createReadStream(key)
+    } catch {
+      return null
+    }
+    const parts: Uint8Array[] = []
+    let total = 0
+    try {
+      for (;;) {
+        const {bytes, done} = await reader.read()
+        if (bytes.length) {
+          total += bytes.length
+          if (total > BLOB_READ_ALL_MAX_BYTES) {
+            throw new Error(`Blob "${key}" exceeds the in-memory read cap — stream it with createReadStream()`)
+          }
+          parts.push(bytes)
+        }
+        if (done) break
+      }
+    } finally {
+      await reader.close().catch(() => {})
+    }
+    const out = new Uint8Array(total)
+    let at = 0
+    for (const p of parts) {
+      out.set(p, at)
+      at += p.length
+    }
+    return out
+  }
+
+  // ── manage ───────────────────────────────────────────────────────────────
+
+  /** Per-app usage + the quota ceiling, in bytes. */
+  usage(): Promise<{bytes: number; count: number; quotaBytes: number}> {
+    return this.session.sendRequest<{bytes: number; count: number; quotaBytes: number}>({
+      type: MiniappRequestType.BLOB_USAGE,
+    })
+  }
+
+  /** Delete the blob under `key`. No-op if absent. */
+  async delete(key: string): Promise<void> {
+    await this.session.sendRequest<void>({type: MiniappRequestType.BLOB_DELETE, key})
+  }
+
+  /** Delete every blob this miniapp owns. */
+  async clear(): Promise<void> {
+    await this.session.sendRequest<void>({type: MiniappRequestType.BLOB_CLEAR})
+  }
+
+  /** Share the blob via the OS share sheet (host shares from disk — no bytes cross the bridge). */
+  async share(key: string): Promise<{success: boolean; cancelled?: boolean}> {
+    const res = await this.session.sendRequest<{success: boolean; cancelled?: boolean}>({
+      type: MiniappRequestType.BLOB_SHARE,
+      key,
+    })
+    return res ?? {success: false}
+  }
+}