@mentra/miniapp 3.3.0-dev.944 → 3.4.0-beta.1237
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +7 -7
- package/dist/background/index.d.ts +5 -2
- package/dist/background/index.d.ts.map +1 -1
- package/dist/background/index.js.map +1 -1
- package/dist/background/register.d.ts +3 -1
- package/dist/background/register.d.ts.map +1 -1
- package/dist/background/register.js +19 -2
- package/dist/background/register.js.map +1 -1
- package/dist/index.d.ts +5 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js.map +1 -1
- package/dist/modules/blob.d.ts +2 -1
- package/dist/modules/blob.d.ts.map +1 -1
- package/dist/modules/blob.js +2 -1
- package/dist/modules/blob.js.map +1 -1
- package/dist/modules/events.d.ts +16 -6
- package/dist/modules/events.d.ts.map +1 -1
- package/dist/modules/events.js +53 -47
- package/dist/modules/events.js.map +1 -1
- package/dist/modules/mic.d.ts +26 -4
- package/dist/modules/mic.d.ts.map +1 -1
- package/dist/modules/mic.js +13 -4
- package/dist/modules/mic.js.map +1 -1
- package/dist/modules/miniapps.d.ts +44 -57
- package/dist/modules/miniapps.d.ts.map +1 -1
- package/dist/modules/miniapps.js +21 -24
- package/dist/modules/miniapps.js.map +1 -1
- package/dist/modules/speaker.d.ts +41 -10
- package/dist/modules/speaker.d.ts.map +1 -1
- package/dist/modules/speaker.js +17 -6
- package/dist/modules/speaker.js.map +1 -1
- package/dist/modules/speechProcessing.d.ts +29 -0
- package/dist/modules/speechProcessing.d.ts.map +1 -0
- package/dist/modules/speechProcessing.js +22 -0
- package/dist/modules/speechProcessing.js.map +1 -0
- package/dist/modules/system.d.ts +8 -3
- package/dist/modules/system.d.ts.map +1 -1
- package/dist/modules/system.js +1 -1
- package/dist/modules/system.js.map +1 -1
- package/dist/modules/telemetry.d.ts +25 -0
- package/dist/modules/telemetry.d.ts.map +1 -0
- package/dist/modules/telemetry.js +61 -0
- package/dist/modules/telemetry.js.map +1 -0
- package/dist/modules/transcription.d.ts +70 -3
- package/dist/modules/transcription.d.ts.map +1 -1
- package/dist/modules/transcription.js +68 -2
- package/dist/modules/transcription.js.map +1 -1
- package/dist/protocol.d.ts +29 -15
- package/dist/protocol.d.ts.map +1 -1
- package/dist/protocol.js +30 -15
- package/dist/protocol.js.map +1 -1
- package/dist/react/MentraProvider.d.ts +13 -1
- package/dist/react/MentraProvider.d.ts.map +1 -1
- package/dist/react/MentraProvider.js +31 -1
- package/dist/react/MentraProvider.js.map +1 -1
- package/dist/session.d.ts +59 -6
- package/dist/session.d.ts.map +1 -1
- package/dist/session.js +203 -43
- package/dist/session.js.map +1 -1
- package/dist/transport/auto.js +6 -0
- package/dist/transport/auto.js.map +1 -1
- package/dist/transport/dispatch.d.ts +2 -0
- package/dist/transport/dispatch.d.ts.map +1 -1
- package/dist/transport/dispatch.js +7 -2
- package/dist/transport/dispatch.js.map +1 -1
- package/dist/transport/local-socket.d.ts +6 -0
- package/dist/transport/local-socket.d.ts.map +1 -1
- package/dist/transport/local-socket.js +34 -2
- package/dist/transport/local-socket.js.map +1 -1
- package/dist/transport/types.d.ts +4 -1
- package/dist/transport/types.d.ts.map +1 -1
- package/dist/ui/index.d.ts +7 -4
- package/dist/ui/index.d.ts.map +1 -1
- package/dist/ui/index.js.map +1 -1
- package/package.json +2 -2
- package/src/background/index.ts +6 -3
- package/src/background/register.ts +24 -2
- package/src/index.ts +11 -3
- package/src/modules/blob.ts +2 -1
- package/src/modules/events.ts +65 -51
- package/src/modules/mic.ts +30 -4
- package/src/modules/miniapps.ts +59 -71
- package/src/modules/speaker.ts +56 -12
- package/src/modules/speechProcessing.ts +42 -0
- package/src/modules/system.ts +8 -3
- package/src/modules/telemetry.ts +62 -0
- package/src/modules/transcription.ts +106 -9
- package/src/protocol.ts +32 -16
- package/src/react/MentraProvider.tsx +23 -2
- package/src/session.ts +206 -52
- package/src/transport/auto.ts +5 -0
- package/src/transport/dispatch.ts +7 -2
- package/src/transport/local-socket.ts +30 -1
- package/src/transport/types.ts +4 -1
- package/src/ui/index.ts +7 -4
package/src/protocol.ts
CHANGED
|
@@ -26,7 +26,16 @@ export enum MiniappRequestType {
|
|
|
26
26
|
/** Request a fresh miniapp-scoped backend auth token. */
|
|
27
27
|
AUTH_REFRESH = "miniapp_auth_refresh",
|
|
28
28
|
|
|
29
|
-
/**
|
|
29
|
+
/**
|
|
30
|
+
* Update the set of streams the miniapp is subscribed to. `subscriptions`
|
|
31
|
+
* lists stream names; a transcription stream is `{stream, processing}`, one
|
|
32
|
+
* entry per processing its listeners ask for, and `transcriptionListeners`
|
|
33
|
+
* lists every transcription listener as `{id, stream, processing}`. Both
|
|
34
|
+
* also carry `forceLocal: true` for `localOnly`, the form hosts before
|
|
35
|
+
* `processing` read. Hosts accept that older form,
|
|
36
|
+
* `{stream, forceLocal?, includeCloud?}`, from SDKs that predate
|
|
37
|
+
* `processing`.
|
|
38
|
+
*/
|
|
30
39
|
SUBSCRIBE = "miniapp_subscribe",
|
|
31
40
|
|
|
32
41
|
/**
|
|
@@ -45,7 +54,7 @@ export enum MiniappRequestType {
|
|
|
45
54
|
/** Stop any audio playback this miniapp initiated. */
|
|
46
55
|
STOP_AUDIO = "miniapp_stop_audio",
|
|
47
56
|
|
|
48
|
-
/** Speak text via cloud TTS
|
|
57
|
+
/** Speak text via cloud or on-device TTS, as its `processing` says. */
|
|
49
58
|
SPEAK = "miniapp_speak",
|
|
50
59
|
|
|
51
60
|
/**
|
|
@@ -189,6 +198,17 @@ export enum MiniappRequestType {
|
|
|
189
198
|
* so future reconnect logic can re-send.
|
|
190
199
|
*/
|
|
191
200
|
TRANSCRIPTION_CONFIG = "miniapp_transcription_config",
|
|
201
|
+
/**
|
|
202
|
+
* End the current on-device utterance now (transcription.finishUtterance).
|
|
203
|
+
* Result: the final text, "" when nothing was pending, or null when the
|
|
204
|
+
* model can't finish early.
|
|
205
|
+
*/
|
|
206
|
+
TRANSCRIPTION_FINISH = "miniapp_transcription_finish",
|
|
207
|
+
|
|
208
|
+
// ----- Telemetry -----
|
|
209
|
+
|
|
210
|
+
/** A miniapp's own analytics event (`session.telemetry.capture`). One-shot; hosts with `hostFeatures.telemetry`. */
|
|
211
|
+
TELEMETRY_CAPTURE = "miniapp_telemetry_capture",
|
|
192
212
|
|
|
193
213
|
// ----- Deferred in v1 -----
|
|
194
214
|
|
|
@@ -225,11 +245,11 @@ export enum MiniappRequestType {
|
|
|
225
245
|
MINIAPPS_START = "miniapp_apps_start",
|
|
226
246
|
/** Stop another miniapp. */
|
|
227
247
|
MINIAPPS_STOP = "miniapp_apps_stop",
|
|
228
|
-
/** Install
|
|
248
|
+
/** Install the miniapp at a miniapp URL. System-list miniapps only. */
|
|
229
249
|
MINIAPPS_INSTALL = "miniapp_apps_install",
|
|
230
250
|
/** Preflight a release's host/SDK/hardware requirements without downloading it. */
|
|
231
251
|
MINIAPPS_INSTALL_CHECK = "miniapp_apps_install_check",
|
|
232
|
-
/** Uninstall a
|
|
252
|
+
/** Uninstall a miniapp installed from a miniapp URL. System-list miniapps only. */
|
|
233
253
|
MINIAPPS_UNINSTALL = "miniapp_apps_uninstall",
|
|
234
254
|
/** Invoke a declared action on another miniapp; headless-wakes it if stopped. */
|
|
235
255
|
ACTION_INVOKE = "miniapp_action_invoke",
|
|
@@ -294,9 +314,6 @@ export enum MiniappResponseType {
|
|
|
294
314
|
/** Push: host color scheme (light/dark) changed. */
|
|
295
315
|
COLOR_SCHEME_CHANGE = "miniapp_color_scheme_change",
|
|
296
316
|
|
|
297
|
-
/** Push: a Store installation moved to another host-side phase. */
|
|
298
|
-
MINIAPPS_INSTALL_PROGRESS = "miniapp_apps_install_progress",
|
|
299
|
-
|
|
300
317
|
/**
|
|
301
318
|
* Push: speaker playback state transitioned. Per-miniapp; the runtime sends
|
|
302
319
|
* to the owning miniapp only. Carries {state, errorCode?, errorMessage?,
|
|
@@ -391,6 +408,10 @@ export enum MiniappStreamType {
|
|
|
391
408
|
// Speech / audio (cloud or local)
|
|
392
409
|
TRANSCRIPTION = "transcription", // language variant: "transcription:en-US"
|
|
393
410
|
TRANSLATION = "translation", // language variant: "translation:en-US"
|
|
411
|
+
/** State of the on-device speech-to-text model (session.transcription.onModelStatus). */
|
|
412
|
+
TRANSCRIPTION_MODEL_STATUS = "transcription_model_status",
|
|
413
|
+
/** On-device "Hey Mentra" keyword spotter (session.mic.onWakeWord). */
|
|
414
|
+
WAKE_WORD = "wake_word",
|
|
394
415
|
AUDIO_CHUNK = "audio_chunk",
|
|
395
416
|
VAD = "vad",
|
|
396
417
|
|
|
@@ -444,7 +465,7 @@ export enum MiniappErrorCode {
|
|
|
444
465
|
TTS_INVALID_VOICE = "TTS_INVALID_VOICE",
|
|
445
466
|
TTS_UPSTREAM_ERROR = "TTS_UPSTREAM_ERROR",
|
|
446
467
|
|
|
447
|
-
/** `speak({
|
|
468
|
+
/** `speak({processing: "localOnly"})` but the on-device TTS model isn't downloaded/ready. */
|
|
448
469
|
TTS_LOCAL_UNAVAILABLE = "TTS_LOCAL_UNAVAILABLE",
|
|
449
470
|
|
|
450
471
|
/** Not connected / pre-ACK and transport closed. */
|
|
@@ -459,21 +480,16 @@ export enum MiniappErrorCode {
|
|
|
459
480
|
// ----- Inter-miniapp interop -----
|
|
460
481
|
/**
|
|
461
482
|
* Caller is not a system app — SYSTEM-only APIs (interop list/start/stop/invoke,
|
|
462
|
-
* setWifiAdbState) reject with this code
|
|
483
|
+
* setWifiAdbState) reject with this code, as installs do from any miniapp off
|
|
484
|
+
* the system list. Also: an uninstall of a miniapp that isn't a URL install.
|
|
463
485
|
*/
|
|
464
486
|
NOT_PERMITTED = "NOT_PERMITTED",
|
|
465
487
|
/** Target miniapp is not installed. */
|
|
466
488
|
APP_NOT_FOUND = "APP_NOT_FOUND",
|
|
467
489
|
/** Target miniapp is incompatible with the connected glasses. */
|
|
468
490
|
APP_NOT_COMPATIBLE = "APP_NOT_COMPATIBLE",
|
|
469
|
-
/**
|
|
491
|
+
/** The miniapp didn't install; the error's `reason` says why (`InstallMiniappFailureReason`). */
|
|
470
492
|
INSTALL_FAILED = "INSTALL_FAILED",
|
|
471
|
-
/** Another Store installation is already in progress for the same package. */
|
|
472
|
-
INSTALL_IN_PROGRESS = "INSTALL_IN_PROGRESS",
|
|
473
|
-
/** An automatic update was deferred because the target is running or starting. */
|
|
474
|
-
APP_RUNNING = "APP_RUNNING",
|
|
475
|
-
/** Another Store owns the installed package's update provenance. */
|
|
476
|
-
STORE_OWNERSHIP_CONFLICT = "STORE_OWNERSHIP_CONFLICT",
|
|
477
493
|
/** Target miniapp does not declare the requested action. */
|
|
478
494
|
ACTION_NOT_FOUND = "ACTION_NOT_FOUND",
|
|
479
495
|
/** Target connected but never registered a handler for the action (within the buffer window). */
|
|
@@ -5,6 +5,8 @@
|
|
|
5
5
|
* miniapp. Currently:
|
|
6
6
|
* - Keeps `<html class="dark">` in sync with the host's color scheme so the
|
|
7
7
|
* shared theme CSS switches automatically.
|
|
8
|
+
* - Calls `mentra.ready()` once the app has mounted, which lifts the host's
|
|
9
|
+
* splash and fires the background's `session.ui.onOpen` handlers.
|
|
8
10
|
*
|
|
9
11
|
* Usage:
|
|
10
12
|
* createRoot(root).render(
|
|
@@ -17,7 +19,7 @@
|
|
|
17
19
|
* things themselves can opt out without forking the provider.
|
|
18
20
|
*/
|
|
19
21
|
|
|
20
|
-
import {type ReactNode} from "react"
|
|
22
|
+
import {type ReactNode, useEffect} from "react"
|
|
21
23
|
|
|
22
24
|
import {useColorScheme} from "./useColorScheme"
|
|
23
25
|
|
|
@@ -32,11 +34,30 @@ export interface MentraProviderProps {
|
|
|
32
34
|
* (e.g. you integrate a theming library like next-themes).
|
|
33
35
|
*/
|
|
34
36
|
syncColorScheme?: boolean
|
|
37
|
+
/**
|
|
38
|
+
* Call `mentra.ready()` after the first mount. A parent's effects run after
|
|
39
|
+
* its children's, so every `mentra.on` subscription the app makes on mount
|
|
40
|
+
* is attached before the background is told the UI is open. Without
|
|
41
|
+
* `ready()` the host keeps its splash up and reports the miniapp as failed.
|
|
42
|
+
*
|
|
43
|
+
* Default: true. Set to false to call `mentra.ready()` yourself, e.g. to keep
|
|
44
|
+
* the splash up until the first screen has its data.
|
|
45
|
+
*/
|
|
46
|
+
autoReady?: boolean
|
|
35
47
|
}
|
|
36
48
|
|
|
37
|
-
|
|
49
|
+
function getBridge(): {ready?: () => void} | null {
|
|
50
|
+
if (typeof window === "undefined") return null
|
|
51
|
+
return (window as unknown as {mentra?: {ready?: () => void}}).mentra ?? null
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
export function MentraProvider({children, syncColorScheme = true, autoReady = true}: MentraProviderProps) {
|
|
38
55
|
const scheme = useColorScheme()
|
|
39
56
|
|
|
57
|
+
useEffect(() => {
|
|
58
|
+
if (autoReady) getBridge()?.ready?.()
|
|
59
|
+
}, [autoReady])
|
|
60
|
+
|
|
40
61
|
// Runs during render — before children paint, before effects fire.
|
|
41
62
|
if (syncColorScheme && typeof document !== "undefined") {
|
|
42
63
|
const el = document.documentElement
|
package/src/session.ts
CHANGED
|
@@ -26,6 +26,7 @@ import {ConfigurationModule} from "./modules/configuration"
|
|
|
26
26
|
import {DashboardAPI} from "./modules/dashboard"
|
|
27
27
|
import {DisplayManager} from "./modules/display"
|
|
28
28
|
import {EventManager, type TranscriptionEventRoute, type UnsubscribeFn} from "./modules/events"
|
|
29
|
+
import type {SpeechProcessingOptions} from "./modules/speechProcessing"
|
|
29
30
|
import {GlassesModule} from "./modules/glasses"
|
|
30
31
|
import {HeadingModule} from "./modules/heading"
|
|
31
32
|
import {ImuModule} from "./modules/imu"
|
|
@@ -45,6 +46,7 @@ import {StreamModule} from "./modules/stream"
|
|
|
45
46
|
import {SystemModule} from "./modules/system"
|
|
46
47
|
import {MiniappsModule} from "./modules/miniapps"
|
|
47
48
|
import {ActionsModule} from "./modules/actions"
|
|
49
|
+
import {TelemetryModule} from "./modules/telemetry"
|
|
48
50
|
import {BlobModule} from "./modules/blob"
|
|
49
51
|
import {
|
|
50
52
|
MeetingModule,
|
|
@@ -130,6 +132,13 @@ export interface HostFeatures {
|
|
|
130
132
|
captureAudio?: boolean
|
|
131
133
|
/** Host keeps the UI closed until a background session that announced it sends READY. */
|
|
132
134
|
initReady?: boolean
|
|
135
|
+
/**
|
|
136
|
+
* Host installs miniapps from a miniapp URL through `session.miniapps.install({url})`. Only a miniapp on the
|
|
137
|
+
* Mentra App's system list may call it; older Mentra Apps answer NOT_PERMITTED.
|
|
138
|
+
*/
|
|
139
|
+
miniappInstall?: boolean
|
|
140
|
+
/** Host takes the miniapp's own events from `session.telemetry.capture` (Fleet Management's miniapp telemetry). */
|
|
141
|
+
telemetry?: boolean
|
|
133
142
|
}
|
|
134
143
|
|
|
135
144
|
export interface MiniappAuthState {
|
|
@@ -171,9 +180,22 @@ export class NotConnectedError extends Error {
|
|
|
171
180
|
}
|
|
172
181
|
}
|
|
173
182
|
|
|
183
|
+
/**
|
|
184
|
+
* @internal — `connect()` rejects with this when the host did not answer CONNECT
|
|
185
|
+
* within `connectTimeoutMs`. The session stays usable: `connect()` sends CONNECT again.
|
|
186
|
+
*/
|
|
187
|
+
export class ConnectAckTimeoutError extends Error {
|
|
188
|
+
constructor() {
|
|
189
|
+
super("MiniappSession: CONNECT_ACK timeout")
|
|
190
|
+
this.name = "ConnectAckTimeoutError"
|
|
191
|
+
}
|
|
192
|
+
}
|
|
193
|
+
|
|
174
194
|
export interface MiniappRequestError {
|
|
175
195
|
code: string
|
|
176
196
|
message: string
|
|
197
|
+
/** A finer cause, where a request documents one (`INSTALL_FAILED` from `session.miniapps.install`). */
|
|
198
|
+
reason?: string
|
|
177
199
|
}
|
|
178
200
|
|
|
179
201
|
// ---------------------------------------------------------------------------
|
|
@@ -189,6 +211,8 @@ interface PendingRequest {
|
|
|
189
211
|
}
|
|
190
212
|
|
|
191
213
|
const DEFAULT_CONNECT_TIMEOUT_MS = 10_000
|
|
214
|
+
/** Pause before a `registerMiniapp` session sends CONNECT again after a CONNECT_ACK timeout. */
|
|
215
|
+
const CONNECT_RETRY_MS = 1_000
|
|
192
216
|
|
|
193
217
|
// Hard ceiling on how long a single bridge request waits for the host's
|
|
194
218
|
// REQUEST_RESULT. Without it, a host that never responds (a hung cloud call, a
|
|
@@ -283,6 +307,8 @@ export class MiniappSession<TChannels extends object = any> {
|
|
|
283
307
|
* declared action; `handle` (open to all) exposes one of your own.
|
|
284
308
|
*/
|
|
285
309
|
public readonly actions: ActionsModule
|
|
310
|
+
/** The miniapp's own analytics, shown in its organization's Fleet Management (see {@link TelemetryModule}). */
|
|
311
|
+
public readonly telemetry: TelemetryModule
|
|
286
312
|
|
|
287
313
|
/** Phone-declared glasses capabilities. Null until CONNECT_ACK arrives. */
|
|
288
314
|
public capabilities: GlassesCapabilities | null = null
|
|
@@ -315,11 +341,26 @@ export class MiniappSession<TChannels extends object = any> {
|
|
|
315
341
|
|
|
316
342
|
/**
|
|
317
343
|
* Outbound queue for anything sent before CONNECT_ACK. Flushed in FIFO order
|
|
318
|
-
* once the phone responds with CONNECT_ACK.
|
|
344
|
+
* once the phone responds with CONNECT_ACK. A queued request carries its id so
|
|
345
|
+
* one that has already been rejected is dropped instead of sent.
|
|
319
346
|
*/
|
|
320
|
-
private readonly outboundQueue: string
|
|
347
|
+
private readonly outboundQueue: Array<{raw: string; requestId?: string}> = []
|
|
321
348
|
private readonly pendingRequests = new Map<string, PendingRequest>()
|
|
349
|
+
/** In flight or succeeded. A failed attempt clears it so `connect()` can send CONNECT again. */
|
|
322
350
|
private connectPromise: Promise<void> | null = null
|
|
351
|
+
/**
|
|
352
|
+
* Set by the first CONNECT_ACK and never cleared: the handshake completes once
|
|
353
|
+
* per session. The host answers every CONNECT, so after a retry the ACK for
|
|
354
|
+
* another CONNECT of this session can still arrive, in either order. Unlike
|
|
355
|
+
* `ready`, this survives a transport drop, which a session does not recover from.
|
|
356
|
+
*/
|
|
357
|
+
private handshakeComplete = false
|
|
358
|
+
/** Rejects the handshake in flight. Set only while waiting for CONNECT_ACK. */
|
|
359
|
+
private failHandshake: ((error: Error) => void) | null = null
|
|
360
|
+
/** Set by `registerMiniapp`: a CONNECT_ACK timeout sends CONNECT again instead of failing `connect()`. */
|
|
361
|
+
private retryHandshake = false
|
|
362
|
+
/** Ends the pause before CONNECT is sent again, with the failure that ended it if any. Set only during that pause. */
|
|
363
|
+
private endRetryPause: ((failure?: Error) => void) | null = null
|
|
323
364
|
private disposed = false
|
|
324
365
|
/**
|
|
325
366
|
* Set by `registerMiniapp` to the host's id for this spawn: CONNECT tells the
|
|
@@ -375,6 +416,12 @@ export class MiniappSession<TChannels extends object = any> {
|
|
|
375
416
|
this.ui = new UIModuleImpl<TChannels>(this)
|
|
376
417
|
this.miniapps = new MiniappsModule(this)
|
|
377
418
|
this.actions = new ActionsModule(this)
|
|
419
|
+
this.telemetry = new TelemetryModule(this)
|
|
420
|
+
}
|
|
421
|
+
|
|
422
|
+
/** @internal Whether CONNECT_ACK arrived, so `hostFeatures` is the host's answer and not just unknown. */
|
|
423
|
+
get handshakeDone(): boolean {
|
|
424
|
+
return this.handshakeComplete
|
|
378
425
|
}
|
|
379
426
|
|
|
380
427
|
/**
|
|
@@ -448,7 +495,7 @@ export class MiniappSession<TChannels extends object = any> {
|
|
|
448
495
|
_subscribe(
|
|
449
496
|
streamType: string,
|
|
450
497
|
handler: (data: unknown) => void,
|
|
451
|
-
options:
|
|
498
|
+
options: SpeechProcessingOptions = {},
|
|
452
499
|
): UnsubscribeFn {
|
|
453
500
|
return this.events.subscribe(streamType, handler, options)
|
|
454
501
|
}
|
|
@@ -458,52 +505,158 @@ export class MiniappSession<TChannels extends object = any> {
|
|
|
458
505
|
// -------------------------------------------------------------------------
|
|
459
506
|
|
|
460
507
|
/**
|
|
461
|
-
* Connect to LocalMiniappRuntime. Idempotent
|
|
462
|
-
*
|
|
508
|
+
* Connect to LocalMiniappRuntime. Idempotent while a handshake is in flight
|
|
509
|
+
* or has succeeded: repeat calls return the same Promise. A failed attempt
|
|
510
|
+
* (CONNECT_ACK timeout, transport failure) does not stick, so a later call
|
|
511
|
+
* sends CONNECT again. A session started by `registerMiniapp` keeps sending
|
|
512
|
+
* CONNECT after a timeout, so this Promise (and `waitForReady()`) settles
|
|
513
|
+
* only when the host answers, the transport fails, or the session ends.
|
|
463
514
|
*/
|
|
464
515
|
connect(): Promise<void> {
|
|
465
516
|
if (this.disposed) {
|
|
466
517
|
return Promise.reject(new NotConnectedError("MiniappSession was disposed"))
|
|
467
518
|
}
|
|
468
519
|
if (this.connectPromise) return this.connectPromise
|
|
520
|
+
// A CONNECT_ACK that arrived after an earlier attempt timed out still completed the handshake.
|
|
521
|
+
if (this.handshakeComplete) {
|
|
522
|
+
this.connectPromise = Promise.resolve()
|
|
523
|
+
return this.connectPromise
|
|
524
|
+
}
|
|
525
|
+
|
|
526
|
+
const attempt = this.retryHandshake ? this.connectUntilAcknowledged() : this.sendConnect()
|
|
527
|
+
this.connectPromise = attempt
|
|
528
|
+
attempt.catch(() => {
|
|
529
|
+
// Registered before the caller's handlers, so a retry from a rejection handler sends CONNECT again.
|
|
530
|
+
if (this.connectPromise === attempt) this.connectPromise = null
|
|
531
|
+
})
|
|
532
|
+
return attempt
|
|
533
|
+
}
|
|
534
|
+
|
|
535
|
+
/**
|
|
536
|
+
* @internal — called by `registerMiniapp` before its handler runs. The host
|
|
537
|
+
* owns this context's lifetime, so a host that has not answered CONNECT is
|
|
538
|
+
* stalled rather than gone: send CONNECT again instead of failing.
|
|
539
|
+
*/
|
|
540
|
+
retryHandshakeOnTimeout(): void {
|
|
541
|
+
this.retryHandshake = true
|
|
542
|
+
}
|
|
543
|
+
|
|
544
|
+
private async connectUntilAcknowledged(): Promise<void> {
|
|
545
|
+
for (;;) {
|
|
546
|
+
try {
|
|
547
|
+
await this.sendConnect()
|
|
548
|
+
return
|
|
549
|
+
} catch (err) {
|
|
550
|
+
if (this.disposed || !(err instanceof ConnectAckTimeoutError)) throw err
|
|
551
|
+
}
|
|
552
|
+
// eslint-disable-next-line no-console
|
|
553
|
+
console.warn("[mentra-miniapp] CONNECT_ACK timed out; sending CONNECT again")
|
|
554
|
+
const failure = await this.pauseBeforeRetry()
|
|
555
|
+
if (failure) throw failure
|
|
556
|
+
// The CONNECT_ACK for an earlier CONNECT can still land during the pause.
|
|
557
|
+
if (this.handshakeComplete) return
|
|
558
|
+
if (this.disposed) throw new NotConnectedError("MiniappSession: connect aborted")
|
|
559
|
+
}
|
|
560
|
+
}
|
|
469
561
|
|
|
562
|
+
/**
|
|
563
|
+
* Resolves after CONNECT_RETRY_MS, or as soon as CONNECT_ACK lands or the
|
|
564
|
+
* session ends. Resolves with the error when the transport failed meanwhile.
|
|
565
|
+
*/
|
|
566
|
+
private pauseBeforeRetry(): Promise<Error | undefined> {
|
|
567
|
+
return new Promise<Error | undefined>((resolve) => {
|
|
568
|
+
const end = (failure?: Error) => {
|
|
569
|
+
clearTimeout(timer)
|
|
570
|
+
this.emitter.off("ready", onReady)
|
|
571
|
+
if (this.endRetryPause === end) this.endRetryPause = null
|
|
572
|
+
resolve(failure)
|
|
573
|
+
}
|
|
574
|
+
const onReady = () => end()
|
|
575
|
+
const timer = setTimeout(end, CONNECT_RETRY_MS)
|
|
576
|
+
this.emitter.on("ready", onReady)
|
|
577
|
+
this.endRetryPause = end
|
|
578
|
+
})
|
|
579
|
+
}
|
|
580
|
+
|
|
581
|
+
/** Send one CONNECT and wait for its CONNECT_ACK. */
|
|
582
|
+
private sendConnect(): Promise<void> {
|
|
583
|
+
// Only a host that received CONNECT can be waited out. Before that, the transport is what failed.
|
|
584
|
+
let connectSent = false
|
|
585
|
+
// This attempt's own outcome. A slow open() can finish after a newer attempt
|
|
586
|
+
// took over, so nothing below acts through the session-wide failHandshake.
|
|
587
|
+
let attemptSettled = false
|
|
588
|
+
let failAttempt: (error: Error) => void = () => {}
|
|
470
589
|
// Register the readiness listener BEFORE any awaits so that a synchronous
|
|
471
590
|
// CONNECT_ACK delivery in tests (or the phone) can't race the subscription.
|
|
472
591
|
const readyPromise = new Promise<void>((resolve, reject) => {
|
|
592
|
+
const settle = (error?: Error) => {
|
|
593
|
+
if (attemptSettled) return
|
|
594
|
+
attemptSettled = true
|
|
595
|
+
clearTimeout(timer)
|
|
596
|
+
this.emitter.off("ready", onReady)
|
|
597
|
+
this.emitter.off("error", onError)
|
|
598
|
+
if (this.failHandshake === onError) this.failHandshake = null
|
|
599
|
+
if (error) reject(error)
|
|
600
|
+
else resolve()
|
|
601
|
+
}
|
|
602
|
+
const onReady = () => settle()
|
|
603
|
+
const onError = (error: Error) => settle(error)
|
|
473
604
|
const timer = setTimeout(() => {
|
|
474
|
-
const err =
|
|
605
|
+
const err = connectSent
|
|
606
|
+
? new ConnectAckTimeoutError()
|
|
607
|
+
: new Error("MiniappSession: transport did not open before the CONNECT_ACK timeout")
|
|
608
|
+
// Settled before the public emit, so a throwing "error" listener cannot leave it pending.
|
|
609
|
+
settle(err)
|
|
610
|
+
// Requests queued for a retried handshake wait for it, bounded by their own timeouts.
|
|
611
|
+
if (connectSent && this.retryHandshake) return
|
|
475
612
|
this.failAllPending({code: MiniappErrorCode.NOT_CONNECTED, message: err.message})
|
|
476
613
|
this.emitter.emit("error", err)
|
|
477
|
-
reject(err)
|
|
478
614
|
}, this.connectTimeoutMs)
|
|
479
|
-
|
|
480
|
-
this.emitter.
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
})
|
|
484
|
-
this.emitter.once("error", (err) => {
|
|
485
|
-
clearTimeout(timer)
|
|
486
|
-
reject(err)
|
|
487
|
-
})
|
|
615
|
+
this.emitter.on("ready", onReady)
|
|
616
|
+
this.emitter.on("error", onError)
|
|
617
|
+
this.failHandshake = onError
|
|
618
|
+
failAttempt = onError
|
|
488
619
|
})
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
620
|
+
// Settles once CONNECT is sent, or rejects if opening or sending fails.
|
|
621
|
+
const sent = (async () => {
|
|
622
|
+
try {
|
|
623
|
+
this.transport.onMessage((raw) => this.handleIncoming(raw))
|
|
624
|
+
this.transport.onDisconnect((reason) => this.handleTransportDisconnect(reason))
|
|
625
|
+
// An open transport stays as it is: a retried handshake only sends CONNECT again.
|
|
626
|
+
const opening = this.transport.isOpen() ? Promise.resolve() : this.transport.open()
|
|
627
|
+
// An open that finishes after disconnect() must not leave the transport open.
|
|
628
|
+
opening.then(
|
|
629
|
+
() => {
|
|
630
|
+
if (this.disposed) this.transport.close()
|
|
631
|
+
},
|
|
632
|
+
() => {},
|
|
633
|
+
)
|
|
634
|
+
await opening
|
|
635
|
+
// Settled while opening: failed (the timeout, disconnect(), a transport drop),
|
|
636
|
+
// or completed by an earlier CONNECT's ACK. Either way, send nothing.
|
|
637
|
+
if (attemptSettled) return
|
|
638
|
+
if (this.disposed) throw new NotConnectedError("MiniappSession: connect aborted")
|
|
639
|
+
|
|
640
|
+
const requestId = makeRequestId()
|
|
641
|
+
const connectPayload = {
|
|
642
|
+
type: MiniappRequestType.CONNECT,
|
|
643
|
+
packageName: this.packageName,
|
|
644
|
+
...(this.initSessionId !== null ? {initReady: true, sessionId: this.initSessionId} : {}),
|
|
645
|
+
}
|
|
646
|
+
connectSent = true
|
|
647
|
+
this.transport.send(serializeEnvelope({payload: connectPayload, requestId}))
|
|
648
|
+
} catch (err) {
|
|
649
|
+
// Already reported through readyPromise; a newer attempt may own the session now.
|
|
650
|
+
if (attemptSettled) return
|
|
651
|
+
const error = err instanceof Error ? err : new Error(String(err))
|
|
652
|
+
if (!this.disposed) this.failAllPending({code: MiniappErrorCode.NOT_CONNECTED, message: error.message})
|
|
653
|
+
failAttempt(error)
|
|
654
|
+
throw error
|
|
500
655
|
}
|
|
501
|
-
this.transport.send(serializeEnvelope({payload: connectPayload, requestId}))
|
|
502
|
-
|
|
503
|
-
await readyPromise
|
|
504
656
|
})()
|
|
505
|
-
|
|
506
|
-
|
|
657
|
+
// The handshake can fail while the transport is still opening (disconnect(),
|
|
658
|
+
// the timeout): the attempt settles then, without waiting for open().
|
|
659
|
+
return Promise.all([sent, readyPromise]).then(() => undefined)
|
|
507
660
|
}
|
|
508
661
|
|
|
509
662
|
/**
|
|
@@ -534,6 +687,10 @@ export class MiniappSession<TChannels extends object = any> {
|
|
|
534
687
|
disconnect(): void {
|
|
535
688
|
if (this.disposed) return
|
|
536
689
|
this.disposed = true
|
|
690
|
+
// End a handshake still waiting for CONNECT_ACK. Its timer would otherwise
|
|
691
|
+
// report a timeout for a session that no longer exists.
|
|
692
|
+
this.failHandshake?.(new NotConnectedError("MiniappSession: connect aborted"))
|
|
693
|
+
this.endRetryPause?.()
|
|
537
694
|
// Give listeners one synchronous chance to flush final messages
|
|
538
695
|
// (e.g. display.render([])) before we tear down the transport.
|
|
539
696
|
try {
|
|
@@ -602,7 +759,7 @@ export class MiniappSession<TChannels extends object = any> {
|
|
|
602
759
|
reject,
|
|
603
760
|
timer,
|
|
604
761
|
})
|
|
605
|
-
this.enqueueOrSend(serializeEnvelope(envelope))
|
|
762
|
+
this.enqueueOrSend(serializeEnvelope(envelope), requestId)
|
|
606
763
|
})
|
|
607
764
|
}
|
|
608
765
|
|
|
@@ -647,7 +804,7 @@ export class MiniappSession<TChannels extends object = any> {
|
|
|
647
804
|
// Internal — transport glue
|
|
648
805
|
// -------------------------------------------------------------------------
|
|
649
806
|
|
|
650
|
-
private enqueueOrSend(raw: string): void {
|
|
807
|
+
private enqueueOrSend(raw: string, requestId?: string): void {
|
|
651
808
|
if (this.ready) {
|
|
652
809
|
try {
|
|
653
810
|
this.transport.send(raw)
|
|
@@ -657,12 +814,15 @@ export class MiniappSession<TChannels extends object = any> {
|
|
|
657
814
|
}
|
|
658
815
|
return
|
|
659
816
|
}
|
|
660
|
-
this.outboundQueue.push(raw)
|
|
817
|
+
this.outboundQueue.push(requestId === undefined ? {raw} : {raw, requestId})
|
|
661
818
|
}
|
|
662
819
|
|
|
663
820
|
private flushQueue(): void {
|
|
664
821
|
const queue = this.outboundQueue.splice(0)
|
|
665
|
-
for (const raw of queue) {
|
|
822
|
+
for (const {raw, requestId} of queue) {
|
|
823
|
+
// Rejected while waiting for the handshake (a CONNECT_ACK timeout or its own
|
|
824
|
+
// timeout). Its caller has seen the failure, so the host must not run it.
|
|
825
|
+
if (requestId !== undefined && !this.pendingRequests.has(requestId)) continue
|
|
666
826
|
try {
|
|
667
827
|
this.transport.send(raw)
|
|
668
828
|
} catch (err) {
|
|
@@ -680,6 +840,10 @@ export class MiniappSession<TChannels extends object = any> {
|
|
|
680
840
|
|
|
681
841
|
switch (type) {
|
|
682
842
|
case MiniappResponseType.CONNECT_ACK: {
|
|
843
|
+
// The answer to another CONNECT of this session (a retry, or one whose
|
|
844
|
+
// attempt timed out). Applying it would run the handshake again: emit
|
|
845
|
+
// "ready" twice and replace state that later updates may have changed.
|
|
846
|
+
if (this.handshakeComplete) return
|
|
683
847
|
const ack = payload as unknown as ConnectAckPayload
|
|
684
848
|
this.userId = ack.userId ?? ""
|
|
685
849
|
if (ack.packageName) this.packageName = ack.packageName
|
|
@@ -698,6 +862,7 @@ export class MiniappSession<TChannels extends object = any> {
|
|
|
698
862
|
// that don't send `permissions` leave the all-false default in place
|
|
699
863
|
// — `hasPermission` getters will simply return false.
|
|
700
864
|
if (ack.permissions) this.applyPermissions(ack.permissions)
|
|
865
|
+
this.handshakeComplete = true
|
|
701
866
|
this.ready = true
|
|
702
867
|
this.flushQueue()
|
|
703
868
|
this.emitter.emit("ready")
|
|
@@ -853,22 +1018,6 @@ export class MiniappSession<TChannels extends object = any> {
|
|
|
853
1018
|
return
|
|
854
1019
|
}
|
|
855
1020
|
|
|
856
|
-
case MiniappResponseType.MINIAPPS_INSTALL_PROGRESS: {
|
|
857
|
-
const {packageName, version, phase} = payload as Record<string, unknown>
|
|
858
|
-
if (
|
|
859
|
-
typeof packageName === "string" &&
|
|
860
|
-
typeof version === "string" &&
|
|
861
|
-
(phase === "downloading" ||
|
|
862
|
-
phase === "verifying" ||
|
|
863
|
-
phase === "extracting" ||
|
|
864
|
-
phase === "activating" ||
|
|
865
|
-
phase === "complete")
|
|
866
|
-
) {
|
|
867
|
-
this.miniapps._deliverInstallProgress({packageName, version, phase})
|
|
868
|
-
}
|
|
869
|
-
return
|
|
870
|
-
}
|
|
871
|
-
|
|
872
1021
|
case MiniappResponseType.REQUEST_RESULT: {
|
|
873
1022
|
const requestId = envelope.requestId
|
|
874
1023
|
if (!requestId) return
|
|
@@ -912,6 +1061,11 @@ export class MiniappSession<TChannels extends object = any> {
|
|
|
912
1061
|
|
|
913
1062
|
private handleTransportDisconnect(reason: string): void {
|
|
914
1063
|
this.ready = false
|
|
1064
|
+
// A transport that drops during the handshake has failed it. Sending CONNECT
|
|
1065
|
+
// again over a dead bridge would keep that failure from the host.
|
|
1066
|
+
const failure = new Error(`MiniappSession: transport disconnected: ${reason}`)
|
|
1067
|
+
this.failHandshake?.(failure)
|
|
1068
|
+
this.endRetryPause?.(failure)
|
|
915
1069
|
this.failAllPending({code: MiniappErrorCode.NOT_CONNECTED, message: `Transport disconnected: ${reason}`})
|
|
916
1070
|
this.emitter.emit("disconnect", reason)
|
|
917
1071
|
}
|
package/src/transport/auto.ts
CHANGED
|
@@ -84,6 +84,11 @@ class LocalSocketWithMockFallback implements Transport {
|
|
|
84
84
|
constructor(private readonly options: LocalSocketTransportOptions) {}
|
|
85
85
|
|
|
86
86
|
async open(): Promise<void> {
|
|
87
|
+
// A retried handshake opens again: keep the transport already selected.
|
|
88
|
+
if (this.active?.isOpen()) return
|
|
89
|
+
// One that dropped is replaced, so it cannot keep delivering to the handlers.
|
|
90
|
+
this.active?.close()
|
|
91
|
+
this.active = null
|
|
87
92
|
const local = new LocalSocketTransport(this.options)
|
|
88
93
|
let timedOut = false
|
|
89
94
|
const timeout = new Promise<void>((_, reject) => {
|
|
@@ -43,6 +43,8 @@ export class DispatchTransport implements Transport {
|
|
|
43
43
|
private messageHandler: TransportMessageHandler | null = null
|
|
44
44
|
private disconnectHandler: TransportDisconnectHandler | null = null
|
|
45
45
|
private open_ = false
|
|
46
|
+
/** The delivery hook this transport installed; another transport may own the global later. */
|
|
47
|
+
private deliverHook: ((raw: string) => void) | null = null
|
|
46
48
|
|
|
47
49
|
/** True iff `__dispatch` is bound on the current globalThis. */
|
|
48
50
|
static isAvailable(): boolean {
|
|
@@ -57,9 +59,10 @@ export class DispatchTransport implements Transport {
|
|
|
57
59
|
// route bridge frames here. Installed lazily so multiple transports
|
|
58
60
|
// can share the same global if a test spins up two.
|
|
59
61
|
const g = globalThis as unknown as BridgeDeliverGlobal
|
|
60
|
-
|
|
62
|
+
this.deliverHook = (raw: string) => {
|
|
61
63
|
if (this.messageHandler) this.messageHandler(raw)
|
|
62
64
|
}
|
|
65
|
+
g.__mentraDeliverBridgeRaw = this.deliverHook
|
|
63
66
|
this.open_ = true
|
|
64
67
|
}
|
|
65
68
|
|
|
@@ -95,9 +98,11 @@ export class DispatchTransport implements Transport {
|
|
|
95
98
|
close(): void {
|
|
96
99
|
this.open_ = false
|
|
97
100
|
const g = globalThis as unknown as BridgeDeliverGlobal
|
|
98
|
-
|
|
101
|
+
// A replacement session's transport may have installed its own hook since.
|
|
102
|
+
if (this.deliverHook && g.__mentraDeliverBridgeRaw === this.deliverHook) {
|
|
99
103
|
delete g.__mentraDeliverBridgeRaw
|
|
100
104
|
}
|
|
105
|
+
this.deliverHook = null
|
|
101
106
|
}
|
|
102
107
|
|
|
103
108
|
isOpen(): boolean {
|