@mentra/miniapp 3.2.1-beta.319 → 3.2.1-beta.355

package/src/modules/meeting.ts

@@ -1,9 +1,8 @@
 /**
  * @fileoverview MeetingModule — phone-native meeting (ACS Teams).
  *
- * V1 token pass-through is deliberate technical debt (identity ticket):
- * later, join(meetingUrl, whepUrl) and the host fetches the credential from
- * Porter. Miniapps must not persist the token.
+ * Workspace credentials belong to the host. Consumer token pass-through remains
+ * available for older hosts and Call backends. Never persist credentials.
  */
 
 import {MiniappErrorCode, MiniappRequestType} from "../protocol"
@@ -30,7 +29,7 @@ export interface MeetingWhepVideoSource {
  * hotspot, binds a local WHIP endpoint, and tells the glasses where to publish. The miniapp only
  * chooses the transport.
  *
- * Android only for now. iOS hosts reject this with `NOT_IMPLEMENTED`.
+ * Supported by current Android and iOS hosts.
  */
 export interface MeetingSoftApVideoSource {
   type: "softap"
@@ -102,13 +101,28 @@ export interface MeetingJoinOptions {
   provider: MeetingProvider
   meetingUrl: string
   videoSource: MeetingVideoSource
-  /** V1-only: Porter-minted ACS guest token. Do not persist. */
-  token: string
+  /** Legacy consumer credential. Omit when getConfiguration().credentialSource is runtime. */
+  token?: string
   displayName?: string
   video?: MeetingOutgoingVideo
   origin?: MeetingOrigin
 }
 
+export interface MeetingCreateOptions {
+  provider: MeetingProvider
+  subject?: string
+  durationMinutes?: number
+}
+
+export interface CreatedMeeting {
+  provider: MeetingProvider
+  joinUrl: string
+  /** Opaque ownership receipt. Keep it to retire this meeting later. */
+  meetingRef: string
+  identityMode: MeetingIdentityMode
+  guestReason?: "no-entra-identity" | "teams-license-unavailable"
+}
+
 export type MeetingParticipantState = "idle" | "connecting" | "connected" | "lobby" | "hold" | "disconnected"
 
 /** A remote participant as reported by the phone-native meeting client. */
@@ -121,9 +135,43 @@ export interface MeetingParticipant {
   isSpeaking: boolean
 }
 
+export type MeetingIdentityMode = "guest" | "teams-user"
+export type MeetingGuestReason = "no-entra-identity" | "teams-license-unavailable" | "legacy-credential"
+
+/**
+ * Identity resolved before joining. `teams-user` means Microsoft accepted the
+ * Teams calling license, not that the account owns a particular M365 SKU or
+ * has permission to organize every meeting. Credentials never cross this API.
+ * Acquisition/consent/provider errors reject instead of reporting guest mode.
+ */
+export interface MeetingIdentity {
+  identityMode: MeetingIdentityMode
+  guestReason?: MeetingGuestReason
+  /** Present when the host has a signed-in Entra account, including unlicensed accounts. */
+  account?: {displayName?: string; email?: string}
+}
+
+/** Host policy; this contains no credentials or deployment endpoints. */
+export interface MeetingConfiguration {
+  enabled: boolean
+  credentialSource: "runtime" | "miniapp"
+  externalBackendAllowed: boolean
+  managedStreams: boolean
+  /** Omitted by older hosts. Runtime creation requires Graph organizer configuration. */
+  creationSource?: "runtime" | "miniapp"
+}
+
 export interface MeetingState {
+  /** Omitted by older hosts. Tokens never cross this boundary. */
+  identityMode?: MeetingIdentityMode
+  guestReason?: MeetingGuestReason
   state: MeetingPhase
   muted: boolean
+  /**
+   * Whether remote participants receive the glasses camera. False after `setVideoEnabled(false)`;
+   * every new join starts true. Omitted by hosts that cannot toggle outgoing video.
+   */
+  videoEnabled?: boolean
   error?: string
   /** Provider termination details, including Teams' invalid meeting-link codes. */
   endReason?: MeetingEndReason
@@ -212,12 +260,16 @@ export function parseMeetingCapabilities(raw: unknown): MeetingCapabilities | un
   if (!value || typeof value !== "object") return undefined
   const capability = value as Record<string, unknown>
   const rawLobby = (raw as Record<string, unknown>).manageLobby
-  const lobby = rawLobby && typeof rawLobby === "object" ? rawLobby as Record<string, unknown> : undefined
+  const lobby = rawLobby && typeof rawLobby === "object" ? (rawLobby as Record<string, unknown>) : undefined
   return {
-    ...(lobby ? {manageLobby: {
-      allowed: typeof lobby.allowed === "boolean" ? lobby.allowed : null,
-      reason: typeof lobby.reason === "string" && lobby.reason ? lobby.reason : null,
-    }} : {}),
+    ...(lobby
+      ? {
+          manageLobby: {
+            allowed: typeof lobby.allowed === "boolean" ? lobby.allowed : null,
+            reason: typeof lobby.reason === "string" && lobby.reason ? lobby.reason : null,
+          },
+        }
+      : {}),
     hangUpForEveryone: {
       allowed: typeof capability.allowed === "boolean" ? capability.allowed : null,
       reason: typeof capability.reason === "string" && capability.reason ? capability.reason : null,
@@ -264,14 +316,7 @@ export interface MeetingSoftApRecovery {
 
 const SOFTAP_STEPS: ReadonlySet<string> = new Set(["hotspot", "scopedJoin", "acsJoin", "publish", "live"])
 const SOFTAP_STEP_STATUSES: ReadonlySet<string> = new Set(["pending", "running", "done", "failed"])
-const SOFTAP_PHASES: ReadonlySet<string> = new Set([
-  "idle",
-  "starting",
-  "recovering",
-  "live",
-  "stopping",
-  "failed",
-])
+const SOFTAP_PHASES: ReadonlySet<string> = new Set(["idle", "starting", "recovering", "live", "stopping", "failed"])
 
 /** Tolerant parse of a host `softap` payload. Unknown steps are dropped; a malformed payload reads as absent. */
 export function parseMeetingSoftApProgress(raw: unknown): MeetingSoftApProgress | undefined {
@@ -386,9 +431,7 @@ export class MeetingModule {
       throw {code: MiniappErrorCode.INVALID_ARGUMENT, message: "meetingUrl is required"}
     }
     const videoSource = validateMeetingVideoSource(options.videoSource)
-    if (!options.token?.trim()) {
-      throw {code: MiniappErrorCode.INVALID_ARGUMENT, message: "token is required"}
-    }
+
     try {
       const result = await this.session.sendRequest<MeetingState | null>(
         {
@@ -396,7 +439,7 @@ export class MeetingModule {
           provider: options.provider,
           meetingUrl: options.meetingUrl,
           videoSource,
-          token: options.token,
+          ...(options.token ? {token: options.token} : {}),
           displayName: options.displayName,
           ...(options.origin ? {origin: options.origin} : {}),
           ...(options.video ? {video: options.video} : {}),
@@ -410,6 +453,52 @@ export class MeetingModule {
     }
   }
 
+  /** Query before using a separate Call backend. Older hosts return NOT_IMPLEMENTED. */
+  async getConfiguration(): Promise<MeetingConfiguration> {
+    return this.session.sendRequest<MeetingConfiguration>({type: MiniappRequestType.MEETING_GET_CONFIGURATION})
+  }
+
+  /** Resolve the current calling identity without creating or joining a meeting. */
+  async getIdentity(): Promise<MeetingIdentity> {
+    try {
+      return await this.session.sendRequest<MeetingIdentity>(
+        {type: MiniappRequestType.MEETING_GET_IDENTITY},
+        {timeoutMs: 30_000},
+      )
+    } catch (error) {
+      mapHostError(error)
+    }
+  }
+
+  /** Create a Teams meeting in the selected Runtime without exposing provider credentials. */
+  async create(options: MeetingCreateOptions): Promise<CreatedMeeting> {
+    if (options.provider !== "acs-teams") {
+      throw {code: MiniappErrorCode.INVALID_ARGUMENT, message: "Unsupported meeting provider"}
+    }
+    try {
+      return await this.session.sendRequest<CreatedMeeting>(
+        {
+          type: MiniappRequestType.MEETING_CREATE,
+          provider: options.provider,
+          subject: options.subject,
+          durationMinutes: options.durationMinutes,
+        },
+        {timeoutMs: 0},
+      )
+    } catch (error) {
+      mapHostError(error)
+    }
+  }
+
+  /** Delete a meeting created by this caller. Does not hang up an active call. */
+  async retire(meetingRef: string): Promise<void> {
+    try {
+      await this.session.sendRequest<void>({type: MiniappRequestType.MEETING_RETIRE, meetingRef}, {timeoutMs: 0})
+    } catch (error) {
+      mapHostError(error)
+    }
+  }
+
   async leave(): Promise<void> {
     try {
       await this.session.sendRequest<void>({type: MiniappRequestType.MEETING_LEAVE})
@@ -459,6 +548,23 @@ export class MeetingModule {
     }
   }
 
+  /**
+   * Stop or resume the glasses camera the meeting receives. The call and the glasses stream stay
+   * up, so a local `<StreamPreview>` keeps drawing while remote participants see the camera off.
+   * Check `state.videoEnabled !== undefined` before offering it; older hosts reject.
+   */
+  async setVideoEnabled(enabled: boolean): Promise<void> {
+    try {
+      const result = await this.session.sendRequest<MeetingState | null>({
+        type: MiniappRequestType.MEETING_SET_VIDEO_ENABLED,
+        enabled,
+      })
+      if (result) this._applyState(result)
+    } catch (error) {
+      mapHostError(error)
+    }
+  }
+
   /**
    * Repoint the host at a new WHEP URL mid-call, the recovery path for a re-published stream.
    *
@@ -502,8 +608,12 @@ export class MeetingModule {
   /** @internal — applied by MiniappSession on inbound MEETING_STATE. */
   _applyState(event: MeetingState): void {
     this._state = {
+      identityMode:
+        event.identityMode === "guest" || event.identityMode === "teams-user" ? event.identityMode : undefined,
+      guestReason: event.identityMode === "guest" ? event.guestReason : undefined,
       state: event.state,
       muted: Boolean(event.muted),
+      videoEnabled: typeof event.videoEnabled === "boolean" ? event.videoEnabled : undefined,
       error: event.error,
       endReason: parseMeetingEndReason(event.endReason),
       meetingUrl: event.meetingUrl,

package/src/modules/stream.ts

@@ -8,7 +8,7 @@
  * to your own ingest URL with no relay.
  */
 
-import {MiniappRequestType} from "../protocol"
+import {MiniappRequestType, type PreviewErrorCode, type PreviewSource} from "../protocol"
 import {MiniappSession} from "../session"
 
 export interface StreamVideoConfig {
@@ -133,9 +133,161 @@ export interface StreamStatus {
   stats?: StreamLiveStats
 }
 
+export interface StreamPreviewOptions {
+  /** Defaults to `"call"`. `"glasses"` is reserved and rejects with `unsupported`. */
+  source?: PreviewSource
+}
+
+export type PreviewHandleState = "held" | "ended"
+
+export interface PreviewHandleStatus {
+  state: PreviewHandleState
+  /** Set when `state` is `"ended"`: `stopped`, `source_ended`, `runtime_stopped`, ... */
+  reason?: string
+}
+
+/** A preview request or lease failed. `code` is one of {@link PreviewErrorCode} when the host sent one. */
+export class PreviewError extends Error {
+  readonly code: PreviewErrorCode | string
+
+  constructor(code: PreviewErrorCode | string, message?: string) {
+    super(message ?? code)
+    this.name = "PreviewError"
+    this.code = code
+  }
+}
+
+/**
+ * The background-owned lease on a preview source.
+ *
+ * The lease is what lets a `<StreamPreview>` in the UI show frames. It survives the UI closing and
+ * the WebView being destroyed, and ends on `stop()`, when the source ends (the meeting is over), or
+ * when the background runtime stops. Hiding the component does not release it.
+ */
+export interface PreviewHandle {
+  readonly source: PreviewSource
+  readonly handleId: string
+  /** Correlation id stamped on every `PREVIEW_TRACE` log line for this lease. */
+  readonly previewTraceId: string
+  readonly state: PreviewHandleState
+  /** Release the lease. Idempotent. */
+  stop(): Promise<void>
+  /** Lease transitions. Fires `{state: "ended", reason}` exactly once. */
+  onStatus(cb: (status: PreviewHandleStatus) => void): () => void
+}
+
+interface PreviewStartResult {
+  handleId: string
+  previewTraceId: string
+  source: PreviewSource
+}
+
+function toPreviewError(error: unknown): PreviewError {
+  if (error instanceof PreviewError) return error
+  const value = (error ?? {}) as {code?: unknown; message?: unknown}
+  const code = typeof value.code === "string" ? value.code : "unsupported"
+  const message = typeof value.message === "string" ? value.message : undefined
+  return new PreviewError(code, message)
+}
+
+class PreviewHandleImpl implements PreviewHandle {
+  state: PreviewHandleState = "held"
+  private readonly listeners = new Set<(status: PreviewHandleStatus) => void>()
+
+  constructor(
+    readonly source: PreviewSource,
+    readonly handleId: string,
+    readonly previewTraceId: string,
+    private readonly release: (handle: PreviewHandleImpl) => Promise<void>,
+  ) {}
+
+  async stop(): Promise<void> {
+    if (this.state === "ended") return
+    this.end("stopped")
+    await this.release(this)
+  }
+
+  onStatus(cb: (status: PreviewHandleStatus) => void): () => void {
+    this.listeners.add(cb)
+    return () => this.listeners.delete(cb)
+  }
+
+  /** @internal */
+  end(reason: string): void {
+    if (this.state === "ended") return
+    this.state = "ended"
+    this.emit({state: "ended", reason})
+  }
+
+  private emit(status: PreviewHandleStatus): void {
+    for (const listener of [...this.listeners]) {
+      try {
+        listener(status)
+      } catch {
+        // A throwing listener must not stop the others from hearing that the lease ended.
+      }
+    }
+  }
+}
+
 export class StreamModule {
+  private readonly previewHandles = new Map<string, PreviewHandleImpl>()
+
   constructor(private readonly session: MiniappSession) {}
 
+  /**
+   * Take the preview lease on a source so a `<StreamPreview>` in the UI can show its frames.
+   *
+   * For `"call"` the caller must declare `CAMERA` and own the active meeting (`session.meeting`).
+   * Only one lease exists at a time; a second request fails with `preview_busy`. Rejects with a
+   * {@link PreviewError}. Never await this on a call's connect path: preview is additive.
+   */
+  async preview(options: StreamPreviewOptions = {}): Promise<PreviewHandle> {
+    const source = options.source ?? "call"
+    if (source !== "call") {
+      throw new PreviewError("unsupported", `Preview source "${String(source)}" is not supported yet`)
+    }
+    let result: PreviewStartResult
+    try {
+      result = await this.session.sendRequest<PreviewStartResult>({
+        type: MiniappRequestType.STREAM_PREVIEW_START,
+        source,
+      })
+    } catch (error) {
+      throw toPreviewError(error)
+    }
+    const handle = new PreviewHandleImpl(result.source ?? source, result.handleId, result.previewTraceId, (h) =>
+      this.releasePreview(h),
+    )
+    this.previewHandles.set(handle.handleId, handle)
+    handle.onStatus((status) => {
+      if (status.state === "ended") this.previewHandles.delete(handle.handleId)
+    })
+    return handle
+  }
+
+  private async releasePreview(handle: PreviewHandleImpl): Promise<void> {
+    this.previewHandles.delete(handle.handleId)
+    try {
+      await this.session.sendRequest<void>({
+        type: MiniappRequestType.STREAM_PREVIEW_STOP,
+        handleId: handle.handleId,
+      })
+    } catch (error) {
+      throw toPreviewError(error)
+    }
+  }
+
+  /** @internal — applied by MiniappSession on inbound STREAM_PREVIEW_STATUS. */
+  _applyPreviewStatus(payload: Record<string, unknown>): void {
+    if (typeof payload.handleId !== "string") return
+    const handle = this.previewHandles.get(payload.handleId)
+    if (!handle) return
+    if (payload.state === "ended") {
+      handle.end(typeof payload.reason === "string" ? payload.reason : "ended")
+    }
+  }
+
   /**
    * Start a live video stream from the glasses camera.
    *

package/src/protocol.ts

@@ -196,6 +196,13 @@ export enum MiniappRequestType {
   STREAM_STOP = "miniapp_stream_stop",
   MANAGED_STREAM_START = "miniapp_managed_stream_start",
   MANAGED_STREAM_STOP = "miniapp_managed_stream_stop",
+  /**
+   * Take the single raw decoded-frame preview lease on a source. See
+   * `session.stream.preview()`. Replies `{handleId, previewTraceId, source}`.
+   */
+  STREAM_PREVIEW_START = "miniapp_stream_preview_start",
+  /** Release a preview lease by `handleId`. */
+  STREAM_PREVIEW_STOP = "miniapp_stream_preview_stop",
 
   /** Ask the host to open the glasses Wi-Fi setup flow (mirrors the cloud SDK's requestWifiSetup). */
   REQUEST_WIFI_SETUP = "miniapp_request_wifi_setup",
@@ -220,6 +227,10 @@ export enum MiniappRequestType {
    * Phone-native meeting (ACS Teams). Join/leave/mute live in the MentraOS
    * host so the miniapp never holds the ACS Calling SDK.
    */
+  MEETING_GET_IDENTITY = "miniapp_meeting_get_identity",
+  MEETING_GET_CONFIGURATION = "miniapp_meeting_get_configuration",
+  MEETING_CREATE = "miniapp_meeting_create",
+  MEETING_RETIRE = "miniapp_meeting_retire",
   MEETING_JOIN = "miniapp_meeting_join",
   MEETING_LEAVE = "miniapp_meeting_leave",
   /** Terminate the meeting for everyone, not just this device. See `meeting.end()`. */
@@ -227,6 +238,8 @@ export enum MiniappRequestType {
   /** Admit one waiting participant, when the host has Teams lobby permission. */
   MEETING_ADMIT = "miniapp_meeting_admit",
   MEETING_SET_MUTED = "miniapp_meeting_set_muted",
+  /** Stop or resume the glasses camera the meeting receives, without leaving. */
+  MEETING_SET_VIDEO_ENABLED = "miniapp_meeting_set_video_enabled",
   MEETING_UPDATE_VIDEO_SOURCE = "miniapp_meeting_update_video_source",
   MEETING_GET_STATE = "miniapp_meeting_get_state",
 }
@@ -291,6 +304,12 @@ export enum MiniappResponseType {
    */
   MEETING_STATE = "miniapp_meeting_state",
 
+  /**
+   * Push: a preview lease changed state. Carries {handleId, state: "held" | "ended", reason?}.
+   * See PreviewHandle.onStatus().
+   */
+  STREAM_PREVIEW_STATUS = "miniapp_stream_preview_status",
+
   /**
    * Push: phone is about to tear down the miniapp's session. Gives the SDK
    * a brief window (~50ms grace on the phone side) to fire one last
@@ -431,3 +450,59 @@ export enum MiniappErrorCode {
   /** `blob.importFile` failed (not the user cancelling — that resolves to null). */
   BLOB_IMPORT_FAILED = "BLOB_IMPORT_FAILED",
 }
+
+// ============================================================================
+// Stream preview
+// ============================================================================
+
+/**
+ * Where a raw preview comes from. `"call"` is the decoded video of the phone-native meeting the
+ * caller owns. `"glasses"` is reserved and currently rejects with `unsupported`.
+ */
+export type PreviewSource = "call" | "glasses"
+
+/**
+ * Typed preview failures and non-terminal statuses, shared by the background handle, the UI
+ * component and the host. `waiting_for_lease` and `paused_background` are statuses, not errors.
+ */
+export type PreviewErrorCode =
+  | "permission_denied"
+  | "not_meeting_owner"
+  | "preview_busy"
+  | "waiting_for_lease"
+  | "source_ended"
+  | "unsupported"
+  | "ack_timeout"
+  | "transport_failed"
+  | "pack_failed"
+  | "paused_background"
+  | "diagnostics_disabled"
+
+export const PREVIEW_ERROR_CODES: readonly PreviewErrorCode[] = [
+  "permission_denied",
+  "not_meeting_owner",
+  "preview_busy",
+  "waiting_for_lease",
+  "source_ended",
+  "unsupported",
+  "ack_timeout",
+  "transport_failed",
+  "pack_failed",
+  "paused_background",
+  "diagnostics_disabled",
+]
+
+export function isPreviewErrorCode(value: unknown): value is PreviewErrorCode {
+  return typeof value === "string" && (PREVIEW_ERROR_CODES as readonly string[]).includes(value)
+}
+
+/** Lease state pushed to the background with `STREAM_PREVIEW_STATUS`. */
+export interface PreviewStatus {
+  handleId: string
+  state: "held" | "ended"
+  /** Why the lease ended: `stopped`, `source_ended`, `runtime_stopped`, ... */
+  reason?: string
+}
+
+/** The single reserved UI channel the host answers itself for preview control. */
+export const PREVIEW_UI_CHANNEL = "_preview"